- claude-sessions: registry manager with list/recover/spawn/resume/register/gc and interactive menu
- claude-sessions-shutdown: graceful systemd shutdown handler
- install-systemd.sh: idempotent service installer for new machines
- config/systemd/user/claude-sessions-save.service: versioned service definition
- README + CONTEXT updated
config/systemd/user/claude-sessions-save.service: source of truth
for the shutdown service, version-controlled alongside the scripts
it calls.
scripts/install-systemd.sh: idempotent install script — copies the
service file to ~/.config/systemd/user/, reloads the daemon, and
enables + starts the service. Run on any new machine to wire up
graceful Claude session shutdown.
claude-sessions: session registry manager with subcommands:
- list: live tmux sessions + resumable registry entries
- recover: scan profile dirs for sessions active before restart
- spawn/resume: start or resume sessions
- register: called by claude-tmux to auto-populate registry
- gc: prune stale entries and backfill session IDs from .jsonl
- (no args): interactive numbered menu
claude-sessions-shutdown: called by systemd at halt/reboot;
sends /exit-session to each Claude tmux session, waits up to
90s for graceful exit, force-kills stragglers.
Symlinks: ~/sbin/claude-sessions, ~/sbin/claude-sessions-shutdown
formatters/sh no longer exits 0 in silence when shfmt/shellcheck are absent —
that silence was the same swallow pattern the linter exists to catch.
Adds SETE-1 (executable script with no set -e), SETE-2 (sh/bash -c with
multiple commands and no set -e inside) and LEAK-1 (secret-named file read into
a string passed to echo/printf/die). Verified against the real defects: SETE-1
and SETE-2 both flag the actual pre-fix sync-deps; LEAK-1 flags the actual
kv-put credential leak. Neither fixed script is flagged.
Supervisor fix on top: SETE-2 was matching line by line and missed the
multi-line sh -c form, i.e. the exact bug it was written for.
Claude-Session: https://claude.ai/code/session_014KNyfHmHpMbdMrHZXDRkAp
SETE-2 matched `sh -c "..."` with a per-line regex requiring both quotes on one
line. The shape that motivated the check spans lines:
sh -c "
hugo mod get ...
hugo mod tidy
"
so the real sync-deps bug — the one this check exists for — was never flagged.
Verified against the actual pre-fix sync-deps: now reports at line 358,
"4 commands and no 'set -e' inside".
Scans the file text with re.DOTALL and reports the line of the match start.
Falls back to counting non-blank lines when the body is newline- rather than
;-separated, which is what the multi-line form looks like.
Adds both regression cases (multi-line without set -e must flag; multi-line
with set -e must not). Verified they go red when the whole-file scan is
disabled. Neither of the two fixed real scripts is flagged.
Note for whoever extends this suite: fixtures written with a heredoc inside it
did not behave; the printf form does. Both new tests use printf.
Claude-Session: https://claude.ai/code/session_014KNyfHmHpMbdMrHZXDRkAp
Supervisor-verified against the two real commands that produced false 'pushed'
messages earlier today (both flagged, rc=2), and against six legitimate
commands from the same session including a correct 'set -o pipefail' form
(none flagged). Advisory only — exit 2 feedback, never blocks.
Claude-Session: https://claude.ai/code/session_014KNyfHmHpMbdMrHZXDRkAp
PreToolUse hook for the Bash tool. When the user writes a pipeline whose
left side changes state (git push, kubectl apply, curl -X PUT, ...) and
whose exit status is then consumed by && / || / an if-condition, the
hook exits 2 and surfaces an advisory naming the masking command and
suggesting ${PIPESTATUS[0]} or dropping the pipe.
Always exits 0 on parse failure, missing python3, empty input, malformed
JSON, or anything it does not recognise — a hook that breaks Bash is
worse than the bug it prevents.
Real-process tests in hooks/tests/ feed JSON on stdin as a subprocess and
include mutation cases (six targeted matcher breakages) to prove each
assertion can actually fail.
Injects a reminder to read the project's memory/gotchas-minimax.md when a prompt mentions
MiniMax or mm-worktree-task, once per session, with the real resolved path. Supervising
MiniMax units has repeatable failure modes (claimed-green dodges, fakes-only tests, a unit
routing around a permission gate) and the write-ups only help if they are opened.
Never blocks: always exits 0 on missing jq, malformed stdin or an unwritable TMPDIR.
Installed into both custom config homes (anthropic + minimax).
Claude-Session: https://claude.ai/code/session_014KNyfHmHpMbdMrHZXDRkAp
Four memory docs (2 skills, 2 wrapper scripts) + MEMORY.md index lines;
ask-minimax-usage.md gains both delegation targets. Records the gac
v0.0.2.10 token-discovery gap (needs GITEA_TOKEN_FILE pointed at
ai_admin/token; the wrapper defaults it).
Claude-Session: https://claude.ai/code/session_01Ku87DDWwbJkTx6SuV3sQDc
Session log for the explore-minimax build; remove stale 2026-06-12
unpushed-commits block (all six repos verified in sync); FUTURE entry for
extending /explore-minimax to more modes and parallel sweeps.
Claude-Session: https://claude.ai/code/session_01Ku87DDWwbJkTx6SuV3sQDc
Add /explore-minimax and explore-minimax-run memory files, backfill
skill-ask-minimax / skill-ask-minimax-with-context entries, index them in
MEMORY.md. ask-minimax-usage.md gains the exploration use case and an
explicit no-secrets rule.
Claude-Session: https://claude.ai/code/session_01Ku87DDWwbJkTx6SuV3sQDc
set-topic.sh now renames the tmux session to the project part of the
topic and stores the full topic in @claude_topic when run inside tmux.
Pairs with ~/.tmux.conf status-right showing #{@claude_topic}.
Claude-Session: https://claude.ai/code/session_01Xt2b3uQtakYGhH5Y653vwd
Keys are often pre-loaded. Added explicit check-first guidance and
a note to use grep -i (case-insensitive) — a case-sensitive grep
will silently miss keys whose comments use different capitalisation.
Add a sentinel-file escape hatch: if `.claude/skip-plan-file-check`
exists in the project's cwd, the ExitPlanMode hook exits 0 without
demanding a local *-PLAN.md file.
Needed by projects (e.g. agent-runtimes) that manage plans via an
external system (work-items CP) rather than local repo files.
Correct two stale paths (octopus/customers/{duel-image,slb} -> octopus/{duel-image,slb})
and add 5 previously-untracked projects to distill scope: agent-runtimes-deploy,
cluster-apps/agent-runtimes, hugo-gabby-oreilly-counselling-content,
hugo-oreillyconsulting-integration, octopus/policy-demo.
- pre-compact-backup.sh: derive transcript path from session_id+cwd (no
longer relies on transcript_path field that Claude Code stopped providing);
register each backup in tracking.json after saving
- extract-transcripts.py: new script managing tracking.json — register,
list, extract conversation text, mark-processed modes
- list-transcripts-here.sh: thin wrapper for extract-transcripts --list
using $(pwd); needed because SKILL.md bang commands reject $() substitution
- install-hooks.sh: now also symlinks skill-helper scripts into
~/.claude/scripts/ via a curated SKILL_HELPERS list
- Memory docs: new script-extract-transcripts.md, script-list-transcripts-here.md;
updated skill-log.md, script-install-hooks.md, MEMORY.md index
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Skill documentation for the new plan/spec review skills. Each file
covers purpose, usage, how it works, referenced best practice files,
and gotchas.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Projects are now worked on from multiple machines and by container
agents, so local state can be behind the remote. Pull with --ff-only
on project entry and warn if it fails.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Remove all best-practices topic files and .distill-state.json from
claude-foundations. BESTPRACTICES.md now redirects to the standalone
repo at ~/dev/claude/projects/best-practices/. Remove the now-unnecessary
sync-best-practices.sh script.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Hard rule: any service with a FQDN, multiple consumers, or concurrent
access MUST use PostgreSQL from day one. Documents the cost of "we'll
migrate later" based on the Gitea SQLite→PostgreSQL migration that cost
nearly a full day of productivity.
Extracted from cluster-bootstrap gitea-scaling session (2026-03-28).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
No server-side credential may cross the server boundary to the client.
The only credentials that cross are the client's own identity (MFA, OIDC, etc.).
Covers: proxy + identity mapping pattern, defense in depth layers,
anti-patterns (browser tokens, shared service accounts, embedded keys),
presigned URL exception for direct uploads, CMS real-world example.
Extracted from hugo-accelerator M4 where this principle drove the
CMS proxy architecture (Authelia + per-user Gitea tokens server-side).
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Add statusline.sh and set-topic.sh for per-session status line topics
- Update context-load with improved directory walking and output format
- Update CLAUDE.md with status line docs and early-call safety note
- Update MEMORY.md and README.md with new script/skill entries
- Add memory files: script-statusline, skill-decompose, skill-orchestrate, gotchas-gitea
- Add networking.md best practice (nftables, systemd sockets, Docker forwarding, TLS)
- Update best practices from prior distill: documentation, kubernetes, scripting,
secrets-management, skills-development
- Prune reflected session logs, add new session logs
- Update reflection state
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
New files:
- PLATFORMHUB.md: index for Platform Hub guidance
- platformhub/architecture.md: Git→PlatformHub→Projects model
- platformhub/ocl-syntax.md: complete OCL reference for templates
- platformhub/process-template-patterns.md: 5 proven patterns
- platformhub/gotchas.md: every error hit and how to fix it
- platformhub/api-reference.md: API vs UI capabilities
- best-practices/octopus-process-templates.md: consolidated best practices
Learned from building PlatformHub-Demo (30 microservices, 3 clouds).
Key discoveries: step templates are space-scoped (can't cross-reference),
worker_pool parameter is mandatory, publishing/sharing is UI-only.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Pattern for matching container user UID/GID to mounted volume owner
via a gosu-based entrypoint wrapper. Covers UID conflicts (Ubuntu 24.04
ships ubuntu:1000), K8s securityContext compatibility, and alternatives.
Learned from agent-runtimes M1 where Claude Code refuses
--dangerously-skip-permissions as root.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Add "Spec-Driven Development" section to global CLAUDE.md:
- Specs must exist before code for any multi-milestone coding project
- Always read SDD and TDD best practices at project start
- SPEC.md index + spec/ directory with numbered requirements
- Tests must reference spec requirement IDs
- Workflow: Plan → Spec → Test → Code
Also update "New Projects" section to reference the SDD requirement.
Prompted by customer-discovery project where we jumped from plan
straight to code, missing the spec step entirely.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Documents the /housekeeping skill: purpose, usage, how it works,
and which scripts it orchestrates.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
