diff --git a/.claude/skills/_ctx-release-notes/SKILL.md b/.claude/skills/_ctx-release-notes/SKILL.md index 193b034b9..e586dc835 100644 --- a/.claude/skills/_ctx-release-notes/SKILL.md +++ b/.claude/skills/_ctx-release-notes/SKILL.md @@ -27,7 +27,9 @@ Generate release notes for the next release of Context CLI. 1. **Read version and find baseline**: ```bash cat VERSION -git describe --tags --abbrev=0 2>/dev/null +# Use the latest tag globally, not ancestry-based git describe +# (git describe follows reachability and misses tags on other branches) +git tag --sort=-v:refname | head -1 ``` 2. **Gather commits since last tag** (filter out noise): diff --git a/.claude/skills/_ctx-release/SKILL.md b/.claude/skills/_ctx-release/SKILL.md index 7e227f9f6..404468a72 100644 --- a/.claude/skills/_ctx-release/SKILL.md +++ b/.claude/skills/_ctx-release/SKILL.md @@ -13,8 +13,8 @@ All three prerequisites must be true: 2. **`dist/RELEASE_NOTES.md`** exists (generate with `/_ctx-release-notes`) 3. **Working tree is clean** (all changes committed) -If any prerequisite fails, stop — running the release script with -missing notes or a dirty tree can produce an incomplete or unsigned +If any prerequisite fails, stop. Running the release script with +missing notes or a dirty tree produces an incomplete or unsigned tag that must be manually deleted. ## When to Use @@ -42,17 +42,23 @@ make release ``` This script: -- Updates version references in `docs/index.md` +- Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock) +- Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md) +- Adds new row to versions.md - Rebuilds the documentation site -- Commits the docs update +- Commits the version and docs update - Runs tests and smoke tests -- Builds binaries for all platforms +- Builds binaries for all 6 platforms - Creates and pushes a signed git tag - Updates the `latest` tag -3. **After completion**, tell the user to create the GitHub release - at the URL shown in the script output and upload binaries from - `dist/`. +3. **After completion**, verify the GitHub release was created by CI + at `https://github.com/ActiveMemory/ctx/releases`. + +## Full Runbook + +See [Cutting a Release](https://ctx.ist/operations/release/) for the +complete step-by-step guide including troubleshooting. ## Quality Checklist @@ -61,4 +67,4 @@ This script: - [ ] Working tree is clean - [ ] Tests and smoke tests pass - [ ] Tag is pushed to origin -- [ ] User reminded to create GitHub release +- [ ] GitHub release created by CI with all 6 binaries diff --git a/.context/DECISIONS.md b/.context/DECISIONS.md index aa5a1f6bb..90aca4797 100644 --- a/.context/DECISIONS.md +++ b/.context/DECISIONS.md @@ -3,6 +3,7 @@ | Date | Decision | |------|--------| +| 2026-03-23 | Pre/pre HTML tags promoted to shared constants in config/marker | | 2026-03-23 | Pure-data param structs in entity — replace function pointers with text keys | | 2026-03-22 | No runtime pluralization — use singular/plural text key pairs | | 2026-03-22 | Output functions belong in write/, never in core/ or cmd/ | @@ -62,6 +63,20 @@ | 2026-02-27 | Webhook and notification design (consolidated) | +## [2026-03-23-165612] Pre/pre HTML tags promoted to shared constants in config/marker + +**Status**: Accepted + +**Context**: Two packages (normalize and format) used hardcoded pre strings independently + +**Decision**: Pre/pre HTML tags promoted to shared constants in config/marker + +**Rationale**: Cross-package magic strings belong in config constants per CONVENTIONS.md + +**Consequence**: marker.TagPre and marker.TagPreClose are the canonical references; package-local constants deleted + +--- + ## [2026-03-23-003346] Pure-data param structs in entity — replace function pointers with text keys **Status**: Accepted diff --git a/.context/LEARNINGS.md b/.context/LEARNINGS.md index 79900dace..ad70bc894 100644 --- a/.context/LEARNINGS.md +++ b/.context/LEARNINGS.md @@ -3,6 +3,8 @@ | Date | Learning | |------|--------| +| 2026-03-23 | Typography detection script needs exclusion lists for intentional uses | +| 2026-03-23 | Subagents rename functions and restructure code beyond their scope | | 2026-03-23 | Splitting core/ into subpackages reveals hidden structure | | 2026-03-23 | Higher-order callbacks in param structs are a code smell | | 2026-03-22 | Types in god-object files create circular dependencies | @@ -91,6 +93,26 @@ --- +## [2026-03-23-165611] Typography detection script needs exclusion lists for intentional uses + +**Context**: detect-ai-typography.sh flagged config/token/delim.go (intentional delimiter constants) and test files (test data containing em-dashes) + +**Lesson**: Detection scripts for convention enforcement need exclusion patterns for files where the flagged patterns are intentional data, not prose + +**Application**: Add exclusion patterns proactively when creating detection scripts; *_test.go and constant-definition files are common false positive sources + +--- + +## [2026-03-23-165610] Subagents rename functions and restructure code beyond their scope + +**Context**: Agents tasked with fixing em-dashes in comments also renamed exported functions, changed import aliases, and modified function signatures + +**Lesson**: Always diff-audit agent output for structural changes before accepting edits, even when the task is narrowly scoped + +**Application**: After any agent batch edit, run git diff --stat and scan for non-comment changes before staging + +--- + ## [2026-03-23-003544] Splitting core/ into subpackages reveals hidden structure **Context**: init core/ was a flat bag of domain objects — splitting into backup/, claude/, entry/, merge/, plan/, plugin/, project/, prompt/, tpl/, validate/ exposed duplicated logic, misplaced types, and function-pointer smuggling that were invisible in the flat layout diff --git a/.context/TASKS.md b/.context/TASKS.md index 2e76538bb..10e20e9ed 100644 --- a/.context/TASKS.md +++ b/.context/TASKS.md @@ -41,6 +41,8 @@ checks field presence, not content safety. - [ ] Make TitleSlugMaxLen configurable via .ctxrc #added:2026-03-21-070944 +- [ ] Replace hack/lint-drift.sh with AST-based Go tests in internal/audit/. Spec: `specs/ast-audit-tests.md` #added:2026-03-23-210000 + - [ ] Add AST-based lint test to detect exported functions with no external callers #added:2026-03-21-070357 - [ ] Audit exported functions used only within their own package and make them private #added:2026-03-21-070346 diff --git a/.context/scratchpad.enc b/.context/scratchpad.enc index d6ba937ff..1e5bb130e 100644 Binary files a/.context/scratchpad.enc and b/.context/scratchpad.enc differ diff --git a/CONTRIBUTING-SKILLS.md b/CONTRIBUTING-SKILLS.md index 129a34b3a..1f49586ed 100644 --- a/CONTRIBUTING-SKILLS.md +++ b/CONTRIBUTING-SKILLS.md @@ -6,7 +6,7 @@ session. This page is for contributors who want to understand what each skill does without reading individual `SKILL.md` files. For ctx plugin skills (`/ctx-status`, `/ctx-recall`, etc.), see the -[ctx skills documentation](docs/skills.md). +[ctx skills documentation](docs/reference/skills.md). ## Skill Catalog diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f22ebc802..574a8959d 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -4,7 +4,7 @@ Thank you for your interest in contributing to `ctx`. -**Full contributing guide**: https://ctx.ist/contributing/ +**Full contributing guide**: https://ctx.ist/home/contributing/ The guide covers: diff --git a/docs/cli/tools.md b/docs/cli/tools.md index f4fd3f790..9c541c1f6 100644 --- a/docs/cli/tools.md +++ b/docs/cli/tools.md @@ -821,7 +821,7 @@ ctx prompt rm - `name`: Template name (without `.md` extension) -**See also**: [Prompt Templates](../recipes/prompts.md) +**See also**: [Prompt Templates](../recipes/prompt-templates.md) --- diff --git a/docs/home/about.md b/docs/home/about.md index 059bc7f63..44b21e31d 100644 --- a/docs/home/about.md +++ b/docs/home/about.md @@ -135,7 +135,7 @@ makes the *next* session **smarter**. **Connect with `ctx`** * [Join the Community →](community.md): ask questions, share workflows, and help shape what comes next -* [Read the Blog →](../../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx` +* [Read the Blog →](../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx` ---- diff --git a/docs/home/contributing.md b/docs/home/contributing.md index 2fe46d771..878276462 100644 --- a/docs/home/contributing.md +++ b/docs/home/contributing.md @@ -120,7 +120,7 @@ ctx/ | Directory | What lives here | Distributed to users? | |----------------------------------|-------------------------------------------------|-----------------------| -| `internal/assets/claude/skills/` | The 29 `ctx-*` skills that ship with the plugin | Yes | +| `internal/assets/claude/skills/` | The 39 `ctx-*` skills that ship with the plugin | Yes | | `.claude/skills/` | Dev-only skills (release, QA, backup, etc.) | No | **`internal/assets/claude/skills/`** is the single source of truth for @@ -164,7 +164,7 @@ and are now available to all ctx users: `/ctx-brainstorm`, `/ctx-check-links`, 6. Add a section to the appropriate CLI doc page in `docs/cli/`. Pattern to follow: `internal/cli/pad/pad.go` (parent with subcommands) or -`internal/cli/complete/complete.go` (single command). +`internal/cli/drift/drift.go` (single command). ### Adding a New Session Parser diff --git a/docs/operations/index.md b/docs/operations/index.md index 950fbca8b..90e5c7088 100644 --- a/docs/operations/index.md +++ b/docs/operations/index.md @@ -31,6 +31,13 @@ Windsurf, and other AI coding tools. --- +### [Cutting a Release](release.md) + +Step-by-step runbook for maintainers: bump version, generate +release notes, run the release script, and verify the result. + +--- + ### [Autonomous Loops](autonomous-loop.md) Run an unattended AI agent that works through tasks overnight, diff --git a/docs/operations/release.md b/docs/operations/release.md new file mode 100644 index 000000000..bae4496ce --- /dev/null +++ b/docs/operations/release.md @@ -0,0 +1,178 @@ +--- +# / ctx: https://ctx.ist +# ,'`./ do you remember? +# `.,'\ +# \ Copyright 2026-present Context contributors. +# SPDX-License-Identifier: Apache-2.0 + +title: Cutting a Release +icon: lucide/package +--- + +![ctx](../images/ctx-banner.png) + +## Prerequisites + +Before you can cut a release you need: + +* Push access to `origin` (GitHub) +* GPG signing configured (`make gpg-test`) +* [Go](https://go.dev/) installed (version in `go.mod`) +* [Zensical](https://github.com/zensical/zensical) installed (`make site-setup`) +* A clean working tree (`git status` shows nothing to commit) + +--- + +## Step-by-Step + +### 1. Update the VERSION File + +```bash +echo "0.9.0" > VERSION +git add VERSION +git commit -m "chore: bump version to 0.9.0" +``` + +The VERSION file uses bare semver (`0.9.0`), no `v` prefix. +The release script adds the `v` prefix for git tags. + +### 2. Generate Release Notes + +In Claude Code: + +``` +/_ctx-release-notes +``` + +This analyzes commits since the last tag and writes +`dist/RELEASE_NOTES.md`. The release script refuses to +proceed without this file. + +### 3. Commit Any Remaining Changes + +```bash +git status # must be clean +make audit # full check: fmt, vet, lint, test +``` + +### 4. Run the Release + +```bash +make release +``` + +Or, if you are in a Claude Code session: + +``` +/_ctx-release +``` + +The release script does everything in order: + +| Step | What happens | +|------|-------------| +| 1 | Reads `VERSION`, verifies release notes exist | +| 2 | Verifies working tree is clean | +| 3 | Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock) | +| 4 | Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md) | +| 5 | Adds new row to versions.md | +| 6 | Rebuilds the documentation site (`make site`) | +| 7 | Commits all version and docs updates | +| 8 | Runs `make test` and `make smoke` | +| 9 | Builds binaries for all 6 platforms via `hack/build-all.sh` | +| 10 | Creates a signed git tag (`v0.9.0`) | +| 11 | Pushes the tag to origin | +| 12 | Updates and pushes the `latest` tag | + +### 5. GitHub CI Takes Over + +Pushing a `v*` tag triggers `.github/workflows/release.yml`: + +1. Checks out the tagged commit +2. Runs the full test suite +3. Builds binaries for all platforms +4. Creates a GitHub Release with auto-generated notes +5. Uploads binaries and SHA256 checksums + +### 6. Verify + +- [ ] [GitHub Releases](https://github.com/ActiveMemory/ctx/releases) shows the new version +- [ ] All 6 binaries are attached (linux/darwin x amd64/arm64, windows x amd64) +- [ ] SHA256 files are attached +- [ ] Release notes look correct + +--- + +## What Gets Updated Automatically + +The release script updates 8 files so you do not have to: + +| File | What changes | +|------|-------------| +| `internal/assets/claude/.claude-plugin/plugin.json` | Plugin version | +| `.claude-plugin/marketplace.json` | Marketplace version (2 fields) | +| `editors/vscode/package.json` | VS Code extension version | +| `editors/vscode/package-lock.json` | VS Code lock version (2 fields) | +| `docs/index.md` | Download URLs | +| `docs/home/getting-started.md` | Download URLs | +| `docs/operations/integrations.md` | VSIX filename version | +| `docs/reference/versions.md` | New version row + latest pointer | + +The Go binary version is injected at build time via `-ldflags` +from the VERSION file. No source file needs editing. + +--- + +## Build Targets Reference + +| Target | What it does | +|--------|-------------| +| `make release` | Full release (script + tag + push) | +| `make build` | Build binary for current platform | +| `make build-all` | Build all 6 platform binaries | +| `make test` | Unit tests | +| `make smoke` | Integration smoke tests | +| `make audit` | Full check (fmt + vet + lint + drift + docs + test) | +| `make site` | Rebuild documentation site | + +--- + +## Troubleshooting + +### "Release notes not found" + +``` +ERROR: dist/RELEASE_NOTES.md not found. +``` + +Run `/_ctx-release-notes` in Claude Code first, or write +`dist/RELEASE_NOTES.md` manually. + +### "Working tree is not clean" + +``` +ERROR: Working tree is not clean. +``` + +Commit or stash all changes before running `make release`. + +### "Tag already exists" + +``` +ERROR: Tag v0.9.0 already exists. +``` + +You cannot release the same version twice. Either bump VERSION +to a new version, or delete the old tag if the release was +incomplete: + +```bash +git tag -d v0.9.0 +git push origin :refs/tags/v0.9.0 +``` + +### CI build fails after tag push + +The tag is already published. Fix the issue, bump to a patch +version (e.g. `0.9.1`), and release again. Do not force-push +tags that others may have already fetched. diff --git a/editors/vscode/package.json b/editors/vscode/package.json index d8e3656a1..5457ed034 100644 --- a/editors/vscode/package.json +++ b/editors/vscode/package.json @@ -2,7 +2,7 @@ "name": "ctx-context", "displayName": "ctx — Persistent Context for AI", "description": "Chat participant (@ctx) for persistent project context across AI coding sessions", - "version": "0.7.0", + "version": "0.8.0", "publisher": "activememory", "license": "Apache-2.0", "homepage": "https://github.com/ActiveMemory/ctx", @@ -86,17 +86,13 @@ "description": "Reconcile context with codebase" }, { - "name": "complete", - "description": "Mark a task as completed" + "name": "task", + "description": "Task operations: complete, archive, snapshot" }, { "name": "remind", "description": "Manage session-scoped reminders" }, - { - "name": "tasks", - "description": "Archive or snapshot tasks" - }, { "name": "pad", "description": "Encrypted scratchpad for sensitive notes" @@ -108,6 +104,66 @@ { "name": "system", "description": "System diagnostics and bootstrap" + }, + { + "name": "memory", + "description": "Memory bridge operations (sync, status, diff, import, publish)" + }, + { + "name": "journal", + "description": "Journal management (site, obsidian)" + }, + { + "name": "doctor", + "description": "Context health diagnostics" + }, + { + "name": "config", + "description": "Runtime configuration (switch, status, schema)" + }, + { + "name": "prompt", + "description": "Prompt templates (list, add, show, rm)" + }, + { + "name": "why", + "description": "Show rationale for context design decisions" + }, + { + "name": "change", + "description": "Show recent codebase changes" + }, + { + "name": "dep", + "description": "Show project dependencies" + }, + { + "name": "guide", + "description": "Quick start guide" + }, + { + "name": "permission", + "description": "Permission snapshot and restore" + }, + { + "name": "site", + "description": "Documentation site (feed)" + }, + { + "name": "loop", + "description": "Generate autonomous iteration scripts" + }, + { + "name": "pause", + "description": "Pause context hooks for current session" + }, + { + "name": "resume", + "description": "Resume context hooks" + }, + { + "name": "reindex", + "description": "Rebuild context file indices" } ], "disambiguation": [ diff --git a/editors/vscode/src/extension.ts b/editors/vscode/src/extension.ts index 99391619f..87feb6f6e 100644 --- a/editors/vscode/src/extension.ts +++ b/editors/vscode/src/extension.ts @@ -584,40 +584,82 @@ async function handleSync( return { metadata: { command: "sync" } }; } -async function handleComplete( +async function handleTask( stream: vscode.ChatResponseStream, prompt: string, cwd: string, token: vscode.CancellationToken ): Promise { - const taskRef = prompt.trim(); - if (!taskRef) { - stream.markdown( - "**Usage:** `@ctx /complete `\n\n" + - "Example: `@ctx /complete 3` or `@ctx /complete Fix login bug`" - ); - return { metadata: { command: "complete" } }; + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + const rest = parts.slice(1).join(" "); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "complete": { + const taskRef = rest.trim(); + if (!taskRef) { + stream.markdown( + "**Usage:** `@ctx /task complete `\n\n" + + "Example: `@ctx /task complete 3` or " + + "`@ctx /task complete Fix login bug`" + ); + return { metadata: { command: "task" } }; + } + args = ["task", "complete", taskRef]; + progressMsg = "Marking task as completed..."; + break; + } + case "archive": + args = ["task", "archive"]; + progressMsg = "Archiving completed tasks..."; + break; + case "snapshot": + args = rest ? ["task", "snapshot", rest] : ["task", "snapshot"]; + progressMsg = "Creating task snapshot..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /task `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `complete ` | Mark a task as completed |\n" + + "| `archive` | Move completed tasks to archive |\n" + + "| `snapshot [name]` | Create point-in-time snapshot |\n\n" + + "Example: `@ctx /task complete 3` or " + + "`@ctx /task archive`" + ); + return { metadata: { command: "task" } }; } + args.push("--no-color"); - stream.progress("Marking task as completed..."); + stream.progress(progressMsg); try { - const { stdout, stderr } = await runCtx( - ["complete", taskRef, "--no-color"], - cwd, - token - ); + const { stdout, stderr } = await runCtx(args, cwd, token); const output = (stdout + stderr).trim(); if (output) { stream.markdown("```\n" + output + "\n```"); } else { - stream.markdown(`Task **${taskRef}** marked as completed.`); + switch (subcmd) { + case "complete": + stream.markdown(`Task **${rest.trim()}** marked as completed.`); + break; + case "archive": + stream.markdown("Completed tasks archived."); + break; + default: + stream.markdown("Task snapshot created."); + break; + } } } catch (err: unknown) { stream.markdown( - `**Error:** Failed to complete task.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + `**Error:** Failed to ${subcmd} task.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` ); } - return { metadata: { command: "complete" } }; + return { metadata: { command: "task" } }; } async function handleRemind( @@ -678,62 +720,6 @@ async function handleRemind( return { metadata: { command: "remind" } }; } -async function handleTasks( - stream: vscode.ChatResponseStream, - prompt: string, - cwd: string, - token: vscode.CancellationToken -): Promise { - const parts = prompt.trim().split(/\s+/); - const subcmd = parts[0]?.toLowerCase(); - const rest = parts.slice(1).join(" "); - - let args: string[]; - let progressMsg: string; - - switch (subcmd) { - case "archive": - args = ["tasks", "archive"]; - progressMsg = "Archiving completed tasks..."; - break; - case "snapshot": - args = rest ? ["tasks", "snapshot", rest] : ["tasks", "snapshot"]; - progressMsg = "Creating task snapshot..."; - break; - default: - stream.markdown( - "**Usage:** `@ctx /tasks `\n\n" + - "| Subcommand | Description |\n" + - "|------------|-------------|\n" + - "| `archive` | Move completed tasks to archive |\n" + - "| `snapshot [name]` | Create point-in-time snapshot |\n\n" + - "Example: `@ctx /tasks archive` or `@ctx /tasks snapshot pre-refactor`" - ); - return { metadata: { command: "tasks" } }; - } - args.push("--no-color"); - - stream.progress(progressMsg); - try { - const { stdout, stderr } = await runCtx(args, cwd, token); - const output = (stdout + stderr).trim(); - if (output) { - stream.markdown("```\n" + output + "\n```"); - } else { - stream.markdown( - subcmd === "archive" - ? "Completed tasks archived." - : "Task snapshot created." - ); - } - } catch (err: unknown) { - stream.markdown( - `**Error:** Failed to ${subcmd} tasks.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` - ); - } - return { metadata: { command: "tasks" } }; -} - async function handlePad( stream: vscode.ChatResponseStream, prompt: string, @@ -813,7 +799,6 @@ async function handleNotify( ): Promise { const parts = prompt.trim().split(/\s+/); const subcmd = parts[0]?.toLowerCase(); - const rest = parts.slice(1).join(" "); let args: string[]; let progressMsg: string; @@ -903,7 +888,7 @@ async function handleSystem( "|------------|-------------|\n" + "| `resources` | Show system resource usage |\n" + "| `bootstrap` | Print context location for AI agents |\n" + - "| `message list\|show\|edit\|reset` | Manage hook messages |\n\n" + + "| `message list|show|edit|reset` | Manage hook messages |\n\n" + "Example: `@ctx /system resources` or `@ctx /system bootstrap`" ); return { metadata: { command: "system" } }; @@ -927,6 +912,553 @@ async function handleSystem( return { metadata: { command: "system" } }; } +async function handleMemory( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "sync": + args = ["memory", "sync"]; + progressMsg = "Syncing memory bridge..."; + break; + case "status": + args = ["memory", "status"]; + progressMsg = "Checking memory status..."; + break; + case "diff": + args = ["memory", "diff"]; + progressMsg = "Diffing memory state..."; + break; + case "import": + args = ["memory", "import"]; + progressMsg = "Importing memory..."; + break; + case "publish": + args = ["memory", "publish"]; + progressMsg = "Publishing memory..."; + break; + case "unpublish": + args = ["memory", "unpublish"]; + progressMsg = "Unpublishing memory..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /memory `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `sync` | Synchronize memory bridge |\n" + + "| `status` | Show memory bridge status |\n" + + "| `diff` | Show memory diff |\n" + + "| `import` | Import external memory |\n" + + "| `publish` | Publish curated context |\n" + + "| `unpublish` | Remove published context |\n\n" + + "Example: `@ctx /memory status` or `@ctx /memory sync`" + ); + return { metadata: { command: "memory" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Memory ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run memory ${subcmd}.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "memory" } }; +} + +async function handleJournal( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "site": + args = ["journal", "site"]; + progressMsg = "Generating journal site..."; + break; + case "obsidian": + args = ["journal", "obsidian"]; + progressMsg = "Exporting journal to Obsidian..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /journal `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `site` | Generate journal site |\n" + + "| `obsidian` | Export journal to Obsidian |\n\n" + + "Example: `@ctx /journal site`" + ); + return { metadata: { command: "journal" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Journal ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run journal ${subcmd}.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "journal" } }; +} + +async function handleDoctor( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Running context health diagnostics..."); + try { + const { stdout, stderr } = await runCtx(["doctor", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("Context health check passed."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run doctor.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "doctor" } }; +} + +async function handleConfig( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + const rest = parts.slice(1).join(" "); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "switch": + args = rest ? ["config", "switch", rest] : ["config", "switch"]; + progressMsg = "Switching configuration..."; + break; + case "status": + args = ["config", "status"]; + progressMsg = "Checking configuration status..."; + break; + case "schema": + args = ["config", "schema"]; + progressMsg = "Showing configuration schema..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /config `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `switch` | Switch active configuration |\n" + + "| `status` | Show current configuration |\n" + + "| `schema` | Show configuration schema |\n\n" + + "Example: `@ctx /config status` or `@ctx /config switch minimal`" + ); + return { metadata: { command: "config" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Config ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run config ${subcmd}.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "config" } }; +} + +async function handlePrompt( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + const rest = parts.slice(1).join(" "); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "list": + case "ls": + args = ["prompt", "list"]; + progressMsg = "Listing prompt templates..."; + break; + case "add": + args = rest ? ["prompt", "add", rest] : ["prompt", "add"]; + progressMsg = "Adding prompt template..."; + break; + case "show": + args = rest ? ["prompt", "show", rest] : ["prompt", "show"]; + progressMsg = "Showing prompt template..."; + break; + case "rm": + args = rest ? ["prompt", "rm", rest] : ["prompt", "rm"]; + progressMsg = "Removing prompt template..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /prompt `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `list` | List prompt templates |\n" + + "| `add ` | Add a prompt template |\n" + + "| `show ` | Show a prompt template |\n" + + "| `rm ` | Remove a prompt template |\n\n" + + "Example: `@ctx /prompt list` or `@ctx /prompt show review`" + ); + return { metadata: { command: "prompt" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Prompt ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run prompt ${subcmd}.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "prompt" } }; +} + +async function handleWhy( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const filename = prompt.trim(); + const args = filename ? ["why", filename] : ["why"]; + args.push("--no-color"); + + stream.progress("Looking up design rationale..."); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("No rationale found."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to look up rationale.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "why" } }; +} + +async function handleChange( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Checking recent codebase changes..."); + try { + const { stdout, stderr } = await runCtx(["change", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("No recent changes found."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to check changes.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "change" } }; +} + +async function handleDep( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Checking project dependencies..."); + try { + const { stdout, stderr } = await runCtx(["dep", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("No dependencies found."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to check dependencies.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "dep" } }; +} + +async function handleGuide( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Loading quick start guide..."); + try { + const { stdout, stderr } = await runCtx(["guide", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown(output); + } else { + stream.markdown("No guide content available."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to load guide.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "guide" } }; +} + +async function handlePermission( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "snapshot": + args = ["permission", "snapshot"]; + progressMsg = "Taking permission snapshot..."; + break; + case "restore": + args = ["permission", "restore"]; + progressMsg = "Restoring permissions..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /permission `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `snapshot` | Capture current file permissions |\n" + + "| `restore` | Restore saved permissions |\n\n" + + "Example: `@ctx /permission snapshot`" + ); + return { metadata: { command: "permission" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Permission ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to ${subcmd} permissions.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "permission" } }; +} + +async function handleSite( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const parts = prompt.trim().split(/\s+/); + const subcmd = parts[0]?.toLowerCase(); + + let args: string[]; + let progressMsg: string; + + switch (subcmd) { + case "feed": + args = ["site", "feed"]; + progressMsg = "Generating site feed..."; + break; + default: + stream.markdown( + "**Usage:** `@ctx /site `\n\n" + + "| Subcommand | Description |\n" + + "|------------|-------------|\n" + + "| `feed` | Generate documentation site feed |\n\n" + + "Example: `@ctx /site feed`" + ); + return { metadata: { command: "site" } }; + } + args.push("--no-color"); + + stream.progress(progressMsg); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown(`Site ${subcmd} completed.`); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to run site ${subcmd}.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "site" } }; +} + +async function handleLoop( + stream: vscode.ChatResponseStream, + prompt: string, + cwd: string, + token: vscode.CancellationToken +): Promise { + const toolName = prompt.trim(); + const args = toolName ? ["loop", toolName] : ["loop"]; + args.push("--no-color"); + + stream.progress("Generating iteration script..."); + try { + const { stdout, stderr } = await runCtx(args, cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("No loop script generated."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to generate loop script.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "loop" } }; +} + +async function handlePause( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Pausing context hooks..."); + try { + const { stdout, stderr } = await runCtx(["pause", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("Context hooks paused for this session."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to pause hooks.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "pause" } }; +} + +async function handleResume( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Resuming context hooks..."); + try { + const { stdout, stderr } = await runCtx(["resume", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("Context hooks resumed."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to resume hooks.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "resume" } }; +} + +async function handleReindex( + stream: vscode.ChatResponseStream, + cwd: string, + token: vscode.CancellationToken +): Promise { + stream.progress("Rebuilding context file indices..."); + try { + const { stdout, stderr } = await runCtx(["reindex", "--no-color"], cwd, token); + const output = (stdout + stderr).trim(); + if (output) { + stream.markdown("```\n" + output + "\n```"); + } else { + stream.markdown("Context indices rebuilt."); + } + } catch (err: unknown) { + stream.markdown( + `**Error:** Failed to reindex.\n\n\`\`\`\n${err instanceof Error ? err.message : String(err)}\n\`\`\`` + ); + } + return { metadata: { command: "reindex" } }; +} + async function handleFreeform( request: vscode.ChatRequest, stream: vscode.ChatResponseStream, @@ -949,13 +1481,13 @@ async function handleFreeform( return handleRecall(stream, request.prompt, cwd, token); } if (prompt.includes("complete") || prompt.includes("done") || prompt.includes("finish")) { - return handleComplete(stream, request.prompt, cwd, token); + return handleTask(stream, "complete " + request.prompt, cwd, token); } if (prompt.includes("remind")) { return handleRemind(stream, request.prompt, cwd, token); } if (prompt.includes("task")) { - return handleTasks(stream, request.prompt, cwd, token); + return handleTask(stream, request.prompt, cwd, token); } if (prompt.includes("pad") || prompt.includes("scratchpad") || prompt.includes("scratch")) { return handlePad(stream, request.prompt, cwd, token); @@ -966,10 +1498,55 @@ async function handleFreeform( if (prompt.includes("system") || prompt.includes("resource") || prompt.includes("bootstrap")) { return handleSystem(stream, request.prompt, cwd, token); } + if (prompt.includes("memory")) { + return handleMemory(stream, request.prompt, cwd, token); + } + if (prompt.includes("journal")) { + return handleJournal(stream, request.prompt, cwd, token); + } + if (prompt.includes("doctor") || prompt.includes("health")) { + return handleDoctor(stream, cwd, token); + } + if (prompt.includes("config") || prompt.includes("configuration")) { + return handleConfig(stream, request.prompt, cwd, token); + } + if (prompt.includes("prompt") || prompt.includes("template")) { + return handlePrompt(stream, request.prompt, cwd, token); + } + if (prompt.includes("why") || prompt.includes("rationale")) { + return handleWhy(stream, request.prompt, cwd, token); + } + if (prompt.includes("change") || prompt.includes("recent")) { + return handleChange(stream, cwd, token); + } + if (prompt.includes("dep") || prompt.includes("dependenc")) { + return handleDep(stream, cwd, token); + } + if (prompt.includes("guide") || prompt.includes("quickstart") || prompt.includes("getting started")) { + return handleGuide(stream, cwd, token); + } + if (prompt.includes("permission")) { + return handlePermission(stream, request.prompt, cwd, token); + } + if (prompt.includes("site") || prompt.includes("feed")) { + return handleSite(stream, request.prompt, cwd, token); + } + if (prompt.includes("loop") || prompt.includes("iterate")) { + return handleLoop(stream, request.prompt, cwd, token); + } + if (prompt.includes("pause")) { + return handlePause(stream, cwd, token); + } + if (prompt.includes("resume")) { + return handleResume(stream, cwd, token); + } + if (prompt.includes("reindex") || prompt.includes("rebuild")) { + return handleReindex(stream, cwd, token); + } // Default: show help with available commands stream.markdown( - "## ctx — Persistent Context for AI\n\n" + + "## ctx -- Persistent Context for AI\n\n" + "Available commands:\n\n" + "| Command | Description |\n" + "|---------|-------------|\n" + @@ -983,12 +1560,26 @@ async function handleFreeform( "| `/load` | Output assembled context |\n" + "| `/compact` | Archive completed tasks |\n" + "| `/sync` | Reconcile context with codebase |\n" + - "| `/complete` | Mark a task as completed |\n" + + "| `/task` | Task operations (complete, archive, snapshot) |\n" + "| `/remind` | Manage session reminders |\n" + - "| `/tasks` | Archive or snapshot tasks |\n" + "| `/pad` | Encrypted scratchpad |\n" + "| `/notify` | Webhook notifications |\n" + - "| `/system` | System diagnostics |\n\n" + + "| `/system` | System diagnostics |\n" + + "| `/memory` | Memory bridge operations |\n" + + "| `/journal` | Journal management |\n" + + "| `/doctor` | Context health diagnostics |\n" + + "| `/config` | Runtime configuration |\n" + + "| `/prompt` | Prompt templates |\n" + + "| `/why` | Design rationale for context files |\n" + + "| `/change` | Recent codebase changes |\n" + + "| `/dep` | Project dependencies |\n" + + "| `/guide` | Quick start guide |\n" + + "| `/permission` | Permission snapshot/restore |\n" + + "| `/site` | Documentation site |\n" + + "| `/loop` | Generate iteration scripts |\n" + + "| `/pause` | Pause context hooks |\n" + + "| `/resume` | Resume context hooks |\n" + + "| `/reindex` | Rebuild context indices |\n\n" + "Example: `@ctx /status` or `@ctx /add task Fix login bug`" ); return { metadata: { command: "help" } }; @@ -1043,18 +1634,46 @@ const handler: vscode.ChatRequestHandler = async ( return handleCompact(stream, cwd, token); case "sync": return handleSync(stream, cwd, token); - case "complete": - return handleComplete(stream, request.prompt, cwd, token); + case "task": + return handleTask(stream, request.prompt, cwd, token); case "remind": return handleRemind(stream, request.prompt, cwd, token); - case "tasks": - return handleTasks(stream, request.prompt, cwd, token); case "pad": return handlePad(stream, request.prompt, cwd, token); case "notify": return handleNotify(stream, request.prompt, cwd, token); case "system": return handleSystem(stream, request.prompt, cwd, token); + case "memory": + return handleMemory(stream, request.prompt, cwd, token); + case "journal": + return handleJournal(stream, request.prompt, cwd, token); + case "doctor": + return handleDoctor(stream, cwd, token); + case "config": + return handleConfig(stream, request.prompt, cwd, token); + case "prompt": + return handlePrompt(stream, request.prompt, cwd, token); + case "why": + return handleWhy(stream, request.prompt, cwd, token); + case "change": + return handleChange(stream, cwd, token); + case "dep": + return handleDep(stream, cwd, token); + case "guide": + return handleGuide(stream, cwd, token); + case "permission": + return handlePermission(stream, request.prompt, cwd, token); + case "site": + return handleSite(stream, request.prompt, cwd, token); + case "loop": + return handleLoop(stream, request.prompt, cwd, token); + case "pause": + return handlePause(stream, cwd, token); + case "resume": + return handleResume(stream, cwd, token); + case "reindex": + return handleReindex(stream, cwd, token); default: return handleFreeform(request, stream, cwd, token); } @@ -1099,7 +1718,8 @@ export function activate(extensionContext: vscode.ExtensionContext) { case "status": followups.push( { prompt: "Detect context drift", command: "drift" }, - { prompt: "Load full context", command: "load" } + { prompt: "Load full context", command: "load" }, + { prompt: "Run health check", command: "doctor" } ); break; case "drift": @@ -1108,10 +1728,10 @@ export function activate(extensionContext: vscode.ExtensionContext) { { prompt: "Show context status", command: "status" } ); break; - case "complete": + case "task": followups.push( { prompt: "Show context status", command: "status" }, - { prompt: "Archive completed tasks", command: "tasks" } + { prompt: "Compact context", command: "compact" } ); break; case "remind": @@ -1119,21 +1739,48 @@ export function activate(extensionContext: vscode.ExtensionContext) { { prompt: "Show context status", command: "status" } ); break; - case "tasks": + case "pad": + followups.push( + { prompt: "List scratchpad", command: "pad" } + ); + break; + case "memory": + followups.push( + { prompt: "Check memory status", command: "memory" }, + { prompt: "Show context status", command: "status" } + ); + break; + case "doctor": followups.push( { prompt: "Show context status", command: "status" }, - { prompt: "Compact context", command: "compact" } + { prompt: "Detect drift", command: "drift" } ); break; - case "pad": + case "config": followups.push( - { prompt: "List scratchpad", command: "pad" } + { prompt: "Show config status", command: "config" } + ); + break; + case "change": + followups.push( + { prompt: "Show context status", command: "status" } + ); + break; + case "pause": + followups.push( + { prompt: "Resume hooks", command: "resume" } + ); + break; + case "resume": + followups.push( + { prompt: "Show context status", command: "status" } ); break; case "help": followups.push( { prompt: "Initialize project context", command: "init" }, - { prompt: "Show context status", command: "status" } + { prompt: "Show context status", command: "status" }, + { prompt: "Quick start guide", command: "guide" } ); break; } @@ -1152,12 +1799,26 @@ export { ensureCtxAvailable, bootstrap, getPlatformInfo, - handleComplete, + handleTask, handleRemind, - handleTasks, handlePad, handleNotify, handleSystem, + handleMemory, + handleJournal, + handleDoctor, + handleConfig, + handlePrompt, + handleWhy, + handleChange, + handleDep, + handleGuide, + handlePermission, + handleSite, + handleLoop, + handlePause, + handleResume, + handleReindex, }; export function deactivate() {} diff --git a/hack/lint-drift.sh b/hack/lint-drift.sh index 08f83326a..8bb2be8de 100755 --- a/hack/lint-drift.sh +++ b/hack/lint-drift.sh @@ -13,6 +13,7 @@ # 3. Magic directory strings that have config.Dir* constants # 4. Literal ".md" (should use config.ExtMarkdown) # 5. Go DescKey ↔ YAML key linkage (embed/{cmd,flag,text} vs commands/) +# Only DescKey* constants are checked — Use* and ExampleKey* are excluded. # # Exit code: number of issues found (0 = clean). @@ -47,7 +48,7 @@ drift_count() { # ── 1. Literal "\n" ───────────────────────────────────────────────── # Match "\n" as a Go string (not inside comments or imports). # Skip config/token.go where the constant is defined. -hits=$(drift_grep '"\\n"' 'token.go') +hits=$(drift_grep '"\\n"' 'whitespace.go') count=$(drift_count "$hits") if [ "$count" -gt 0 ]; then echo "==> Literal \"\\n\" found ($count occurrences, use config.NewlineLF):" @@ -82,7 +83,7 @@ done # ── 4. Literal ".md" ──────────────────────────────────────────────── # Skip config/file.go where ExtMarkdown is defined. -hits=$(drift_grep '"\.md"' 'file.go') +hits=$(drift_grep '"\.md"' 'ext.go') count=$(drift_count "$hits") if [ "$count" -gt 0 ]; then echo "==> Literal \".md\" found ($count occurrences, use config.ExtMarkdown):" @@ -130,11 +131,11 @@ check_linkage() { } # cmd constants ↔ commands.yaml -# ExampleKey* constants map to examples.yaml, not commands.yaml — exclude them. +# Only DescKey* constants are YAML lookup keys. +# Use* constants are cobra Use fields; ExampleKey* map to examples.yaml. cmd_go_dir="internal/config/embed/cmd" -cmd_go_keys=$(grep -rh '= "' "$cmd_go_dir"/*.go 2>/dev/null \ +cmd_go_keys=$(grep -rh 'DescKey.*= "' "$cmd_go_dir"/*.go 2>/dev/null \ | grep -v '//' \ - | grep -v 'ExampleKey' \ | sed 's/.*= "//; s/"//' \ | sort -u) cmd_yaml_keys=$(grep -E '^[a-z]' "internal/assets/commands/commands.yaml" \ @@ -170,20 +171,10 @@ check_linkage "text↔text/*.yaml" \ "$text_yaml_merged" rm -f "$text_yaml_merged" -# Cross-namespace duplicates (same key value in cmd + flag + text) -dupes=$( - grep -rh '= "' internal/config/embed/cmd/*.go internal/config/embed/flag/*.go internal/config/embed/text/*.go 2>/dev/null \ - | grep -v '//' \ - | sed 's/.*= "//; s/"//' \ - | sort | uniq -d -) -if [ -n "$dupes" ]; then - dupe_count=$(echo "$dupes" | wc -l | tr -d ' ') - echo "==> Cross-namespace duplicates ($dupe_count key(s) appear in multiple embed packages):" - echo "$dupes" | sed 's/^/ /' - echo "" - issues=$((issues + dupe_count)) -fi +# Cross-namespace duplicates: cmd, flag, and text are separate YAML files +# with separate Go packages — the same key in each is by design (e.g. "agent" +# appears as a command description, a flag description, and a text string). +# No check needed. # ── Summary ────────────────────────────────────────────────────────── if [ "$issues" -eq 0 ]; then diff --git a/hack/release.sh b/hack/release.sh index 1771c5e51..d9885be21 100755 --- a/hack/release.sh +++ b/hack/release.sh @@ -100,15 +100,31 @@ rm -f "${PLUGIN_JSON}.bak" sed -i.bak -E "s/\"version\": \"[0-9]+\.[0-9]+\.[0-9]+\"/\"version\": \"${VERSION_NUM}\"/" "${MARKETPLACE_JSON}" rm -f "${MARKETPLACE_JSON}.bak" +# Update VS Code extension version +VSCODE_PKG="editors/vscode/package.json" +VSCODE_LOCK="editors/vscode/package-lock.json" +echo "Updating VS Code extension version in ${VSCODE_PKG} and ${VSCODE_LOCK}..." +sed -i.bak -E "s/\"version\": \"[0-9]+\.[0-9]+\.[0-9]+\"/\"version\": \"${VERSION_NUM}\"/" "${VSCODE_PKG}" +rm -f "${VSCODE_PKG}.bak" +sed -i.bak -E "s/\"version\": \"[0-9]+\.[0-9]+\.[0-9]+\"/\"version\": \"${VERSION_NUM}\"/" "${VSCODE_LOCK}" +rm -f "${VSCODE_LOCK}.bak" + # Update version references in documentation -echo "Updating version references in docs/index.md..." -sed -i.bak -E "s|/v[0-9]+\.[0-9]+\.[0-9]+/ctx-[0-9]+\.[0-9]+\.[0-9]+|/v${VERSION_NUM}/ctx-${VERSION_NUM}|g" docs/index.md -sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-linux-amd64|ctx-${VERSION_NUM}-linux-amd64|g" docs/index.md -sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-linux-arm64|ctx-${VERSION_NUM}-linux-arm64|g" docs/index.md -sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-darwin-amd64|ctx-${VERSION_NUM}-darwin-amd64|g" docs/index.md -sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-darwin-arm64|ctx-${VERSION_NUM}-darwin-arm64|g" docs/index.md -sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-windows-amd64|ctx-${VERSION_NUM}-windows-amd64|g" docs/index.md -rm -f docs/index.md.bak +echo "Updating version references in docs/index.md and docs/home/getting-started.md..." +for doc in docs/index.md docs/home/getting-started.md; do + sed -i.bak -E "s|/v[0-9]+\.[0-9]+\.[0-9]+/ctx-[0-9]+\.[0-9]+\.[0-9]+|/v${VERSION_NUM}/ctx-${VERSION_NUM}|g" "${doc}" + sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-linux-amd64|ctx-${VERSION_NUM}-linux-amd64|g" "${doc}" + sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-linux-arm64|ctx-${VERSION_NUM}-linux-arm64|g" "${doc}" + sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-darwin-amd64|ctx-${VERSION_NUM}-darwin-amd64|g" "${doc}" + sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-darwin-arm64|ctx-${VERSION_NUM}-darwin-arm64|g" "${doc}" + sed -i.bak -E "s|ctx-[0-9]+\.[0-9]+\.[0-9]+-windows-amd64|ctx-${VERSION_NUM}-windows-amd64|g" "${doc}" + rm -f "${doc}.bak" +done + +# Update VSIX version in integrations doc +echo "Updating VSIX version in docs/operations/integrations.md..." +sed -i.bak -E "s|ctx-context-[0-9]+\.[0-9]+\.[0-9]+\.vsix|ctx-context-${VERSION_NUM}.vsix|g" docs/operations/integrations.md +rm -f docs/operations/integrations.md.bak # Update versions.md with new release echo "Updating docs/versions.md..." @@ -129,7 +145,7 @@ make site # Commit docs and site updates echo "Committing documentation updates..." -git add docs/index.md docs/versions.md site/ "${PLUGIN_JSON}" +git add docs/index.md docs/home/getting-started.md docs/operations/integrations.md docs/versions.md site/ "${PLUGIN_JSON}" "${MARKETPLACE_JSON}" "${VSCODE_PKG}" "${VSCODE_LOCK}" git diff --cached --quiet || git commit -m "docs: update download links and versions page for ${VERSION}" echo "" diff --git a/internal/assets/hooks/messages/doc.go b/internal/assets/hooks/messages/doc.go new file mode 100644 index 000000000..02c753ed4 --- /dev/null +++ b/internal/assets/hooks/messages/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package messages provides metadata for hook message templates. +package messages diff --git a/internal/assets/hooks/messages/registry.go b/internal/assets/hooks/messages/registry.go index 7bd757fb6..fb8f17715 100644 --- a/internal/assets/hooks/messages/registry.go +++ b/internal/assets/hooks/messages/registry.go @@ -4,19 +4,14 @@ // \ Copyright 2026-present Context contributors. // SPDX-License-Identifier: Apache-2.0 -// Package messages provides metadata for hook message templates. -// -// The registry is parsed from an embedded registry.yaml that lives -// alongside the .txt template files. It is the metadata layer over -// the embedded FS and changes only when hooks are added or removed. package messages import ( "sync" "github.com/ActiveMemory/ctx/internal/assets/read/hook" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" - errparser "github.com/ActiveMemory/ctx/internal/err/parser" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" + errParser "github.com/ActiveMemory/ctx/internal/err/parser" "gopkg.in/yaml.v3" ) @@ -59,12 +54,12 @@ func Registry() []HookMessageInfo { registryOnce.Do(func() { raw, readErr := hook.MessageRegistry() if readErr != nil { - registryErr = fserr.FileRead("registry.yaml", readErr) + registryErr = errFs.FileRead("registry.yaml", readErr) return } var entries []HookMessageInfo if unmarshalErr := yaml.Unmarshal(raw, &entries); unmarshalErr != nil { - registryErr = errparser.ParseFile("registry.yaml", unmarshalErr) + registryErr = errParser.ParseFile("registry.yaml", unmarshalErr) return } registryData = entries diff --git a/internal/assets/why/about.md b/internal/assets/why/about.md index 059bc7f63..44b21e31d 100644 --- a/internal/assets/why/about.md +++ b/internal/assets/why/about.md @@ -135,7 +135,7 @@ makes the *next* session **smarter**. **Connect with `ctx`** * [Join the Community →](community.md): ask questions, share workflows, and help shape what comes next -* [Read the Blog →](../../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx` +* [Read the Blog →](../blog/): real-world patterns, ponderings, and lessons learned from building `ctx` using `ctx` ---- diff --git a/internal/bootstrap/cmd.go b/internal/bootstrap/cmd.go index 7dab83c9b..870d82d06 100644 --- a/internal/bootstrap/cmd.go +++ b/internal/bootstrap/cmd.go @@ -20,7 +20,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/flag" ctxContext "github.com/ActiveMemory/ctx/internal/context/validate" "github.com/ActiveMemory/ctx/internal/err/fs" - errInitialize "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/validation" ) @@ -89,7 +89,7 @@ func RootCmd() *cobra.Command { // Require initialization. if !ctxContext.Initialized(rc.ContextDir()) { - return errInitialize.NotInitialized() + return errInit.NotInitialized() } return nil diff --git a/internal/claude/claude_test.go b/internal/claude/claude_test.go index 2a5d55349..6100557cd 100644 --- a/internal/claude/claude_test.go +++ b/internal/claude/claude_test.go @@ -13,7 +13,7 @@ import ( "testing" "github.com/ActiveMemory/ctx/internal/assets" - ctxerr "github.com/ActiveMemory/ctx/internal/err/skill" + errSkill "github.com/ActiveMemory/ctx/internal/err/skill" ) func TestSkills(t *testing.T) { @@ -98,29 +98,29 @@ func TestSettingsStructure(t *testing.T) { func TestErrSkillList(t *testing.T) { cause := errors.New("read dir failed") - err := ctxerr.List(cause) + err := errSkill.List(cause) if err == nil { - t.Fatal("ctxerr.List() returned nil") + t.Fatal("errSkill.List() returned nil") } if !strings.Contains(err.Error(), "failed to list skills") { - t.Errorf("ctxerr.List() error missing prefix: %v", err) + t.Errorf("errSkill.List() error missing prefix: %v", err) } if !errors.Is(err, cause) { - t.Error("ctxerr.List() does not wrap the cause error") + t.Error("errSkill.List() does not wrap the cause error") } } func TestErrSkillRead(t *testing.T) { cause := errors.New("not found") - err := ctxerr.Read("my-skill", cause) + err := errSkill.Read("my-skill", cause) if err == nil { - t.Fatal("ctxerr.Read() returned nil") + t.Fatal("errSkill.Read() returned nil") } if !strings.Contains(err.Error(), "my-skill") { - t.Errorf("ctxerr.Read() error missing skill name: %v", err) + t.Errorf("errSkill.Read() error missing skill name: %v", err) } if !errors.Is(err, cause) { - t.Error("ctxerr.Read() does not wrap the cause error") + t.Error("errSkill.Read() does not wrap the cause error") } } diff --git a/internal/cli/add/cmd/coverage_test.go b/internal/cli/add/cmd/coverage_test.go index dd25a7978..76cdc8148 100644 --- a/internal/cli/add/cmd/coverage_test.go +++ b/internal/cli/add/cmd/coverage_test.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/cli/add/cmd/root" - entry2 "github.com/ActiveMemory/ctx/internal/cli/add/core/entry" + coreEntry "github.com/ActiveMemory/ctx/internal/cli/add/core/entry" "github.com/ActiveMemory/ctx/internal/cli/add/core/example" "github.com/ActiveMemory/ctx/internal/cli/add/core/extract" "github.com/ActiveMemory/ctx/internal/cli/add/core/format" @@ -27,7 +27,7 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/cli/initialize" - entrytype "github.com/ActiveMemory/ctx/internal/config/entry" + entryType "github.com/ActiveMemory/ctx/internal/config/entry" "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/entry" ) @@ -44,7 +44,7 @@ func TestErrNoContent(t *testing.T) { } func TestErrNoContentProvided(t *testing.T) { - for _, fType := range []string{entrytype.Decision, entrytype.Task, entrytype.Learning, entrytype.Convention, entrytype.Unknown} { + for _, fType := range []string{entryType.Decision, entryType.Task, entryType.Learning, entryType.Convention, entryType.Unknown} { t.Run(fType, func(t *testing.T) { err := add.ErrNoContentProvided(fType, example.ForType(fType)) if err == nil { @@ -152,11 +152,11 @@ func TestExamplesForType(t *testing.T) { fType string contains string }{ - {entrytype.Decision, "ctx add decision"}, - {entrytype.Task, "ctx add task"}, - {entrytype.Learning, "ctx add learning"}, - {entrytype.Convention, "ctx add convention"}, - {entrytype.Unknown, "ctx add "}, + {entryType.Decision, "ctx add decision"}, + {entryType.Task, "ctx add task"}, + {entryType.Learning, "ctx add learning"}, + {entryType.Convention, "ctx add convention"}, + {entryType.Unknown, "ctx add "}, } for _, tt := range tests { t.Run(tt.fType, func(t *testing.T) { @@ -742,23 +742,23 @@ func TestRun_TaskWithSection(t *testing.T) { func TestPredicates(t *testing.T) { // Test plural forms - if !entry2.FileTypeIsTask("tasks") { + if !coreEntry.FileTypeIsTask("tasks") { t.Error("FileTypeIsTask should accept 'tasks'") } - if !entry2.FileTypeIsDecision("decisions") { + if !coreEntry.FileTypeIsDecision("decisions") { t.Error("FileTypeIsDecision should accept 'decisions'") } - if !entry2.FileTypeIsLearning("learnings") { + if !coreEntry.FileTypeIsLearning("learnings") { t.Error("FileTypeIsLearning should accept 'learnings'") } // Test negative cases - if entry2.FileTypeIsTask("decision") { + if coreEntry.FileTypeIsTask("decision") { t.Error("FileTypeIsTask should reject 'decision'") } - if entry2.FileTypeIsDecision("task") { + if coreEntry.FileTypeIsDecision("task") { t.Error("FileTypeIsDecision should reject 'task'") } - if entry2.FileTypeIsLearning("convention") { + if coreEntry.FileTypeIsLearning("convention") { t.Error("FileTypeIsLearning should reject 'convention'") } } diff --git a/internal/cli/agent/agent.go b/internal/cli/agent/agent.go index ef4806f99..832baa3b2 100644 --- a/internal/cli/agent/agent.go +++ b/internal/cli/agent/agent.go @@ -9,10 +9,10 @@ package agent import ( "github.com/spf13/cobra" - agentroot "github.com/ActiveMemory/ctx/internal/cli/agent/cmd/root" + agentRoot "github.com/ActiveMemory/ctx/internal/cli/agent/cmd/root" ) // Cmd returns the "ctx agent" command for generating AI-ready context packets. func Cmd() *cobra.Command { - return agentroot.Cmd() + return agentRoot.Cmd() } diff --git a/internal/cli/agent/cmd/root/run.go b/internal/cli/agent/cmd/root/run.go index 345cce07d..00f7973e5 100644 --- a/internal/cli/agent/cmd/root/run.go +++ b/internal/cli/agent/cmd/root/run.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fmt" "github.com/ActiveMemory/ctx/internal/context/load" errCtx "github.com/ActiveMemory/ctx/internal/err/context" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" ) // Run executes the agent command logic. @@ -53,7 +53,7 @@ func Run( if err != nil { var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return ctxErr.NotInitialized() + return errInit.NotInitialized() } return err } diff --git a/internal/cli/agent/core/budget/assemble.go b/internal/cli/agent/core/budget/assemble.go index 082246e15..24d189040 100644 --- a/internal/cli/agent/core/budget/assemble.go +++ b/internal/cli/agent/core/budget/assemble.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/agent/core/score" "github.com/ActiveMemory/ctx/internal/cli/agent/core/sort" "github.com/ActiveMemory/ctx/internal/config/agent" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" ctxToken "github.com/ActiveMemory/ctx/internal/context/token" "github.com/ActiveMemory/ctx/internal/entity" @@ -85,8 +85,8 @@ func AssemblePacket(ctx *entity.Context, budget int) *assembledPacket { keywords := score.ExtractTaskKeywords(pkt.Tasks) // Tier 4+5: Decisions + Learnings (share remaining budget) - decisionBlocks := ParseEntryBlocks(ctx, ctxCfg.Decision) - learningBlocks := ParseEntryBlocks(ctx, ctxCfg.Learning) + decisionBlocks := ParseEntryBlocks(ctx, cfgCtx.Decision) + learningBlocks := ParseEntryBlocks(ctx, cfgCtx.Learning) scoredDecisions := score.ScoreEntries(decisionBlocks, keywords, now) scoredLearnings := score.ScoreEntries(learningBlocks, keywords, now) diff --git a/internal/cli/agent/core/budget/parse.go b/internal/cli/agent/core/budget/parse.go index a44e02d89..ded1bb501 100644 --- a/internal/cli/agent/core/budget/parse.go +++ b/internal/cli/agent/core/budget/parse.go @@ -9,7 +9,7 @@ package budget import ( "github.com/ActiveMemory/ctx/internal/cli/agent/core/extract" "github.com/ActiveMemory/ctx/internal/config/agent" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/index" ) @@ -38,7 +38,7 @@ func ParseEntryBlocks(ctx *entity.Context, fileName string) []index.EntryBlock { // Returns: // - []string: All convention bullet items; nil if the file is not found func ExtractAllConventions(ctx *entity.Context) []string { - if f := ctx.File(ctxCfg.Convention); f != nil { + if f := ctx.File(cfgCtx.Convention); f != nil { return extract.BulletItems(string(f.Content), agent.BulletItemLimit) } return nil diff --git a/internal/cli/agent/core/extract/extract.go b/internal/cli/agent/core/extract/extract.go index 9db92f83f..8070ced9e 100644 --- a/internal/cli/agent/core/extract/extract.go +++ b/internal/cli/agent/core/extract/extract.go @@ -9,7 +9,7 @@ package extract import ( "strings" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/marker" "github.com/ActiveMemory/ctx/internal/config/regex" "github.com/ActiveMemory/ctx/internal/config/token" @@ -69,7 +69,7 @@ func CheckboxItems(content string) []string { // Returns: // - []string: List of constitution rules; nil if the file is not found func ConstitutionRules(ctx *entity.Context) []string { - if f := ctx.File(ctxCfg.Constitution); f != nil { + if f := ctx.File(cfgCtx.Constitution); f != nil { return CheckboxItems(string(f.Content)) } return nil @@ -105,7 +105,7 @@ func UncheckedTasks(content string) []string { // - []string: List of active tasks with "- [ ]" prefix; nil if // the file is not found func ActiveTasks(ctx *entity.Context) []string { - if f := ctx.File(ctxCfg.Task); f != nil { + if f := ctx.File(cfgCtx.Task); f != nil { return UncheckedTasks(string(f.Content)) } return nil diff --git a/internal/cli/agent/core/sort/sort.go b/internal/cli/agent/core/sort/sort.go index 68e78aa46..6fc0b5bb0 100644 --- a/internal/cli/agent/core/sort/sort.go +++ b/internal/cli/agent/core/sort/sort.go @@ -9,7 +9,7 @@ package sort import ( "path/filepath" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/entity" ) @@ -26,7 +26,7 @@ import ( // - []string: File paths in reading order (e.g., ".context/CONSTITUTION.md") func ReadOrder(ctx *entity.Context) []string { var order []string - for _, name := range ctxCfg.ReadOrder { + for _, name := range cfgCtx.ReadOrder { if f := ctx.File(name); f != nil && !f.IsEmpty { order = append(order, filepath.Join(ctx.Dir, f.Name)) } diff --git a/internal/cli/change/cmd/root/run.go b/internal/cli/change/cmd/root/run.go index 303b9a14a..9df4e665e 100644 --- a/internal/cli/change/cmd/root/run.go +++ b/internal/cli/change/cmd/root/run.go @@ -12,7 +12,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/change/core/scan" "github.com/spf13/cobra" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" writeChange "github.com/ActiveMemory/ctx/internal/write/change" ) @@ -30,7 +30,7 @@ import ( func Run(cmd *cobra.Command, since string) error { refTime, refLabel, err := detect.ReferenceTime(since) if err != nil { - return ctxErr.DetectReferenceTime(err) + return errInit.DetectReferenceTime(err) } ctxChanges, _ := scan.FindContextChanges(refTime) diff --git a/internal/cli/change/core/cmd_test.go b/internal/cli/change/core/cmd_test.go index 680f1743b..fe09f7310 100644 --- a/internal/cli/change/core/cmd_test.go +++ b/internal/cli/change/core/cmd_test.go @@ -15,7 +15,7 @@ import ( "time" "github.com/ActiveMemory/ctx/internal/cli/change/core/detect" - format2 "github.com/ActiveMemory/ctx/internal/cli/change/core/render" + coreRender "github.com/ActiveMemory/ctx/internal/cli/change/core/render" "github.com/ActiveMemory/ctx/internal/cli/change/core/scan" "github.com/ActiveMemory/ctx/internal/format" @@ -134,7 +134,7 @@ func TestRenderChanges(t *testing.T) { Authors: []string{"Volkan"}, } - out := format2.Changes("6 hours ago", ctxChanges, code) + out := coreRender.Changes("6 hours ago", ctxChanges, code) if !strings.Contains(out, "## Changes Since Last Session") { t.Error("missing header") } @@ -155,7 +155,7 @@ func TestRenderChangesForHook(t *testing.T) { } code := entity.CodeSummary{CommitCount: 3, LatestMsg: "Fix bug"} - out := format2.ChangesForHook("2 hours ago", ctxChanges, code) + out := coreRender.ChangesForHook("2 hours ago", ctxChanges, code) if !strings.Contains(out, "Changes since last session") { t.Error("missing hook header") } @@ -164,14 +164,14 @@ func TestRenderChangesForHook(t *testing.T) { } // Empty case. - out = format2.ChangesForHook("1 hour ago", nil, entity.CodeSummary{}) + out = coreRender.ChangesForHook("1 hour ago", nil, entity.CodeSummary{}) if out != "" { t.Errorf("expected empty for no changes, got: %q", out) } } func TestRenderChanges_NoChanges(t *testing.T) { - out := format2.Changes("1 hour ago", nil, entity.CodeSummary{}) + out := coreRender.Changes("1 hour ago", nil, entity.CodeSummary{}) if !strings.Contains(out, "No changes detected") { t.Error("expected 'No changes detected' message") } diff --git a/internal/cli/change/core/detect/doc.go b/internal/cli/change/core/detect/doc.go new file mode 100644 index 000000000..7157ad832 --- /dev/null +++ b/internal/cli/change/core/detect/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package detect determines the reference time for change detection using markers, events, or flags. +package detect diff --git a/internal/cli/change/core/render/doc.go b/internal/cli/change/core/render/doc.go new file mode 100644 index 000000000..4b18e9ce1 --- /dev/null +++ b/internal/cli/change/core/render/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package render formats change summaries into human-readable Markdown output. +package render diff --git a/internal/cli/change/core/scan/doc.go b/internal/cli/change/core/scan/doc.go new file mode 100644 index 000000000..a40734733 --- /dev/null +++ b/internal/cli/change/core/scan/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package scan finds context and code files modified after a reference time. +package scan diff --git a/internal/cli/compact/cmd/root/run.go b/internal/cli/compact/cmd/root/run.go index 06b26a7d8..da110b7b6 100644 --- a/internal/cli/compact/cmd/root/run.go +++ b/internal/cli/compact/cmd/root/run.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/context/load" errCtx "github.com/ActiveMemory/ctx/internal/err/context" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/tidy" writeCompact "github.com/ActiveMemory/ctx/internal/write/compact" @@ -38,7 +38,7 @@ func Run(cmd *cobra.Command, archive bool) error { if err != nil { var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return ctxErr.ContextNotInitialized() + return errInit.ContextNotInitialized() } return err } diff --git a/internal/cli/compact/compact_test.go b/internal/cli/compact/compact_test.go index dc0746d90..bb3af9540 100644 --- a/internal/cli/compact/compact_test.go +++ b/internal/cli/compact/compact_test.go @@ -12,7 +12,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/add" "github.com/ActiveMemory/ctx/internal/cli/initialize" - taskcomplete "github.com/ActiveMemory/ctx/internal/cli/task/cmd/complete" + taskComplete "github.com/ActiveMemory/ctx/internal/cli/task/cmd/complete" ) // TestCompactCommand tests the compact command. @@ -72,7 +72,7 @@ func TestCompactWithTasks(t *testing.T) { t.Fatalf("add task failed: %v", err) } - completeCmd := taskcomplete.Cmd() + completeCmd := taskComplete.Cmd() completeCmd.SetArgs([]string{"Task to complete"}) if err := completeCmd.Execute(); err != nil { t.Fatalf("complete task failed: %v", err) diff --git a/internal/cli/compact/core/task.go b/internal/cli/compact/core/task.go index 3274061c1..572be40f6 100644 --- a/internal/cli/compact/core/task.go +++ b/internal/cli/compact/core/task.go @@ -12,7 +12,7 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/assets/read/desc" - archiveCfg "github.com/ActiveMemory/ctx/internal/config/archive" + cfgArchive "github.com/ActiveMemory/ctx/internal/config/archive" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/token" @@ -82,7 +82,7 @@ func CompactTasks( archiveContent += block.BlockContent() + nl + nl } if archiveFile, archiveErr := tidy.WriteArchive( - archiveCfg.ArchiveScopeTasks, + cfgArchive.ArchiveScopeTasks, desc.Text(text.DescKeyHeadingArchivedTasks), archiveContent, ); archiveErr == nil { diff --git a/internal/cli/config/cmd/status/cmd.go b/internal/cli/config/cmd/status/cmd.go index 63d1a59d6..4520db746 100644 --- a/internal/cli/config/cmd/status/cmd.go +++ b/internal/cli/config/cmd/status/cmd.go @@ -8,7 +8,7 @@ package status import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" - internalConfig "github.com/ActiveMemory/ctx/internal/config/cli" + cfgCli "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/embed/cmd" "github.com/spf13/cobra" @@ -25,7 +25,7 @@ func Cmd() *cobra.Command { return &cobra.Command{ Use: cmd.UseConfigStatus, Short: short, - Annotations: map[string]string{internalConfig.AnnotationSkipInit: ""}, + Annotations: map[string]string{cfgCli.AnnotationSkipInit: ""}, Args: cobra.NoArgs, RunE: func(cmd *cobra.Command, _ []string) error { root, rootErr := core.GitRoot() diff --git a/internal/cli/config/cmd/switchcmd/cmd.go b/internal/cli/config/cmd/switchcmd/cmd.go index 5b4498c0b..a54527de7 100644 --- a/internal/cli/config/cmd/switchcmd/cmd.go +++ b/internal/cli/config/cmd/switchcmd/cmd.go @@ -11,7 +11,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/cli/config/core" - internalConfig "github.com/ActiveMemory/ctx/internal/config/cli" + cfgCli "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/embed/cmd" ) @@ -25,7 +25,7 @@ func Cmd() *cobra.Command { return &cobra.Command{ Use: cmd.UseConfigSwitch, Short: short, - Annotations: map[string]string{internalConfig.AnnotationSkipInit: ""}, + Annotations: map[string]string{cfgCli.AnnotationSkipInit: ""}, Long: long, Args: cobra.MaximumNArgs(1), RunE: func(cmd *cobra.Command, args []string) error { diff --git a/internal/cli/config/cmd/switchcmd/run.go b/internal/cli/config/cmd/switchcmd/run.go index dcf454932..6afdfbab8 100644 --- a/internal/cli/config/cmd/switchcmd/run.go +++ b/internal/cli/config/cmd/switchcmd/run.go @@ -11,7 +11,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/config/core" "github.com/ActiveMemory/ctx/internal/config/file" - ctxErr "github.com/ActiveMemory/ctx/internal/err/config" + errConfig "github.com/ActiveMemory/ctx/internal/err/config" writeConfig "github.com/ActiveMemory/ctx/internal/write/config" ) @@ -50,7 +50,7 @@ func Run(cmd *cobra.Command, root string, args []string) error { profile = file.ProfileDev } default: - return ctxErr.UnknownProfile(target) + return errConfig.UnknownProfile(target) } msg, switchErr := core.SwitchTo(root, profile) diff --git a/internal/cli/config/core/core.go b/internal/cli/config/core/core.go index 7fda5308d..b45e9e07f 100644 --- a/internal/cli/config/core/core.go +++ b/internal/cli/config/core/core.go @@ -20,7 +20,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fs" cfgGit "github.com/ActiveMemory/ctx/internal/config/git" "github.com/ActiveMemory/ctx/internal/err/config" - ctxErr "github.com/ActiveMemory/ctx/internal/err/git" + errGit "github.com/ActiveMemory/ctx/internal/err/git" "github.com/ActiveMemory/ctx/internal/io" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -95,14 +95,14 @@ func SwitchTo(root, profile string) (string, error) { // degrade gracefully when this returns an error. func GitRoot() (string, error) { if _, lookErr := exec.LookPath(cfgGit.Binary); lookErr != nil { - return "", ctxErr.NotFound() + return "", errGit.NotFound() } out, execErr := exec.Command( //nolint:gosec // args are literal constants cfgGit.Binary, cfgGit.RevParse, cfgGit.FlagShowToplevel, ).Output() if execErr != nil { - return "", ctxErr.NotInRepo(execErr) + return "", errGit.NotInRepo(execErr) } return strings.TrimSpace(string(out)), nil } diff --git a/internal/cli/dep/cmd/root/run.go b/internal/cli/dep/cmd/root/run.go index 07ccf5349..6c97aa95f 100644 --- a/internal/cli/dep/cmd/root/run.go +++ b/internal/cli/dep/cmd/root/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/dep/core" "github.com/ActiveMemory/ctx/internal/config/fmt" "github.com/ActiveMemory/ctx/internal/config/token" - ctxErr "github.com/ActiveMemory/ctx/internal/err/config" + errConfig "github.com/ActiveMemory/ctx/internal/err/config" "github.com/ActiveMemory/ctx/internal/write/deps" ) @@ -37,14 +37,14 @@ func Run(cmd *cobra.Command, format string, external bool, projType string) erro switch format { case fmt.FormatMermaid, fmt.FormatTable, fmt.FormatJSON: default: - return ctxErr.UnknownFormat(format, supportedFormats) + return errConfig.UnknownFormat(format, supportedFormats) } var builder core.GraphBuilder if projType != "" { builder = core.FindBuilder(projType) if builder == nil { - return ctxErr.UnknownProjectType(projType, strings.Join(core.BuilderNames(), token.CommaSpace)) + return errConfig.UnknownProjectType(projType, strings.Join(core.BuilderNames(), token.CommaSpace)) } } else { builder = core.DetectBuilder() diff --git a/internal/cli/drift/cmd/root/run.go b/internal/cli/drift/cmd/root/run.go index 200af357d..0209ab97b 100644 --- a/internal/cli/drift/cmd/root/run.go +++ b/internal/cli/drift/cmd/root/run.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/context/load" "github.com/ActiveMemory/ctx/internal/drift" errCtx "github.com/ActiveMemory/ctx/internal/err/context" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" writeDrift "github.com/ActiveMemory/ctx/internal/write/drift" ) @@ -37,7 +37,7 @@ func Run(cmd *cobra.Command, jsonOutput, fix bool) error { if err != nil { var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return ctxErr.NotInitialized() + return errInit.NotInitialized() } return err } diff --git a/internal/cli/drift/core/fix.go b/internal/cli/drift/core/fix.go index 7bf1989b7..fe304e029 100644 --- a/internal/cli/drift/core/fix.go +++ b/internal/cli/drift/core/fix.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/assets/read/template" "github.com/ActiveMemory/ctx/internal/config/archive" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/marker" @@ -27,7 +27,7 @@ import ( "github.com/ActiveMemory/ctx/internal/entity" errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/err/prompt" - ctxErr "github.com/ActiveMemory/ctx/internal/err/task" + errTask "github.com/ActiveMemory/ctx/internal/err/task" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/task" "github.com/ActiveMemory/ctx/internal/tidy" @@ -106,10 +106,10 @@ func ApplyFixes( // Returns: // - error: Non-nil if file operations fail func FixStaleness(cmd *cobra.Command, ctx *entity.Context) error { - tasksFile := ctx.File(ctxCfg.Task) + tasksFile := ctx.File(cfgCtx.Task) if tasksFile == nil { - return ctxErr.FileNotFound() + return errTask.FileNotFound() } nl := token.NewlineLF @@ -145,7 +145,7 @@ func FixStaleness(cmd *cobra.Command, ctx *entity.Context) error { } if len(completedTasks) == 0 { - return ctxErr.NoneCompleted() + return errTask.NoneCompleted() } // Build archive content @@ -167,7 +167,7 @@ func FixStaleness(cmd *cobra.Command, ctx *entity.Context) error { if writeErr := os.WriteFile( tasksFile.Path, []byte(newContent), fs.PermFile, ); writeErr != nil { - return ctxErr.FileWrite(writeErr) + return errTask.FileWrite(writeErr) } writeDrift.Archived(cmd, len(completedTasks), archiveFile) diff --git a/internal/cli/drift/core/out.go b/internal/cli/drift/core/out.go index 891a9b527..18d15bb14 100644 --- a/internal/cli/drift/core/out.go +++ b/internal/cli/drift/core/out.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/drift" - errdrift "github.com/ActiveMemory/ctx/internal/err/drift" + errDrift "github.com/ActiveMemory/ctx/internal/err/drift" writeDrift "github.com/ActiveMemory/ctx/internal/write/drift" ) @@ -119,7 +119,7 @@ func OutputDriftText(cmd *cobra.Command, report *drift.Report) error { switch status { case drift.StatusViolation: writeDrift.StatusViolation(cmd) - return errdrift.Violations() + return errDrift.Violations() case drift.StatusWarning: writeDrift.StatusWarning(cmd) default: diff --git a/internal/cli/hook/cmd/root/run.go b/internal/cli/hook/cmd/root/run.go index 34ecc9084..7204f6dd9 100644 --- a/internal/cli/hook/cmd/root/run.go +++ b/internal/cli/hook/cmd/root/run.go @@ -18,11 +18,11 @@ import ( "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/fs" - hookCfg "github.com/ActiveMemory/ctx/internal/config/hook" + cfgHook "github.com/ActiveMemory/ctx/internal/config/hook" "github.com/ActiveMemory/ctx/internal/config/marker" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/err/config" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" writeErr "github.com/ActiveMemory/ctx/internal/write/err" "github.com/ActiveMemory/ctx/internal/write/hook" ) @@ -44,16 +44,16 @@ func Run(cmd *cobra.Command, args []string, writeFile bool) error { tool := strings.ToLower(args[0]) switch tool { - case hookCfg.ToolClaudeCode, hookCfg.ToolClaude: + case cfgHook.ToolClaudeCode, cfgHook.ToolClaude: hook.InfoTool(cmd, desc.Text(text.DescKeyHookClaude)) - case hookCfg.ToolCursor: + case cfgHook.ToolCursor: hook.InfoTool(cmd, desc.Text(text.DescKeyHookCursor)) - case hookCfg.ToolAider: + case cfgHook.ToolAider: hook.InfoTool(cmd, desc.Text(text.DescKeyHookAider)) - case hookCfg.ToolCopilot: + case cfgHook.ToolCopilot: if writeFile { return WriteCopilotInstructions(cmd) } @@ -65,7 +65,7 @@ func Run(cmd *cobra.Command, args []string, writeFile bool) error { } hook.Content(cmd, string(content)) - case hookCfg.ToolWindsurf: + case cfgHook.ToolWindsurf: hook.InfoTool(cmd, desc.Text(text.DescKeyHookWindsurf)) default: @@ -89,11 +89,11 @@ func Run(cmd *cobra.Command, args []string, writeFile bool) error { // Returns: // - error: Non-nil if directory creation or file write fails func WriteCopilotInstructions(cmd *cobra.Command) error { - targetFile := filepath.Join(hookCfg.DirGitHub, hookCfg.FileCopilotInstructions) + targetFile := filepath.Join(cfgHook.DirGitHub, cfgHook.FileCopilotInstructions) // Create .github/ directory if needed - if err := os.MkdirAll(hookCfg.DirGitHub, fs.PermExec); err != nil { - return ctxErr.Mkdir(hookCfg.DirGitHub, err) + if err := os.MkdirAll(cfgHook.DirGitHub, fs.PermExec); err != nil { + return errFs.Mkdir(cfgHook.DirGitHub, err) } // Load the copilot instructions from embedded assets @@ -116,7 +116,7 @@ func WriteCopilotInstructions(cmd *cobra.Command) error { // File exists without ctx markers: append ctx content merged := existingStr + token.NewlineLF + string(instructions) if wErr := os.WriteFile(targetFile, []byte(merged), fs.PermFile); wErr != nil { - return ctxErr.FileWrite(targetFile, wErr) + return errFs.FileWrite(targetFile, wErr) } hook.InfoCopilotMerged(cmd, targetFile) return nil @@ -126,7 +126,7 @@ func WriteCopilotInstructions(cmd *cobra.Command) error { if wErr := os.WriteFile( targetFile, instructions, fs.PermFile, ); wErr != nil { - return ctxErr.FileWrite(targetFile, wErr) + return errFs.FileWrite(targetFile, wErr) } hook.InfoCopilotCreated(cmd, targetFile) diff --git a/internal/cli/hook/hook.go b/internal/cli/hook/hook.go index fea9ee339..2a661ccf4 100644 --- a/internal/cli/hook/hook.go +++ b/internal/cli/hook/hook.go @@ -9,10 +9,10 @@ package hook import ( "github.com/spf13/cobra" - hookroot "github.com/ActiveMemory/ctx/internal/cli/hook/cmd/root" + hookRoot "github.com/ActiveMemory/ctx/internal/cli/hook/cmd/root" ) // Cmd returns the "ctx hook" command for generating AI tool integrations. func Cmd() *cobra.Command { - return hookroot.Cmd() + return hookRoot.Cmd() } diff --git a/internal/cli/hook/hook_test.go b/internal/cli/hook/hook_test.go index 0b1bc75a2..11afc4ab1 100644 --- a/internal/cli/hook/hook_test.go +++ b/internal/cli/hook/hook_test.go @@ -13,7 +13,7 @@ import ( "strings" "testing" - hookroot "github.com/ActiveMemory/ctx/internal/cli/hook/cmd/root" + hookRoot "github.com/ActiveMemory/ctx/internal/cli/hook/cmd/root" "github.com/spf13/cobra" ) @@ -70,7 +70,7 @@ func hookCmdOutput(cmd *cobra.Command) string { func TestWriteCopilotInstructions_NewFile(t *testing.T) { tmpDir := t.TempDir() - // hookroot.WriteCopilotInstructions uses relative paths, so chdir. + // hookRoot.WriteCopilotInstructions uses relative paths, so chdir. origDir, wdErr := os.Getwd() if wdErr != nil { t.Fatal(wdErr) @@ -83,8 +83,8 @@ func TestWriteCopilotInstructions_NewFile(t *testing.T) { }) cmd := newHookTestCmd() - if runErr := hookroot.WriteCopilotInstructions(cmd); runErr != nil { - t.Fatalf("hookroot.WriteCopilotInstructions failed: %v", runErr) + if runErr := hookRoot.WriteCopilotInstructions(cmd); runErr != nil { + t.Fatalf("hookRoot.WriteCopilotInstructions failed: %v", runErr) } targetFile := filepath.Join(tmpDir, ".github", "copilot-instructions.md") @@ -129,8 +129,8 @@ func TestWriteCopilotInstructions_ExistingWithMarker(t *testing.T) { } cmd := newHookTestCmd() - if runErr := hookroot.WriteCopilotInstructions(cmd); runErr != nil { - t.Fatalf("hookroot.WriteCopilotInstructions failed: %v", runErr) + if runErr := hookRoot.WriteCopilotInstructions(cmd); runErr != nil { + t.Fatalf("hookRoot.WriteCopilotInstructions failed: %v", runErr) } // File should be unchanged (skipped). @@ -175,8 +175,8 @@ func TestWriteCopilotInstructions_ExistingWithoutMarker(t *testing.T) { } cmd := newHookTestCmd() - if runErr := hookroot.WriteCopilotInstructions(cmd); runErr != nil { - t.Fatalf("hookroot.WriteCopilotInstructions failed: %v", runErr) + if runErr := hookRoot.WriteCopilotInstructions(cmd); runErr != nil { + t.Fatalf("hookRoot.WriteCopilotInstructions failed: %v", runErr) } data, readErr := os.ReadFile(targetFile) diff --git a/internal/cli/initialize/cmd/root/run.go b/internal/cli/initialize/cmd/root/run.go index 5907484ee..b32e811a5 100644 --- a/internal/cli/initialize/cmd/root/run.go +++ b/internal/cli/initialize/cmd/root/run.go @@ -12,12 +12,12 @@ import ( "path/filepath" "strings" - claude2 "github.com/ActiveMemory/ctx/internal/cli/initialize/core/claude" + coreClaude "github.com/ActiveMemory/ctx/internal/cli/initialize/core/claude" "github.com/ActiveMemory/ctx/internal/cli/initialize/core/entry" coreMerge "github.com/ActiveMemory/ctx/internal/cli/initialize/core/merge" "github.com/ActiveMemory/ctx/internal/cli/initialize/core/plan" "github.com/ActiveMemory/ctx/internal/cli/initialize/core/plugin" - project2 "github.com/ActiveMemory/ctx/internal/cli/initialize/core/project" + coreProject "github.com/ActiveMemory/ctx/internal/cli/initialize/core/project" "github.com/ActiveMemory/ctx/internal/cli/initialize/core/prompt" "github.com/ActiveMemory/ctx/internal/cli/initialize/core/validate" "github.com/spf13/cobra" @@ -39,7 +39,7 @@ import ( "github.com/ActiveMemory/ctx/internal/crypto" errCrypto "github.com/ActiveMemory/ctx/internal/err/crypto" errFs "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/prompt" + errPrompt "github.com/ActiveMemory/ctx/internal/err/prompt" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/initialize" ) @@ -102,7 +102,7 @@ func Run( var listErr error templatesToCreate, listErr = catalog.List() if listErr != nil { - return ctxErr.ListTemplates(listErr) + return errPrompt.ListTemplates(listErr) } } @@ -118,7 +118,7 @@ func Run( content, err := template.Template(name) if err != nil { - return ctxErr.ReadTemplate(name, err) + return errPrompt.ReadTemplate(name, err) } if err := os.WriteFile(targetPath, content, fs.PermFile); err != nil { @@ -152,7 +152,7 @@ func Run( initialize.InfoCreatingRootFiles(cmd) // Create specs/ and ideas/ directories with README.md - if err := project2.CreateProjectDirs(cmd); err != nil { + if err := coreProject.CreateProjectDirs(cmd); err != nil { initialize.InfoWarnNonFatal(cmd, desc.Text(text.DescKeyInitLabelProjectDirs), err) } @@ -184,13 +184,13 @@ func Run( } // Handle CLAUDE.md creation/merge - if err := claude2.HandleClaudeMd(cmd, force, merge); err != nil { + if err := coreClaude.HandleClaudeMd(cmd, force, merge); err != nil { // Non-fatal: warn but continue initialize.InfoWarnNonFatal(cmd, claude.Md, err) } // Deploy Makefile.ctx and amend user Makefile - if err := project2.HandleMakefileCtx(cmd); err != nil { + if err := coreProject.HandleMakefileCtx(cmd); err != nil { // Non-fatal: warn but continue initialize.InfoWarnNonFatal(cmd, sync.PatternMakefile, err) } diff --git a/internal/cli/initialize/core/backup/file.go b/internal/cli/initialize/core/backup/file.go index a9185f9ce..05a9d778c 100644 --- a/internal/cli/initialize/core/backup/file.go +++ b/internal/cli/initialize/core/backup/file.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/config/fs" - backupPkg "github.com/ActiveMemory/ctx/internal/err/backup" + errBackup "github.com/ActiveMemory/ctx/internal/err/backup" "github.com/ActiveMemory/ctx/internal/write/initialize" "github.com/spf13/cobra" ) @@ -31,7 +31,7 @@ func File(cmd *cobra.Command, filename string, content []byte) error { timestamp := time.Now().Unix() backupName := fmt.Sprintf(file.BackupFormat, filename, timestamp) if writeErr := os.WriteFile(backupName, content, fs.PermFile); writeErr != nil { - return backupPkg.Create(backupName, writeErr) + return errBackup.Create(backupName, writeErr) } initialize.Backup(cmd, backupName) return nil diff --git a/internal/cli/initialize/core/claude/claude.go b/internal/cli/initialize/core/claude/claude.go index 3ace980a8..f87bc42d7 100644 --- a/internal/cli/initialize/core/claude/claude.go +++ b/internal/cli/initialize/core/claude/claude.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/marker" "github.com/ActiveMemory/ctx/internal/entity" - errInitialize "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/write/initialize" ) @@ -32,7 +32,7 @@ import ( func HandleClaudeMd(cmd *cobra.Command, force, autoMerge bool) error { templateContent, err := readClaude.Md() if err != nil { - return errInitialize.ReadTemplate(claude.Md, err) + return errInit.ReadTemplate(claude.Md, err) } created, mergeErr := merge.CreateOrMerge(cmd, entity.MergeParams{ diff --git a/internal/cli/initialize/core/merge/create.go b/internal/cli/initialize/core/merge/create.go index 2e3aef0a4..26438450a 100644 --- a/internal/cli/initialize/core/merge/create.go +++ b/internal/cli/initialize/core/merge/create.go @@ -20,7 +20,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" errFs "github.com/ActiveMemory/ctx/internal/err/fs" - promptErr "github.com/ActiveMemory/ctx/internal/err/prompt" + errPrompt "github.com/ActiveMemory/ctx/internal/err/prompt" "github.com/ActiveMemory/ctx/internal/write/initialize" ) @@ -126,7 +126,7 @@ func UpdateMarkedSection( ) error { startIdx := strings.Index(existing, markerStart) if startIdx == -1 { - return promptErr.MarkerNotFound(filename) + return errPrompt.MarkerNotFound(filename) } endIdx := strings.Index(existing, markerEnd) @@ -140,7 +140,7 @@ func UpdateMarkedSection( templateStart := strings.Index(templateStr, markerStart) templateEnd := strings.Index(templateStr, markerEnd) if templateStart == -1 || templateEnd == -1 { - return promptErr.TemplateMissingMarkers(filename) + return errPrompt.TemplateMissingMarkers(filename) } sectionContent := templateStr[templateStart : templateEnd+len(markerEnd)] diff --git a/internal/cli/initialize/core/project/dir.go b/internal/cli/initialize/core/project/dir.go index d254e642b..3869204fe 100644 --- a/internal/cli/initialize/core/project/dir.go +++ b/internal/cli/initialize/core/project/dir.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/config/fs" errFs "github.com/ActiveMemory/ctx/internal/err/fs" - errInitialize "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/write/initialize" ) @@ -42,7 +42,7 @@ func CreateProjectDirs(cmd *cobra.Command) error { readme, readErr := project.Readme(d) if readErr != nil { - return errInitialize.ReadProjectReadme(d, readErr) + return errInit.ReadProjectReadme(d, readErr) } readmePath := filepath.Join(d, file.Readme) diff --git a/internal/cli/initialize/core/project/makefile.go b/internal/cli/initialize/core/project/makefile.go index 87961b2bb..2881a8e84 100644 --- a/internal/cli/initialize/core/project/makefile.go +++ b/internal/cli/initialize/core/project/makefile.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/project" "github.com/ActiveMemory/ctx/internal/config/token" errFs "github.com/ActiveMemory/ctx/internal/err/fs" - errInitialize "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/write/initialize" ) @@ -32,7 +32,7 @@ func HandleMakefileCtx(cmd *cobra.Command) error { content, err := makefile.Ctx() if err != nil { - return errInitialize.ReadTemplate(project.MakefileCtx, err) + return errInit.ReadTemplate(project.MakefileCtx, err) } if err = os.WriteFile(project.MakefileCtx, content, fs.PermFile); err != nil { @@ -47,7 +47,7 @@ func HandleMakefileCtx(cmd *cobra.Command) error { if err := os.WriteFile( project.Makefile, []byte(minimal), fs.PermFile, ); err != nil { - return errInitialize.CreateMakefile(err) + return errInit.CreateMakefile(err) } initialize.MakefileCreated(cmd) return nil diff --git a/internal/cli/initialize/init_test.go b/internal/cli/initialize/init_test.go index 72959fb1d..fa5336f4e 100644 --- a/internal/cli/initialize/init_test.go +++ b/internal/cli/initialize/init_test.go @@ -14,7 +14,7 @@ import ( "testing" "github.com/ActiveMemory/ctx/internal/claude" - claude2 "github.com/ActiveMemory/ctx/internal/config/claude" + cfgClaude "github.com/ActiveMemory/ctx/internal/config/claude" "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/env" ) @@ -417,7 +417,7 @@ func TestRunInit_Merge(t *testing.T) { t.Setenv("HOME", tmpDir) t.Setenv(env.SkipPathCheck, env.True) - if err = os.WriteFile(claude2.Md, []byte("# My Project\n\nExisting.\n"), 0600); err != nil { + if err = os.WriteFile(cfgClaude.Md, []byte("# My Project\n\nExisting.\n"), 0600); err != nil { t.Fatal(err) } @@ -427,7 +427,7 @@ func TestRunInit_Merge(t *testing.T) { t.Fatalf("init --merge failed: %v", err) } - content, _ := os.ReadFile(claude2.Md) + content, _ := os.ReadFile(cfgClaude.Md) if !strings.Contains(string(content), "My Project") { t.Error("original content lost with --merge") } diff --git a/internal/cli/journal/cmd/site/doc.go b/internal/cli/journal/cmd/site/doc.go new file mode 100644 index 000000000..8dfc31aa1 --- /dev/null +++ b/internal/cli/journal/cmd/site/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package site provides the journal site subcommand for generating a static site from journal entries. +package site diff --git a/internal/cli/journal/core/collapse/doc.go b/internal/cli/journal/core/collapse/doc.go new file mode 100644 index 000000000..97dedf946 --- /dev/null +++ b/internal/cli/journal/core/collapse/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package collapse wraps long tool output turns in collapsible HTML details blocks. +package collapse diff --git a/internal/cli/journal/core/consolidate/doc.go b/internal/cli/journal/core/consolidate/doc.go new file mode 100644 index 000000000..16501781a --- /dev/null +++ b/internal/cli/journal/core/consolidate/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package consolidate collapses consecutive identical tool turns into a single turn with a count. +package consolidate diff --git a/internal/cli/journal/core/format/doc.go b/internal/cli/journal/core/format/doc.go new file mode 100644 index 000000000..5409c6e20 --- /dev/null +++ b/internal/cli/journal/core/format/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package format renders file sizes and other journal metadata in human-readable form. +package format diff --git a/internal/cli/journal/core/frontmatter/doc.go b/internal/cli/journal/core/frontmatter/doc.go new file mode 100644 index 000000000..58106e3dd --- /dev/null +++ b/internal/cli/journal/core/frontmatter/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package frontmatter transforms journal YAML frontmatter into Obsidian-compatible format. +package frontmatter diff --git a/internal/cli/journal/core/generate/doc.go b/internal/cli/journal/core/generate/doc.go new file mode 100644 index 000000000..229306a14 --- /dev/null +++ b/internal/cli/journal/core/generate/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package generate builds site index pages, READMEs, and navigation for journal static sites. +package generate diff --git a/internal/cli/journal/core/group/doc.go b/internal/cli/journal/core/group/doc.go new file mode 100644 index 000000000..2cb6b9618 --- /dev/null +++ b/internal/cli/journal/core/group/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package group organizes journal entries by month for chronological display. +package group diff --git a/internal/cli/journal/core/moc/doc.go b/internal/cli/journal/core/moc/doc.go new file mode 100644 index 000000000..5bfc4898b --- /dev/null +++ b/internal/cli/journal/core/moc/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package moc generates Obsidian Maps of Content for journal vault navigation. +package moc diff --git a/internal/cli/journal/core/normalize/doc.go b/internal/cli/journal/core/normalize/doc.go new file mode 100644 index 000000000..226f807cf --- /dev/null +++ b/internal/cli/journal/core/normalize/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package normalize sanitizes journal Markdown for static site rendering by fixing fences, headings, and list formatting. +package normalize diff --git a/internal/cli/journal/core/parse/doc.go b/internal/cli/journal/core/parse/doc.go new file mode 100644 index 000000000..f5470bec1 --- /dev/null +++ b/internal/cli/journal/core/parse/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package parse scans journal directories and extracts entry metadata from Markdown files. +package parse diff --git a/internal/cli/journal/core/reduce/doc.go b/internal/cli/journal/core/reduce/doc.go new file mode 100644 index 000000000..ecbe1cb35 --- /dev/null +++ b/internal/cli/journal/core/reduce/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package reduce strips code fence markers from journal content to eliminate nesting conflicts. +package reduce diff --git a/internal/cli/journal/core/section/doc.go b/internal/cli/journal/core/section/doc.go new file mode 100644 index 000000000..6874c4ed7 --- /dev/null +++ b/internal/cli/journal/core/section/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package section builds topic indexes and section pages for journal site navigation. +package section diff --git a/internal/cli/journal/core/section/section.go b/internal/cli/journal/core/section/section.go index 1b360f342..72ba972d5 100644 --- a/internal/cli/journal/core/section/section.go +++ b/internal/cli/journal/core/section/section.go @@ -22,7 +22,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/regex" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" ) // WriteSection creates a subdirectory, writes its index page, and calls @@ -43,14 +43,14 @@ func WriteSection( ) error { dir := filepath.Join(docsDir, subdir) if mkErr := os.MkdirAll(dir, fs.PermExec); mkErr != nil { - return ctxErr.Mkdir(dir, mkErr) + return errFs.Mkdir(dir, mkErr) } indexPath := filepath.Join(dir, file.Index) if writeErr := os.WriteFile( indexPath, []byte(indexContent), fs.PermFile, ); writeErr != nil { - return ctxErr.FileWrite(indexPath, writeErr) + return errFs.FileWrite(indexPath, writeErr) } writePages(dir) diff --git a/internal/cli/journal/core/session/doc.go b/internal/cli/journal/core/session/doc.go new file mode 100644 index 000000000..df428b764 --- /dev/null +++ b/internal/cli/journal/core/session/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package session counts unique sessions across topic data. +package session diff --git a/internal/cli/journal/core/turn/doc.go b/internal/cli/journal/core/turn/doc.go new file mode 100644 index 000000000..a5f9366c7 --- /dev/null +++ b/internal/cli/journal/core/turn/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package turn extracts and merges conversation turn bodies from journal entries. +package turn diff --git a/internal/cli/journal/core/wikilink/doc.go b/internal/cli/journal/core/wikilink/doc.go new file mode 100644 index 000000000..2182cdb51 --- /dev/null +++ b/internal/cli/journal/core/wikilink/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package wikilink converts standard Markdown links to Obsidian wikilink format. +package wikilink diff --git a/internal/cli/journal/core/wrap/doc.go b/internal/cli/journal/core/wrap/doc.go new file mode 100644 index 000000000..b1b1c3b6b --- /dev/null +++ b/internal/cli/journal/core/wrap/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package wrap soft-wraps long lines in journal files to approximately 80 characters. +package wrap diff --git a/internal/cli/load/cmd/root/run.go b/internal/cli/load/cmd/root/run.go index 06a5f6274..927172adf 100644 --- a/internal/cli/load/cmd/root/run.go +++ b/internal/cli/load/cmd/root/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/load/core" "github.com/ActiveMemory/ctx/internal/context/load" errCtx "github.com/ActiveMemory/ctx/internal/err/context" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" writeLoad "github.com/ActiveMemory/ctx/internal/write/load" ) @@ -35,7 +35,7 @@ func Run(cmd *cobra.Command, budget int, raw bool) error { if err != nil { var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return ctxErr.NotInitialized() + return errInit.NotInitialized() } return err } diff --git a/internal/cli/loop/cmd/root/run.go b/internal/cli/loop/cmd/root/run.go index 82af6928e..c92a6f68b 100644 --- a/internal/cli/loop/cmd/root/run.go +++ b/internal/cli/loop/cmd/root/run.go @@ -14,9 +14,9 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/fs" - loopCfg "github.com/ActiveMemory/ctx/internal/config/loop" + cfgLoop "github.com/ActiveMemory/ctx/internal/config/loop" "github.com/ActiveMemory/ctx/internal/err/config" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/write/loop" ) @@ -41,7 +41,7 @@ func Run( maxIterations int, completionMsg, outputFile string, ) error { - if !loopCfg.ValidTools[tool] { + if !cfgLoop.ValidTools[tool] { return config.InvalidTool(tool) } @@ -50,7 +50,7 @@ func Run( if writeErr := os.WriteFile( outputFile, []byte(script), fs.PermExec, ); writeErr != nil { - return ctxErr.FileWrite(outputFile, writeErr) + return errFs.FileWrite(outputFile, writeErr) } loop.InfoGenerated( diff --git a/internal/cli/loop/cmd/root/script.go b/internal/cli/loop/cmd/root/script.go index a5c87d67c..1a13eab93 100644 --- a/internal/cli/loop/cmd/root/script.go +++ b/internal/cli/loop/cmd/root/script.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/assets/tpl" "github.com/ActiveMemory/ctx/internal/config/embed/text" - loopCfg "github.com/ActiveMemory/ctx/internal/config/loop" + cfgLoop "github.com/ActiveMemory/ctx/internal/config/loop" ) // GenerateLoopScript creates a bash script for running a Ralph loop. @@ -37,11 +37,11 @@ func GenerateLoopScript( var aiCommand string switch tool { - case loopCfg.DefaultTool: + case cfgLoop.DefaultTool: aiCommand = fmt.Sprintf(`claude --print "$(cat %s)"`, absPrompt) - case loopCfg.ToolAider: + case cfgLoop.ToolAider: aiCommand = fmt.Sprintf(`aider --message-file %s`, absPrompt) - case loopCfg.ToolGeneric: + case cfgLoop.ToolGeneric: aiCommand = fmt.Sprintf(`# Replace with your AI CLI command cat %s | your-ai-cli`, absPrompt) } diff --git a/internal/cli/loop/loop.go b/internal/cli/loop/loop.go index eb5669f5d..70ec6ed5c 100644 --- a/internal/cli/loop/loop.go +++ b/internal/cli/loop/loop.go @@ -9,10 +9,10 @@ package loop import ( "github.com/spf13/cobra" - looproot "github.com/ActiveMemory/ctx/internal/cli/loop/cmd/root" + loopRoot "github.com/ActiveMemory/ctx/internal/cli/loop/cmd/root" ) // Cmd returns the "ctx loop" command for generating Ralph loop scripts. func Cmd() *cobra.Command { - return looproot.Cmd() + return loopRoot.Cmd() } diff --git a/internal/cli/mcp/cmd/root/doc.go b/internal/cli/mcp/cmd/root/doc.go new file mode 100644 index 000000000..ff8028673 --- /dev/null +++ b/internal/cli/mcp/cmd/root/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package root provides the run function for the ctx MCP server command. +package root diff --git a/internal/cli/memory/cmd/diff/run.go b/internal/cli/memory/cmd/diff/run.go index fda14375d..46a6586ce 100644 --- a/internal/cli/memory/cmd/diff/run.go +++ b/internal/cli/memory/cmd/diff/run.go @@ -11,7 +11,7 @@ import ( "github.com/spf13/cobra" - ctxErr "github.com/ActiveMemory/ctx/internal/err/memory" + errMemory "github.com/ActiveMemory/ctx/internal/err/memory" mem "github.com/ActiveMemory/ctx/internal/memory" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/memory" @@ -31,12 +31,12 @@ func Run(cmd *cobra.Command) error { sourcePath, discoverErr := mem.DiscoverMemoryPath(projectRoot) if discoverErr != nil { - return ctxErr.DiscoverFailed(discoverErr) + return errMemory.DiscoverFailed(discoverErr) } diff, diffErr := mem.Diff(contextDir, sourcePath) if diffErr != nil { - return ctxErr.DiffFailed(diffErr) + return errMemory.DiffFailed(diffErr) } if diff == "" { diff --git a/internal/cli/memory/cmd/publish/run.go b/internal/cli/memory/cmd/publish/run.go index 5ee5ed48c..cb2a0a508 100644 --- a/internal/cli/memory/cmd/publish/run.go +++ b/internal/cli/memory/cmd/publish/run.go @@ -11,7 +11,7 @@ import ( "github.com/spf13/cobra" - ctxErr "github.com/ActiveMemory/ctx/internal/err/memory" + errMemory "github.com/ActiveMemory/ctx/internal/err/memory" mem "github.com/ActiveMemory/ctx/internal/memory" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/publish" @@ -35,12 +35,12 @@ func Run(cmd *cobra.Command, budget int, dryRun bool) error { memoryPath, discoverErr := mem.DiscoverMemoryPath(projectRoot) if discoverErr != nil { sync.ErrAutoMemoryNotActive(cmd, discoverErr) - return ctxErr.NotFound() + return errMemory.NotFound() } result, selectErr := mem.SelectContent(contextDir, budget) if selectErr != nil { - return ctxErr.SelectContentFailed(selectErr) + return errMemory.SelectContentFailed(selectErr) } publish.PublishPlan(cmd, budget, @@ -57,7 +57,7 @@ func Run(cmd *cobra.Command, budget int, dryRun bool) error { if _, publishErr := mem.Publish( contextDir, memoryPath, budget, ); publishErr != nil { - return ctxErr.PublishFailed(publishErr) + return errMemory.PublishFailed(publishErr) } publish.PublishDone(cmd) diff --git a/internal/cli/memory/cmd/sync/run.go b/internal/cli/memory/cmd/sync/run.go index 276c45fd5..3bf133dea 100644 --- a/internal/cli/memory/cmd/sync/run.go +++ b/internal/cli/memory/cmd/sync/run.go @@ -13,7 +13,7 @@ import ( cfgMem "github.com/ActiveMemory/ctx/internal/config/memory" errMem "github.com/ActiveMemory/ctx/internal/err/memory" - ctxErr "github.com/ActiveMemory/ctx/internal/err/state" + errState "github.com/ActiveMemory/ctx/internal/err/state" "github.com/ActiveMemory/ctx/internal/memory" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/sync" @@ -59,11 +59,11 @@ func Run(cmd *cobra.Command, dryRun bool) error { // Update sync state state, loadErr := memory.LoadState(contextDir) if loadErr != nil { - return ctxErr.Load(loadErr) + return errState.Load(loadErr) } state.MarkSynced() if saveErr := memory.SaveState(contextDir, state); saveErr != nil { - return ctxErr.Save(saveErr) + return errState.Save(saveErr) } return nil diff --git a/internal/cli/notify/cmd/setup/run.go b/internal/cli/notify/cmd/setup/run.go index ca7c60497..55a035ad5 100644 --- a/internal/cli/notify/cmd/setup/run.go +++ b/internal/cli/notify/cmd/setup/run.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/crypto" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/notify" + errNotify "github.com/ActiveMemory/ctx/internal/err/notify" iNotify "github.com/ActiveMemory/ctx/internal/notify" "github.com/ActiveMemory/ctx/internal/write/notify" ) @@ -39,11 +39,11 @@ func Run(cmd *cobra.Command, stdin *os.File) error { } url := strings.TrimSpace(scanner.Text()) if url == "" { - return ctxErr.WebhookEmpty() + return errNotify.WebhookEmpty() } if saveErr := iNotify.SaveWebhook(url); saveErr != nil { - return ctxErr.SaveWebhook(saveErr) + return errNotify.SaveWebhook(saveErr) } notify.SetupDone(cmd, iNotify.MaskURL(url), crypto.NotifyEnc) diff --git a/internal/cli/notify/cmd/test/run.go b/internal/cli/notify/cmd/test/run.go index ed414fb40..27b94f3e8 100644 --- a/internal/cli/notify/cmd/test/run.go +++ b/internal/cli/notify/cmd/test/run.go @@ -15,10 +15,10 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/config/crypto" - ctxErr "github.com/ActiveMemory/ctx/internal/err/notify" + errNotify "github.com/ActiveMemory/ctx/internal/err/notify" "github.com/ActiveMemory/ctx/internal/notify" "github.com/ActiveMemory/ctx/internal/rc" - iNotify "github.com/ActiveMemory/ctx/internal/write/notify" + writeNotify "github.com/ActiveMemory/ctx/internal/write/notify" ) // runTest sends a test notification to the configured webhook. @@ -31,10 +31,10 @@ import ( func runTest(cmd *cobra.Command) error { url, loadErr := notify.LoadWebhook() if loadErr != nil { - return ctxErr.LoadWebhook(loadErr) + return errNotify.LoadWebhook(loadErr) } if url == "" { - iNotify.TestNoWebhook(cmd) + writeNotify.TestNoWebhook(cmd) return nil } @@ -52,20 +52,20 @@ func runTest(cmd *cobra.Command) error { body, marshalErr := json.Marshal(payload) if marshalErr != nil { - return ctxErr.MarshalPayload(marshalErr) + return errNotify.MarshalPayload(marshalErr) } if !notify.EventAllowed("test", rc.NotifyEvents()) { - iNotify.TestFiltered(cmd) + writeNotify.TestFiltered(cmd) } resp, postErr := notify.PostJSON(url, body) if postErr != nil { - return ctxErr.SendNotification(postErr) + return errNotify.SendNotification(postErr) } defer func() { _ = resp.Body.Close() }() - iNotify.TestResult(cmd, resp.StatusCode, crypto.NotifyEnc) + writeNotify.TestResult(cmd, resp.StatusCode, crypto.NotifyEnc) return nil } diff --git a/internal/cli/notify/notify_test.go b/internal/cli/notify/notify_test.go index 92ef8058e..90a39c95e 100644 --- a/internal/cli/notify/notify_test.go +++ b/internal/cli/notify/notify_test.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/notify/cmd/setup" "github.com/ActiveMemory/ctx/internal/config/ctx" - notifylib "github.com/ActiveMemory/ctx/internal/notify" + libNotify "github.com/ActiveMemory/ctx/internal/notify" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -139,9 +139,9 @@ func TestMaskURL(t *testing.T) { } for _, tc := range tests { - got := notifylib.MaskURL(tc.input) + got := libNotify.MaskURL(tc.input) if got != tc.want { - t.Errorf("notifylib.MaskURL(%q) = %q, want %q", tc.input, got, tc.want) + t.Errorf("libNotify.MaskURL(%q) = %q, want %q", tc.input, got, tc.want) } } } @@ -206,7 +206,7 @@ func TestTest_WebhookSuccess(t *testing.T) { defer server.Close() // Save the test server URL as the webhook. - if saveErr := notifylib.SaveWebhook(server.URL); saveErr != nil { + if saveErr := libNotify.SaveWebhook(server.URL); saveErr != nil { t.Fatalf("SaveWebhook() error = %v", saveErr) } @@ -240,7 +240,7 @@ func TestTest_WebhookServerError(t *testing.T) { })) defer server.Close() - if saveErr := notifylib.SaveWebhook(server.URL); saveErr != nil { + if saveErr := libNotify.SaveWebhook(server.URL); saveErr != nil { t.Fatalf("SaveWebhook() error = %v", saveErr) } diff --git a/internal/cli/pad/cmd/add/run.go b/internal/cli/pad/cmd/add/run.go index d6a24d95b..367c23d35 100644 --- a/internal/cli/pad/cmd/add/run.go +++ b/internal/cli/pad/cmd/add/run.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/pad" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" "github.com/ActiveMemory/ctx/internal/io" writePad "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -58,7 +58,7 @@ func runAddBlob(cmd *cobra.Command, label, filePath string) error { } if len(data) > pad.MaxBlobSize { - return ctxErr.FileTooLarge(len(data), pad.MaxBlobSize) + return errPad.FileTooLarge(len(data), pad.MaxBlobSize) } entries, readErr := store.ReadEntries() diff --git a/internal/cli/pad/cmd/edit/cmd.go b/internal/cli/pad/cmd/edit/cmd.go index eabf01247..986aaf45f 100644 --- a/internal/cli/pad/cmd/edit/cmd.go +++ b/internal/cli/pad/cmd/edit/cmd.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/embed/cmd" "github.com/ActiveMemory/ctx/internal/config/embed/flag" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" - ctxErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" ) // Cmd returns the pad edit subcommand. @@ -48,7 +48,7 @@ func Cmd() *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { n, err := strconv.Atoi(args[0]) if err != nil { - return ctxErr.InvalidIndex(args[0]) + return errPad.InvalidIndex(args[0]) } hasPositional := len(args) == 2 @@ -59,7 +59,7 @@ func Cmd() *cobra.Command { // --file/--label conflict with positional/--append/--prepend. if (hasFile || hasLabel) && (hasPositional || hasAppend || hasPrepend) { - return ctxErr.EditBlobTextConflict() + return errPad.EditBlobTextConflict() } // Blob edit mode. @@ -80,10 +80,10 @@ func Cmd() *cobra.Command { } if flagCount == 0 { - return ctxErr.EditNoMode() + return errPad.EditNoMode() } if flagCount > 1 { - return ctxErr.EditTextConflict() + return errPad.EditTextConflict() } switch { diff --git a/internal/cli/pad/cmd/edit/run.go b/internal/cli/pad/cmd/edit/run.go index 957814ea2..370c938b0 100644 --- a/internal/cli/pad/cmd/edit/run.go +++ b/internal/cli/pad/cmd/edit/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/pad" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" "github.com/ActiveMemory/ctx/internal/io" writePad "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -68,7 +68,7 @@ func runEditAppend(cmd *cobra.Command, n int, text string) error { } if blob.ContainsBlob(entries[n-1]) { - return ctxErr.BlobAppendNotAllowed() + return errPad.BlobAppendNotAllowed() } entries[n-1] = entries[n-1] + " " + text @@ -101,7 +101,7 @@ func runEditPrepend(cmd *cobra.Command, n int, text string) error { } if blob.ContainsBlob(entries[n-1]) { - return ctxErr.BlobPrependNotAllowed() + return errPad.BlobPrependNotAllowed() } entries[n-1] = text + " " + entries[n-1] @@ -136,7 +136,7 @@ func runEditBlob(cmd *cobra.Command, n int, filePath, labelText string) error { oldLabel, oldData, ok := blob.SplitBlob(entries[n-1]) if !ok { - return ctxErr.NotBlobEntry(n) + return errPad.NotBlobEntry(n) } newLabel := oldLabel @@ -152,7 +152,7 @@ func runEditBlob(cmd *cobra.Command, n int, filePath, labelText string) error { return fs.ReadFile(readErr) } if len(data) > pad.MaxBlobSize { - return ctxErr.FileTooLarge(len(data), pad.MaxBlobSize) + return errPad.FileTooLarge(len(data), pad.MaxBlobSize) } newData = data } diff --git a/internal/cli/pad/cmd/export/run.go b/internal/cli/pad/cmd/export/run.go index d56aa3045..b07113e30 100644 --- a/internal/cli/pad/cmd/export/run.go +++ b/internal/cli/pad/cmd/export/run.go @@ -18,7 +18,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/token" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/write/export" "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -53,7 +53,7 @@ func runExport(cmd *cobra.Command, dir string, force, dryRun bool) error { if !dryRun { if mkErr := os.MkdirAll(dir, fs.PermExec); mkErr != nil { - return ctxErr.Mkdir(dir, mkErr) + return errFs.Mkdir(dir, mkErr) } } diff --git a/internal/cli/pad/cmd/imp/run.go b/internal/cli/pad/cmd/imp/run.go index 0ac62861b..9bf391e99 100644 --- a/internal/cli/pad/cmd/imp/run.go +++ b/internal/cli/pad/cmd/imp/run.go @@ -18,7 +18,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/pad" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" internalIo "github.com/ActiveMemory/ctx/internal/io" writePad "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -38,7 +38,7 @@ func runImport(cmd *cobra.Command, file string) error { } else { f, err := internalIo.SafeOpenUserFile(file) if err != nil { - return ctxErr.OpenFile(file, err) + return errFs.OpenFile(file, err) } defer func() { if cErr := f.Close(); cErr != nil { @@ -64,7 +64,7 @@ func runImport(cmd *cobra.Command, file string) error { count++ } if scanErr := scanner.Err(); scanErr != nil { - return ctxErr.ReadInput(scanErr) + return errFs.ReadInput(scanErr) } if count == 0 { @@ -92,15 +92,15 @@ func runImport(cmd *cobra.Command, file string) error { func runImportBlobs(cmd *cobra.Command, path string) error { info, statErr := os.Stat(path) if statErr != nil { - return ctxErr.StatPath(path, statErr) + return errFs.StatPath(path, statErr) } if !info.IsDir() { - return ctxErr.NotDirectory(path) + return errFs.NotDirectory(path) } dirEntries, readErr := os.ReadDir(path) if readErr != nil { - return ctxErr.ReadDirectory(path, readErr) + return errFs.ReadDirectory(path, readErr) } entries, loadErr := store.ReadEntries() diff --git a/internal/cli/pad/cmd/merge/run.go b/internal/cli/pad/cmd/merge/run.go index 2e2127637..6d756e5ba 100644 --- a/internal/cli/pad/cmd/merge/run.go +++ b/internal/cli/pad/cmd/merge/run.go @@ -12,7 +12,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/pad/core/store" "github.com/spf13/cobra" - ctEerr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -53,7 +53,7 @@ func Run( for _, file := range files { entries, fileErr := merge.ReadFileEntries(file, key) if fileErr != nil { - return ctEerr.OpenFile(file, fileErr) + return errFs.OpenFile(file, fileErr) } if merge.HasBinaryEntries(entries) { diff --git a/internal/cli/pad/cmd/resolve/run.go b/internal/cli/pad/cmd/resolve/run.go index 6d9a572a2..a5b9a81ad 100644 --- a/internal/cli/pad/cmd/resolve/run.go +++ b/internal/cli/pad/cmd/resolve/run.go @@ -7,14 +7,14 @@ package resolve import ( - crypto2 "github.com/ActiveMemory/ctx/internal/cli/pad/core/crypto" + padCrypto "github.com/ActiveMemory/ctx/internal/cli/pad/core/crypto" "github.com/ActiveMemory/ctx/internal/cli/pad/core/store" "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/config/pad" "github.com/ActiveMemory/ctx/internal/crypto" errCrypto "github.com/ActiveMemory/ctx/internal/err/crypto" - ctxErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" "github.com/ActiveMemory/ctx/internal/rc" writePad "github.com/ActiveMemory/ctx/internal/write/pad" ) @@ -28,7 +28,7 @@ import ( // - error: Non-nil if no conflict files found or decryption fails func Run(cmd *cobra.Command) error { if !rc.ScratchpadEncrypt() { - return ctxErr.ResolveNotEncrypted() + return errPad.ResolveNotEncrypted() } kp := store.KeyPath() @@ -39,11 +39,11 @@ func Run(cmd *cobra.Command) error { dir := rc.ContextDir() - ours, errOurs := crypto2.DecryptFile(key, dir, pad.EncOurs) - theirs, errTheirs := crypto2.DecryptFile(key, dir, pad.EncTheirs) + ours, errOurs := padCrypto.DecryptFile(key, dir, pad.EncOurs) + theirs, errTheirs := padCrypto.DecryptFile(key, dir, pad.EncTheirs) if errOurs != nil && errTheirs != nil { - return ctxErr.NoConflictFiles(pad.Enc) + return errPad.NoConflictFiles(pad.Enc) } if errOurs == nil { diff --git a/internal/cli/pad/cmd/show/cmd.go b/internal/cli/pad/cmd/show/cmd.go index f34db02b9..589af9b57 100644 --- a/internal/cli/pad/cmd/show/cmd.go +++ b/internal/cli/pad/cmd/show/cmd.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/embed/cmd" "github.com/ActiveMemory/ctx/internal/config/embed/flag" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" - ctxErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" ) // Cmd returns the pad show subcommand. @@ -39,7 +39,7 @@ func Cmd() *cobra.Command { RunE: func(cmd *cobra.Command, args []string) error { n, err := strconv.Atoi(args[0]) if err != nil { - return ctxErr.InvalidIndex(args[0]) + return errPad.InvalidIndex(args[0]) } return Run(cmd, n, outPath) }, diff --git a/internal/cli/pad/core/blob/doc.go b/internal/cli/pad/core/blob/doc.go new file mode 100644 index 000000000..6d0d979fb --- /dev/null +++ b/internal/cli/pad/core/blob/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package blob handles binary blob encoding and decoding within scratchpad entries. +package blob diff --git a/internal/cli/pad/core/crypto/crypto.go b/internal/cli/pad/core/crypto/crypto.go index 00c086e53..d58df0515 100644 --- a/internal/cli/pad/core/crypto/crypto.go +++ b/internal/cli/pad/core/crypto/crypto.go @@ -9,7 +9,7 @@ package crypto import ( "github.com/ActiveMemory/ctx/internal/cli/pad/core/parse" "github.com/ActiveMemory/ctx/internal/crypto" - ctxErr "github.com/ActiveMemory/ctx/internal/err/crypto" + errCrypto "github.com/ActiveMemory/ctx/internal/err/crypto" "github.com/ActiveMemory/ctx/internal/io" ) @@ -31,7 +31,7 @@ func DecryptFile(key []byte, baseDir, filename string) ([]string, error) { plaintext, decErr := crypto.Decrypt(key, data) if decErr != nil { - return nil, ctxErr.DecryptFailed() + return nil, errCrypto.DecryptFailed() } return parse.ParseEntries(plaintext), nil diff --git a/internal/cli/pad/core/crypto/doc.go b/internal/cli/pad/core/crypto/doc.go new file mode 100644 index 000000000..82960565a --- /dev/null +++ b/internal/cli/pad/core/crypto/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package crypto reads and decrypts encrypted scratchpad files. +package crypto diff --git a/internal/cli/pad/core/merge/doc.go b/internal/cli/pad/core/merge/doc.go new file mode 100644 index 000000000..99ec238fb --- /dev/null +++ b/internal/cli/pad/core/merge/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package merge reads scratchpad files with automatic decryption fallback and merges entries. +package merge diff --git a/internal/cli/pad/core/parse/doc.go b/internal/cli/pad/core/parse/doc.go new file mode 100644 index 000000000..05e46615b --- /dev/null +++ b/internal/cli/pad/core/parse/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package parse splits raw scratchpad content into individual entry lines. +package parse diff --git a/internal/cli/pad/core/store/doc.go b/internal/cli/pad/core/store/doc.go new file mode 100644 index 000000000..db368d1fa --- /dev/null +++ b/internal/cli/pad/core/store/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package store manages scratchpad file persistence including encryption and path resolution. +package store diff --git a/internal/cli/pad/core/validate/doc.go b/internal/cli/pad/core/validate/doc.go new file mode 100644 index 000000000..292fbfe66 --- /dev/null +++ b/internal/cli/pad/core/validate/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package validate checks that scratchpad entry indexes are within valid bounds. +package validate diff --git a/internal/cli/pad/core/validate/validate.go b/internal/cli/pad/core/validate/validate.go index 55ef7f5c9..eafec942f 100644 --- a/internal/cli/pad/core/validate/validate.go +++ b/internal/cli/pad/core/validate/validate.go @@ -7,7 +7,7 @@ package validate import ( - padErr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" ) // ValidateIndex checks that n is a valid 1-based index into entries. @@ -20,7 +20,7 @@ import ( // - error: Non-nil if n is out of range func ValidateIndex(n int, entries []string) error { if n < 1 || n > len(entries) { - return padErr.EntryRange(n, len(entries)) + return errPad.EntryRange(n, len(entries)) } return nil } diff --git a/internal/cli/pad/pad_test.go b/internal/cli/pad/pad_test.go index 31e41c7ca..76fca73d9 100644 --- a/internal/cli/pad/pad_test.go +++ b/internal/cli/pad/pad_test.go @@ -16,13 +16,13 @@ import ( "testing" "github.com/ActiveMemory/ctx/internal/cli/pad/core/blob" - crypto2 "github.com/ActiveMemory/ctx/internal/cli/pad/core/crypto" + padCrypto "github.com/ActiveMemory/ctx/internal/cli/pad/core/crypto" "github.com/ActiveMemory/ctx/internal/cli/pad/core/parse" "github.com/ActiveMemory/ctx/internal/cli/pad/core/store" "github.com/ActiveMemory/ctx/internal/cli/pad/core/validate" "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/pad" - ctxerr "github.com/ActiveMemory/ctx/internal/err/pad" + errPad "github.com/ActiveMemory/ctx/internal/err/pad" "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/config/fs" @@ -632,7 +632,7 @@ func TestValidateIndex_EmptySlice(t *testing.T) { } func TestErrEntryRange(t *testing.T) { - err := ctxerr.EntryRange(5, 3) + err := errPad.EntryRange(5, 3) msg := err.Error() if !strings.Contains(msg, "5") || !strings.Contains(msg, "3") { t.Errorf("EntryRange = %q, want indices 5 and 3 mentioned", msg) @@ -1123,7 +1123,7 @@ func TestDecryptFile_BadData(t *testing.T) { t.Fatal(writeErr) } - _, err := crypto2.DecryptFile(key, tmpDir, "bad.enc") + _, err := padCrypto.DecryptFile(key, tmpDir, "bad.enc") if err == nil { t.Fatal("expected decryption error for bad data") } @@ -1136,7 +1136,7 @@ func TestDecryptFile_MissingFile(t *testing.T) { key, _ := crypto.GenerateKey() tmpDir := t.TempDir() - _, err := crypto2.DecryptFile(key, tmpDir, "nonexistent.enc") + _, err := padCrypto.DecryptFile(key, tmpDir, "nonexistent.enc") if err == nil { t.Fatal("expected error for missing file") } @@ -1155,7 +1155,7 @@ func TestDecryptFile_ValidData(t *testing.T) { t.Fatal(writeErr) } - entries, err := crypto2.DecryptFile(key, tmpDir, "good.enc") + entries, err := padCrypto.DecryptFile(key, tmpDir, "good.enc") if err != nil { t.Fatalf("decryptFile error: %v", err) } diff --git a/internal/cli/pause/cmd/root/run.go b/internal/cli/pause/cmd/root/run.go index 58ba077b0..4f327b31e 100644 --- a/internal/cli/pause/cmd/root/run.go +++ b/internal/cli/pause/cmd/root/run.go @@ -10,7 +10,7 @@ import ( "os" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" - session2 "github.com/ActiveMemory/ctx/internal/cli/system/core/session" + coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/write/session" @@ -26,7 +26,7 @@ import ( // - error: Always nil func Run(cmd *cobra.Command, sessionID string) error { if sessionID == "" { - sessionID = session2.ReadSessionID(os.Stdin) + sessionID = coreSession.ReadSessionID(os.Stdin) } nudge.Pause(sessionID) session.SessionPaused(cmd, sessionID) diff --git a/internal/cli/permission/cmd/restore/run.go b/internal/cli/permission/cmd/restore/run.go index af50d3562..075aa38de 100644 --- a/internal/cli/permission/cmd/restore/run.go +++ b/internal/cli/permission/cmd/restore/run.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/claude" "github.com/ActiveMemory/ctx/internal/cli/permission/core" - configClaude "github.com/ActiveMemory/ctx/internal/config/claude" + cfgClaude "github.com/ActiveMemory/ctx/internal/config/claude" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/err/config" errFs "github.com/ActiveMemory/ctx/internal/err/fs" @@ -31,26 +31,26 @@ import ( // Returns: // - error: Non-nil on read/write/parse failure or missing golden file func Run(cmd *cobra.Command) error { - goldenBytes, goldenReadErr := os.ReadFile(configClaude.SettingsGolden) + goldenBytes, goldenReadErr := os.ReadFile(cfgClaude.SettingsGolden) if goldenReadErr != nil { if os.IsNotExist(goldenReadErr) { return config.GoldenNotFound() } - return errFs.FileRead(configClaude.SettingsGolden, goldenReadErr) + return errFs.FileRead(cfgClaude.SettingsGolden, goldenReadErr) } - localBytes, localReadErr := os.ReadFile(configClaude.Settings) + localBytes, localReadErr := os.ReadFile(cfgClaude.Settings) if localReadErr != nil { if os.IsNotExist(localReadErr) { if writeErr := os.WriteFile( - configClaude.Settings, goldenBytes, fs.PermFile, + cfgClaude.Settings, goldenBytes, fs.PermFile, ); writeErr != nil { - return errFs.FileWrite(configClaude.Settings, writeErr) + return errFs.FileWrite(cfgClaude.Settings, writeErr) } restore.RestoreNoLocal(cmd) return nil } - return errFs.FileRead(configClaude.Settings, localReadErr) + return errFs.FileRead(cfgClaude.Settings, localReadErr) } if bytes.Equal(goldenBytes, localBytes) { @@ -60,10 +60,10 @@ func Run(cmd *cobra.Command) error { var golden, local claude.Settings if goldenParseErr := json.Unmarshal(goldenBytes, &golden); goldenParseErr != nil { - return errParser.ParseFile(configClaude.SettingsGolden, goldenParseErr) + return errParser.ParseFile(cfgClaude.SettingsGolden, goldenParseErr) } if localParseErr := json.Unmarshal(localBytes, &local); localParseErr != nil { - return errParser.ParseFile(configClaude.Settings, localParseErr) + return errParser.ParseFile(cfgClaude.Settings, localParseErr) } restored, dropped := core.DiffStringSlices( @@ -76,9 +76,9 @@ func Run(cmd *cobra.Command) error { restore.RestoreDiff(cmd, dropped, restored, denyDropped, denyRestored) if writeErr := os.WriteFile( - configClaude.Settings, goldenBytes, fs.PermFile, + cfgClaude.Settings, goldenBytes, fs.PermFile, ); writeErr != nil { - return errFs.FileWrite(configClaude.Settings, writeErr) + return errFs.FileWrite(cfgClaude.Settings, writeErr) } restore.RestoreDone(cmd) diff --git a/internal/cli/permission/cmd/snapshot/run.go b/internal/cli/permission/cmd/snapshot/run.go index d338a44f5..5d221a0d7 100644 --- a/internal/cli/permission/cmd/snapshot/run.go +++ b/internal/cli/permission/cmd/snapshot/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/claude" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/err/config" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/write/restore" ) @@ -31,7 +31,7 @@ func Run(cmd *cobra.Command) error { if os.IsNotExist(readErr) { return config.SettingsNotFound() } - return ctxErr.FileRead(claude.Settings, readErr) + return errFs.FileRead(claude.Settings, readErr) } updated := false @@ -42,7 +42,7 @@ func Run(cmd *cobra.Command) error { if writeErr := os.WriteFile( claude.SettingsGolden, content, fs.PermFile, ); writeErr != nil { - return ctxErr.FileWrite(claude.SettingsGolden, writeErr) + return errFs.FileWrite(claude.SettingsGolden, writeErr) } restore.SnapshotDone(cmd, updated, claude.SettingsGolden) diff --git a/internal/cli/prompt/cmd/add/run.go b/internal/cli/prompt/cmd/add/run.go index 6a4860c51..4bd06d582 100644 --- a/internal/cli/prompt/cmd/add/run.go +++ b/internal/cli/prompt/cmd/add/run.go @@ -18,7 +18,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/config/fs" errFs "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/prompt" + errPrompt "github.com/ActiveMemory/ctx/internal/err/prompt" "github.com/ActiveMemory/ctx/internal/write/prompt" ) @@ -41,7 +41,7 @@ func runAdd(cmd *cobra.Command, name string, fromStdin bool) error { // Check if the file already exists. if _, statErr := os.Stat(path); statErr == nil { - return ctxErr.Exists(name) + return errPrompt.Exists(name) } var content []byte @@ -57,7 +57,7 @@ func runAdd(cmd *cobra.Command, name string, fromStdin bool) error { var templateErr error content, templateErr = readPrompt.Template(name + file.ExtMarkdown) if templateErr != nil { - return ctxErr.NoPromptTemplate(name) + return errPrompt.NoPromptTemplate(name) } } diff --git a/internal/cli/prompt/cmd/list/run.go b/internal/cli/prompt/cmd/list/run.go index c0fabfefb..221393b80 100644 --- a/internal/cli/prompt/cmd/list/run.go +++ b/internal/cli/prompt/cmd/list/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/prompt/core" "github.com/ActiveMemory/ctx/internal/config/file" - ctxErr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/write/prompt" ) @@ -34,7 +34,7 @@ func Run(cmd *cobra.Command) error { prompt.PromptNone(cmd) return nil } - return ctxErr.ReadDirectory(dir, readErr) + return errFs.ReadDirectory(dir, readErr) } var found bool diff --git a/internal/cli/prompt/cmd/rm/run.go b/internal/cli/prompt/cmd/rm/run.go index 25c05c55f..8448e7add 100644 --- a/internal/cli/prompt/cmd/rm/run.go +++ b/internal/cli/prompt/cmd/rm/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/prompt/core" "github.com/ActiveMemory/ctx/internal/config/file" - ctxErr "github.com/ActiveMemory/ctx/internal/err/prompt" + errPrompt "github.com/ActiveMemory/ctx/internal/err/prompt" "github.com/ActiveMemory/ctx/internal/write/prompt" ) @@ -30,11 +30,11 @@ func Run(cmd *cobra.Command, name string) error { path := filepath.Join(core.PromptsDir(), name+file.ExtMarkdown) if _, statErr := os.Stat(path); os.IsNotExist(statErr) { - return ctxErr.NotFound(name) + return errPrompt.NotFound(name) } if removeErr := os.Remove(path); removeErr != nil { - return ctxErr.Remove(removeErr) + return errPrompt.Remove(removeErr) } prompt.Removed(cmd, name) diff --git a/internal/cli/prompt/cmd/show/run.go b/internal/cli/prompt/cmd/show/run.go index 8c9bfa545..463667ca3 100644 --- a/internal/cli/prompt/cmd/show/run.go +++ b/internal/cli/prompt/cmd/show/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/prompt/core" "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/prompt" + errPrompt "github.com/ActiveMemory/ctx/internal/err/prompt" "github.com/ActiveMemory/ctx/internal/io" writePrompt "github.com/ActiveMemory/ctx/internal/write/prompt" ) @@ -33,7 +33,7 @@ func Run(cmd *cobra.Command, name string) error { ) if readErr != nil { if os.IsNotExist(readErr) { - return ctxErr.NotFound(name) + return errPrompt.NotFound(name) } return fs.ReadFile(readErr) } diff --git a/internal/cli/recall/cmd/export/run.go b/internal/cli/recall/cmd/export/run.go index 512dc562c..5a7b53289 100644 --- a/internal/cli/recall/cmd/export/run.go +++ b/internal/cli/recall/cmd/export/run.go @@ -27,7 +27,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/journal" errFs "github.com/ActiveMemory/ctx/internal/err/fs" errJournal "github.com/ActiveMemory/ctx/internal/err/journal" - ctxErr "github.com/ActiveMemory/ctx/internal/err/session" + errSession "github.com/ActiveMemory/ctx/internal/err/session" "github.com/ActiveMemory/ctx/internal/journal/state" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/err" @@ -64,7 +64,7 @@ func Run(cmd *cobra.Command, args []string, opts entity.ExportOpts) error { // 3. Resolve sessions. sessions, scanErr := query.FindSessions(opts.AllProjects) if scanErr != nil { - return ctxErr.Find(scanErr) + return errSession.Find(scanErr) } if len(sessions) == 0 { @@ -85,12 +85,12 @@ func Run(cmd *cobra.Command, args []string, opts entity.ExportOpts) error { } } if len(toExport) == 0 { - return ctxErr.NotFound(args[0]) + return errSession.NotFound(args[0]) } if len(toExport) > 1 { lines := format.SessionMatchLines(toExport) recall.AmbiguousSessionMatch(cmd, args[0], lines) - return ctxErr.AmbiguousQuery() + return errSession.AmbiguousQuery() } singleSession = true } diff --git a/internal/cli/recall/cmd/list/run.go b/internal/cli/recall/cmd/list/run.go index 9919a0d09..c439ce1db 100644 --- a/internal/cli/recall/cmd/list/run.go +++ b/internal/cli/recall/cmd/list/run.go @@ -22,7 +22,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/err/date" - ctxErr "github.com/ActiveMemory/ctx/internal/err/session" + errSession "github.com/ActiveMemory/ctx/internal/err/session" "github.com/ActiveMemory/ctx/internal/parse" "github.com/ActiveMemory/ctx/internal/write/recall" ) @@ -64,7 +64,7 @@ func Run( sessions, scanErr := query.FindSessions(allProjects) if scanErr != nil { - return ctxErr.Find(scanErr) + return errSession.Find(scanErr) } if len(sessions) == 0 { diff --git a/internal/cli/recall/cmd/show/run.go b/internal/cli/recall/cmd/show/run.go index 82b6a3176..247c18b05 100644 --- a/internal/cli/recall/cmd/show/run.go +++ b/internal/cli/recall/cmd/show/run.go @@ -19,7 +19,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" - ctxErr "github.com/ActiveMemory/ctx/internal/err/session" + errSession "github.com/ActiveMemory/ctx/internal/err/session" "github.com/ActiveMemory/ctx/internal/write/recall" ) @@ -42,14 +42,14 @@ func Run( ) error { sessions, scanErr := query.FindSessions(allProjects) if scanErr != nil { - return ctxErr.Find(scanErr) + return errSession.Find(scanErr) } if len(sessions) == 0 { if allProjects { - return ctxErr.NoneFound("") + return errSession.NoneFound("") } - return ctxErr.NoneFound(desc.Text(text.DescKeyLabelHintUseAllProjects)) + return errSession.NoneFound(desc.Text(text.DescKeyLabelHintUseAllProjects)) } var session *entity.Session @@ -58,7 +58,7 @@ func Run( case latest: session = sessions[0] case len(args) == 0: - return ctxErr.IDRequired() + return errSession.IDRequired() default: query := strings.ToLower(args[0]) var matches []*entity.Session @@ -69,14 +69,14 @@ func Run( } } if len(matches) == 0 { - return ctxErr.NotFound(args[0]) + return errSession.NotFound(args[0]) } if len(matches) > 1 { lines := format.SessionMatchLines(matches) recall.AmbiguousSessionMatchWithHint( cmd, args[0], lines, matches[0].ID[:journal.SessionIDHintLen], ) - return ctxErr.AmbiguousQuery() + return errSession.AmbiguousQuery() } session = matches[0] } diff --git a/internal/cli/recall/cmd/sync/run.go b/internal/cli/recall/cmd/sync/run.go index 805c22be1..00f0604f9 100644 --- a/internal/cli/recall/cmd/sync/run.go +++ b/internal/cli/recall/cmd/sync/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/journal" - ctxErr "github.com/ActiveMemory/ctx/internal/err/journal" + errJournal "github.com/ActiveMemory/ctx/internal/err/journal" "github.com/ActiveMemory/ctx/internal/journal/state" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/write/recall" @@ -33,7 +33,7 @@ func Run(cmd *cobra.Command) error { jstate, loadErr := state.Load(journalDir) if loadErr != nil { - return ctxErr.LoadState(loadErr) + return errJournal.LoadState(loadErr) } files, matchErr := lock.MatchJournalFiles(journalDir, nil, true) @@ -65,7 +65,7 @@ func Run(cmd *cobra.Command) error { } if saveErr := jstate.Save(journalDir); saveErr != nil { - return ctxErr.SaveState(saveErr) + return errJournal.SaveState(saveErr) } recall.JournalSyncSummary(cmd, locked, unlocked) diff --git a/internal/cli/recall/core/confirm/doc.go b/internal/cli/recall/core/confirm/doc.go new file mode 100644 index 000000000..608d83999 --- /dev/null +++ b/internal/cli/recall/core/confirm/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package confirm prompts the user to confirm an export plan before execution. +package confirm diff --git a/internal/cli/recall/core/execute/doc.go b/internal/cli/recall/core/execute/doc.go new file mode 100644 index 000000000..2041f71f4 --- /dev/null +++ b/internal/cli/recall/core/execute/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package execute writes journal files according to an export plan. +package execute diff --git a/internal/cli/recall/core/extract/doc.go b/internal/cli/recall/core/extract/doc.go new file mode 100644 index 000000000..b4e04786d --- /dev/null +++ b/internal/cli/recall/core/extract/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package extract extracts YAML frontmatter blocks from Markdown content. +package extract diff --git a/internal/cli/recall/core/format/doc.go b/internal/cli/recall/core/format/doc.go new file mode 100644 index 000000000..fa077e84d --- /dev/null +++ b/internal/cli/recall/core/format/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package format transforms session data into formatted journal Markdown with frontmatter and turn headers. +package format diff --git a/internal/cli/recall/core/frontmatter/doc.go b/internal/cli/recall/core/frontmatter/doc.go new file mode 100644 index 000000000..388a2d953 --- /dev/null +++ b/internal/cli/recall/core/frontmatter/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package frontmatter resolves headings and builds YAML frontmatter for journal entries. +package frontmatter diff --git a/internal/cli/recall/core/index/doc.go b/internal/cli/recall/core/index/doc.go new file mode 100644 index 000000000..ef34d39dd --- /dev/null +++ b/internal/cli/recall/core/index/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package index builds a session-ID-to-filename index from existing journal files. +package index diff --git a/internal/cli/recall/core/lock/doc.go b/internal/cli/recall/core/lock/doc.go new file mode 100644 index 000000000..887ee5e0a --- /dev/null +++ b/internal/cli/recall/core/lock/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package lock marks journal entries as locked to prevent re-export and manages multipart files. +package lock diff --git a/internal/cli/recall/core/lock/lock.go b/internal/cli/recall/core/lock/lock.go index ab3dfa931..2ce46d763 100644 --- a/internal/cli/recall/core/lock/lock.go +++ b/internal/cli/recall/core/lock/lock.go @@ -21,7 +21,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/session" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/err/journal" - ctxErr "github.com/ActiveMemory/ctx/internal/err/session" + errSession "github.com/ActiveMemory/ctx/internal/err/session" "github.com/ActiveMemory/ctx/internal/io" "github.com/ActiveMemory/ctx/internal/journal/state" "github.com/ActiveMemory/ctx/internal/rc" @@ -244,7 +244,7 @@ func RunLockUnlock( return cmd.Help() } if len(args) > 0 && all { - return ctxErr.AllWithPattern() + return errSession.AllWithPattern() } journalDir := filepath.Join(rc.ContextDir(), dir.Journal) diff --git a/internal/cli/recall/core/plan/doc.go b/internal/cli/recall/core/plan/doc.go new file mode 100644 index 000000000..c4c0d0967 --- /dev/null +++ b/internal/cli/recall/core/plan/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package plan builds an export plan that maps sessions to journal output files. +package plan diff --git a/internal/cli/recall/core/query/doc.go b/internal/cli/recall/core/query/doc.go new file mode 100644 index 000000000..17ca9a780 --- /dev/null +++ b/internal/cli/recall/core/query/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package query finds sessions for the current or all projects. +package query diff --git a/internal/cli/recall/core/query/query.go b/internal/cli/recall/core/query/query.go index efbe7cd57..c57ea8705 100644 --- a/internal/cli/recall/core/query/query.go +++ b/internal/cli/recall/core/query/query.go @@ -10,7 +10,7 @@ import ( "os" "github.com/ActiveMemory/ctx/internal/entity" - errfs "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/recall/parser" ) @@ -29,7 +29,7 @@ func FindSessions(allProjects bool) ([]*entity.Session, error) { } cwd, cwdErr := os.Getwd() if cwdErr != nil { - return nil, errfs.WorkingDirectory(cwdErr) + return nil, errFs.WorkingDirectory(cwdErr) } return parser.FindSessionsForCWD(cwd) } diff --git a/internal/cli/recall/core/slug/doc.go b/internal/cli/recall/core/slug/doc.go new file mode 100644 index 000000000..70e3ef884 --- /dev/null +++ b/internal/cli/recall/core/slug/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package slug converts human-readable titles into URL-friendly slugs for journal filenames. +package slug diff --git a/internal/cli/recall/core/validate/doc.go b/internal/cli/recall/core/validate/doc.go new file mode 100644 index 000000000..c8f65330e --- /dev/null +++ b/internal/cli/recall/core/validate/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package validate checks messages and flag combinations for recall export validity. +package validate diff --git a/internal/cli/recall/core/validate/validate.go b/internal/cli/recall/core/validate/validate.go index 0454f68a2..994020f27 100644 --- a/internal/cli/recall/core/validate/validate.go +++ b/internal/cli/recall/core/validate/validate.go @@ -9,7 +9,7 @@ package validate import ( "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/err/journal" - ctxErr "github.com/ActiveMemory/ctx/internal/err/session" + errSession "github.com/ActiveMemory/ctx/internal/err/session" ) // EmptyMessage reports whether a message has no meaningful content @@ -34,7 +34,7 @@ func EmptyMessage(msg entity.Message) bool { // - error: non-nil if flags conflict. func ExportFlags(args []string, opts entity.ExportOpts) error { if len(args) > 0 && opts.All { - return ctxErr.AllWithID() + return errSession.AllWithID() } if opts.Regenerate && !opts.All { return journal.RegenerateRequiresAll() diff --git a/internal/cli/remind/cmd/dismiss/cmd.go b/internal/cli/remind/cmd/dismiss/cmd.go index 009ce105a..2a11b20df 100644 --- a/internal/cli/remind/cmd/dismiss/cmd.go +++ b/internal/cli/remind/cmd/dismiss/cmd.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/embed/cmd" "github.com/ActiveMemory/ctx/internal/config/embed/flag" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" - ctxErr "github.com/ActiveMemory/ctx/internal/err/reminder" + errReminder "github.com/ActiveMemory/ctx/internal/err/reminder" ) // Cmd returns the remind dismiss subcommand. @@ -34,7 +34,7 @@ func Cmd() *cobra.Command { return RunDismissAll(cmd) } if len(args) == 0 { - return ctxErr.IDRequired() + return errReminder.IDRequired() } return RunDismiss(cmd, args[0]) }, diff --git a/internal/cli/remind/cmd/dismiss/run.go b/internal/cli/remind/cmd/dismiss/run.go index 9074cee90..0ee4bb190 100644 --- a/internal/cli/remind/cmd/dismiss/run.go +++ b/internal/cli/remind/cmd/dismiss/run.go @@ -12,7 +12,7 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/cli/remind/core" - ctxErr "github.com/ActiveMemory/ctx/internal/err/reminder" + errReminder "github.com/ActiveMemory/ctx/internal/err/reminder" "github.com/ActiveMemory/ctx/internal/write/remind" ) @@ -27,7 +27,7 @@ import ( func RunDismiss(cmd *cobra.Command, idStr string) error { id, parseErr := strconv.Atoi(idStr) if parseErr != nil { - return ctxErr.InvalidID(idStr) + return errReminder.InvalidID(idStr) } reminders, readErr := core.ReadReminders() @@ -44,7 +44,7 @@ func RunDismiss(cmd *cobra.Command, idStr string) error { } if found < 0 { - return ctxErr.NotFound(id) + return errReminder.NotFound(id) } remind.ReminderDismissed(cmd, reminders[found].ID, reminders[found].Message) diff --git a/internal/cli/remind/core/store.go b/internal/cli/remind/core/store.go index fd86a96af..41e19b7e7 100644 --- a/internal/cli/remind/core/store.go +++ b/internal/cli/remind/core/store.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/reminder" - ctxErr "github.com/ActiveMemory/ctx/internal/err/reminder" + errReminder "github.com/ActiveMemory/ctx/internal/err/reminder" "github.com/ActiveMemory/ctx/internal/io" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -30,11 +30,11 @@ func ReadReminders() ([]Reminder, error) { if errors.Is(readErr, os.ErrNotExist) { return nil, nil } - return nil, ctxErr.Read(readErr) + return nil, errReminder.Read(readErr) } var reminders []Reminder if parseErr := json.Unmarshal(data, &reminders); parseErr != nil { - return nil, ctxErr.Parse(parseErr) + return nil, errReminder.Parse(parseErr) } return reminders, nil } diff --git a/internal/cli/resume/cmd/root/run.go b/internal/cli/resume/cmd/root/run.go index 15162038c..bd311477d 100644 --- a/internal/cli/resume/cmd/root/run.go +++ b/internal/cli/resume/cmd/root/run.go @@ -10,7 +10,7 @@ import ( "os" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" - session2 "github.com/ActiveMemory/ctx/internal/cli/system/core/session" + coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/write/session" @@ -26,7 +26,7 @@ import ( // - error: Always nil func Run(cmd *cobra.Command, sessionID string) error { if sessionID == "" { - sessionID = session2.ReadSessionID(os.Stdin) + sessionID = coreSession.ReadSessionID(os.Stdin) } nudge.Resume(sessionID) session.SessionResumed(cmd, sessionID) diff --git a/internal/cli/serve/cmd/root/run.go b/internal/cli/serve/cmd/root/run.go index 217687028..a3e68ac8c 100644 --- a/internal/cli/serve/cmd/root/run.go +++ b/internal/cli/serve/cmd/root/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/zensical" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/site" + errSite "github.com/ActiveMemory/ctx/internal/err/site" zensicalBin "github.com/ActiveMemory/ctx/internal/exec/zensical" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -48,13 +48,13 @@ func Run(args []string) error { // Check zensical.toml exists tomlPath := filepath.Join(d, zensical.Toml) if _, statErr = os.Stat(tomlPath); os.IsNotExist(statErr) { - return ctxErr.NoConfig(d) + return errSite.NoConfig(d) } // Check if zensical is available _, lookErr := exec.LookPath(zensical.Bin) if lookErr != nil { - return ctxErr.ZensicalNotFound() + return errSite.ZensicalNotFound() } return zensicalBin.Run(d) diff --git a/internal/cli/serve/serve_test.go b/internal/cli/serve/serve_test.go index 8ddb76030..db081a84a 100644 --- a/internal/cli/serve/serve_test.go +++ b/internal/cli/serve/serve_test.go @@ -12,10 +12,10 @@ import ( "strings" "testing" - serveroot "github.com/ActiveMemory/ctx/internal/cli/serve/cmd/root" + serveRoot "github.com/ActiveMemory/ctx/internal/cli/serve/cmd/root" "github.com/ActiveMemory/ctx/internal/config/zensical" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxerr "github.com/ActiveMemory/ctx/internal/err/site" + errSite "github.com/ActiveMemory/ctx/internal/err/site" ) func TestCmd(t *testing.T) { @@ -60,7 +60,7 @@ func TestCmd_AcceptsArgs(t *testing.T) { } func TestRunServe_DirNotFound(t *testing.T) { - err := serveroot.Run([]string{"/tmp/nonexistent-dir-ctx-test-xyz"}) + err := serveRoot.Run([]string{"/tmp/nonexistent-dir-ctx-test-xyz"}) if err == nil { t.Fatal("expected error for nonexistent directory") } @@ -77,7 +77,7 @@ func TestRunServe_NotADirectory(t *testing.T) { defer func() { _ = os.Remove(tmpFile.Name()) }() _ = tmpFile.Close() - serveErr := serveroot.Run([]string{tmpFile.Name()}) + serveErr := serveRoot.Run([]string{tmpFile.Name()}) if serveErr == nil { t.Fatal("expected error for non-directory path") } @@ -93,7 +93,7 @@ func TestRunServe_NoSiteConfig(t *testing.T) { } defer func() { _ = os.RemoveAll(tmpDir) }() - serveErr := serveroot.Run([]string{tmpDir}) + serveErr := serveRoot.Run([]string{tmpDir}) if serveErr == nil { t.Fatal("expected error for missing zensical.toml") } @@ -118,7 +118,7 @@ func TestRunServe_ZensicalNotFound(t *testing.T) { // Ensure zensical is not in PATH t.Setenv("PATH", "") - serveErr := serveroot.Run([]string{tmpDir}) + serveErr := serveRoot.Run([]string{tmpDir}) if serveErr == nil { t.Fatal("expected error for missing zensical binary") } @@ -128,9 +128,9 @@ func TestRunServe_ZensicalNotFound(t *testing.T) { } func TestRunServe_DefaultDir(t *testing.T) { - // When no args are given, serveroot.Run uses the default journal-site directory + // When no args are given, serveRoot.Run uses the default journal-site directory // which won't exist in test, so we expect directory not found - err := serveroot.Run([]string{}) + err := serveRoot.Run([]string{}) if err == nil { t.Fatal("expected error when default dir doesn't exist") } @@ -168,7 +168,7 @@ func TestErrNotDir(t *testing.T) { } func TestErrNoSiteConfig(t *testing.T) { - err := ctxerr.NoConfig("/some/dir") + err := errSite.NoConfig("/some/dir") if err == nil { t.Fatal("expected non-nil error") } @@ -210,14 +210,14 @@ func TestRunServe_WithMockZensical(t *testing.T) { origPath := os.Getenv("PATH") t.Setenv("PATH", binDir+":"+origPath) - serveErr := serveroot.Run([]string{tmpDir}) + serveErr := serveRoot.Run([]string{tmpDir}) if serveErr != nil { t.Errorf("unexpected error: %v", serveErr) } } func TestCmd_RunE(t *testing.T) { - // Test that Cmd().RunE actually invokes serveroot.Run via the command + // Test that Cmd().RunE actually invokes serveRoot.Run via the command cmd := Cmd() // Set args to a nonexistent dir so we get a predictable error cmd.SetArgs([]string{"/tmp/nonexistent-ctx-test-xyz"}) @@ -234,7 +234,7 @@ func TestCmd_RunE(t *testing.T) { } func TestErrZensicalNotFound(t *testing.T) { - err := ctxerr.ZensicalNotFound() + err := errSite.ZensicalNotFound() if err == nil { t.Fatal("expected non-nil error") } diff --git a/internal/cli/site/core/rss/doc.go b/internal/cli/site/core/rss/doc.go new file mode 100644 index 000000000..abdf67d02 --- /dev/null +++ b/internal/cli/site/core/rss/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package rss generates Atom XML feeds from blog post metadata. +package rss diff --git a/internal/cli/site/core/scan/doc.go b/internal/cli/site/core/scan/doc.go new file mode 100644 index 000000000..3666a3e0f --- /dev/null +++ b/internal/cli/site/core/scan/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package scan reads blog post directories, parses frontmatter, and returns sorted post metadata. +package scan diff --git a/internal/cli/status/cmd/root/run.go b/internal/cli/status/cmd/root/run.go index f283cff2a..b22e87f46 100644 --- a/internal/cli/status/cmd/root/run.go +++ b/internal/cli/status/cmd/root/run.go @@ -11,10 +11,10 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/status/core/out" "github.com/ActiveMemory/ctx/internal/context/load" - ctxerr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/spf13/cobra" - errctx "github.com/ActiveMemory/ctx/internal/err/context" + errCtx "github.com/ActiveMemory/ctx/internal/err/context" ) // Run executes the status command logic. @@ -29,9 +29,9 @@ import ( func Run(cmd *cobra.Command, jsonOutput, verbose bool) error { ctx, err := load.Do("") if err != nil { - var notFoundError *errctx.NotFoundError + var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return ctxerr.ContextNotInitialized() + return errInit.ContextNotInitialized() } return err } diff --git a/internal/cli/status/core/out/doc.go b/internal/cli/status/core/out/doc.go new file mode 100644 index 000000000..4dd83c49d --- /dev/null +++ b/internal/cli/status/core/out/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package out writes context status as JSON or formatted text to command output. +package out diff --git a/internal/cli/status/core/preview/doc.go b/internal/cli/status/core/preview/doc.go new file mode 100644 index 000000000..23f7dec66 --- /dev/null +++ b/internal/cli/status/core/preview/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package preview extracts short content previews from context files for status display. +package preview diff --git a/internal/cli/status/core/sort/doc.go b/internal/cli/status/core/sort/doc.go new file mode 100644 index 000000000..f7ae350f1 --- /dev/null +++ b/internal/cli/status/core/sort/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package sort orders context files by priority and recency for status output. +package sort diff --git a/internal/cli/status/status.go b/internal/cli/status/status.go index 6a832faa3..e889a9104 100644 --- a/internal/cli/status/status.go +++ b/internal/cli/status/status.go @@ -9,10 +9,10 @@ package status import ( "github.com/spf13/cobra" - statuRroot "github.com/ActiveMemory/ctx/internal/cli/status/cmd/root" + statusRoot "github.com/ActiveMemory/ctx/internal/cli/status/cmd/root" ) // Cmd returns the status command. func Cmd() *cobra.Command { - return statuRroot.Cmd() + return statusRoot.Cmd() } diff --git a/internal/cli/sync/cmd/root/run.go b/internal/cli/sync/cmd/root/run.go index 885c0214a..9ba94bf0d 100644 --- a/internal/cli/sync/cmd/root/run.go +++ b/internal/cli/sync/cmd/root/run.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/context/load" errCtx "github.com/ActiveMemory/ctx/internal/err/context" - initErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/write/sync" ) @@ -35,7 +35,7 @@ func Run(cmd *cobra.Command, dryRun bool) error { if err != nil { var notFoundError *errCtx.NotFoundError if errors.As(err, ¬FoundError) { - return initErr.ContextNotInitialized() + return errInit.ContextNotInitialized() } return err } diff --git a/internal/cli/sync/core/action/doc.go b/internal/cli/sync/core/action/doc.go new file mode 100644 index 000000000..1190dfc24 --- /dev/null +++ b/internal/cli/sync/core/action/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package action detects discrepancies between the codebase and context documentation. +package action diff --git a/internal/cli/sync/core/validate/doc.go b/internal/cli/sync/core/validate/doc.go new file mode 100644 index 000000000..d16827b2f --- /dev/null +++ b/internal/cli/sync/core/validate/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package validate checks for undocumented package managers, config files, and directories. +package validate diff --git a/internal/cli/sync/core/validate/validate.go b/internal/cli/sync/core/validate/validate.go index 148ba23bf..e27d1f157 100644 --- a/internal/cli/sync/core/validate/validate.go +++ b/internal/cli/sync/core/validate/validate.go @@ -15,10 +15,10 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/assets/read/lookup" "github.com/ActiveMemory/ctx/internal/cli/sync/core" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/dep" "github.com/ActiveMemory/ctx/internal/config/embed/text" - syncCfg "github.com/ActiveMemory/ctx/internal/config/sync" + cfgSync "github.com/ActiveMemory/ctx/internal/config/sync" "github.com/ActiveMemory/ctx/internal/entity" ) @@ -41,12 +41,12 @@ func CheckPackageFiles(ctx *entity.Context) []core.Action { if _, err := os.Stat(f); err == nil { // File exists, check if we have DEPENDENCIES.md or similar hasDepsDoc := false - if f := ctx.File(ctxCfg.Dependency); f != nil { + if f := ctx.File(cfgCtx.Dependency); f != nil { hasDepsDoc = true } else { for _, f := range ctx.Files { if strings.Contains(strings.ToLower(string(f.Content)), - syncCfg.KeywordDependencies, + cfgSync.KeywordDependencies, ) { hasDepsDoc = true break @@ -56,15 +56,15 @@ func CheckPackageFiles(ctx *entity.Context) []core.Action { if !hasDepsDoc { actions = append(actions, core.Action{ - Type: syncCfg.ActionDeps, - File: ctxCfg.Architecture, + Type: cfgSync.ActionDeps, + File: cfgCtx.Architecture, Description: fmt.Sprintf( lookup.TextDesc(text.DescKeySyncDepsDescription), f, d, ), Suggestion: fmt.Sprintf( lookup.TextDesc(text.DescKeySyncDepsSuggestion), - ctxCfg.Architecture, ctxCfg.Dependency, + cfgCtx.Architecture, cfgCtx.Dependency, ), }) } @@ -93,7 +93,7 @@ func CheckConfigFiles(ctx *entity.Context) []core.Action { if len(matches) > 0 { // Check if CONVENTIONS.md mentions this var convContent string - if f := ctx.File(ctxCfg.Convention); f != nil { + if f := ctx.File(cfgCtx.Convention); f != nil { convContent = strings.ToLower(string(f.Content)) } @@ -101,15 +101,15 @@ func CheckConfigFiles(ctx *entity.Context) []core.Action { keyword = strings.TrimSuffix(keyword, "*") if convContent == "" || !strings.Contains(convContent, keyword) { actions = append(actions, core.Action{ - Type: syncCfg.ActionConfig, - File: ctxCfg.Convention, + Type: cfgSync.ActionConfig, + File: cfgCtx.Convention, Description: fmt.Sprintf( desc.Text(text.DescKeySyncConfigDescription), matches[0], cfg.Topic, ), Suggestion: fmt.Sprintf( desc.Text(text.DescKeySyncConfigSuggestion), - cfg.Topic, ctxCfg.Convention, + cfg.Topic, cfgCtx.Convention, ), }) } @@ -136,7 +136,7 @@ func CheckNewDirectories(ctx *entity.Context) []core.Action { // Get ARCHITECTURE.md content var archContent string - if f := ctx.File(ctxCfg.Architecture); f != nil { + if f := ctx.File(cfgCtx.Architecture); f != nil { archContent = strings.ToLower(string(f.Content)) } @@ -151,21 +151,21 @@ func CheckNewDirectories(ctx *entity.Context) []core.Action { continue } name := entry.Name() - if strings.HasPrefix(name, ".") || syncCfg.SkipDirs[name] { + if strings.HasPrefix(name, ".") || cfgSync.SkipDirs[name] { continue } - if syncCfg.ImportantDirs[name] && !strings.Contains(archContent, name) { + if cfgSync.ImportantDirs[name] && !strings.Contains(archContent, name) { actions = append(actions, core.Action{ - Type: syncCfg.ActionNewDir, - File: ctxCfg.Architecture, + Type: cfgSync.ActionNewDir, + File: cfgCtx.Architecture, Description: fmt.Sprintf( desc.Text(text.DescKeySyncDirDescription), name, ), Suggestion: fmt.Sprintf( desc.Text(text.DescKeySyncDirSuggestion), - name, ctxCfg.Architecture, + name, cfgCtx.Architecture, ), }) } diff --git a/internal/cli/system/cmd/backup/run.go b/internal/cli/system/cmd/backup/run.go index 3e21ed8b6..808c5a7c7 100644 --- a/internal/cli/system/cmd/backup/run.go +++ b/internal/cli/system/cmd/backup/run.go @@ -11,7 +11,7 @@ import ( "os" "time" - archive2 "github.com/ActiveMemory/ctx/internal/cli/system/core/archive" + coreArchive "github.com/ActiveMemory/ctx/internal/cli/system/core/archive" "github.com/ActiveMemory/ctx/internal/entity" "github.com/spf13/cobra" @@ -19,7 +19,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/env" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" errBackup "github.com/ActiveMemory/ctx/internal/err/backup" - ctxErr "github.com/ActiveMemory/ctx/internal/err/initialize" + errInit "github.com/ActiveMemory/ctx/internal/err/initialize" "github.com/ActiveMemory/ctx/internal/write/backup" ) @@ -46,15 +46,15 @@ func Run(cmd *cobra.Command) error { home, homeErr := os.UserHomeDir() if homeErr != nil { - return ctxErr.HomeDir(homeErr) + return errInit.HomeDir(homeErr) } smbURL := os.Getenv(env.BackupSMBURL) smbSubdir := os.Getenv(env.BackupSMBSubdir) - var smb *archive2.SMBConfig + var smb *coreArchive.SMBConfig if smbURL != "" { var smbErr error - smb, smbErr = archive2.ParseSMBConfig(smbURL, smbSubdir) + smb, smbErr = coreArchive.ParseSMBConfig(smbURL, smbSubdir) if smbErr != nil { return errBackup.SMBConfig(smbErr) } @@ -64,7 +64,7 @@ func Run(cmd *cobra.Command) error { var results []entity.BackupResult if scope == archive.BackupScopeProject || scope == archive.BackupScopeAll { - result, projErr := archive2.BackupProject(cmd.ErrOrStderr(), home, timestamp, smb) + result, projErr := coreArchive.BackupProject(cmd.ErrOrStderr(), home, timestamp, smb) if projErr != nil { return errBackup.Project(projErr) } @@ -72,7 +72,7 @@ func Run(cmd *cobra.Command) error { } if scope == archive.BackupScopeGlobal || scope == archive.BackupScopeAll { - result, globalErr := archive2.BackupGlobal(cmd.ErrOrStderr(), home, timestamp, smb) + result, globalErr := coreArchive.BackupGlobal(cmd.ErrOrStderr(), home, timestamp, smb) if globalErr != nil { return errBackup.Global(globalErr) } diff --git a/internal/cli/system/cmd/bootstrap/run.go b/internal/cli/system/cmd/bootstrap/run.go index 108db15b6..4f1cfbde3 100644 --- a/internal/cli/system/cmd/bootstrap/run.go +++ b/internal/cli/system/cmd/bootstrap/run.go @@ -9,7 +9,7 @@ package bootstrap import ( "os" - bootstrap2 "github.com/ActiveMemory/ctx/internal/cli/system/core/bootstrap" + coreBootstrap "github.com/ActiveMemory/ctx/internal/cli/system/core/bootstrap" "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/assets/read/desc" @@ -43,14 +43,14 @@ func Run(cmd *cobra.Command) error { return nil } - files := bootstrap2.ListContextFiles(dir) - rules := bootstrap2.ParseNumberedLines( + files := coreBootstrap.ListContextFiles(dir) + rules := coreBootstrap.ParseNumberedLines( desc.Text(text.DescKeyBootstrapRules), ) - nextSteps := bootstrap2.ParseNumberedLines( + nextSteps := coreBootstrap.ParseNumberedLines( desc.Text(text.DescKeyBootstrapNextSteps), ) - warning := bootstrap2.PluginWarning() + warning := coreBootstrap.PluginWarning() jsonFlag, _ := cmd.Flags().GetBool(cFlag.JSON) if jsonFlag { @@ -58,7 +58,7 @@ func Run(cmd *cobra.Command) error { return nil } - fileList := bootstrap2.WrapFileList( + fileList := coreBootstrap.WrapFileList( files, cfgBootstrap.BootstrapFileListWidth, cfgBootstrap.BootstrapFileListIndent, diff --git a/internal/cli/system/cmd/check_journal/run.go b/internal/cli/system/cmd/check_journal/run.go index bf224db8e..442d97b24 100644 --- a/internal/cli/system/cmd/check_journal/run.go +++ b/internal/cli/system/cmd/check_journal/run.go @@ -11,8 +11,8 @@ import ( "os" "path/filepath" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" - journal2 "github.com/ActiveMemory/ctx/internal/cli/system/core/journal" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreJournal "github.com/ActiveMemory/ctx/internal/cli/system/core/journal" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" @@ -46,7 +46,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { if !state.Initialized() { return nil } - input, _, paused := hook2.Preamble(stdin) + input, _, paused := coreCheck.Preamble(stdin) if paused { return nil } @@ -58,7 +58,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { ) // Only remind once per day - if hook2.DailyThrottled(remindedFile) { + if coreCheck.DailyThrottled(remindedFile) { return nil } @@ -72,13 +72,13 @@ func Run(cmd *cobra.Command, stdin *os.File) error { } // Stage 1: Unexported sessions - newestJournal := journal2.NewestMtime(jDir, file.ExtMarkdown) - unexported := journal2.CountNewerFiles( + newestJournal := coreJournal.NewestMtime(jDir, file.ExtMarkdown) + unexported := coreJournal.CountNewerFiles( claudeProjectsDir, file.ExtJSONL, newestJournal, ) // Stage 2: Unenriched entries - unenriched := journal2.CountUnenriched(jDir) + unenriched := coreJournal.CountUnenriched(jDir) if unexported == 0 && unenriched == 0 { return nil diff --git a/internal/cli/system/cmd/check_knowledge/run.go b/internal/cli/system/cmd/check_knowledge/run.go index 5a46570c5..b6475ea6c 100644 --- a/internal/cli/system/cmd/check_knowledge/run.go +++ b/internal/cli/system/cmd/check_knowledge/run.go @@ -11,7 +11,7 @@ import ( "path/filepath" "github.com/ActiveMemory/ctx/internal/cli/system/core/check" - knowledge2 "github.com/ActiveMemory/ctx/internal/cli/system/core/knowledge" + coreKnowledge "github.com/ActiveMemory/ctx/internal/cli/system/core/knowledge" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" "github.com/spf13/cobra" @@ -48,7 +48,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { return nil } - if box, warned := knowledge2.CheckKnowledgeHealth(sessionID); warned { + if box, warned := coreKnowledge.CheckKnowledgeHealth(sessionID); warned { writeHook.Nudge(cmd, box) internalIo.TouchFile(markerPath) } diff --git a/internal/cli/system/cmd/check_memory_drift/run.go b/internal/cli/system/cmd/check_memory_drift/run.go index d456643e6..b248c4400 100644 --- a/internal/cli/system/cmd/check_memory_drift/run.go +++ b/internal/cli/system/cmd/check_memory_drift/run.go @@ -10,7 +10,7 @@ import ( "os" "path/filepath" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" "github.com/spf13/cobra" @@ -28,7 +28,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { return nil } - input, sessionID, paused := hook2.Preamble(stdin) + input, sessionID, paused := coreCheck.Preamble(stdin) if paused { return nil } diff --git a/internal/cli/system/cmd/check_reminder/run.go b/internal/cli/system/cmd/check_reminder/run.go index 10529a38b..ef50a5df0 100644 --- a/internal/cli/system/cmd/check_reminder/run.go +++ b/internal/cli/system/cmd/check_reminder/run.go @@ -11,7 +11,7 @@ import ( "os" "time" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" @@ -45,7 +45,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { return nil } - input, _, paused := hook2.Preamble(stdin) + input, _, paused := coreCheck.Preamble(stdin) if paused { return nil } diff --git a/internal/cli/system/cmd/events/run.go b/internal/cli/system/cmd/events/run.go index 12beb1a1d..879575355 100644 --- a/internal/cli/system/cmd/events/run.go +++ b/internal/cli/system/cmd/events/run.go @@ -11,7 +11,7 @@ import ( coreEvent "github.com/ActiveMemory/ctx/internal/cli/system/core/event" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" - errRcall "github.com/ActiveMemory/ctx/internal/err/recall" + errRecall "github.com/ActiveMemory/ctx/internal/err/recall" "github.com/ActiveMemory/ctx/internal/log" writeEvents "github.com/ActiveMemory/ctx/internal/write/events" ) @@ -42,7 +42,7 @@ func Run(cmd *cobra.Command) error { evts, queryErr := log.Query(opts) if queryErr != nil { - return errRcall.EventLogRead(queryErr) + return errRecall.EventLogRead(queryErr) } if len(evts) == 0 { diff --git a/internal/cli/system/cmd/heartbeat/run.go b/internal/cli/system/cmd/heartbeat/run.go index a5e2312d3..95e52e479 100644 --- a/internal/cli/system/cmd/heartbeat/run.go +++ b/internal/cli/system/cmd/heartbeat/run.go @@ -11,10 +11,10 @@ import ( "os" "path/filepath" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/counter" - heartbeat2 "github.com/ActiveMemory/ctx/internal/cli/system/core/heartbeat" - log2 "github.com/ActiveMemory/ctx/internal/cli/system/core/log" + coreHeartbeat "github.com/ActiveMemory/ctx/internal/cli/system/core/heartbeat" + coreLog "github.com/ActiveMemory/ctx/internal/cli/system/core/log" "github.com/ActiveMemory/ctx/internal/cli/system/core/session" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" "github.com/ActiveMemory/ctx/internal/cli/system/core/time" @@ -48,7 +48,7 @@ func Run(_ *cobra.Command, stdin *os.File) error { if !state.Initialized() { return nil } - _, sessionID, paused := hook2.Preamble(stdin) + _, sessionID, paused := coreCheck.Preamble(stdin) if paused { return nil } @@ -69,9 +69,9 @@ func Run(_ *cobra.Command, stdin *os.File) error { // Detect context modification since the last heartbeat. currentMtime := time.GetLatestContextMtime(contextDir) - lastMtime := heartbeat2.ReadMtime(mtimeFile) + lastMtime := coreHeartbeat.ReadMtime(mtimeFile) contextModified := currentMtime > lastMtime - heartbeat2.WriteMtime(mtimeFile, currentMtime) + coreHeartbeat.WriteMtime(mtimeFile, currentMtime) // Read token usage for this session. info, _ := session.ReadSessionTokenInfo(sessionID) @@ -113,7 +113,7 @@ func Run(_ *cobra.Command, stdin *os.File) error { logLine = fmt.Sprintf(desc.Text(text.DescKeyHeartbeatLogPlain), count, contextModified) } - log2.Message(logFile, sessionID, logLine) + coreLog.Message(logFile, sessionID, logLine) // No stdout - agent never sees this hook. return nil diff --git a/internal/cli/system/cmd/message/cmd/edit/doc.go b/internal/cli/system/cmd/message/cmd/edit/doc.go new file mode 100644 index 000000000..e95fbeb28 --- /dev/null +++ b/internal/cli/system/cmd/message/cmd/edit/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package edit provides the ctx system message edit subcommand for customizing hook templates. +package edit diff --git a/internal/cli/system/cmd/message/cmd/edit/run.go b/internal/cli/system/cmd/message/cmd/edit/run.go index 0ba8d2aba..dc5171233 100644 --- a/internal/cli/system/cmd/message/cmd/edit/run.go +++ b/internal/cli/system/cmd/message/cmd/edit/run.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/hook" "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/err/fs" - ctxErr "github.com/ActiveMemory/ctx/internal/err/hook" + errHook "github.com/ActiveMemory/ctx/internal/err/hook" writeMessage "github.com/ActiveMemory/ctx/internal/write/message" ) @@ -34,13 +34,13 @@ import ( func Run(cmd *cobra.Command, hk, variant string) error { info := messages.Lookup(hk, variant) if info == nil { - return ctxErr.Validate(messages.Variants(hk) != nil, hk, variant) + return errHook.Validate(messages.Variants(hk) != nil, hk, variant) } oPath := message.OverridePath(hk, variant) if _, statErr := os.Stat(oPath); statErr == nil { - return ctxErr.OverrideExists(oPath, hk, variant) + return errHook.OverrideExists(oPath, hk, variant) } if info.Category == messages.CategoryCtxSpecific { @@ -49,7 +49,7 @@ func Run(cmd *cobra.Command, hk, variant string) error { data, readErr := hook.Message(hk, variant+file.ExtTxt) if readErr != nil { - return ctxErr.EmbeddedTemplateNotFound(hk, variant) + return errHook.EmbeddedTemplateNotFound(hk, variant) } dir := filepath.Dir(oPath) @@ -58,7 +58,7 @@ func Run(cmd *cobra.Command, hk, variant string) error { } if writeErr := os.WriteFile(oPath, data, 0o600); writeErr != nil { - return ctxErr.WriteOverride(oPath, writeErr) + return errHook.WriteOverride(oPath, writeErr) } writeMessage.OverrideCreated(cmd, oPath) diff --git a/internal/cli/system/cmd/message/cmd/list/doc.go b/internal/cli/system/cmd/message/cmd/list/doc.go new file mode 100644 index 000000000..df0ada529 --- /dev/null +++ b/internal/cli/system/cmd/message/cmd/list/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package list provides the ctx system message list subcommand for displaying available hook messages. +package list diff --git a/internal/cli/system/cmd/message/cmd/reset/doc.go b/internal/cli/system/cmd/message/cmd/reset/doc.go new file mode 100644 index 000000000..b461cdba0 --- /dev/null +++ b/internal/cli/system/cmd/message/cmd/reset/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package reset provides the ctx system message reset subcommand for restoring default hook templates. +package reset diff --git a/internal/cli/system/cmd/message/cmd/reset/run.go b/internal/cli/system/cmd/message/cmd/reset/run.go index d43b912a6..8604adbbc 100644 --- a/internal/cli/system/cmd/message/cmd/reset/run.go +++ b/internal/cli/system/cmd/message/cmd/reset/run.go @@ -14,7 +14,7 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/assets/hooks/messages" - ctxErr "github.com/ActiveMemory/ctx/internal/err/hook" + errHook "github.com/ActiveMemory/ctx/internal/err/hook" writeMessage "github.com/ActiveMemory/ctx/internal/write/message" ) @@ -30,7 +30,7 @@ import ( func Run(cmd *cobra.Command, hk, variant string) error { info := messages.Lookup(hk, variant) if info == nil { - return ctxErr.Validate(messages.Variants(hk) != nil, hk, variant) + return errHook.Validate(messages.Variants(hk) != nil, hk, variant) } oPath := message.OverridePath(hk, variant) @@ -40,7 +40,7 @@ func Run(cmd *cobra.Command, hk, variant string) error { writeMessage.NoOverride(cmd, hk, variant) return nil } - return ctxErr.RemoveOverride(oPath, removeErr) + return errHook.RemoveOverride(oPath, removeErr) } hookDir := filepath.Dir(oPath) diff --git a/internal/cli/system/cmd/message/cmd/show/doc.go b/internal/cli/system/cmd/message/cmd/show/doc.go new file mode 100644 index 000000000..63130135e --- /dev/null +++ b/internal/cli/system/cmd/message/cmd/show/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package show provides the ctx system message show subcommand for viewing hook template content. +package show diff --git a/internal/cli/system/cmd/message/cmd/show/run.go b/internal/cli/system/cmd/message/cmd/show/run.go index 341781f56..42747144c 100644 --- a/internal/cli/system/cmd/message/cmd/show/run.go +++ b/internal/cli/system/cmd/message/cmd/show/run.go @@ -11,9 +11,9 @@ import ( "github.com/spf13/cobra" "github.com/ActiveMemory/ctx/internal/assets/hooks/messages" - hook "github.com/ActiveMemory/ctx/internal/assets/read/hook" + readHook "github.com/ActiveMemory/ctx/internal/assets/read/hook" "github.com/ActiveMemory/ctx/internal/config/file" - ctxErr "github.com/ActiveMemory/ctx/internal/err/hook" + errHook "github.com/ActiveMemory/ctx/internal/err/hook" "github.com/ActiveMemory/ctx/internal/io" writeMessage "github.com/ActiveMemory/ctx/internal/write/message" ) @@ -30,7 +30,7 @@ import ( func Run(cmd *cobra.Command, hk, variant string) error { info := messages.Lookup(hk, variant) if info == nil { - return ctxErr.Validate(messages.Variants(hk) != nil, hk, variant) + return errHook.Validate(messages.Variants(hk) != nil, hk, variant) } oPath := message.OverridePath(hk, variant) @@ -41,9 +41,9 @@ func Run(cmd *cobra.Command, hk, variant string) error { return nil } - data, readErr := hook.Message(hk, variant+file.ExtTxt) + data, readErr := readHook.Message(hk, variant+file.ExtTxt) if readErr != nil { - return ctxErr.EmbeddedTemplateNotFound(hk, variant) + return errHook.EmbeddedTemplateNotFound(hk, variant) } writeMessage.SourceDefault(cmd) diff --git a/internal/cli/system/cmd/message/doc.go b/internal/cli/system/cmd/message/doc.go new file mode 100644 index 000000000..274f26cf8 --- /dev/null +++ b/internal/cli/system/cmd/message/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package message provides the parent command for ctx system message. +package message diff --git a/internal/cli/system/cmd/message/message.go b/internal/cli/system/cmd/message/message.go index 813758dda..2b625f9b5 100644 --- a/internal/cli/system/cmd/message/message.go +++ b/internal/cli/system/cmd/message/message.go @@ -4,7 +4,6 @@ // \ Copyright 2026-present Context contributors. // SPDX-License-Identifier: Apache-2.0 -// Package message provides the parent command for ctx system message. package message import ( diff --git a/internal/cli/system/cmd/post_commit/run.go b/internal/cli/system/cmd/post_commit/run.go index d83c473c4..540e44e67 100644 --- a/internal/cli/system/cmd/post_commit/run.go +++ b/internal/cli/system/cmd/post_commit/run.go @@ -11,7 +11,7 @@ import ( "os" "regexp" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/drift" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" @@ -48,7 +48,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { if !state.Initialized() { return nil } - input, sessionID, paused := hook2.Preamble(stdin) + input, sessionID, paused := coreCheck.Preamble(stdin) if paused { return nil } diff --git a/internal/cli/system/cmd/prune/run.go b/internal/cli/system/cmd/prune/run.go index c526b1858..f5eaf2e58 100644 --- a/internal/cli/system/cmd/prune/run.go +++ b/internal/cli/system/cmd/prune/run.go @@ -13,8 +13,8 @@ import ( "github.com/ActiveMemory/ctx/internal/cli/system/core/health" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" - time2 "github.com/ActiveMemory/ctx/internal/config/time" - ctxerr "github.com/ActiveMemory/ctx/internal/err/state" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" + errState "github.com/ActiveMemory/ctx/internal/err/state" "github.com/ActiveMemory/ctx/internal/write/prune" "github.com/spf13/cobra" ) @@ -37,10 +37,10 @@ func Run(cmd *cobra.Command, days int, dryRun bool) error { entries, readErr := os.ReadDir(dir) if readErr != nil { - return ctxerr.ReadingDir(readErr) + return errState.ReadingDir(readErr) } - cutoff := time.Now().Add(-time.Duration(days) * time2.HoursPerDay * time.Hour) + cutoff := time.Now().Add(-time.Duration(days) * cfgTime.HoursPerDay * time.Hour) var pruned, skipped, preserved int for _, entry := range entries { diff --git a/internal/cli/system/cmd/qa_reminder/run.go b/internal/cli/system/cmd/qa_reminder/run.go index e739db6de..5e6eabf30 100644 --- a/internal/cli/system/cmd/qa_reminder/run.go +++ b/internal/cli/system/cmd/qa_reminder/run.go @@ -11,7 +11,7 @@ import ( "os" "strings" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" @@ -41,7 +41,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { if !state.Initialized() { return nil } - input, _, paused := hook2.Preamble(stdin) + input, _, paused := coreCheck.Preamble(stdin) if paused { return nil } diff --git a/internal/cli/system/cmd/resume/run.go b/internal/cli/system/cmd/resume/run.go index 045bd6d27..8a1553909 100644 --- a/internal/cli/system/cmd/resume/run.go +++ b/internal/cli/system/cmd/resume/run.go @@ -15,7 +15,7 @@ import ( coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" cFlag "github.com/ActiveMemory/ctx/internal/config/flag" "github.com/ActiveMemory/ctx/internal/config/session" - session2 "github.com/ActiveMemory/ctx/internal/write/session" + writeSession "github.com/ActiveMemory/ctx/internal/write/session" ) // Run executes the resume logic. @@ -41,6 +41,6 @@ func Run(cmd *cobra.Command, stdin *os.File) error { path := nudge.PauseMarkerPath(sessionID) _ = os.Remove(path) - session2.SessionResumed(cmd, sessionID) + writeSession.SessionResumed(cmd, sessionID) return nil } diff --git a/internal/cli/system/cmd/specs_nudge/run.go b/internal/cli/system/cmd/specs_nudge/run.go index 93a900418..877c7245e 100644 --- a/internal/cli/system/cmd/specs_nudge/run.go +++ b/internal/cli/system/cmd/specs_nudge/run.go @@ -10,7 +10,7 @@ import ( "fmt" "os" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/check" + coreCheck "github.com/ActiveMemory/ctx/internal/cli/system/core/check" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" "github.com/ActiveMemory/ctx/internal/cli/system/core/nudge" coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" @@ -41,7 +41,7 @@ func Run(cmd *cobra.Command, stdin *os.File) error { if !state.Initialized() { return nil } - input, _, paused := hook2.Preamble(stdin) + input, _, paused := coreCheck.Preamble(stdin) if paused { return nil } diff --git a/internal/cli/system/core/archive/backup.go b/internal/cli/system/core/archive/backup.go index 7533c2b39..a33cb3bdc 100644 --- a/internal/cli/system/core/archive/backup.go +++ b/internal/cli/system/core/archive/backup.go @@ -19,7 +19,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/archive" "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/embed/text" - configFs "github.com/ActiveMemory/ctx/internal/config/fs" + cfgFs "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/entity" errBackup "github.com/ActiveMemory/ctx/internal/err/backup" internalIo "github.com/ActiveMemory/ctx/internal/io" @@ -37,7 +37,7 @@ import ( func CreateArchive( archivePath string, entries []entity.ArchiveEntry, w io.Writer, ) error { - outFile, createErr := internalIo.SafeCreateFile(archivePath, configFs.PermFile) + outFile, createErr := internalIo.SafeCreateFile(archivePath, cfgFs.PermFile) if createErr != nil { return errBackup.CreateArchive(createErr) } @@ -95,7 +95,7 @@ func BackupProject( // Touch marker file for check-backup-age hook. markerDir := filepath.Join(home, archive.BackupMarkerDir) - _ = os.MkdirAll(markerDir, configFs.PermExec) + _ = os.MkdirAll(markerDir, cfgFs.PermExec) markerPath := filepath.Join(markerDir, archive.BackupMarkerFile) internalIo.TouchFile(markerPath) diff --git a/internal/cli/system/core/archive/doc.go b/internal/cli/system/core/archive/doc.go new file mode 100644 index 000000000..53011e648 --- /dev/null +++ b/internal/cli/system/core/archive/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package archive creates compressed tar archives of context data with optional SMB backup. +package archive diff --git a/internal/cli/system/core/archive/smb.go b/internal/cli/system/core/archive/smb.go index 90474cde5..a2b0a8fa7 100644 --- a/internal/cli/system/core/archive/smb.go +++ b/internal/cli/system/core/archive/smb.go @@ -17,8 +17,8 @@ import ( "github.com/ActiveMemory/ctx/internal/config/archive" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/fs" - backupErr "github.com/ActiveMemory/ctx/internal/err/backup" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" + errBackup "github.com/ActiveMemory/ctx/internal/err/backup" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" "github.com/ActiveMemory/ctx/internal/io" ) @@ -44,7 +44,7 @@ type SMBConfig struct { func ParseSMBConfig(smbURL, subdir string) (*SMBConfig, error) { u, parseErr := url.Parse(smbURL) if parseErr != nil || u.Host == "" { - return nil, backupErr.InvalidSMBURL(smbURL) + return nil, errBackup.InvalidSMBURL(smbURL) } host := u.Host @@ -53,7 +53,7 @@ func ParseSMBConfig(smbURL, subdir string) (*SMBConfig, error) { share = share[1:] } if share == "" { - return nil, backupErr.SMBMissingShare(smbURL) + return nil, errBackup.SMBMissingShare(smbURL) } if subdir == "" { @@ -87,7 +87,7 @@ func EnsureSMBMount(cfg *SMBConfig) error { //nolint:gosec // G204: smbURL is from user env, not untrusted input mountCmd := exec.Command("gio", "mount", cfg.SourceURL) if mountErr := mountCmd.Run(); mountErr != nil { - return backupErr.MountFailed(cfg.SourceURL, mountErr) + return errBackup.MountFailed(cfg.SourceURL, mountErr) } return nil @@ -104,17 +104,17 @@ func EnsureSMBMount(cfg *SMBConfig) error { func CopyToSMB(cfg *SMBConfig, localPath string) error { dest := filepath.Join(cfg.GVFSPath, cfg.Subdir) if mkdirErr := os.MkdirAll(dest, fs.PermExec); mkdirErr != nil { - return fserr.CreateDir(dest, mkdirErr) + return errFs.CreateDir(dest, mkdirErr) } data, readErr := io.SafeReadUserFile(localPath) if readErr != nil { - return fserr.ReadFile(readErr) + return errFs.ReadFile(readErr) } destFile := filepath.Join(dest, filepath.Base(localPath)) if writeErr := os.WriteFile(destFile, data, fs.PermFile); writeErr != nil { - return backupErr.WriteSMB(writeErr) + return errBackup.WriteSMB(writeErr) } return nil diff --git a/internal/cli/system/core/bootstrap/doc.go b/internal/cli/system/core/bootstrap/doc.go new file mode 100644 index 000000000..db043ed92 --- /dev/null +++ b/internal/cli/system/core/bootstrap/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package bootstrap checks plugin installation status and emits warnings during context bootstrap. +package bootstrap diff --git a/internal/cli/system/core/ceremony/doc.go b/internal/cli/system/core/ceremony/doc.go new file mode 100644 index 000000000..74beec55e --- /dev/null +++ b/internal/cli/system/core/ceremony/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package ceremony assembles hook ceremony output from recent journal files and message templates. +package ceremony diff --git a/internal/cli/system/core/check/doc.go b/internal/cli/system/core/check/doc.go new file mode 100644 index 000000000..0bf896fcb --- /dev/null +++ b/internal/cli/system/core/check/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package check provides shared preamble logic and throttling for hook input processing. +package check diff --git a/internal/cli/system/core/counter/doc.go b/internal/cli/system/core/counter/doc.go new file mode 100644 index 000000000..bfd09f2a4 --- /dev/null +++ b/internal/cli/system/core/counter/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package counter reads and writes integer counters persisted in state files. +package counter diff --git a/internal/cli/system/core/drift/doc.go b/internal/cli/system/core/drift/doc.go new file mode 100644 index 000000000..84988cb6d --- /dev/null +++ b/internal/cli/system/core/drift/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package drift detects version drift across VERSION, plugin, and marketplace files and reports stale context entries. +package drift diff --git a/internal/cli/system/core/event/doc.go b/internal/cli/system/core/event/doc.go new file mode 100644 index 000000000..6212effea --- /dev/null +++ b/internal/cli/system/core/event/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package event formats and renders event log timestamps and entries. +package event diff --git a/internal/cli/system/core/health/doc.go b/internal/cli/system/core/health/doc.go new file mode 100644 index 000000000..426b104bb --- /dev/null +++ b/internal/cli/system/core/health/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package health monitors context health by detecting stale architecture maps and pruning expired state files. +package health diff --git a/internal/cli/system/core/health/prune.go b/internal/cli/system/core/health/prune.go index a911aa059..52c2493c8 100644 --- a/internal/cli/system/core/health/prune.go +++ b/internal/cli/system/core/health/prune.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" "github.com/ActiveMemory/ctx/internal/config/embed/text" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" ) // UUIDPattern matches a UUID (v4) anywhere in a filename. @@ -42,7 +42,7 @@ func AutoPrune(days int) int { return 0 } - cutoff := time.Now().Add(-time.Duration(days) * time2.HoursPerDay * time.Hour) + cutoff := time.Now().Add(-time.Duration(days) * cfgTime.HoursPerDay * time.Hour) var pruned int for _, entry := range entries { diff --git a/internal/cli/system/core/heartbeat/doc.go b/internal/cli/system/core/heartbeat/doc.go new file mode 100644 index 000000000..3011ba674 --- /dev/null +++ b/internal/cli/system/core/heartbeat/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package heartbeat reads and writes mtime values for session heartbeat tracking. +package heartbeat diff --git a/internal/cli/system/core/journal/doc.go b/internal/cli/system/core/journal/doc.go new file mode 100644 index 000000000..5ebeeefc9 --- /dev/null +++ b/internal/cli/system/core/journal/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package journal scans journal directories for the newest file modification time and manages journal state. +package journal diff --git a/internal/cli/system/core/knowledge/doc.go b/internal/cli/system/core/knowledge/doc.go new file mode 100644 index 000000000..6650199b9 --- /dev/null +++ b/internal/cli/system/core/knowledge/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package knowledge scans knowledge files against configured thresholds and emits warnings when limits are exceeded. +package knowledge diff --git a/internal/cli/system/core/load/doc.go b/internal/cli/system/core/load/doc.go new file mode 100644 index 000000000..2da08df09 --- /dev/null +++ b/internal/cli/system/core/load/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package load extracts index content from context files and handles load-gate logic during session startup. +package load diff --git a/internal/cli/system/core/log/doc.go b/internal/cli/system/core/log/doc.go new file mode 100644 index 000000000..962db87b5 --- /dev/null +++ b/internal/cli/system/core/log/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package log appends timestamped messages to hook log files with automatic rotation. +package log diff --git a/internal/cli/system/core/message/doc.go b/internal/cli/system/core/message/doc.go new file mode 100644 index 000000000..e260fd37d --- /dev/null +++ b/internal/cli/system/core/message/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package message loads and renders hook message templates with priority resolution between user overrides and defaults. +package message diff --git a/internal/cli/system/core/nudge/context_size.go b/internal/cli/system/core/nudge/context_size.go index 40b1d3a76..a362cc069 100644 --- a/internal/cli/system/core/nudge/context_size.go +++ b/internal/cli/system/core/nudge/context_size.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/cli/system/core/log" "github.com/ActiveMemory/ctx/internal/cli/system/core/message" - hook2 "github.com/ActiveMemory/ctx/internal/cli/system/core/session" + coreSession "github.com/ActiveMemory/ctx/internal/cli/system/core/session" "github.com/ActiveMemory/ctx/internal/cli/system/core/state" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/hook" @@ -78,12 +78,12 @@ func EmitCheckpoint(logFile, sessionID string, count, tokens, pct, windowSize in func EmitWindowWarning(logFile, sessionID string, count, tokens, pct int) string { fallback := fmt.Sprintf( desc.Text(text.DescKeyCheckContextSizeWindowFallback), - pct, hook2.FormatTokenCount(tokens), + pct, coreSession.FormatTokenCount(tokens), ) content := message.LoadMessage(hook.CheckContextSize, hook.VariantWindow, map[string]any{ stats.VarPercentage: pct, - stats.VarTokenCount: hook2.FormatTokenCount(tokens), + stats.VarTokenCount: coreSession.FormatTokenCount(tokens), }, fallback) if content == "" { log.Message( @@ -107,7 +107,7 @@ func EmitWindowWarning(logFile, sessionID string, count, tokens, pct int) string ref := notify.NewTemplateRef(hook.CheckContextSize, hook.VariantWindow, map[string]any{ stats.VarPercentage: pct, - stats.VarTokenCount: hook2.FormatTokenCount(tokens), + stats.VarTokenCount: coreSession.FormatTokenCount(tokens), }, ) windowMsg := fmt.Sprintf(desc.Text(text.DescKeyRelayPrefixFormat), @@ -139,11 +139,11 @@ func EmitBillingWarning(logFile, sessionID string, count, tokens, threshold int) } fallback := fmt.Sprintf(desc.Text(text.DescKeyCheckContextSizeBillingFallback), - hook2.FormatTokenCount(tokens), hook2.FormatTokenCount(threshold)) + coreSession.FormatTokenCount(tokens), coreSession.FormatTokenCount(threshold)) content := message.LoadMessage(hook.CheckContextSize, hook.VariantBilling, map[string]any{ - stats.VarTokenCount: hook2.FormatTokenCount(tokens), - stats.VarThreshold: hook2.FormatTokenCount(threshold), + stats.VarTokenCount: coreSession.FormatTokenCount(tokens), + stats.VarThreshold: coreSession.FormatTokenCount(threshold), }, fallback) if content == "" { log.Message( @@ -171,15 +171,15 @@ func EmitBillingWarning(logFile, sessionID string, count, tokens, threshold int) ref := notify.NewTemplateRef( hook.CheckContextSize, hook.VariantBilling, map[string]any{ - stats.VarTokenCount: hook2.FormatTokenCount(tokens), - stats.VarThreshold: hook2.FormatTokenCount(threshold), + stats.VarTokenCount: coreSession.FormatTokenCount(tokens), + stats.VarThreshold: coreSession.FormatTokenCount(threshold), }, ) billingMsg := fmt.Sprintf(desc.Text(text.DescKeyRelayPrefixFormat), hook.CheckContextSize, fmt.Sprintf( desc.Text(text.DescKeyCheckContextSizeBillingRelayFormat), - hook2.FormatTokenCount(tokens), hook2.FormatTokenCount(threshold), + coreSession.FormatTokenCount(tokens), coreSession.FormatTokenCount(threshold), ), ) NudgeAndRelay(billingMsg, sessionID, ref) diff --git a/internal/cli/system/core/nudge/doc.go b/internal/cli/system/core/nudge/doc.go new file mode 100644 index 000000000..c589e0046 --- /dev/null +++ b/internal/cli/system/core/nudge/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package nudge emits checkpoint, pause, and oversize nudge notifications during sessions. +package nudge diff --git a/internal/cli/system/core/persistence/doc.go b/internal/cli/system/core/persistence/doc.go new file mode 100644 index 000000000..6aad217af --- /dev/null +++ b/internal/cli/system/core/persistence/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package persistence tracks edit counter state for persistence nudge timing. +package persistence diff --git a/internal/cli/system/core/session/doc.go b/internal/cli/system/core/session/doc.go new file mode 100644 index 000000000..e2bc2aa45 --- /dev/null +++ b/internal/cli/system/core/session/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package session builds hook JSON responses and manages session token tracking. +package session diff --git a/internal/cli/system/core/session/session_token.go b/internal/cli/system/core/session/session_token.go index eaca55397..ec391ec53 100644 --- a/internal/cli/system/core/session/session_token.go +++ b/internal/cli/system/core/session/session_token.go @@ -27,7 +27,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/stats" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" - io2 "github.com/ActiveMemory/ctx/internal/io" + internalIo "github.com/ActiveMemory/ctx/internal/io" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -74,7 +74,7 @@ func ReadSessionTokenInfo(sessionID string) (entity.TokenInfo, error) { func FindJSONLPath(sessionID string) (string, error) { // Check cache first cacheFile := filepath.Join(state.StateDir(), stats.JsonlPathCachePrefix+sessionID) - if data, readErr := io2.SafeReadUserFile(cacheFile); readErr == nil { + if data, readErr := internalIo.SafeReadUserFile(cacheFile); readErr == nil { cached := strings.TrimSpace(string(data)) if cached != "" { if _, statErr := os.Stat(cached); statErr == nil { @@ -113,7 +113,7 @@ func FindJSONLPath(sessionID string) (string, error) { // - SessionTokenInfo: Token count and model, or zero value if not found // - error: Non-nil only on I/O errors func ParseLastUsageAndModel(path string) (entity.TokenInfo, error) { - f, openErr := io2.SafeOpenUserFile(path) + f, openErr := internalIo.SafeOpenUserFile(path) if openErr != nil { return entity.TokenInfo{}, openErr } @@ -243,7 +243,7 @@ func ClaudeSettingsHas1M() bool { if homeErr != nil { return false } - data, readErr := io2.SafeReadUserFile(filepath.Join(home, dir.Claude, claude.GlobalSettings)) + data, readErr := internalIo.SafeReadUserFile(filepath.Join(home, dir.Claude, claude.GlobalSettings)) if readErr != nil { return false } diff --git a/internal/cli/system/core/state/doc.go b/internal/cli/system/core/state/doc.go new file mode 100644 index 000000000..84e428d5b --- /dev/null +++ b/internal/cli/system/core/state/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package state provides the project-scoped runtime state directory and initialization checks. +package state diff --git a/internal/cli/system/core/stats/stats.go b/internal/cli/system/core/stats/stats.go index ee415fe2e..6ad760870 100644 --- a/internal/cli/system/core/stats/stats.go +++ b/internal/cli/system/core/stats/stats.go @@ -22,11 +22,11 @@ import ( "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/config/journal" "github.com/ActiveMemory/ctx/internal/config/stats" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" - ctxerr "github.com/ActiveMemory/ctx/internal/err/recall" - io2 "github.com/ActiveMemory/ctx/internal/io" + errRecall "github.com/ActiveMemory/ctx/internal/err/recall" + internalIo "github.com/ActiveMemory/ctx/internal/io" ) // ReadStatsDir reads all stats JSONL files, optionally filtered by session prefix. @@ -42,7 +42,7 @@ func ReadStatsDir(dir, sessionFilter string) ([]Entry, error) { pattern := filepath.Join(dir, stats.FilePrefix+"*"+file.ExtJSONL) matches, globErr := filepath.Glob(pattern) if globErr != nil { - return nil, ctxerr.StatsGlob(globErr) + return nil, errRecall.StatsGlob(globErr) } var entries []Entry @@ -93,7 +93,7 @@ func ExtractStatsSessionID(basename string) string { // - []Entry: parsed entries // - error: non-nil on read failure func ParseStatsFile(path, sid string) ([]Entry, error) { - data, readErr := io2.SafeReadUserFile(path) + data, readErr := internalIo.SafeReadUserFile(path) if readErr != nil { return nil, readErr } @@ -212,7 +212,7 @@ func FormatStatsTimestamp(ts string) string { if parseErr != nil { return ts } - return t.Local().Format(time2.DateTimePreciseFormat) + return t.Local().Format(cfgTime.DateTimePreciseFormat) } // ReadNewLines reads bytes from offset to end and parses JSONL lines. @@ -225,7 +225,7 @@ func FormatStatsTimestamp(ts string) string { // Returns: // - []Entry: newly parsed entries func ReadNewLines(path string, offset int64, sid string) []Entry { - f, openErr := io2.SafeOpenUserFile(path) + f, openErr := internalIo.SafeOpenUserFile(path) if openErr != nil { return nil } diff --git a/internal/cli/system/core/time/doc.go b/internal/cli/system/core/time/doc.go new file mode 100644 index 000000000..c541f3abb --- /dev/null +++ b/internal/cli/system/core/time/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package time returns the most recent modification time across context files. +package time diff --git a/internal/cli/system/core/version/doc.go b/internal/cli/system/core/version/doc.go new file mode 100644 index 000000000..4ca4a5a1a --- /dev/null +++ b/internal/cli/system/core/version/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package version parses semantic versions and checks for update availability. +package version diff --git a/internal/cli/task/cmd/complete/run.go b/internal/cli/task/cmd/complete/run.go index ba440a1e4..6f87e854f 100644 --- a/internal/cli/task/cmd/complete/run.go +++ b/internal/cli/task/cmd/complete/run.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/regex" "github.com/ActiveMemory/ctx/internal/config/token" - ctxerr "github.com/ActiveMemory/ctx/internal/err/task" + errTask "github.com/ActiveMemory/ctx/internal/err/task" "github.com/ActiveMemory/ctx/internal/write/complete" "github.com/spf13/cobra" @@ -44,13 +44,13 @@ func CompleteTask(query, contextDir string) (string, error) { // Check if the file exists if _, statErr := os.Stat(filePath); os.IsNotExist(statErr) { - return "", ctxerr.FileNotFound() + return "", errTask.FileNotFound() } // Read existing content content, readErr := os.ReadFile(filepath.Clean(filePath)) if readErr != nil { - return "", ctxerr.FileRead(readErr) + return "", errTask.FileRead(readErr) } // Parse tasks and find matching one @@ -85,7 +85,7 @@ func CompleteTask(query, contextDir string) (string, error) { strings.ToLower(taskText), strings.ToLower(query), ) { if matchedLine != -1 { - return "", ctxerr.MultipleMatches(query) + return "", errTask.MultipleMatches(query) } matchedLine = i matchedTask = taskText @@ -94,7 +94,7 @@ func CompleteTask(query, contextDir string) (string, error) { } if matchedLine == -1 { - return "", ctxerr.NotFound(query) + return "", errTask.NotFound(query) } // Mark the task as complete @@ -105,7 +105,7 @@ func CompleteTask(query, contextDir string) (string, error) { // Write back newContent := strings.Join(lines, token.NewlineLF) if writeErr := os.WriteFile(filePath, []byte(newContent), fs.PermFile); writeErr != nil { - return "", ctxerr.FileWrite(writeErr) + return "", errTask.FileWrite(writeErr) } return matchedTask, nil diff --git a/internal/cli/task/core/count/doc.go b/internal/cli/task/core/count/doc.go new file mode 100644 index 000000000..83a071fb8 --- /dev/null +++ b/internal/cli/task/core/count/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package count counts pending top-level tasks in TASKS.md. +package count diff --git a/internal/cli/task/core/path/doc.go b/internal/cli/task/core/path/doc.go new file mode 100644 index 000000000..eb060cfaf --- /dev/null +++ b/internal/cli/task/core/path/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package path resolves file paths for TASKS.md and the task archive directory. +package path diff --git a/internal/cli/watch/core/apply/doc.go b/internal/cli/watch/core/apply/doc.go new file mode 100644 index 000000000..f59ed6137 --- /dev/null +++ b/internal/cli/watch/core/apply/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package apply routes context updates to the appropriate handler for writing entries or completing tasks. +package apply diff --git a/internal/cli/watch/core/stream/doc.go b/internal/cli/watch/core/stream/doc.go new file mode 100644 index 000000000..1c8aa58b5 --- /dev/null +++ b/internal/cli/watch/core/stream/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package stream parses stdin for XML context-update tags and dispatches them for processing. +package stream diff --git a/internal/cli/watch/core/stream/stream.go b/internal/cli/watch/core/stream/stream.go index d7feae53f..cd50146c3 100644 --- a/internal/cli/watch/core/stream/stream.go +++ b/internal/cli/watch/core/stream/stream.go @@ -17,8 +17,8 @@ import ( "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/regex" "github.com/ActiveMemory/ctx/internal/config/watch" - ctxerr "github.com/ActiveMemory/ctx/internal/err/fs" - watch2 "github.com/ActiveMemory/ctx/internal/write/watch" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" + writeWatch "github.com/ActiveMemory/ctx/internal/write/watch" "github.com/spf13/cobra" ) @@ -79,13 +79,13 @@ func ProcessStream(cmd *cobra.Command, reader io.Reader, dryRun bool) error { } if dryRun { - watch2.DryRunPreview(cmd, update.Type, update.Content) + writeWatch.DryRunPreview(cmd, update.Type, update.Content) } else { err := apply.ApplyUpdate(update) if err != nil { - watch2.ApplyFailed(cmd, update.Type, err) + writeWatch.ApplyFailed(cmd, update.Type, err) } else { - watch2.ApplySuccess(cmd, update.Type, update.Content) + writeWatch.ApplySuccess(cmd, update.Type, update.Content) updateCount++ } } @@ -94,7 +94,7 @@ func ProcessStream(cmd *cobra.Command, reader io.Reader, dryRun bool) error { } if err := scanner.Err(); err != nil { - return ctxerr.ReadInputStream(err) + return errFs.ReadInputStream(err) } return nil diff --git a/internal/cli/watch/watch.go b/internal/cli/watch/watch.go index 0b861ed8a..5562d5220 100644 --- a/internal/cli/watch/watch.go +++ b/internal/cli/watch/watch.go @@ -9,10 +9,10 @@ package watch import ( "github.com/spf13/cobra" - watchroot "github.com/ActiveMemory/ctx/internal/cli/watch/cmd/root" + watchRoot "github.com/ActiveMemory/ctx/internal/cli/watch/cmd/root" ) // Cmd returns the watch command. func Cmd() *cobra.Command { - return watchroot.Cmd() + return watchRoot.Cmd() } diff --git a/internal/cli/why/cmd/root/run.go b/internal/cli/why/cmd/root/run.go index 730a17466..d287d70bb 100644 --- a/internal/cli/why/cmd/root/run.go +++ b/internal/cli/why/cmd/root/run.go @@ -16,8 +16,8 @@ import ( "github.com/ActiveMemory/ctx/internal/write/why" "github.com/spf13/cobra" - errcli "github.com/ActiveMemory/ctx/internal/err/cli" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" + errCli "github.com/ActiveMemory/ctx/internal/err/cli" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" ) // Run dispatches to the interactive menu or direct document display. @@ -47,13 +47,13 @@ func showMenu(cmd *cobra.Command) error { reader := bufio.NewReader(os.Stdin) input, readErr := reader.ReadString('\n') if readErr != nil { - return fserr.ReadInput(readErr) + return errFs.ReadInput(readErr) } input = strings.TrimSpace(input) choice, parseErr := strconv.Atoi(input) if parseErr != nil || choice < 1 || choice > len(DocOrder) { - return errcli.InvalidSelection(input, len(DocOrder)) + return errCli.InvalidSelection(input, len(DocOrder)) } why.Separator(cmd) @@ -71,12 +71,12 @@ func showMenu(cmd *cobra.Command) error { func ShowDoc(cmd *cobra.Command, alias string) error { name, ok := DocAliases[alias] if !ok { - return errcli.UnknownDocument(alias) + return errCli.UnknownDocument(alias) } content, loadErr := philosophy.WhyDoc(name) if loadErr != nil { - return fserr.FileRead(name, loadErr) + return errFs.FileRead(name, loadErr) } cleaned := StripMkDocs(string(content)) diff --git a/internal/cli/why/strip_test.go b/internal/cli/why/strip_test.go index 143046d65..8d59f5fa9 100644 --- a/internal/cli/why/strip_test.go +++ b/internal/cli/why/strip_test.go @@ -11,12 +11,12 @@ import ( "testing" "github.com/ActiveMemory/ctx/internal/assets/read/philosophy" - whyroot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" + whyRoot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" ) func TestStripMkDocs_Frontmatter(t *testing.T) { input := "---\ntitle: Test\nicon: lucide/flame\n---\n\n# Hello\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if strings.Contains(got, "title: Test") { t.Error("frontmatter was not stripped") } @@ -27,7 +27,7 @@ func TestStripMkDocs_Frontmatter(t *testing.T) { func TestStripMkDocs_Images(t *testing.T) { input := "# Title\n\n![banner](images/banner.png)\n\nSome text.\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if strings.Contains(got, "![banner]") { t.Error("image line was not stripped") } @@ -43,7 +43,7 @@ func TestStripMkDocs_Admonitions(t *testing.T) { Normal text. ` - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if !strings.Contains(got, `> **Important Note**`) { t.Errorf("admonition title not converted, got:\n%s", got) } @@ -60,7 +60,7 @@ Normal text. func TestStripMkDocs_AdmonitionNoTitle(t *testing.T) { input := "!!! warning\n Body here.\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if strings.Contains(got, "!!!") { t.Error("admonition marker was not stripped") } @@ -81,7 +81,7 @@ func TestStripMkDocs_Tabs(t *testing.T) { Normal text. ` - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if !strings.Contains(got, "**Without ctx**") { t.Errorf("tab title not converted, got:\n%s", got) } @@ -101,7 +101,7 @@ Normal text. func TestStripMkDocs_RelativeLinks(t *testing.T) { input := "[Getting Started](getting-started.md) and [About](../home/about.md)\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if strings.Contains(got, ".md") { t.Errorf("relative .md link not stripped, got:\n%s", got) } @@ -115,7 +115,7 @@ func TestStripMkDocs_RelativeLinks(t *testing.T) { func TestStripMkDocs_PreservesExternalLinks(t *testing.T) { input := "[ctx site](https://ctx.ist) stays.\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if !strings.Contains(got, "[ctx site](https://ctx.ist)") { t.Errorf("external link was modified, got:\n%s", got) } @@ -123,7 +123,7 @@ func TestStripMkDocs_PreservesExternalLinks(t *testing.T) { func TestStripMkDocs_PreservesCodeBlocks(t *testing.T) { input := "```text\n{} --> what\nctx --> why\n```\n" - got := whyroot.StripMkDocs(input) + got := whyRoot.StripMkDocs(input) if !strings.Contains(got, "ctx --> why") { t.Errorf("code block content was lost, got:\n%s", got) } @@ -135,7 +135,7 @@ func TestStripMkDocs_EmbeddedManifesto(t *testing.T) { t.Fatalf("failed to load embedded manifesto: %v", loadErr) } - got := whyroot.StripMkDocs(string(content)) + got := whyRoot.StripMkDocs(string(content)) // Should not contain MkDocs artifacts. if strings.Contains(got, "---\ntitle:") { diff --git a/internal/cli/why/why.go b/internal/cli/why/why.go index c7f5a1f6d..6ca9af703 100644 --- a/internal/cli/why/why.go +++ b/internal/cli/why/why.go @@ -9,10 +9,10 @@ package why import ( "github.com/spf13/cobra" - whyroot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" + whyRoot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" ) // Cmd returns the "ctx why" cobra command. func Cmd() *cobra.Command { - return whyroot.Cmd() + return whyRoot.Cmd() } diff --git a/internal/cli/why/why_test.go b/internal/cli/why/why_test.go index 5db92df1d..fa3a33e89 100644 --- a/internal/cli/why/why_test.go +++ b/internal/cli/why/why_test.go @@ -11,7 +11,7 @@ import ( "strings" "testing" - whyroot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" + whyRoot "github.com/ActiveMemory/ctx/internal/cli/why/cmd/root" "github.com/spf13/cobra" ) @@ -27,7 +27,7 @@ func newTestCmd() (*cobra.Command, *bytes.Buffer) { func TestShowDoc_Manifesto(t *testing.T) { cmd, buf := newTestCmd() - showErr := whyroot.ShowDoc(cmd, "manifesto") + showErr := whyRoot.ShowDoc(cmd, "manifesto") if showErr != nil { t.Fatalf("ShowDoc(manifesto) error = %v", showErr) } @@ -44,7 +44,7 @@ func TestShowDoc_Manifesto(t *testing.T) { func TestShowDoc_UnknownAlias(t *testing.T) { cmd, _ := newTestCmd() - showErr := whyroot.ShowDoc(cmd, "nonexistent") + showErr := whyRoot.ShowDoc(cmd, "nonexistent") if showErr == nil { t.Fatal("expected error for unknown document alias") } @@ -106,7 +106,7 @@ func TestExtractAdmonitionTitle(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - got := whyroot.ExtractAdmonitionTitle(tc.input) + got := whyRoot.ExtractAdmonitionTitle(tc.input) if got != tc.want { t.Errorf("ExtractAdmonitionTitle(%q) = %q, want %q", tc.input, got, tc.want) } @@ -139,7 +139,7 @@ func TestExtractTabTitle(t *testing.T) { for _, tc := range tests { t.Run(tc.name, func(t *testing.T) { - got := whyroot.ExtractTabTitle(tc.input) + got := whyRoot.ExtractTabTitle(tc.input) if got != tc.want { t.Errorf("ExtractTabTitle(%q) = %q, want %q", tc.input, got, tc.want) } diff --git a/internal/context/load/loader.go b/internal/context/load/loader.go index 640e9daf8..4b856bf61 100644 --- a/internal/context/load/loader.go +++ b/internal/context/load/loader.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/context/summary" "github.com/ActiveMemory/ctx/internal/context/token" "github.com/ActiveMemory/ctx/internal/entity" - errctx "github.com/ActiveMemory/ctx/internal/err/context" + errCtx "github.com/ActiveMemory/ctx/internal/err/context" "github.com/ActiveMemory/ctx/internal/rc" "github.com/ActiveMemory/ctx/internal/validation" ) @@ -40,12 +40,12 @@ func Do(dir string) (*entity.Context, error) { info, statErr := os.Stat(dir) if statErr != nil { if os.IsNotExist(statErr) { - return nil, errctx.NotFound(dir) + return nil, errCtx.NotFound(dir) } return nil, statErr } if !info.IsDir() { - return nil, errctx.NotFound(dir) + return nil, errCtx.NotFound(dir) } // Reject context directories that contain symlinks (M-2 defense). diff --git a/internal/context/load/loader_test.go b/internal/context/load/loader_test.go index 6a07f912c..41fcc3f00 100644 --- a/internal/context/load/loader_test.go +++ b/internal/context/load/loader_test.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/context/sanitize" "github.com/ActiveMemory/ctx/internal/context/validate" - errctx "github.com/ActiveMemory/ctx/internal/err/context" + errCtx "github.com/ActiveMemory/ctx/internal/err/context" ) func TestExists(t *testing.T) { @@ -137,7 +137,7 @@ func TestLoadNonExistent(t *testing.T) { t.Error("Do() should return error for non-existent directory") } - var notFoundError *errctx.NotFoundError + var notFoundError *errCtx.NotFoundError ok := errors.As(err, ¬FoundError) if !ok { t.Errorf("error should be *NotFoundError, got %T", err) @@ -188,7 +188,7 @@ func TestIsEffectivelyEmpty(t *testing.T) { } func TestNotFoundError(t *testing.T) { - err := errctx.NotFound("/test/path") + err := errCtx.NotFound("/test/path") expected := "context directory not found: /test/path" if err.Error() != expected { t.Errorf("NotFoundError.Error() = %q, want %q", err.Error(), expected) diff --git a/internal/crypto/crypto.go b/internal/crypto/crypto.go index 6fa68e410..e7fdd329e 100644 --- a/internal/crypto/crypto.go +++ b/internal/crypto/crypto.go @@ -20,8 +20,8 @@ import ( "github.com/ActiveMemory/ctx/internal/config/crypto" "github.com/ActiveMemory/ctx/internal/config/fs" - ctxerr "github.com/ActiveMemory/ctx/internal/err/crypto" - io2 "github.com/ActiveMemory/ctx/internal/io" + errCrypto "github.com/ActiveMemory/ctx/internal/err/crypto" + internalIo "github.com/ActiveMemory/ctx/internal/io" ) // GenerateKey returns a new 256-bit random key. @@ -32,7 +32,7 @@ import ( func GenerateKey() ([]byte, error) { key := make([]byte, crypto.KeySize) if _, err := io.ReadFull(rand.Reader, key); err != nil { - return nil, ctxerr.GenerateKey(err) + return nil, errCrypto.GenerateKey(err) } return key, nil } @@ -53,17 +53,17 @@ func GenerateKey() ([]byte, error) { func Encrypt(key, plaintext []byte) ([]byte, error) { block, err := aes.NewCipher(key) if err != nil { - return nil, ctxerr.CreateCipher(err) + return nil, errCrypto.CreateCipher(err) } gcm, err := cipher.NewGCM(block) if err != nil { - return nil, ctxerr.CreateGCM(err) + return nil, errCrypto.CreateGCM(err) } nonce := make([]byte, crypto.NonceSize) if _, err := io.ReadFull(rand.Reader, nonce); err != nil { - return nil, ctxerr.GenerateNonce(err) + return nil, errCrypto.GenerateNonce(err) } ciphertext := gcm.Seal(nonce, nonce, plaintext, nil) @@ -82,17 +82,17 @@ func Encrypt(key, plaintext []byte) ([]byte, error) { // authentication fails func Decrypt(key, ciphertext []byte) ([]byte, error) { if len(ciphertext) < crypto.NonceSize { - return nil, ctxerr.CiphertextTooShort() + return nil, errCrypto.CiphertextTooShort() } block, err := aes.NewCipher(key) if err != nil { - return nil, ctxerr.CreateCipher(err) + return nil, errCrypto.CreateCipher(err) } gcm, err := cipher.NewGCM(block) if err != nil { - return nil, ctxerr.CreateGCM(err) + return nil, errCrypto.CreateGCM(err) } nonce := ciphertext[:crypto.NonceSize] @@ -100,7 +100,7 @@ func Decrypt(key, ciphertext []byte) ([]byte, error) { plaintext, err := gcm.Open(nil, nonce, data, nil) if err != nil { - return nil, ctxerr.Decrypt(err) + return nil, errCrypto.Decrypt(err) } return plaintext, nil @@ -115,12 +115,12 @@ func Decrypt(key, ciphertext []byte) ([]byte, error) { // - []byte: The 32-byte key // - error: Non-nil if the file cannot be read or is not exactly 32 bytes func LoadKey(path string) ([]byte, error) { - key, err := io2.SafeReadUserFile(path) + key, err := internalIo.SafeReadUserFile(path) if err != nil { - return nil, ctxerr.ReadKey(err) + return nil, errCrypto.ReadKey(err) } if len(key) != crypto.KeySize { - return nil, ctxerr.InvalidKeySize(len(key), crypto.KeySize) + return nil, errCrypto.InvalidKeySize(len(key), crypto.KeySize) } return key, nil } @@ -135,7 +135,7 @@ func LoadKey(path string) ([]byte, error) { // - error: Non-nil if the file cannot be written func SaveKey(path string, key []byte) error { if err := os.WriteFile(path, key, fs.PermSecret); err != nil { - return ctxerr.WriteKey(err) + return errCrypto.WriteKey(err) } return nil } diff --git a/internal/crypto/keypath.go b/internal/crypto/keypath.go index 28c70ae28..942f1234c 100644 --- a/internal/crypto/keypath.go +++ b/internal/crypto/keypath.go @@ -11,7 +11,7 @@ import ( "path/filepath" "strings" - cryptocfg "github.com/ActiveMemory/ctx/internal/config/crypto" + cfgCrypto "github.com/ActiveMemory/ctx/internal/config/crypto" "github.com/ActiveMemory/ctx/internal/config/dir" ) @@ -24,7 +24,7 @@ func GlobalKeyPath() string { if err != nil { return "" } - return filepath.Join(home, dir.CtxData, cryptocfg.ContextKey) + return filepath.Join(home, dir.CtxData, cfgCrypto.ContextKey) } // ExpandHome expands a leading ~/ prefix to the user's home directory. @@ -69,7 +69,7 @@ func ResolveKeyPath(contextDir, overridePath string) string { } // Tier 2: project-local key. - local := filepath.Join(contextDir, cryptocfg.ContextKey) + local := filepath.Join(contextDir, cfgCrypto.ContextKey) if _, err := os.Stat(local); err == nil { return local } diff --git a/internal/crypto/keypath_test.go b/internal/crypto/keypath_test.go index bfa24a94f..f2e91cc1d 100644 --- a/internal/crypto/keypath_test.go +++ b/internal/crypto/keypath_test.go @@ -11,7 +11,7 @@ import ( "path/filepath" "testing" - cryptocfg "github.com/ActiveMemory/ctx/internal/config/crypto" + cfgCrypto "github.com/ActiveMemory/ctx/internal/config/crypto" "github.com/ActiveMemory/ctx/internal/config/fs" ) @@ -20,7 +20,7 @@ func TestGlobalKeyPath(t *testing.T) { t.Setenv("HOME", dir) got := GlobalKeyPath() - want := filepath.Join(dir, ".ctx", cryptocfg.ContextKey) + want := filepath.Join(dir, ".ctx", cfgCrypto.ContextKey) if got != want { t.Errorf("GlobalKeyPath() = %q, want %q", got, want) } @@ -71,7 +71,7 @@ func TestResolveKeyPath_ProjectLocalBeforeGlobal(t *testing.T) { if err := os.MkdirAll(contextDir, 0750); err != nil { t.Fatal(err) } - localKey := filepath.Join(contextDir, cryptocfg.ContextKey) + localKey := filepath.Join(contextDir, cfgCrypto.ContextKey) if err := os.WriteFile(localKey, []byte("local-key"), fs.PermSecret); err != nil { t.Fatal(err) } @@ -80,7 +80,7 @@ func TestResolveKeyPath_ProjectLocalBeforeGlobal(t *testing.T) { if err := os.MkdirAll(globalDir, fs.PermKeyDir); err != nil { t.Fatal(err) } - globalKey := filepath.Join(globalDir, cryptocfg.ContextKey) + globalKey := filepath.Join(globalDir, cfgCrypto.ContextKey) if err := os.WriteFile(globalKey, []byte("global-key"), fs.PermSecret); err != nil { t.Fatal(err) } @@ -100,7 +100,7 @@ func TestResolveKeyPath_FallbackToGlobal(t *testing.T) { if err := os.MkdirAll(globalDir, fs.PermKeyDir); err != nil { t.Fatal(err) } - globalKey := filepath.Join(globalDir, cryptocfg.ContextKey) + globalKey := filepath.Join(globalDir, cfgCrypto.ContextKey) if err := os.WriteFile(globalKey, []byte("global-key"), fs.PermSecret); err != nil { t.Fatal(err) } diff --git a/internal/index/index.go b/internal/index/index.go index ce2943fba..c9f4232b4 100644 --- a/internal/index/index.go +++ b/internal/index/index.go @@ -19,8 +19,8 @@ import ( "github.com/ActiveMemory/ctx/internal/config/marker" "github.com/ActiveMemory/ctx/internal/config/regex" "github.com/ActiveMemory/ctx/internal/config/token" - ctxerr "github.com/ActiveMemory/ctx/internal/err/recall" - io2 "github.com/ActiveMemory/ctx/internal/io" + errRecall "github.com/ActiveMemory/ctx/internal/err/recall" + internalIo "github.com/ActiveMemory/ctx/internal/io" ) // ParseHeaders extracts all entries from file content. @@ -216,18 +216,18 @@ func ReindexFile( entryType string, ) error { if _, err := os.Stat(filePath); os.IsNotExist(err) { - return ctxerr.ReindexFileNotFound(fileName) + return errRecall.ReindexFileNotFound(fileName) } - content, err := io2.SafeReadUserFile(filePath) + content, err := internalIo.SafeReadUserFile(filePath) if err != nil { - return ctxerr.ReindexFileRead(filePath, err) + return errRecall.ReindexFileRead(filePath, err) } updated := updateFunc(string(content)) if err := os.WriteFile(filePath, []byte(updated), fs.PermFile); err != nil { - return ctxerr.ReindexFileWrite(filePath, err) + return errRecall.ReindexFileWrite(filePath, err) } entries := ParseHeaders(string(content)) diff --git a/internal/io/security.go b/internal/io/security.go index 7e3e154f7..b18de52e2 100644 --- a/internal/io/security.go +++ b/internal/io/security.go @@ -15,9 +15,9 @@ import ( "strings" "time" - configFs "github.com/ActiveMemory/ctx/internal/config/fs" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" - ctxerr "github.com/ActiveMemory/ctx/internal/err/http" + cfgFs "github.com/ActiveMemory/ctx/internal/config/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" + errHTTP "github.com/ActiveMemory/ctx/internal/err/http" ) // SafeReadFile resolves filename within baseDir, verifies the result @@ -37,13 +37,13 @@ import ( func SafeReadFile(baseDir, filename string) ([]byte, error) { absBase, absErr := filepath.Abs(baseDir) if absErr != nil { - return nil, fserr.ResolveBase(absErr) + return nil, errFs.ResolveBase(absErr) } safe := filepath.Join(absBase, filepath.Base(filename)) if !strings.HasPrefix(safe, absBase+string(os.PathSeparator)) { - return nil, fserr.PathEscapesBase(filename) + return nil, errFs.PathEscapesBase(filename) } data, readErr := os.ReadFile(safe) //nolint:gosec @@ -154,7 +154,7 @@ func SafeWriteFile(path string, data []byte, perm os.FileMode) error { // Parameters: // - path: absolute file path to touch func TouchFile(path string) { - _ = os.WriteFile(path, nil, configFs.PermSecret) //nolint:gosec // state marker, path from internal code + _ = os.WriteFile(path, nil, cfgFs.PermSecret) //nolint:gosec // state marker, path from internal code } // maxRedirects caps the number of HTTP redirects the client will follow. @@ -205,7 +205,7 @@ func SafePost( Timeout: timeout, CheckRedirect: func(_ *http.Request, via []*http.Request) error { if len(via) >= maxRedirects { - return ctxerr.TooManyRedirects() + return errHTTP.TooManyRedirects() } return nil }, @@ -221,11 +221,11 @@ func SafePost( func validateHTTPScheme(rawURL string) error { parsed, parseErr := url.Parse(rawURL) if parseErr != nil { - return ctxerr.ParseURL(parseErr) + return errHTTP.ParseURL(parseErr) } scheme := strings.ToLower(parsed.Scheme) if scheme != "http" && scheme != "https" { - return ctxerr.UnsafeURLScheme(parsed.Scheme) + return errHTTP.UnsafeURLScheme(parsed.Scheme) } return nil } diff --git a/internal/io/validate.go b/internal/io/validate.go index fcab7728d..fa97c3b37 100644 --- a/internal/io/validate.go +++ b/internal/io/validate.go @@ -10,18 +10,18 @@ import ( "path/filepath" "strings" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" ) // rejectDangerousPath returns an error if the resolved absolute path // falls under a system directory that ctx should never touch. func rejectDangerousPath(absPath string) error { if absPath == "/" { - return fserr.RefuseSystemPathRoot() + return errFs.RefuseSystemPathRoot() } for _, prefix := range dangerousPrefixes { if strings.HasPrefix(absPath, prefix) { - return fserr.RefuseSystemPath(absPath) + return errFs.RefuseSystemPath(absPath) } } return nil @@ -33,7 +33,7 @@ func cleanAndValidate(path string) (string, error) { clean := filepath.Clean(path) abs, absErr := filepath.Abs(clean) if absErr != nil { - return "", fserr.ResolvePath(absErr) + return "", errFs.ResolvePath(absErr) } if checkErr := rejectDangerousPath(abs); checkErr != nil { return "", checkErr diff --git a/internal/mcp/handler/task/doc.go b/internal/mcp/handler/task/doc.go new file mode 100644 index 000000000..45da8d231 --- /dev/null +++ b/internal/mcp/handler/task/doc.go @@ -0,0 +1,8 @@ +// / ctx: https://ctx.ist +// ,'`./ do you remember? +// `.,'\ +// \ Copyright 2026-present Context contributors. +// SPDX-License-Identifier: Apache-2.0 + +// Package task iterates pending tasks from TASKS.md for MCP tool responses. +package task diff --git a/internal/mcp/handler/tool.go b/internal/mcp/handler/tool.go index 47bd2a462..774581f9f 100644 --- a/internal/mcp/handler/tool.go +++ b/internal/mcp/handler/tool.go @@ -13,22 +13,22 @@ import ( "time" "github.com/ActiveMemory/ctx/internal/assets/read/desc" - remindcore "github.com/ActiveMemory/ctx/internal/cli/remind/core" - taskcomplete "github.com/ActiveMemory/ctx/internal/cli/task/cmd/complete" - archiveCfg "github.com/ActiveMemory/ctx/internal/config/archive" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + remindCore "github.com/ActiveMemory/ctx/internal/cli/remind/core" + taskComplete "github.com/ActiveMemory/ctx/internal/cli/task/cmd/complete" + cfgArchive "github.com/ActiveMemory/ctx/internal/config/archive" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" - entryCfg "github.com/ActiveMemory/ctx/internal/config/entry" - configfs "github.com/ActiveMemory/ctx/internal/config/fs" + cfgEntry "github.com/ActiveMemory/ctx/internal/config/entry" + cfgFs "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/mcp/event" "github.com/ActiveMemory/ctx/internal/config/mcp/field" - timeCfg "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/context/load" "github.com/ActiveMemory/ctx/internal/drift" "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/entry" - mcpErr "github.com/ActiveMemory/ctx/internal/err/mcp" + errMcp "github.com/ActiveMemory/ctx/internal/err/mcp" "github.com/ActiveMemory/ctx/internal/mcp/handler/task" "github.com/ActiveMemory/ctx/internal/mcp/server/stat" "github.com/ActiveMemory/ctx/internal/mcp/session" @@ -131,7 +131,7 @@ func (h *Handler) Complete(query string) (string, error) { return "", boundaryErr } - completedTask, completeErr := taskcomplete.CompleteTask( + completedTask, completeErr := taskComplete.CompleteTask( query, h.ContextDir, ) if completeErr != nil { @@ -245,7 +245,7 @@ func (h *Handler) Recall(limit int, since time.Time) (string, error) { _, _ = fmt.Fprintf( &sb, desc.Text(text.DescKeyMCPRecallItemFormat), - i+1, sess.StartTime.Format(timeCfg.DateTimeFormat), + i+1, sess.StartTime.Format(cfgTime.DateTimeFormat), ) if sess.Project != "" { _, _ = fmt.Fprintf( @@ -289,8 +289,8 @@ func (h *Handler) WatchUpdate( } // Handle the "complete" type as a special case. - if entryType == entryCfg.Complete { - completedTask, completeErr := taskcomplete.CompleteTask( + if entryType == cfgEntry.Complete { + completedTask, completeErr := taskComplete.CompleteTask( content, h.ContextDir) if completeErr != nil { return "", completeErr @@ -366,7 +366,7 @@ func (h *Handler) Compact(archive bool) (string, error) { if writeErr := os.WriteFile( result.TasksFileUpdate.Path, result.TasksFileUpdate.Content, - configfs.PermFile, + cfgFs.PermFile, ); writeErr != nil { return "", writeErr } @@ -375,7 +375,7 @@ func (h *Handler) Compact(archive bool) (string, error) { // Write section-cleaned files. for _, fu := range result.SectionFileUpdates { if writeErr := os.WriteFile( - fu.Path, fu.Content, configfs.PermFile, + fu.Path, fu.Content, cfgFs.PermFile, ); writeErr != nil { return "", writeErr } @@ -390,7 +390,7 @@ func (h *Handler) Compact(archive bool) (string, error) { token.NewlineLF + token.NewlineLF } if _, archiveErr := tidy.WriteArchive( - archiveCfg.ArchiveScopeTasks, + cfgArchive.ArchiveScopeTasks, desc.Text(text.DescKeyHeadingArchivedTasks), archiveContent, ); archiveErr != nil { @@ -445,7 +445,7 @@ func (h *Handler) Next() (string, error) { return "", loadErr } - tasksFile := ctx.File(ctxCfg.Task) + tasksFile := ctx.File(cfgCtx.Task) if tasksFile == nil { return desc.Text(text.DescKeyMCPNoTasks), nil } @@ -483,7 +483,7 @@ func (h *Handler) CheckTaskCompletion(recentAction string) (string, error) { return "", loadErr } - tasksFile := ctx.File(ctxCfg.Task) + tasksFile := ctx.File(cfgCtx.Task) if tasksFile == nil { return "", nil } @@ -572,7 +572,7 @@ func (h *Handler) SessionEvent( return sb.String(), nil default: - return "", mcpErr.UnknownEventType(eventType) + return "", errMcp.UnknownEventType(eventType) } } @@ -582,7 +582,7 @@ func (h *Handler) SessionEvent( // - string: formatted reminder list or no-reminders message // - error: reminder read error func (h *Handler) Remind() (string, error) { - reminders, readErr := remindcore.ReadReminders() + reminders, readErr := remindCore.ReadReminders() if readErr != nil { return "", readErr } @@ -591,7 +591,7 @@ func (h *Handler) Remind() (string, error) { return desc.Text(text.DescKeyMCPNoReminders), nil } - today := time.Now().Format(timeCfg.DateFormat) + today := time.Now().Format(cfgTime.DateFormat) var sb strings.Builder _, _ = fmt.Fprintf( &sb, diff --git a/internal/mcp/server/catalog/data.go b/internal/mcp/server/catalog/data.go index 8068cec2a..40ae8f39f 100644 --- a/internal/mcp/server/catalog/data.go +++ b/internal/mcp/server/catalog/data.go @@ -8,7 +8,7 @@ package catalog import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/mcp/resource" ) @@ -23,14 +23,14 @@ type mapping struct { // table defines all individual context file resources. var table = []mapping{ - {ctxCfg.Constitution, resource.Constitution, desc.Text(text.DescKeyMCPResConstitution)}, - {ctxCfg.Task, resource.Tasks, desc.Text(text.DescKeyMCPResTasks)}, - {ctxCfg.Convention, resource.Conventions, desc.Text(text.DescKeyMCPResConventions)}, - {ctxCfg.Architecture, resource.Architecture, desc.Text(text.DescKeyMCPResArchitecture)}, - {ctxCfg.Decision, resource.Decisions, desc.Text(text.DescKeyMCPResDecisions)}, - {ctxCfg.Learning, resource.Learnings, desc.Text(text.DescKeyMCPResLearnings)}, - {ctxCfg.Glossary, resource.Glossary, desc.Text(text.DescKeyMCPResGlossary)}, - {ctxCfg.AgentPlaybook, resource.Playbook, desc.Text(text.DescKeyMCPResPlaybook)}, + {cfgCtx.Constitution, resource.Constitution, desc.Text(text.DescKeyMCPResConstitution)}, + {cfgCtx.Task, resource.Tasks, desc.Text(text.DescKeyMCPResTasks)}, + {cfgCtx.Convention, resource.Conventions, desc.Text(text.DescKeyMCPResConventions)}, + {cfgCtx.Architecture, resource.Architecture, desc.Text(text.DescKeyMCPResArchitecture)}, + {cfgCtx.Decision, resource.Decisions, desc.Text(text.DescKeyMCPResDecisions)}, + {cfgCtx.Learning, resource.Learnings, desc.Text(text.DescKeyMCPResLearnings)}, + {cfgCtx.Glossary, resource.Glossary, desc.Text(text.DescKeyMCPResGlossary)}, + {cfgCtx.AgentPlaybook, resource.Playbook, desc.Text(text.DescKeyMCPResPlaybook)}, } // uriLookup maps full resource URIs to context file names. Populated diff --git a/internal/mcp/server/def/prompt/prompt.go b/internal/mcp/server/def/prompt/prompt.go index 8efd0103b..3c071e503 100644 --- a/internal/mcp/server/def/prompt/prompt.go +++ b/internal/mcp/server/def/prompt/prompt.go @@ -11,19 +11,19 @@ import ( "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/mcp/field" - promptCfg "github.com/ActiveMemory/ctx/internal/config/mcp/prompt" + cfgMcpPrompt "github.com/ActiveMemory/ctx/internal/config/mcp/prompt" "github.com/ActiveMemory/ctx/internal/mcp/proto" ) // Defs defines all available MCP prompts. var Defs = []proto.Prompt{ { - Name: promptCfg.SessionStart, + Name: cfgMcpPrompt.SessionStart, Description: desc.Text( text.DescKeyMCPPromptSessionStartDesc), }, { - Name: promptCfg.AddDecision, + Name: cfgMcpPrompt.AddDecision, Description: desc.Text( text.DescKeyMCPPromptAddDecisionDesc), Arguments: []proto.PromptArgument{ @@ -50,7 +50,7 @@ var Defs = []proto.Prompt{ }, }, { - Name: promptCfg.AddLearning, + Name: cfgMcpPrompt.AddLearning, Description: desc.Text( text.DescKeyMCPPromptAddLearningDesc), Arguments: []proto.PromptArgument{ @@ -77,12 +77,12 @@ var Defs = []proto.Prompt{ }, }, { - Name: promptCfg.Reflect, + Name: cfgMcpPrompt.Reflect, Description: desc.Text( text.DescKeyMCPPromptReflectDesc), }, { - Name: promptCfg.Checkpoint, + Name: cfgMcpPrompt.Checkpoint, Description: desc.Text( text.DescKeyMCPPromptCheckpointDesc), }, diff --git a/internal/mcp/server/def/tool/tool.go b/internal/mcp/server/def/tool/tool.go index dd4c25665..8713f6e2d 100644 --- a/internal/mcp/server/def/tool/tool.go +++ b/internal/mcp/server/def/tool/tool.go @@ -13,21 +13,21 @@ import ( "github.com/ActiveMemory/ctx/internal/config/entry" "github.com/ActiveMemory/ctx/internal/config/mcp/field" "github.com/ActiveMemory/ctx/internal/config/mcp/schema" - toolCfg "github.com/ActiveMemory/ctx/internal/config/mcp/tool" + cfgMcpTool "github.com/ActiveMemory/ctx/internal/config/mcp/tool" "github.com/ActiveMemory/ctx/internal/mcp/proto" ) // Defs defines all available MCP tools. var Defs = []proto.Tool{ { - Name: toolCfg.Status, + Name: cfgMcpTool.Status, Description: desc.Text( text.DescKeyMCPToolStatusDesc), InputSchema: proto.InputSchema{Type: schema.Object}, Annotations: &proto.ToolAnnotations{ReadOnlyHint: true}, }, { - Name: toolCfg.Add, + Name: cfgMcpTool.Add, Description: desc.Text( text.DescKeyMCPToolAddDesc), InputSchema: proto.InputSchema{ @@ -60,7 +60,7 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{}, }, { - Name: toolCfg.Complete, + Name: cfgMcpTool.Complete, Description: desc.Text( text.DescKeyMCPToolCompleteDesc), InputSchema: proto.InputSchema{ @@ -77,14 +77,14 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{IdempotentHint: true}, }, { - Name: toolCfg.Drift, + Name: cfgMcpTool.Drift, Description: desc.Text( text.DescKeyMCPToolDriftDesc), InputSchema: proto.InputSchema{Type: schema.Object}, Annotations: &proto.ToolAnnotations{ReadOnlyHint: true}, }, { - Name: toolCfg.Recall, + Name: cfgMcpTool.Recall, Description: desc.Text( text.DescKeyMCPToolRecallDesc), InputSchema: proto.InputSchema{ @@ -105,7 +105,7 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{ReadOnlyHint: true}, }, { - Name: toolCfg.WatchUpdate, + Name: cfgMcpTool.WatchUpdate, Description: desc.Text( text.DescKeyMCPToolWatchUpdateDesc), InputSchema: proto.InputSchema{ @@ -128,7 +128,7 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{}, }, { - Name: toolCfg.Compact, + Name: cfgMcpTool.Compact, Description: desc.Text( text.DescKeyMCPToolCompactDesc), InputSchema: proto.InputSchema{ @@ -144,14 +144,14 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{}, }, { - Name: toolCfg.Next, + Name: cfgMcpTool.Next, Description: desc.Text( text.DescKeyMCPToolNextDesc), InputSchema: proto.InputSchema{Type: schema.Object}, Annotations: &proto.ToolAnnotations{ReadOnlyHint: true}, }, { - Name: toolCfg.CheckTaskCompletion, + Name: cfgMcpTool.CheckTaskCompletion, Description: desc.Text( text.DescKeyMCPToolCheckTaskDesc), InputSchema: proto.InputSchema{ @@ -167,7 +167,7 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{ReadOnlyHint: true}, }, { - Name: toolCfg.SessionEvent, + Name: cfgMcpTool.SessionEvent, Description: desc.Text( text.DescKeyMCPToolSessionDesc), InputSchema: proto.InputSchema{ @@ -189,7 +189,7 @@ var Defs = []proto.Tool{ Annotations: &proto.ToolAnnotations{}, }, { - Name: toolCfg.Remind, + Name: cfgMcpTool.Remind, Description: desc.Text( text.DescKeyMCPToolRemindDesc), InputSchema: proto.InputSchema{Type: schema.Object}, diff --git a/internal/mcp/server/extract/extract.go b/internal/mcp/server/extract/extract.go index 16ac7e6ad..441503b0f 100644 --- a/internal/mcp/server/extract/extract.go +++ b/internal/mcp/server/extract/extract.go @@ -9,7 +9,7 @@ package extract import ( "github.com/ActiveMemory/ctx/internal/config/cli" "github.com/ActiveMemory/ctx/internal/config/mcp/field" - mcperr "github.com/ActiveMemory/ctx/internal/err/mcp" + errMcp "github.com/ActiveMemory/ctx/internal/err/mcp" "github.com/ActiveMemory/ctx/internal/mcp/handler" ) @@ -29,7 +29,7 @@ func EntryArgs( content, _ := args[field.Content].(string) if entryType == "" || content == "" { - return "", "", mcperr.TypeContentRequired() + return "", "", errMcp.TypeContentRequired() } return entryType, content, nil diff --git a/internal/mcp/server/resource/resource.go b/internal/mcp/server/resource/resource.go index 96f3d4ed1..b6673c4d1 100644 --- a/internal/mcp/server/resource/resource.go +++ b/internal/mcp/server/resource/resource.go @@ -12,7 +12,7 @@ import ( "strings" "github.com/ActiveMemory/ctx/internal/assets/read/desc" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/mcp/mime" "github.com/ActiveMemory/ctx/internal/config/token" @@ -78,7 +78,7 @@ func readAgentPacket( tokensUsed := ctxToken.EstimateTokensString(header) var skipped []string - for _, fileName := range ctxCfg.ReadOrder { + for _, fileName := range cfgCtx.ReadOrder { f := ctx.File(fileName) if f == nil || f.IsEmpty { continue diff --git a/internal/mcp/server/route/prompt/dispatch.go b/internal/mcp/server/route/prompt/dispatch.go index 11c169260..dcce69264 100644 --- a/internal/mcp/server/route/prompt/dispatch.go +++ b/internal/mcp/server/route/prompt/dispatch.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/mcp/prompt" "github.com/ActiveMemory/ctx/internal/mcp/handler" "github.com/ActiveMemory/ctx/internal/mcp/proto" - promptdef "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" + defPrompt "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" "github.com/ActiveMemory/ctx/internal/mcp/server/out" ) @@ -28,7 +28,7 @@ import ( // - *proto.Response: prompt list response func DispatchList(req proto.Request) *proto.Response { return out.OkResponse( - req.ID, proto.PromptListResult{Prompts: promptdef.Defs}, + req.ID, proto.PromptListResult{Prompts: defPrompt.Defs}, ) } diff --git a/internal/mcp/server/route/prompt/entry.go b/internal/mcp/server/route/prompt/entry.go index fabd290f0..891e6a4e1 100644 --- a/internal/mcp/server/route/prompt/entry.go +++ b/internal/mcp/server/route/prompt/entry.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/mcp/prompt" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/mcp/proto" - promptdef "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" + defPrompt "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" "github.com/ActiveMemory/ctx/internal/mcp/server/out" ) @@ -30,7 +30,7 @@ import ( // Returns: // - *proto.Response: formatted entry prompt func buildEntry( - id json.RawMessage, spec promptdef.EntryPromptSpec, + id json.RawMessage, spec defPrompt.EntryPromptSpec, ) *proto.Response { fieldFmt := desc.Text(spec.FieldFmtK) diff --git a/internal/mcp/server/route/prompt/prompt.go b/internal/mcp/server/route/prompt/prompt.go index a906612a8..65e545cb3 100644 --- a/internal/mcp/server/route/prompt/prompt.go +++ b/internal/mcp/server/route/prompt/prompt.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/config/cli" - ctxCfg "github.com/ActiveMemory/ctx/internal/config/ctx" + cfgCtx "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/mcp/field" "github.com/ActiveMemory/ctx/internal/config/mcp/mime" @@ -21,7 +21,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/context/load" "github.com/ActiveMemory/ctx/internal/mcp/proto" - promptdef "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" + defPrompt "github.com/ActiveMemory/ctx/internal/mcp/server/def/prompt" "github.com/ActiveMemory/ctx/internal/mcp/server/out" "github.com/ActiveMemory/ctx/internal/mcp/server/stat" ) @@ -51,7 +51,7 @@ func sessionStart( sb.WriteString(token.NewlineLF) sb.WriteString(token.NewlineLF) - for _, fileName := range ctxCfg.ReadOrder { + for _, fileName := range cfgCtx.ReadOrder { f := ctx.File(fileName) if f == nil || f.IsEmpty { continue @@ -146,12 +146,12 @@ func checkpoint( func addDecision( id json.RawMessage, args map[string]string, ) *proto.Response { - return buildEntry(id, promptdef.EntryPromptSpec{ + return buildEntry(id, defPrompt.EntryPromptSpec{ KeyHeader: text.DescKeyMCPPromptAddDecisionHeader, KeyFooter: text.DescKeyMCPPromptAddDecisionFooter, FieldFmtK: text.DescKeyMCPPromptAddDecisionFieldFmt, KeyResultD: text.DescKeyMCPPromptAddDecisionResultD, - Fields: []promptdef.EntryField{ + Fields: []defPrompt.EntryField{ {KeyLabel: text.DescKeyMCPPromptLabelDecision, Value: args[field.Content]}, {KeyLabel: text.DescKeyMCPPromptLabelContext, @@ -176,12 +176,12 @@ func addDecision( func addLearning( id json.RawMessage, args map[string]string, ) *proto.Response { - return buildEntry(id, promptdef.EntryPromptSpec{ + return buildEntry(id, defPrompt.EntryPromptSpec{ KeyHeader: text.DescKeyMCPPromptAddLearningHeader, KeyFooter: text.DescKeyMCPPromptAddLearningFooter, FieldFmtK: text.DescKeyMCPPromptAddLearningFieldFmt, KeyResultD: text.DescKeyMCPPromptAddLearningResultD, - Fields: []promptdef.EntryField{ + Fields: []defPrompt.EntryField{ {KeyLabel: text.DescKeyMCPPromptLabelLearning, Value: args[field.Content]}, {KeyLabel: text.DescKeyMCPPromptLabelContext, diff --git a/internal/mcp/server/route/tool/dispatch.go b/internal/mcp/server/route/tool/dispatch.go index 76fb5ea32..46bd0f774 100644 --- a/internal/mcp/server/route/tool/dispatch.go +++ b/internal/mcp/server/route/tool/dispatch.go @@ -15,7 +15,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/mcp/tool" "github.com/ActiveMemory/ctx/internal/mcp/handler" "github.com/ActiveMemory/ctx/internal/mcp/proto" - tooldef "github.com/ActiveMemory/ctx/internal/mcp/server/def/tool" + defTool "github.com/ActiveMemory/ctx/internal/mcp/server/def/tool" "github.com/ActiveMemory/ctx/internal/mcp/server/out" ) @@ -27,7 +27,7 @@ import ( // Returns: // - *proto.Response: tool list response func DispatchList(req proto.Request) *proto.Response { - return out.OkResponse(req.ID, proto.ToolListResult{Tools: tooldef.Defs}) + return out.OkResponse(req.ID, proto.ToolListResult{Tools: defTool.Defs}) } // DispatchCall unmarshals tool call params and dispatches to the diff --git a/internal/mcp/server/route/tool/tool.go b/internal/mcp/server/route/tool/tool.go index 12dfe2d7a..e5aa22f52 100644 --- a/internal/mcp/server/route/tool/tool.go +++ b/internal/mcp/server/route/tool/tool.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/mcp/cfg" "github.com/ActiveMemory/ctx/internal/config/mcp/field" - timeCfg "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/mcp/handler" "github.com/ActiveMemory/ctx/internal/mcp/proto" "github.com/ActiveMemory/ctx/internal/mcp/server/extract" @@ -88,7 +88,7 @@ func recall( var since time.Time if sinceStr, _ := args[field.Since].(string); sinceStr != "" { var parseErr error - since, parseErr = time.Parse(timeCfg.DateFormat, sinceStr) + since, parseErr = time.Parse(cfgTime.DateFormat, sinceStr) if parseErr != nil { return out.ToolError( id, fmt.Sprintf( diff --git a/internal/memory/discover.go b/internal/memory/discover.go index 4960abc15..ac96e2bc9 100644 --- a/internal/memory/discover.go +++ b/internal/memory/discover.go @@ -13,7 +13,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/memory" - ctxerr "github.com/ActiveMemory/ctx/internal/err/memory" + errMemory "github.com/ActiveMemory/ctx/internal/err/memory" ) // DiscoverMemoryPath locates Claude Code's auto memory file for the @@ -26,19 +26,19 @@ import ( func DiscoverMemoryPath(projectRoot string) (string, error) { abs, absErr := filepath.Abs(projectRoot) if absErr != nil { - return "", ctxerr.DiscoverResolveRoot(absErr) + return "", errMemory.DiscoverResolveRoot(absErr) } home, homeErr := os.UserHomeDir() if homeErr != nil { - return "", ctxerr.DiscoverResolveHome(homeErr) + return "", errMemory.DiscoverResolveHome(homeErr) } slug := ProjectSlug(abs) memPath := filepath.Join(home, dir.Claude, dir.Projects, slug, dir.Memory, memory.MemorySource) if _, statErr := os.Stat(memPath); statErr != nil { - return "", ctxerr.DiscoverNoMemory(memPath) + return "", errMemory.DiscoverNoMemory(memPath) } return memPath, nil } diff --git a/internal/memory/mirror.go b/internal/memory/mirror.go index 6ac03d3d5..c59d59b05 100644 --- a/internal/memory/mirror.go +++ b/internal/memory/mirror.go @@ -20,9 +20,9 @@ import ( "github.com/ActiveMemory/ctx/internal/config/file" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/memory" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" - ctxerr "github.com/ActiveMemory/ctx/internal/err/memory" + errMemory "github.com/ActiveMemory/ctx/internal/err/memory" "github.com/ActiveMemory/ctx/internal/io" ) @@ -34,7 +34,7 @@ func Sync(contextDir, sourcePath string) (SyncResult, error) { sourceData, readErr := io.SafeReadUserFile(sourcePath) if readErr != nil { - return SyncResult{}, ctxerr.ReadSource(readErr) + return SyncResult{}, errMemory.ReadSource(readErr) } result := SyncResult{ @@ -48,17 +48,17 @@ func Sync(contextDir, sourcePath string) (SyncResult, error) { result.MirrorLines = countLines(existingData) archivePath, archiveErr := Archive(contextDir) if archiveErr != nil { - return SyncResult{}, ctxerr.ArchivePrevious(archiveErr) + return SyncResult{}, errMemory.ArchivePrevious(archiveErr) } result.ArchivedTo = archivePath } if mkErr := os.MkdirAll(mirrorDir, fs.PermExec); mkErr != nil { - return SyncResult{}, ctxerr.CreateDir(mkErr) + return SyncResult{}, errMemory.CreateDir(mkErr) } if writeErr := os.WriteFile(mirrorPath, sourceData, fs.PermFile); writeErr != nil { - return SyncResult{}, ctxerr.WriteMirror(writeErr) + return SyncResult{}, errMemory.WriteMirror(writeErr) } return result, nil @@ -72,18 +72,18 @@ func Archive(contextDir string) (string, error) { data, readErr := io.SafeReadUserFile(mirrorPath) if readErr != nil { - return "", ctxerr.ReadMirrorArchive(readErr) + return "", errMemory.ReadMirrorArchive(readErr) } if mkErr := os.MkdirAll(archiveDir, fs.PermExec); mkErr != nil { - return "", ctxerr.CreateArchiveDir(mkErr) + return "", errMemory.CreateArchiveDir(mkErr) } - ts := time.Now().Format(time2.TimestampCompact) + ts := time.Now().Format(cfgTime.TimestampCompact) archivePath := filepath.Join(archiveDir, memory.PrefixMirror+ts+file.ExtMarkdown) if writeErr := os.WriteFile(archivePath, data, fs.PermFile); writeErr != nil { - return "", ctxerr.WriteArchive(writeErr) + return "", errMemory.WriteArchive(writeErr) } return archivePath, nil @@ -96,12 +96,12 @@ func Diff(contextDir, sourcePath string) (string, error) { mirrorData, mirrorErr := io.SafeReadUserFile(mirrorPath) if mirrorErr != nil { - return "", ctxerr.ReadMirror(mirrorErr) + return "", errMemory.ReadMirror(mirrorErr) } sourceData, sourceErr := io.SafeReadUserFile(sourcePath) if sourceErr != nil { - return "", ctxerr.ReadDiffSource(sourceErr) + return "", errMemory.ReadDiffSource(sourceErr) } if bytes.Equal(mirrorData, sourceData) { diff --git a/internal/memory/promote.go b/internal/memory/promote.go index dc1a6b1b5..58addf5b8 100644 --- a/internal/memory/promote.go +++ b/internal/memory/promote.go @@ -10,7 +10,7 @@ import ( "github.com/ActiveMemory/ctx/internal/assets/read/desc" "github.com/ActiveMemory/ctx/internal/config/embed/text" "github.com/ActiveMemory/ctx/internal/config/entry" - ctxentry "github.com/ActiveMemory/ctx/internal/entry" + ctxEntry "github.com/ActiveMemory/ctx/internal/entry" ) // Promote writes a classified entry to the appropriate .context/ file. @@ -28,7 +28,7 @@ func Promote(e Entry, classification Classification) error { // (first line, trimmed of Markdown markers) title := extractTitle(e.Text) - params := ctxentry.Params{ + params := ctxEntry.Params{ Type: classification.Target, Content: title, } @@ -51,5 +51,5 @@ func Promote(e Entry, classification Classification) error { // Conventions just need content: FormatConvention handles the rest } - return ctxentry.Write(params) + return ctxEntry.Write(params) } diff --git a/internal/memory/publish.go b/internal/memory/publish.go index b25e10901..a75449b78 100644 --- a/internal/memory/publish.go +++ b/internal/memory/publish.go @@ -17,7 +17,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/marker" "github.com/ActiveMemory/ctx/internal/config/memory" "github.com/ActiveMemory/ctx/internal/config/token" - ctxerr "github.com/ActiveMemory/ctx/internal/err/memory" + errMemory "github.com/ActiveMemory/ctx/internal/err/memory" "github.com/ActiveMemory/ctx/internal/io" ) @@ -157,7 +157,7 @@ func RemovePublished(content string) (string, bool) { func Publish(contextDir, memoryPath string, budget int) (PublishResult, error) { result, selectErr := SelectContent(contextDir, budget) if selectErr != nil { - return PublishResult{}, ctxerr.SelectContent(selectErr) + return PublishResult{}, errMemory.SelectContent(selectErr) } formatted := result.Format() @@ -173,7 +173,7 @@ func Publish(contextDir, memoryPath string, budget int) (PublishResult, error) { if writeErr := os.WriteFile( memoryPath, []byte(merged), fs.PermFile, ); writeErr != nil { - return PublishResult{}, ctxerr.WriteMemory(writeErr) + return PublishResult{}, errMemory.WriteMemory(writeErr) } return result, nil diff --git a/internal/memory/publish_test.go b/internal/memory/publish_test.go index 8f5cda105..d0071ff25 100644 --- a/internal/memory/publish_test.go +++ b/internal/memory/publish_test.go @@ -17,8 +17,8 @@ import ( "github.com/ActiveMemory/ctx/internal/config/ctx" "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/marker" - cfgmem "github.com/ActiveMemory/ctx/internal/config/memory" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgMem "github.com/ActiveMemory/ctx/internal/config/memory" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -151,7 +151,7 @@ func TestSelectContent(t *testing.T) { } // Create DECISIONS.md with a recent entry - ts := time.Now().Format(time2.TimestampCompact) + ts := time.Now().Format(cfgTime.TimestampCompact) decisions := fmt.Sprintf("# Decisions\n\n## [%s] Use SQLite\n\nContext: testing\n", ts) if writeErr := os.WriteFile(filepath.Join(contextDir, ctx.Decision), []byte(decisions), 0o644); writeErr != nil { t.Fatal(writeErr) @@ -168,7 +168,7 @@ func TestSelectContent(t *testing.T) { t.Fatal(writeErr) } - result, selectErr := SelectContent(contextDir, cfgmem.DefaultPublishBudget) + result, selectErr := SelectContent(contextDir, cfgMem.DefaultPublishBudget) if selectErr != nil { t.Fatalf("SelectContent: %v", selectErr) } diff --git a/internal/memory/state.go b/internal/memory/state.go index 44acaed0d..fcd7a0cf8 100644 --- a/internal/memory/state.go +++ b/internal/memory/state.go @@ -20,7 +20,7 @@ import ( cfgFmt "github.com/ActiveMemory/ctx/internal/config/format" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/config/memory" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/io" ) @@ -90,7 +90,7 @@ func (s *State) Imported(hash string) bool { // MarkImported records an entry hash with its target and date. func (s *State) MarkImported(hash, target string) { - date := time.Now().Format(time2.DateFormat) + date := time.Now().Format(cfgTime.DateFormat) entry := strings.Join([]string{hash, target, date}, token.Colon) s.ImportedHashes = append(s.ImportedHashes, entry) } diff --git a/internal/notify/notify.go b/internal/notify/notify.go index 69b43094a..faf1b950c 100644 --- a/internal/notify/notify.go +++ b/internal/notify/notify.go @@ -18,7 +18,7 @@ import ( "path/filepath" "time" - cryptoCfg "github.com/ActiveMemory/ctx/internal/config/crypto" + cfgCrypto "github.com/ActiveMemory/ctx/internal/config/crypto" "github.com/ActiveMemory/ctx/internal/config/fs" "github.com/ActiveMemory/ctx/internal/crypto" "github.com/ActiveMemory/ctx/internal/io" @@ -35,7 +35,7 @@ import ( // - error: non-nil only if decryption fails (missing files are silent) func LoadWebhook() (string, error) { kp := rc.KeyPath() - encPath := filepath.Join(rc.ContextDir(), cryptoCfg.NotifyEnc) + encPath := filepath.Join(rc.ContextDir(), cfgCrypto.NotifyEnc) key, err := crypto.LoadKey(kp) if err != nil { @@ -72,7 +72,7 @@ func LoadWebhook() (string, error) { // - error: non-nil if key generation, encryption, or file write fails func SaveWebhook(url string) error { kp := rc.KeyPath() - encPath := filepath.Join(rc.ContextDir(), cryptoCfg.NotifyEnc) + encPath := filepath.Join(rc.ContextDir(), cfgCrypto.NotifyEnc) key, err := crypto.LoadKey(kp) if err != nil { diff --git a/internal/parse/date.go b/internal/parse/date.go index b12ff67ec..b90a3733b 100644 --- a/internal/parse/date.go +++ b/internal/parse/date.go @@ -9,7 +9,7 @@ package parse import ( "time" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" ) // Date parses a YYYY-MM-DD string into a time.Time at midnight UTC. @@ -25,5 +25,5 @@ func Date(s string) (time.Time, error) { if s == "" { return time.Time{}, nil } - return time.Parse(time2.DateFormat, s) + return time.Parse(cfgTime.DateFormat, s) } diff --git a/internal/recall/parser/claude.go b/internal/recall/parser/claude.go index 2d8475516..8aa06ee5b 100644 --- a/internal/recall/parser/claude.go +++ b/internal/recall/parser/claude.go @@ -19,7 +19,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/parser" "github.com/ActiveMemory/ctx/internal/config/session" "github.com/ActiveMemory/ctx/internal/entity" - ctxerr "github.com/ActiveMemory/ctx/internal/err/parser" + errParser "github.com/ActiveMemory/ctx/internal/err/parser" ) // ClaudeCodeParser parses Claude Code JSONL session files. @@ -108,7 +108,7 @@ func (p *ClaudeCodeParser) Matches(path string) bool { func (p *ClaudeCodeParser) ParseFile(path string) ([]*entity.Session, error) { f, openErr := os.Open(filepath.Clean(path)) if openErr != nil { - return nil, ctxerr.OpenFile(openErr) + return nil, errParser.OpenFile(openErr) } defer func() { _ = f.Close() }() @@ -147,7 +147,7 @@ func (p *ClaudeCodeParser) ParseFile(path string) ([]*entity.Session, error) { } if scanErr := scanner.Err(); scanErr != nil { - return nil, ctxerr.ScanFile(scanErr) + return nil, errParser.ScanFile(scanErr) } // Convert to sessions @@ -187,7 +187,7 @@ func (p *ClaudeCodeParser) ParseLine(line []byte) (*entity.Message, string, erro var raw claudeRawMessage if unmarshalErr := json.Unmarshal(line, &raw); unmarshalErr != nil { - return nil, "", ctxerr.Unmarshal(unmarshalErr) + return nil, "", errParser.Unmarshal(unmarshalErr) } // Skip non-message lines diff --git a/internal/recall/parser/markdown.go b/internal/recall/parser/markdown.go index fbb55806c..68a5d3e86 100644 --- a/internal/recall/parser/markdown.go +++ b/internal/recall/parser/markdown.go @@ -16,7 +16,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/parser" "github.com/ActiveMemory/ctx/internal/config/session" "github.com/ActiveMemory/ctx/internal/entity" - ctxerr "github.com/ActiveMemory/ctx/internal/err/parser" + errParser "github.com/ActiveMemory/ctx/internal/err/parser" ) // MarkdownSessionParser parses Markdown session files written by AI agents. @@ -110,7 +110,7 @@ func (p *MarkdownSessionParser) Matches(path string) bool { func (p *MarkdownSessionParser) ParseFile(path string) ([]*entity.Session, error) { content, err := os.ReadFile(filepath.Clean(path)) if err != nil { - return nil, ctxerr.ReadFile(err) + return nil, errParser.ReadFile(err) } s := p.parseMarkdownSession(string(content), path) diff --git a/internal/recall/parser/parser.go b/internal/recall/parser/parser.go index 2c1015e1a..e9db58672 100644 --- a/internal/recall/parser/parser.go +++ b/internal/recall/parser/parser.go @@ -14,7 +14,7 @@ import ( "github.com/ActiveMemory/ctx/internal/config/parser" "github.com/ActiveMemory/ctx/internal/entity" - ctxerr "github.com/ActiveMemory/ctx/internal/err/parser" + errParser "github.com/ActiveMemory/ctx/internal/err/parser" ) // registeredParsers holds all available session parsers. @@ -40,7 +40,7 @@ func ParseFile(path string) ([]*entity.Session, error) { return parser.ParseFile(path) } } - return nil, ctxerr.NoMatch(path) + return nil, errParser.NoMatch(path) } // ScanDirectory recursively scans a directory for session files. @@ -103,7 +103,7 @@ func ScanDirectoryWithErrors(dir string) ([]*entity.Session, []error, error) { if parser.Matches(path) { sessions, err := parser.ParseFile(path) if err != nil { - parseErrors = append(parseErrors, ctxerr.FileError(path, err)) + parseErrors = append(parseErrors, errParser.FileError(path, err)) break } allSessions = append(allSessions, sessions...) @@ -115,7 +115,7 @@ func ScanDirectoryWithErrors(dir string) ([]*entity.Session, []error, error) { }) if err != nil { - return nil, nil, ctxerr.WalkDir(err) + return nil, nil, errParser.WalkDir(err) } // Sort by start time (newest first) diff --git a/internal/tidy/archive.go b/internal/tidy/archive.go index 6fd64cd55..3f2421897 100644 --- a/internal/tidy/archive.go +++ b/internal/tidy/archive.go @@ -15,9 +15,9 @@ import ( "github.com/ActiveMemory/ctx/internal/config/archive" "github.com/ActiveMemory/ctx/internal/config/dir" "github.com/ActiveMemory/ctx/internal/config/fs" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" - ctxerr "github.com/ActiveMemory/ctx/internal/err/backup" + errBackup "github.com/ActiveMemory/ctx/internal/err/backup" "github.com/ActiveMemory/ctx/internal/rc" ) @@ -35,11 +35,11 @@ import ( func WriteArchive(prefix, heading, content string) (string, error) { archiveDir := filepath.Join(rc.ContextDir(), dir.Archive) if mkErr := os.MkdirAll(archiveDir, fs.PermExec); mkErr != nil { - return "", ctxerr.CreateArchiveDir(mkErr) + return "", errBackup.CreateArchiveDir(mkErr) } now := time.Now() - dateStr := now.Format(time2.DateFormat) + dateStr := now.Format(cfgTime.DateFormat) archiveFile := filepath.Join( archiveDir, fmt.Sprintf(archive.TplArchiveFilename, prefix, dateStr), @@ -55,7 +55,7 @@ func WriteArchive(prefix, heading, content string) (string, error) { } if writeErr := os.WriteFile(archiveFile, []byte(finalContent), fs.PermFile); writeErr != nil { - return "", ctxerr.WriteArchive(writeErr) + return "", errBackup.WriteArchive(writeErr) } return archiveFile, nil diff --git a/internal/tidy/parse.go b/internal/tidy/parse.go index e0f8cc48e..82346a265 100644 --- a/internal/tidy/parse.go +++ b/internal/tidy/parse.go @@ -11,7 +11,7 @@ import ( "time" "github.com/ActiveMemory/ctx/internal/config/regex" - time2 "github.com/ActiveMemory/ctx/internal/config/time" + cfgTime "github.com/ActiveMemory/ctx/internal/config/time" "github.com/ActiveMemory/ctx/internal/config/token" "github.com/ActiveMemory/ctx/internal/entity" "github.com/ActiveMemory/ctx/internal/task" @@ -111,7 +111,7 @@ func parseDoneTimestamp(line string) *time.Time { } // Parse YYYY-MM-DD-HHMMSS format - t, err := time.Parse(time2.TimestampCompact, match[1]) + t, err := time.Parse(cfgTime.TimestampCompact, match[1]) if err != nil { return nil } diff --git a/internal/validation/path.go b/internal/validation/path.go index bb9f12e9c..a507b0476 100644 --- a/internal/validation/path.go +++ b/internal/validation/path.go @@ -11,8 +11,8 @@ import ( "path/filepath" "strings" - errctx "github.com/ActiveMemory/ctx/internal/err/context" - fserr "github.com/ActiveMemory/ctx/internal/err/fs" + errCtx "github.com/ActiveMemory/ctx/internal/err/context" + errFs "github.com/ActiveMemory/ctx/internal/err/fs" ) // ValidateBoundary checks that dir resolves to a path within the current @@ -21,19 +21,19 @@ import ( func ValidateBoundary(dir string) error { cwd, err := os.Getwd() if err != nil { - return fserr.BoundaryViolation(err) + return errFs.BoundaryViolation(err) } absDir, err := filepath.Abs(dir) if err != nil { - return fserr.BoundaryViolation(err) + return errFs.BoundaryViolation(err) } // Resolve symlinks in both paths so traversal via symlinked parents // is caught. resolvedCwd, err := filepath.EvalSymlinks(cwd) if err != nil { - return fserr.BoundaryViolation(err) + return errFs.BoundaryViolation(err) } resolvedDir, err := filepath.EvalSymlinks(absDir) @@ -47,7 +47,7 @@ func ValidateBoundary(dir string) error { // Append os.PathSeparator to avoid "/foo/bar" matching "/foo/b". root := resolvedCwd + string(os.PathSeparator) if resolvedDir != resolvedCwd && !strings.HasPrefix(resolvedDir, root) { - return errctx.OutsideRoot(dir, resolvedCwd) + return errCtx.OutsideRoot(dir, resolvedCwd) } return nil @@ -63,7 +63,7 @@ func CheckSymlinks(dir string) error { return nil } if info.Mode()&os.ModeSymlink != 0 { - return errctx.DirSymlink(dir) + return errCtx.DirSymlink(dir) } // Check immediate children. @@ -79,7 +79,7 @@ func CheckSymlinks(dir string) error { continue } if ci.Mode()&os.ModeSymlink != 0 { - return errctx.FileSymlink(child) + return errCtx.FileSymlink(child) } } diff --git a/site/404.html b/site/404.html index 8fa94ad68..585d61db2 100644 --- a/site/404.html +++ b/site/404.html @@ -3084,6 +3084,8 @@ + + @@ -3239,6 +3241,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-01-27-building-ctx-using-ctx/index.html b/site/blog/2026-01-27-building-ctx-using-ctx/index.html index 444c3ab3f..044d6015b 100644 --- a/site/blog/2026-01-27-building-ctx-using-ctx/index.html +++ b/site/blog/2026-01-27-building-ctx-using-ctx/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/index.html b/site/blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/index.html index c7af0af92..831153e98 100644 --- a/site/blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/index.html +++ b/site/blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-01-refactoring-with-intent/index.html b/site/blog/2026-02-01-refactoring-with-intent/index.html index 0958ad429..01588ec56 100644 --- a/site/blog/2026-02-01-refactoring-with-intent/index.html +++ b/site/blog/2026-02-01-refactoring-with-intent/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-03-the-attention-budget/index.html b/site/blog/2026-02-03-the-attention-budget/index.html index a4db41a5e..65c9d243b 100644 --- a/site/blog/2026-02-03-the-attention-budget/index.html +++ b/site/blog/2026-02-03-the-attention-budget/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-04-skills-that-fight-the-platform/index.html b/site/blog/2026-02-04-skills-that-fight-the-platform/index.html index 40c8325c9..1d0b1ead1 100644 --- a/site/blog/2026-02-04-skills-that-fight-the-platform/index.html +++ b/site/blog/2026-02-04-skills-that-fight-the-platform/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-05-you-cant-import-expertise/index.html b/site/blog/2026-02-05-you-cant-import-expertise/index.html index 3b6c5584e..2f3673fda 100644 --- a/site/blog/2026-02-05-you-cant-import-expertise/index.html +++ b/site/blog/2026-02-05-you-cant-import-expertise/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-07-the-anatomy-of-a-skill-that-works/index.html b/site/blog/2026-02-07-the-anatomy-of-a-skill-that-works/index.html index e0a28e451..ed389faf2 100644 --- a/site/blog/2026-02-07-the-anatomy-of-a-skill-that-works/index.html +++ b/site/blog/2026-02-07-the-anatomy-of-a-skill-that-works/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-08-not-everything-is-a-skill/index.html b/site/blog/2026-02-08-not-everything-is-a-skill/index.html index e9150d940..79fc36818 100644 --- a/site/blog/2026-02-08-not-everything-is-a-skill/index.html +++ b/site/blog/2026-02-08-not-everything-is-a-skill/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-09-defense-in-depth-securing-ai-agents/index.html b/site/blog/2026-02-09-defense-in-depth-securing-ai-agents/index.html index 207dc93e1..22af96cd8 100644 --- a/site/blog/2026-02-09-defense-in-depth-securing-ai-agents/index.html +++ b/site/blog/2026-02-09-defense-in-depth-securing-ai-agents/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-12-how-deep-is-too-deep/index.html b/site/blog/2026-02-12-how-deep-is-too-deep/index.html index 311b8099e..3cdb2e365 100644 --- a/site/blog/2026-02-12-how-deep-is-too-deep/index.html +++ b/site/blog/2026-02-12-how-deep-is-too-deep/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-14-irc-as-context/index.html b/site/blog/2026-02-14-irc-as-context/index.html index b2d5387e8..bbc1e2c63 100644 --- a/site/blog/2026-02-14-irc-as-context/index.html +++ b/site/blog/2026-02-14-irc-as-context/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-14-parallel-agents-with-worktrees/index.html b/site/blog/2026-02-14-parallel-agents-with-worktrees/index.html index d6b015eb5..c0d87a49d 100644 --- a/site/blog/2026-02-14-parallel-agents-with-worktrees/index.html +++ b/site/blog/2026-02-14-parallel-agents-with-worktrees/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-15-ctx-v0.3.0-the-discipline-release/index.html b/site/blog/2026-02-15-ctx-v0.3.0-the-discipline-release/index.html index 342db2c17..715c1c4d5 100644 --- a/site/blog/2026-02-15-ctx-v0.3.0-the-discipline-release/index.html +++ b/site/blog/2026-02-15-ctx-v0.3.0-the-discipline-release/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-15-eight-ways-a-hook-can-talk/index.html b/site/blog/2026-02-15-eight-ways-a-hook-can-talk/index.html index 082d2985a..76959dcf1 100644 --- a/site/blog/2026-02-15-eight-ways-a-hook-can-talk/index.html +++ b/site/blog/2026-02-15-eight-ways-a-hook-can-talk/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-15-why-zensical/index.html b/site/blog/2026-02-15-why-zensical/index.html index 6bd8aab0c..4fd51636f 100644 --- a/site/blog/2026-02-15-why-zensical/index.html +++ b/site/blog/2026-02-15-why-zensical/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-16-ctx-v0.6.0-the-integration-release/index.html b/site/blog/2026-02-16-ctx-v0.6.0-the-integration-release/index.html index e483c7dd9..4e477df63 100644 --- a/site/blog/2026-02-16-ctx-v0.6.0-the-integration-release/index.html +++ b/site/blog/2026-02-16-ctx-v0.6.0-the-integration-release/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-17-code-is-cheap-judgment-is-not/index.html b/site/blog/2026-02-17-code-is-cheap-judgment-is-not/index.html index 008ed859c..42fdbb2f5 100644 --- a/site/blog/2026-02-17-code-is-cheap-judgment-is-not/index.html +++ b/site/blog/2026-02-17-code-is-cheap-judgment-is-not/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-17-context-as-infrastructure/index.html b/site/blog/2026-02-17-context-as-infrastructure/index.html index 84f8aa358..f134d4693 100644 --- a/site/blog/2026-02-17-context-as-infrastructure/index.html +++ b/site/blog/2026-02-17-context-as-infrastructure/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/index.html b/site/blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/index.html index 387742805..b690a6008 100644 --- a/site/blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/index.html +++ b/site/blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-17-the-3-1-ratio/index.html b/site/blog/2026-02-17-the-3-1-ratio/index.html index e7fa36892..2e786d4ca 100644 --- a/site/blog/2026-02-17-the-3-1-ratio/index.html +++ b/site/blog/2026-02-17-the-3-1-ratio/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-17-when-a-system-starts-explaining-itself/index.html b/site/blog/2026-02-17-when-a-system-starts-explaining-itself/index.html index a5e05476f..680d96b7a 100644 --- a/site/blog/2026-02-17-when-a-system-starts-explaining-itself/index.html +++ b/site/blog/2026-02-17-when-a-system-starts-explaining-itself/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-25-the-homework-problem/index.html b/site/blog/2026-02-25-the-homework-problem/index.html index aea96d921..0dc93778d 100644 --- a/site/blog/2026-02-25-the-homework-problem/index.html +++ b/site/blog/2026-02-25-the-homework-problem/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-02-28-the-last-question/index.html b/site/blog/2026-02-28-the-last-question/index.html index 341831016..95e927378 100644 --- a/site/blog/2026-02-28-the-last-question/index.html +++ b/site/blog/2026-02-28-the-last-question/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/2026-03-04-agent-memory-is-infrastructure/index.html b/site/blog/2026-03-04-agent-memory-is-infrastructure/index.html index 3ed01c9ef..99923a24e 100644 --- a/site/blog/2026-03-04-agent-memory-is-infrastructure/index.html +++ b/site/blog/2026-03-04-agent-memory-is-infrastructure/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/blog/index.html b/site/blog/index.html index c66e2cd36..794c033f6 100644 --- a/site/blog/index.html +++ b/site/blog/index.html @@ -3102,6 +3102,8 @@ + + @@ -3257,6 +3259,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/config/index.html b/site/cli/config/index.html index 97fda08fa..fa3af6416 100644 --- a/site/cli/config/index.html +++ b/site/cli/config/index.html @@ -3187,6 +3187,8 @@ + + @@ -3342,6 +3344,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/context/index.html b/site/cli/context/index.html index 03d303e9f..ab3d85702 100644 --- a/site/cli/context/index.html +++ b/site/cli/context/index.html @@ -3348,6 +3348,8 @@ + + @@ -3503,6 +3505,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/doctor/index.html b/site/cli/doctor/index.html index c4bc72f3b..6a9ddd28e 100644 --- a/site/cli/doctor/index.html +++ b/site/cli/doctor/index.html @@ -3231,6 +3231,8 @@ + + @@ -3386,6 +3388,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/index.html b/site/cli/index.html index 03c036e52..d98063422 100644 --- a/site/cli/index.html +++ b/site/cli/index.html @@ -3102,6 +3102,8 @@ + + @@ -3257,6 +3259,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/init-status/index.html b/site/cli/init-status/index.html index 3d04f8369..aabb2e692 100644 --- a/site/cli/init-status/index.html +++ b/site/cli/init-status/index.html @@ -3192,6 +3192,8 @@ + + @@ -3347,6 +3349,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/mcp/index.html b/site/cli/mcp/index.html index 5b202b6e9..193218e55 100644 --- a/site/cli/mcp/index.html +++ b/site/cli/mcp/index.html @@ -3464,6 +3464,8 @@ + + @@ -3619,6 +3621,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/recall/index.html b/site/cli/recall/index.html index 1b034edd3..4729c45de 100644 --- a/site/cli/recall/index.html +++ b/site/cli/recall/index.html @@ -3281,6 +3281,8 @@ + + @@ -3436,6 +3438,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/system/index.html b/site/cli/system/index.html index e60fc959d..8f5cdd40b 100644 --- a/site/cli/system/index.html +++ b/site/cli/system/index.html @@ -3264,6 +3264,8 @@ + + @@ -3419,6 +3421,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/cli/tools/index.html b/site/cli/tools/index.html index 3ff4195b1..93ca89a50 100644 --- a/site/cli/tools/index.html +++ b/site/cli/tools/index.html @@ -3663,6 +3663,8 @@ + + @@ -3818,6 +3820,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • @@ -5538,7 +5570,7 @@

    ctx prompt rmPrompt Templates

    +

    See also: Prompt Templates

    ctx remind

    Session-scoped reminders that surface at session start. Reminders are diff --git a/site/home/about/index.html b/site/home/about/index.html index 0f4186fa4..3d26d7dca 100644 --- a/site/home/about/index.html +++ b/site/home/about/index.html @@ -3198,6 +3198,8 @@ + + @@ -3353,6 +3355,36 @@ +

  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • @@ -3796,7 +3828,7 @@

    How ctx Solves ThisJoin the Community →: ask questions, share workflows, and help shape what comes next

    • -
  • Read the Blog →: real-world patterns, ponderings, and lessons learned from building ctx using ctx
    • +
  • Read the Blog →: real-world patterns, ponderings, and lessons learned from building ctx using ctx

    • Ready to Get Started?

    diff --git a/site/home/common-workflows/index.html b/site/home/common-workflows/index.html index 2a2ce1f09..03157f591 100644 --- a/site/home/common-workflows/index.html +++ b/site/home/common-workflows/index.html @@ -3336,6 +3336,8 @@ + + @@ -3491,6 +3493,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/community/index.html b/site/home/community/index.html index e53149158..09f4c148d 100644 --- a/site/home/community/index.html +++ b/site/home/community/index.html @@ -3192,6 +3192,8 @@ + + @@ -3347,6 +3349,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/configuration/index.html b/site/home/configuration/index.html index 3ba5ffb03..5efd694b4 100644 --- a/site/home/configuration/index.html +++ b/site/home/configuration/index.html @@ -3392,6 +3392,8 @@ + + @@ -3547,6 +3549,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/context-files/index.html b/site/home/context-files/index.html index ba0a3aa0c..2016fe092 100644 --- a/site/home/context-files/index.html +++ b/site/home/context-files/index.html @@ -3587,6 +3587,8 @@ + + @@ -3742,6 +3744,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/contributing/index.html b/site/home/contributing/index.html index 1c003abcb..d0ba4ba14 100644 --- a/site/home/contributing/index.html +++ b/site/home/contributing/index.html @@ -3520,6 +3520,8 @@ + + @@ -3675,6 +3677,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • @@ -4410,7 +4442,7 @@

    Skills: Two Directories, One Rule internal/assets/claude/skills/ -The 29 ctx-* skills that ship with the plugin +The 39 ctx-* skills that ship with the plugin Yes @@ -4486,7 +4518,7 @@

    Adding a New CLI CommandAdd a section to the appropriate CLI doc page in docs/cli/.

    • Pattern to follow: internal/cli/pad/pad.go (parent with subcommands) or -internal/cli/complete/complete.go (single command).

    +internal/cli/drift/drift.go (single command).

    Adding a New Session Parser

    The recall system uses a SessionParser interface. To add support for a new AI tool (e.g. Aider, Cursor):

    diff --git a/site/home/faq/index.html b/site/home/faq/index.html index 81ee2b96a..97108e826 100644 --- a/site/home/faq/index.html +++ b/site/home/faq/index.html @@ -3247,6 +3247,8 @@ + + @@ -3402,6 +3404,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/first-session/index.html b/site/home/first-session/index.html index 6870e67b3..3903d495a 100644 --- a/site/home/first-session/index.html +++ b/site/home/first-session/index.html @@ -3225,6 +3225,8 @@ + + @@ -3380,6 +3382,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/getting-started/index.html b/site/home/getting-started/index.html index cacb12a0c..970df37d4 100644 --- a/site/home/getting-started/index.html +++ b/site/home/getting-started/index.html @@ -3276,6 +3276,8 @@ + + @@ -3431,6 +3433,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/index.html b/site/home/index.html index 81f66ad7d..a41ba91da 100644 --- a/site/home/index.html +++ b/site/home/index.html @@ -3102,6 +3102,8 @@ + + @@ -3257,6 +3259,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/is-ctx-right/index.html b/site/home/is-ctx-right/index.html index 18a4f48eb..359417fd2 100644 --- a/site/home/is-ctx-right/index.html +++ b/site/home/is-ctx-right/index.html @@ -3231,6 +3231,8 @@ + + @@ -3386,6 +3388,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/joining-a-project/index.html b/site/home/joining-a-project/index.html index 042a69c41..9aa091ef9 100644 --- a/site/home/joining-a-project/index.html +++ b/site/home/joining-a-project/index.html @@ -3214,6 +3214,8 @@ + + @@ -3369,6 +3371,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/keeping-ai-honest/index.html b/site/home/keeping-ai-honest/index.html index 5f50d54da..ac4923cf7 100644 --- a/site/home/keeping-ai-honest/index.html +++ b/site/home/keeping-ai-honest/index.html @@ -3236,6 +3236,8 @@ + + @@ -3391,6 +3393,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/prompting-guide/index.html b/site/home/prompting-guide/index.html index 27e30f75a..f49f9697f 100644 --- a/site/home/prompting-guide/index.html +++ b/site/home/prompting-guide/index.html @@ -3730,6 +3730,8 @@ + + @@ -3885,6 +3887,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/home/repeated-mistakes/index.html b/site/home/repeated-mistakes/index.html index dd39d0783..d1bfc6524 100644 --- a/site/home/repeated-mistakes/index.html +++ b/site/home/repeated-mistakes/index.html @@ -3242,6 +3242,8 @@ + + @@ -3397,6 +3399,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/index.html b/site/index.html index 624ef1152..607ea3785 100644 --- a/site/index.html +++ b/site/index.html @@ -3310,6 +3310,8 @@ + + @@ -3465,6 +3467,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/operations/autonomous-loop/index.html b/site/operations/autonomous-loop/index.html index 4c569a528..dcf3ca171 100644 --- a/site/operations/autonomous-loop/index.html +++ b/site/operations/autonomous-loop/index.html @@ -15,7 +15,7 @@ - + @@ -3099,6 +3099,8 @@ + + @@ -3255,6 +3257,36 @@ + + +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + @@ -4496,7 +4528,7 @@

    Resources - +
    @@ -4506,7 +4538,7 @@

    Resources - AI Tools + Cutting a Release

    diff --git a/site/operations/index.html b/site/operations/index.html index a05b25392..6adeaafb4 100644 --- a/site/operations/index.html +++ b/site/operations/index.html @@ -3099,6 +3099,8 @@ + + @@ -3257,6 +3259,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • @@ -3484,6 +3516,17 @@ +
    • + +
  • + + + + Cutting a Release + + + +
  • @@ -3581,6 +3624,10 @@

    AI ToolsConfigure ctx with Claude Code, Cursor, Aider, Copilot, Windsurf, and other AI coding tools.

    +

    Cutting a Release

    +

    Step-by-step runbook for maintainers: bump version, generate +release notes, run the release script, and verify the result.

    +

    Autonomous Loops

    Run an unattended AI agent that works through tasks overnight, with ctx providing persistent memory between iterations.

    diff --git a/site/operations/integrations/index.html b/site/operations/integrations/index.html index ac4c7a093..3f90cc248 100644 --- a/site/operations/integrations/index.html +++ b/site/operations/integrations/index.html @@ -18,7 +18,7 @@ - + @@ -3099,6 +3099,8 @@ + + @@ -3940,6 +3942,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • @@ -5781,13 +5813,13 @@

    Further Reading +
    Next
    - Autonomous Loops + Cutting a Release
    diff --git a/site/operations/migration/index.html b/site/operations/migration/index.html index b191f4a25..271ac64f5 100644 --- a/site/operations/migration/index.html +++ b/site/operations/migration/index.html @@ -3099,6 +3099,8 @@ + + @@ -3569,6 +3571,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/operations/release/index.html b/site/operations/release/index.html new file mode 100644 index 000000000..b34cdd226 --- /dev/null +++ b/site/operations/release/index.html @@ -0,0 +1,4330 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + Cutting a Release - ctx: do you remember? + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    + +
    + + + + + + +
    + + + + + + + +
    + +
    + + + + +
    +
    + + + +
    +
    +
    + + + + + + + +
    +
    +
    + + + +
    +
    +
    + + + + +
    +
    +
    + + + +
    + + + + + + + + + + + +
    + + + + + + +

    Cutting a Release

    + +

    ctx

    +

    Prerequisites

    +

    Before you can cut a release you need:

    +
      +
    • Push access to origin (GitHub)
      • +
    • GPG signing configured (make gpg-test)
      • +
    • Go installed (version in go.mod)
      • +
    • Zensical installed (make site-setup)
      • +
    • A clean working tree (git status shows nothing to commit)
      • +
    +
    +

    Step-by-Step

    +

    1. Update the VERSION File

    +
    echo "0.9.0" > VERSION
+git add VERSION
+git commit -m "chore: bump version to 0.9.0"
+
    +

    The VERSION file uses bare semver (0.9.0), no v prefix. +The release script adds the v prefix for git tags.

    +

    2. Generate Release Notes

    +

    In Claude Code:

    +
    /_ctx-release-notes
+
    +

    This analyzes commits since the last tag and writes +dist/RELEASE_NOTES.md. The release script refuses to +proceed without this file.

    +

    3. Commit Any Remaining Changes

    +
    git status          # must be clean
+make audit          # full check: fmt, vet, lint, test
+
    +

    4. Run the Release

    +
    make release
+
    +

    Or, if you are in a Claude Code session:

    +
    /_ctx-release
+
    +

    The release script does everything in order:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    StepWhat happens
    1Reads VERSION, verifies release notes exist
    2Verifies working tree is clean
    3Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock)
    4Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md)
    5Adds new row to versions.md
    6Rebuilds the documentation site (make site)
    7Commits all version and docs updates
    8Runs make test and make smoke
    9Builds binaries for all 6 platforms via hack/build-all.sh
    10Creates a signed git tag (v0.9.0)
    11Pushes the tag to origin
    12Updates and pushes the latest tag
    +

    5. GitHub CI Takes Over

    +

    Pushing a v* tag triggers .github/workflows/release.yml:

    +
      +
    1. Checks out the tagged commit
      2. +
    2. Runs the full test suite
      3. +
    3. Builds binaries for all platforms
      4. +
    4. Creates a GitHub Release with auto-generated notes
      5. +
    5. Uploads binaries and SHA256 checksums
      6. +
    +

    6. Verify

    +
      +
    • GitHub Releases shows the new version
      • +
    • All 6 binaries are attached (linux/darwin x amd64/arm64, windows x amd64)
      • +
    • SHA256 files are attached
      • +
    • Release notes look correct
      • +
    +
    +

    What Gets Updated Automatically

    +

    The release script updates 8 files so you do not have to:

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FileWhat changes
    internal/assets/claude/.claude-plugin/plugin.jsonPlugin version
    .claude-plugin/marketplace.jsonMarketplace version (2 fields)
    editors/vscode/package.jsonVS Code extension version
    editors/vscode/package-lock.jsonVS Code lock version (2 fields)
    docs/index.mdDownload URLs
    docs/home/getting-started.mdDownload URLs
    docs/operations/integrations.mdVSIX filename version
    docs/reference/versions.mdNew version row + latest pointer
    +

    The Go binary version is injected at build time via -ldflags +from the VERSION file. No source file needs editing.

    +
    +

    Build Targets Reference

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    TargetWhat it does
    make releaseFull release (script + tag + push)
    make buildBuild binary for current platform
    make build-allBuild all 6 platform binaries
    make testUnit tests
    make smokeIntegration smoke tests
    make auditFull check (fmt + vet + lint + drift + docs + test)
    make siteRebuild documentation site
    +
    +

    Troubleshooting

    +

    "Release notes not found"

    +
    ERROR: dist/RELEASE_NOTES.md not found.
+
    +

    Run /_ctx-release-notes in Claude Code first, or write +dist/RELEASE_NOTES.md manually.

    +

    "Working tree is not clean"

    +
    ERROR: Working tree is not clean.
+
    +

    Commit or stash all changes before running make release.

    +

    "Tag already exists"

    +
    ERROR: Tag v0.9.0 already exists.
+
    +

    You cannot release the same version twice. Either bump VERSION +to a new version, or delete the old tag if the release was +incomplete:

    +
    git tag -d v0.9.0
+git push origin :refs/tags/v0.9.0
+
    +

    CI build fails after tag push

    +

    The tag is already published. Fix the issue, bump to a patch +version (e.g. 0.9.1), and release again. Do not force-push +tags that others may have already fetched.

    + + + + + + + + + + + + + + + + + + +
    +
    + + + + + +
    + + + +
    + + + +
    +
    +
    +
    + + + + + + + + + + + + + + \ No newline at end of file diff --git a/site/operations/upgrading/index.html b/site/operations/upgrading/index.html index beef6f6e2..f3f28d54a 100644 --- a/site/operations/upgrading/index.html +++ b/site/operations/upgrading/index.html @@ -3099,6 +3099,8 @@ + + @@ -3430,6 +3432,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/autonomous-loops/index.html b/site/recipes/autonomous-loops/index.html index 517a6c00e..4c38f8c7d 100644 --- a/site/recipes/autonomous-loops/index.html +++ b/site/recipes/autonomous-loops/index.html @@ -3463,6 +3463,8 @@ + + @@ -3618,6 +3620,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/building-skills/index.html b/site/recipes/building-skills/index.html index 41ee6a523..d2137b0dc 100644 --- a/site/recipes/building-skills/index.html +++ b/site/recipes/building-skills/index.html @@ -3319,6 +3319,8 @@ + + @@ -3474,6 +3476,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/claude-code-permissions/index.html b/site/recipes/claude-code-permissions/index.html index 534cc415f..86a317597 100644 --- a/site/recipes/claude-code-permissions/index.html +++ b/site/recipes/claude-code-permissions/index.html @@ -3347,6 +3347,8 @@ + + @@ -3502,6 +3504,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/context-health/index.html b/site/recipes/context-health/index.html index 4ffa9fda8..2524ad622 100644 --- a/site/recipes/context-health/index.html +++ b/site/recipes/context-health/index.html @@ -3413,6 +3413,8 @@ + + @@ -3568,6 +3570,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/customizing-hook-messages/index.html b/site/recipes/customizing-hook-messages/index.html index 481b1e6d8..ebafc2166 100644 --- a/site/recipes/customizing-hook-messages/index.html +++ b/site/recipes/customizing-hook-messages/index.html @@ -3358,6 +3358,8 @@ + + @@ -3513,6 +3515,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/dependency-graph/index.html b/site/recipes/dependency-graph/index.html index 0893c02a3..36d219e50 100644 --- a/site/recipes/dependency-graph/index.html +++ b/site/recipes/dependency-graph/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/design-before-coding/index.html b/site/recipes/design-before-coding/index.html index 35f5758e5..7f1379259 100644 --- a/site/recipes/design-before-coding/index.html +++ b/site/recipes/design-before-coding/index.html @@ -3308,6 +3308,8 @@ + + @@ -3463,6 +3465,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/external-context/index.html b/site/recipes/external-context/index.html index a132fd41c..c2c0a7758 100644 --- a/site/recipes/external-context/index.html +++ b/site/recipes/external-context/index.html @@ -3408,6 +3408,8 @@ + + @@ -3563,6 +3565,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/guide-your-agent/index.html b/site/recipes/guide-your-agent/index.html index 94041e6e3..a0eabc05e 100644 --- a/site/recipes/guide-your-agent/index.html +++ b/site/recipes/guide-your-agent/index.html @@ -3203,6 +3203,8 @@ + + @@ -3358,6 +3360,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/hook-output-patterns/index.html b/site/recipes/hook-output-patterns/index.html index a91b0f30c..f0ec68182 100644 --- a/site/recipes/hook-output-patterns/index.html +++ b/site/recipes/hook-output-patterns/index.html @@ -3424,6 +3424,8 @@ + + @@ -3579,6 +3581,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/hook-sequence-diagrams/index.html b/site/recipes/hook-sequence-diagrams/index.html index aa67d5f05..2fa2d9598 100644 --- a/site/recipes/hook-sequence-diagrams/index.html +++ b/site/recipes/hook-sequence-diagrams/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/import-plans/index.html b/site/recipes/import-plans/index.html index 2f3daeb59..09d93afec 100644 --- a/site/recipes/import-plans/index.html +++ b/site/recipes/import-plans/index.html @@ -3297,6 +3297,8 @@ + + @@ -3452,6 +3454,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/index.html b/site/recipes/index.html index 01eb350f6..4c17ab41f 100644 --- a/site/recipes/index.html +++ b/site/recipes/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/knowledge-capture/index.html b/site/recipes/knowledge-capture/index.html index f8754114c..d8ce7bcd2 100644 --- a/site/recipes/knowledge-capture/index.html +++ b/site/recipes/knowledge-capture/index.html @@ -3369,6 +3369,8 @@ + + @@ -3524,6 +3526,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/memory-bridge/index.html b/site/recipes/memory-bridge/index.html index b05dc8617..f2a70190a 100644 --- a/site/recipes/memory-bridge/index.html +++ b/site/recipes/memory-bridge/index.html @@ -3381,6 +3381,8 @@ + + @@ -3536,6 +3538,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/multi-tool-setup/index.html b/site/recipes/multi-tool-setup/index.html index 355664bf1..c0b437cc9 100644 --- a/site/recipes/multi-tool-setup/index.html +++ b/site/recipes/multi-tool-setup/index.html @@ -3369,6 +3369,8 @@ + + @@ -3524,6 +3526,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/multilingual-sessions/index.html b/site/recipes/multilingual-sessions/index.html index ae3bee9b8..afeb46a0b 100644 --- a/site/recipes/multilingual-sessions/index.html +++ b/site/recipes/multilingual-sessions/index.html @@ -3286,6 +3286,8 @@ + + @@ -3441,6 +3443,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/parallel-worktrees/index.html b/site/recipes/parallel-worktrees/index.html index f7df43c6f..63157813f 100644 --- a/site/recipes/parallel-worktrees/index.html +++ b/site/recipes/parallel-worktrees/index.html @@ -3352,6 +3352,8 @@ + + @@ -3507,6 +3509,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/permission-snapshots/index.html b/site/recipes/permission-snapshots/index.html index 347750abd..76109881c 100644 --- a/site/recipes/permission-snapshots/index.html +++ b/site/recipes/permission-snapshots/index.html @@ -3319,6 +3319,8 @@ + + @@ -3474,6 +3476,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/prompt-templates/index.html b/site/recipes/prompt-templates/index.html index 6f03f73ca..ffcf69928 100644 --- a/site/recipes/prompt-templates/index.html +++ b/site/recipes/prompt-templates/index.html @@ -3275,6 +3275,8 @@ + + @@ -3430,6 +3432,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/publishing/index.html b/site/recipes/publishing/index.html index f730a96c7..ed5231b7e 100644 --- a/site/recipes/publishing/index.html +++ b/site/recipes/publishing/index.html @@ -3352,6 +3352,8 @@ + + @@ -3507,6 +3509,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/scratchpad-sync/index.html b/site/recipes/scratchpad-sync/index.html index aa481d46c..ebe5705f8 100644 --- a/site/recipes/scratchpad-sync/index.html +++ b/site/recipes/scratchpad-sync/index.html @@ -3336,6 +3336,8 @@ + + @@ -3491,6 +3493,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/scratchpad-with-claude/index.html b/site/recipes/scratchpad-with-claude/index.html index 082b187eb..3622d0ef7 100644 --- a/site/recipes/scratchpad-with-claude/index.html +++ b/site/recipes/scratchpad-with-claude/index.html @@ -3385,6 +3385,8 @@ + + @@ -3540,6 +3542,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-archaeology/index.html b/site/recipes/session-archaeology/index.html index f7dd1506f..cf659b1da 100644 --- a/site/recipes/session-archaeology/index.html +++ b/site/recipes/session-archaeology/index.html @@ -3391,6 +3391,8 @@ + + @@ -3546,6 +3548,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-ceremonies/index.html b/site/recipes/session-ceremonies/index.html index f78425867..eba2b1a69 100644 --- a/site/recipes/session-ceremonies/index.html +++ b/site/recipes/session-ceremonies/index.html @@ -3363,6 +3363,8 @@ + + @@ -3518,6 +3520,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-changes/index.html b/site/recipes/session-changes/index.html index 697daee81..e06226a50 100644 --- a/site/recipes/session-changes/index.html +++ b/site/recipes/session-changes/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-lifecycle/index.html b/site/recipes/session-lifecycle/index.html index 96044a278..6862a99ac 100644 --- a/site/recipes/session-lifecycle/index.html +++ b/site/recipes/session-lifecycle/index.html @@ -3352,6 +3352,8 @@ + + @@ -3507,6 +3509,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-pause/index.html b/site/recipes/session-pause/index.html index b1a54c743..25ffa4ec1 100644 --- a/site/recipes/session-pause/index.html +++ b/site/recipes/session-pause/index.html @@ -3258,6 +3258,8 @@ + + @@ -3413,6 +3415,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/session-reminders/index.html b/site/recipes/session-reminders/index.html index 6c503bd74..e27730b12 100644 --- a/site/recipes/session-reminders/index.html +++ b/site/recipes/session-reminders/index.html @@ -3330,6 +3330,8 @@ + + @@ -3485,6 +3487,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/state-maintenance/index.html b/site/recipes/state-maintenance/index.html index 6a8c18c2d..168befd9b 100644 --- a/site/recipes/state-maintenance/index.html +++ b/site/recipes/state-maintenance/index.html @@ -3091,6 +3091,8 @@ + + @@ -3246,6 +3248,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/system-hooks-audit/index.html b/site/recipes/system-hooks-audit/index.html index 3c8bdc7e8..79d80deea 100644 --- a/site/recipes/system-hooks-audit/index.html +++ b/site/recipes/system-hooks-audit/index.html @@ -3613,6 +3613,8 @@ + + @@ -3768,6 +3770,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/task-management/index.html b/site/recipes/task-management/index.html index e95442f26..a4b8ff5ec 100644 --- a/site/recipes/task-management/index.html +++ b/site/recipes/task-management/index.html @@ -3413,6 +3413,8 @@ + + @@ -3568,6 +3570,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/troubleshooting/index.html b/site/recipes/troubleshooting/index.html index 9c4736c6a..7971a2d01 100644 --- a/site/recipes/troubleshooting/index.html +++ b/site/recipes/troubleshooting/index.html @@ -3369,6 +3369,8 @@ + + @@ -3524,6 +3526,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/webhook-notifications/index.html b/site/recipes/webhook-notifications/index.html index 46a094bb5..d68b1669a 100644 --- a/site/recipes/webhook-notifications/index.html +++ b/site/recipes/webhook-notifications/index.html @@ -3391,6 +3391,8 @@ + + @@ -3546,6 +3548,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/recipes/when-to-use-agent-teams/index.html b/site/recipes/when-to-use-agent-teams/index.html index 7c3edf5e4..ebfe1774c 100644 --- a/site/recipes/when-to-use-agent-teams/index.html +++ b/site/recipes/when-to-use-agent-teams/index.html @@ -3397,6 +3397,8 @@ + + @@ -3552,6 +3554,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/comparison/index.html b/site/reference/comparison/index.html index 8987c237a..0112fb417 100644 --- a/site/reference/comparison/index.html +++ b/site/reference/comparison/index.html @@ -3341,6 +3341,8 @@ + + @@ -3496,6 +3498,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/design-invariants/index.html b/site/reference/design-invariants/index.html index a8e804ae3..16d39a0ca 100644 --- a/site/reference/design-invariants/index.html +++ b/site/reference/design-invariants/index.html @@ -3295,6 +3295,8 @@ + + @@ -3450,6 +3452,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/index.html b/site/reference/index.html index 46d4a753b..e5139d3ce 100644 --- a/site/reference/index.html +++ b/site/reference/index.html @@ -3102,6 +3102,8 @@ + + @@ -3257,6 +3259,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/scratchpad/index.html b/site/reference/scratchpad/index.html index ac680cac2..52e599d7e 100644 --- a/site/reference/scratchpad/index.html +++ b/site/reference/scratchpad/index.html @@ -3297,6 +3297,8 @@ + + @@ -3452,6 +3454,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/session-journal/index.html b/site/reference/session-journal/index.html index ca145616e..dc57ecf3d 100644 --- a/site/reference/session-journal/index.html +++ b/site/reference/session-journal/index.html @@ -3419,6 +3419,8 @@ + + @@ -3574,6 +3576,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/skills/index.html b/site/reference/skills/index.html index 7921c5059..a09892688 100644 --- a/site/reference/skills/index.html +++ b/site/reference/skills/index.html @@ -3763,6 +3763,8 @@ + + @@ -3918,6 +3920,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/reference/versions/index.html b/site/reference/versions/index.html index 5e253f4eb..59e9edc2b 100644 --- a/site/reference/versions/index.html +++ b/site/reference/versions/index.html @@ -3264,6 +3264,8 @@ + + @@ -3419,6 +3421,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/search.json b/site/search.json index 9fb124d54..ecb0179b7 100644 --- a/site/search.json +++ b/site/search.json @@ -1 +1 @@ -{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"The ctx Manifesto","text":"","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-manifesto","level":1,"title":"ctx Manifesto","text":"

    Creation, not code.

    Context, not prompts.

    Verification, not vibes.

    This Is NOT a Metaphor

    Code executes instructions.

    Creation produces outcomes.

    Confusing the two is how teams ship motion...

    ...instead of progress.

    • It was never about the code.
    • Code has zero standalone value.
    • Code is an implementation detail.

    Code is an incantation.

    Creation is the act.

    And creation does not happen in a vacuum.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-is-the-substrate","level":2,"title":"ctx Is the Substrate","text":"

    Constraints Have Moved

    Human bandwidth is no longer the limiting factor.

    Context integrity is.

    Human bandwidth is no longer the constraint.

    ctx is.

    • Without durable context, intelligence resets.
    • Without memory, reasoning decays.
    • Without structure, scale collapses.

    Creation is now limited by:

    • Clarity of intent;
    • Quality of context;
    • Rigor of verification.

    Not by speed.

    Not by capacity.

    Velocity Amplifies

    Faster execution on broken context compounds error.

    Speed multiplies whatever is already wrong.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#humans-author-meaning","level":2,"title":"Humans Author Meaning","text":"

    Intent Is Authored

    Systems can optimize.

    Models can generalize.

    Meaning must be chosen.

    Intent is not emergent.

    Vision, goals, and direction are human responsibilities.

    We decide:

    • What matters;
    • What success means;
    • What world we are building.

    ctx encodes the intent so it

    • survives time,
    • survives handoffs,
    • survives scale.

    Nothing important should live only in conversation.

    Nothing critical should depend on recall.

    Oral Tradition Does not Scale

    If intent cannot be inspected, it cannot be enforced.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-before-action","level":2,"title":"ctx Before Action","text":"

    Orientation Precedes Motion

    Acting first and understanding later is not bravery.

    It is debt.

    Never act without ctx.

    Before execution, we must verify:

    • Where we are;
    • Why we are here;
    • What constraints apply;
    • What assumptions are active.

    Action without ctx is gambling.

    Speed without orientation is noise.

    ctx is not overhead: It is the cost of correctness.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#persistent-context-beats-prompt-memory","level":2,"title":"Persistent Context Beats Prompt Memory","text":"

    Transience Is the Default Failure Mode

    • Prompts decay.
    • Chats fragment.
    • Memory heuristics drift.

    Prompts are transient.

    Chats are lossy.

    Memory heuristics drift.

    ctx must be:

    • Durable;
    • Structured;
    • Explicit;
    • Queryable.

    Intent Must Be Intentional

    If intent exists only in a prompt...

    ...alignment is already degrading.

    Knowledge lives in the artifacts:

    • Decisions;
    • Documentation;
    • Dependency maps;
    • Evaluation history.

    Artifacts Outlive Sessions

    What is not written will be re-learned.

    At full cost.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#what-ctx-is-not","level":2,"title":"What ctx Is Not","text":"

    Avoid Category Errors

    Mislabeling ctx guarantees misuse.

    ctx is not a memory feature.

    • ctx is not prompt engineering.
    • ctx is not a productivity hack.
    • ctx is not automation theater.

    ctx is a system for preserving intent under scale.

    ctx is infrastructure.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#verified-reality-is-the-scoreboard","level":2,"title":"Verified Reality Is the Scoreboard","text":"

    Activity is a False Proxy

    Output volume correlates poorly with impact.

    • Code is not progress.
    • Activity is not impact.

    The only truth that compounds is verified change.

    Verified change must exist in the real world.

    Hypotheses are cheap; outcomes are not.

    ctx captures:

    • What we expected;
    • What we observed;
    • Where reality diverged.

    If we cannot predict, measure, and verify the result...

    ...it does not count.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#build-to-learn-not-to-accumulate","level":2,"title":"Build to Learn, Not to Accumulate","text":"

    Prototypes Have an Expiration Date

    A prototype's value is information, not longevity.

    Prototypes exist to reduce uncertainty.

    We build to:

    • Test assumptions;
    • Validate architecture;
    • Answer specific questions.

    Not everything.

    Not blindly.

    Not permanently.

    ctx records archeology so the cost is paid once.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#failures-are-assets","level":2,"title":"Failures Are Assets","text":"

    Failure Without Capture is Waste

    Pain that does not teach is pure loss.

    Failures are not erased: They are preserved.

    Each failure becomes:

    • A documented hypothesis;
    • An analyzed deviation;
    • A permanent artifact.

    Rollback fixes symptoms: ctx fixes systems.

    A repeated mistake is a missing ctx artifact.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#structure-enables-scale","level":2,"title":"Structure Enables Scale","text":"

    Unbounded Autonomy Destabilizes

    Power without a structure produces chaos.

    Transpose it:

    Power without any structure becomes chaos.

    ctx defines:

    • Roles;
    • Boundaries;
    • Protocols;
    • Escalation paths;
    • Decision rights.

    Ambiguity is a system failure:

    • Debates must be structured.
    • Decisions must be explicit.
    • History must be retained.
    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#encode-intent-into-the-environment","level":2,"title":"Encode Intent Into the Environment","text":"

    Goodwill Does not Belong to the Table

    Alignment that depends on memory will drift.

    Alignment cannot depend on memory or goodwill.

    Do not rely on people to remember.

    Encode the behavior, so it happens by default.

    Intent is encoded as:

    • Policies;
    • Schemas;
    • Constraints;
    • Evaluation harnesses.

    Rules must be machine-readable.

    Laws must be enforceable.

    If intent is implicit, drift is guaranteed.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#cost-is-a-first-class-signal","level":2,"title":"Cost Is a First-Class Signal","text":"

    Attention Is the Scarcest Resource

    Not ideas.

    Not ambition.

    Ideas do not compete on time:

    They compete on cost and impact:

    • Attention is finite.
    • Compute is finite.
    • Context is expensive.

    We continuously ask:

    • What the most valuable next action is.
    • What outcome justifies the cost.

    ctx guides allocation.

    Learning reshapes priority.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#show-the-why","level":2,"title":"Show the Why","text":"

    {} (code, artifacts, apps, binaries) produce outputs; they do not preserve reasoning.

    Systems that cannot explain themselves will not be trusted.

    Traceability builds trust.

         {} --> what\n\n    ctx --> why\n

    We record:

    • Explored paths;
    • Rejected options;
    • Assumptions made;
    • Evidence used.

    Opaque systems erode trust:

    Transparent ctx compounds understanding.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#continuously-verify-the-system","level":2,"title":"Continuously Verify the System","text":"

    Stability is Temporary

    Every assumption has a half-life:

    • Models drift.
    • Tools change.
    • Assumptions rot.

    ctx must be verified against reality.

    Trust is a spectrum.

    Trust is continuously re-earned:

    • Benchmarks,
    • regressions,
    • and evaluations...

    ...are safety rails.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-is-leverage","level":2,"title":"ctx Is Leverage","text":"

    Humans are Decision Engines

    Execution should not consume judgment.

    Humans must not be typists.

    We are the authors.

    Human effort is reserved for:

    • Judgment;
    • Design;
    • Taste;
    • Synthesis.

    Repetition is delegated.

    Toil is automated.

    ctx preserves leverage across time.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#the-thesis","level":2,"title":"The Thesis","text":"

    Invariant

    Everything else is an implementation detail.

    • Creation is the act.
    • ctx is the substrate.
    • Verification is the truth.

    Code executes → Models reason → Agents amplify.

    ctx lives on.

    • Without ctx, intelligence resets.
    • With ctx, creation compounds.
    ","path":["The ctx Manifesto"],"tags":[]},{"location":"blog/","level":1,"title":"Blog","text":"

    Stories, insights, and lessons learned from building and using ctx.

    ","path":["Blog"],"tags":[]},{"location":"blog/#context-engineering","level":2,"title":"Context Engineering","text":"","path":["Blog"],"tags":[]},{"location":"blog/#agent-memory-is-infrastructure","level":3,"title":"Agent Memory Is Infrastructure","text":"

    March 4, 2026: Every AI coding agent starts fresh. The obvious fix is \"memory.\" But there's a different problem memory doesn't touch: the project itself accumulates knowledge that has nothing to do with any single session. This post argues that agent memory is L2 (runtime cache); what's missing is L3 (project infrastructure).

    Topics: context engineering, agent memory, infrastructure, persistence, team knowledge

    ","path":["Blog"],"tags":[]},{"location":"blog/#context-as-infrastructure","level":3,"title":"Context as Infrastructure","text":"

    February 17, 2026: Where does your AI's knowledge live between sessions? If the answer is \"in a prompt I paste at the start,\" you are treating context as a consumable. This post argues for treating it as infrastructure instead: persistent files, separation of concerns, two-tier storage, progressive disclosure, and the filesystem as the most mature interface available.

    Topics: context engineering, infrastructure, progressive disclosure, persistence, design philosophy

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-attention-budget-why-your-ai-forgets-what-you-just-told-it","level":3,"title":"The Attention Budget: Why Your AI Forgets What You Just Told It","text":"

    February 3, 2026: Every token you send to an AI consumes a finite resource: the attention budget. Understanding this constraint shaped every design decision in ctx: hierarchical file structure, explicit budgets, progressive disclosure, and filesystem-as-index.

    Topics: attention mechanics, context engineering, progressive disclosure, ctx primitives, token budgets

    ","path":["Blog"],"tags":[]},{"location":"blog/#before-context-windows-we-had-bouncers","level":3,"title":"Before Context Windows, We Had Bouncers","text":"

    February 14, 2026: IRC is stateless. You disconnect, you vanish. Modern systems are not much different. This post traces the line from IRC bouncers to context engineering: stateless protocols require stateful wrappers, volatile interfaces require durable memory.

    Topics: context engineering, infrastructure, IRC, persistence, state continuity

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-last-question","level":3,"title":"The Last Question","text":"

    February 28, 2026: In 1956, Asimov wrote a story about a question that spans the entire future of the universe. A reading of \"The Last Question\" through the lens of persistence, substrate migration, and what it means to build systems where sessions don't reset.

    Topics: context continuity, long-lived systems, persistence, intelligence over time, field notes

    ","path":["Blog"],"tags":[]},{"location":"blog/#agent-behavior-and-design","level":2,"title":"Agent Behavior and Design","text":"","path":["Blog"],"tags":[]},{"location":"blog/#the-dog-ate-my-homework-teaching-ai-agents-to-read-before-they-write","level":3,"title":"The Dog Ate My Homework: Teaching AI Agents to Read Before They Write","text":"

    February 25, 2026: You wrote the playbook. The agent skipped all of it. Five sessions, five failure modes, and the discovery that observable compliance beats perfect compliance.

    Topics: hooks, agent behavior, context engineering, behavioral design, testing methodology, compliance monitoring

    ","path":["Blog"],"tags":[]},{"location":"blog/#skills-that-fight-the-platform","level":3,"title":"Skills That Fight the Platform","text":"

    February 4, 2026: When custom skills conflict with system prompt defaults, the AI has to reconcile contradictory instructions. Five conflict patterns discovered while building ctx.

    Topics: context engineering, skill design, system prompts, antipatterns, AI safety primitives

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-anatomy-of-a-skill-that-works","level":3,"title":"The Anatomy of a Skill That Works","text":"

    February 7, 2026: I had 20 skills. Most were well-intentioned stubs. Then I rewrote all of them. Seven lessons emerged: quality gates prevent premature execution, negative triggers are load-bearing, examples set boundaries better than rules.

    Topics: skill design, context engineering, quality gates, E/A/R framework, practical patterns

    ","path":["Blog"],"tags":[]},{"location":"blog/#you-cant-import-expertise","level":3,"title":"You Can't Import Expertise","text":"

    February 5, 2026: I found a well-crafted consolidation skill. Applied my own E/A/R framework: 70% was noise. This post is about why good skills can't be copy-pasted, and how to grow them from your project's own drift history.

    Topics: skill adaptation, E/A/R framework, convention drift, consolidation, project-specific expertise

    ","path":["Blog"],"tags":[]},{"location":"blog/#not-everything-is-a-skill","level":3,"title":"Not Everything Is a Skill","text":"

    February 8, 2026: I ran an 8-agent codebase audit and got actionable results. The natural instinct was to wrap the prompt as a skill. Then I applied my own criteria: it failed all three tests.

    Topics: skill design, context engineering, automation discipline, recipes, agent teams

    ","path":["Blog"],"tags":[]},{"location":"blog/#defense-in-depth-securing-ai-agents","level":3,"title":"Defense in Depth: Securing AI Agents","text":"

    February 9, 2026: The security advice was \"use CONSTITUTION.md for guardrails.\" That is wishful thinking. Five defense layers for unattended AI agents, each with a bypass, and why the strength is in the combination.

    Topics: agent security, defense in depth, prompt injection, autonomous loops, container isolation

    ","path":["Blog"],"tags":[]},{"location":"blog/#development-practice","level":2,"title":"Development Practice","text":"","path":["Blog"],"tags":[]},{"location":"blog/#code-is-cheap-judgment-is-not","level":3,"title":"Code Is Cheap. Judgment Is Not.","text":"

    February 17, 2026: AI does not replace workers. It replaces unstructured effort. Three weeks of building ctx with an AI agent proved it: YOLO mode showed production is cheap, the 3:1 ratio showed judgment has a cadence.

    Topics: AI and expertise, context engineering, judgment vs production, human-AI collaboration, automation discipline

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-31-ratio","level":3,"title":"The 3:1 Ratio","text":"

    February 17, 2026: AI makes technical debt worse: not because it writes bad code, but because it writes code so fast that drift accumulates before you notice. Three feature sessions, one consolidation session.

    Topics: consolidation, technical debt, development workflow, convention drift, code quality

    ","path":["Blog"],"tags":[]},{"location":"blog/#refactoring-with-intent-human-guided-sessions-in-ai-development","level":3,"title":"Refactoring with Intent: Human-Guided Sessions in AI Development","text":"

    February 1, 2026: The YOLO mode shipped 14 commands in a week. But technical debt doesn't send invoices. This is the story of what happened when we started guiding the AI with intent.

    Topics: refactoring, code quality, documentation standards, module decomposition, YOLO versus intentional development

    ","path":["Blog"],"tags":[]},{"location":"blog/#how-deep-is-too-deep","level":3,"title":"How Deep Is Too Deep?","text":"

    February 12, 2026: I kept feeling like I should go deeper into ML theory. Then I spent a week debugging an agent failure that had nothing to do with model architecture. When depth compounds and when it doesn't.

    Topics: AI foundations, abstraction boundaries, agentic systems, context engineering, failure modes

    ","path":["Blog"],"tags":[]},{"location":"blog/#agent-workflows","level":2,"title":"Agent Workflows","text":"","path":["Blog"],"tags":[]},{"location":"blog/#parallel-agents-merge-debt-and-the-myth-of-overnight-progress","level":3,"title":"Parallel Agents, Merge Debt, and the Myth of Overnight Progress","text":"

    February 17, 2026: You discover agents can run in parallel. So you open ten terminals. It is not progress: it is merge debt being manufactured in real time. The five-agent ceiling and why role separation beats file locking.

    Topics: agent workflows, parallelism, verification, context engineering, engineering practice

    ","path":["Blog"],"tags":[]},{"location":"blog/#parallel-agents-with-git-worktrees","level":3,"title":"Parallel Agents with Git Worktrees","text":"

    February 14, 2026: I had 30 open tasks that didn't touch the same files. Using git worktrees to partition a backlog by file overlap, run 3-4 agents simultaneously, and merge the results.

    Topics: agent teams, parallelism, git worktrees, context engineering, task management

    ","path":["Blog"],"tags":[]},{"location":"blog/#field-notes-and-signals","level":2,"title":"Field Notes and Signals","text":"","path":["Blog"],"tags":[]},{"location":"blog/#when-a-system-starts-explaining-itself","level":3,"title":"When a System Starts Explaining Itself","text":"

    February 17, 2026: Every new substrate begins as a private advantage. Reality begins when other people start describing it in their own language. \"Better than Adderall\" is not praise; it is a diagnostic.

    Topics: field notes, adoption signals, infrastructure vs tools, context engineering, substrates

    ","path":["Blog"],"tags":[]},{"location":"blog/#why-zensical","level":3,"title":"Why Zensical","text":"

    February 15, 2026: I needed a static site generator for the journal system. The instinct was Hugo. But instinct is not analysis. Why zensical was the right choice: thin dependencies, MkDocs-compatible config, and zero lock-in.

    Topics: tooling, static site generators, journal system, infrastructure decisions, context engineering

    ","path":["Blog"],"tags":[]},{"location":"blog/#releases","level":2,"title":"Releases","text":"","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v060-the-integration-release","level":3,"title":"ctx v0.6.0: The Integration Release","text":"

    February 16, 2026: ctx is now a Claude Marketplace plugin. Two commands, no build step, no shell scripts. v0.6.0 replaces six Bash hook scripts with compiled Go subcommands and ships 25+ Skills as a plugin.

    Topics: release, plugin system, Claude Marketplace, distribution, security hardening

    ","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v030-the-discipline-release","level":3,"title":"ctx v0.3.0: The Discipline Release","text":"

    February 15, 2026: No new headline feature. Just 35+ documentation and quality commits against ~15 feature commits. What a release looks like when the ratio of polish to features is 3:1.

    Topics: release, skills migration, consolidation, code quality, E/A/R framework

    ","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v020-the-archaeology-release","level":3,"title":"ctx v0.2.0: The Archaeology Release","text":"

    February 1, 2026: What if your AI could remember everything? Not just the current session, but every session. ctx v0.2.0 introduces the recall and journal systems.

    Topics: session recall, journal system, structured entries, token budgets, meta-tools

    ","path":["Blog"],"tags":[]},{"location":"blog/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":3,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"

    January 27, 2026: What happens when you build a tool designed to give AI memory, using that very same tool to remember what you're building? This is the story of ctx.

    Topics: dogfooding, AI-assisted development, Ralph Loop, session persistence, architectural decisions

    ","path":["Blog"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/","level":1,"title":"Building ctx Using ctx","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    References to .context/sessions/, auto-save hooks, and SessionEnd auto-save in this post reflect the architecture at the time of writing.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#a-meta-experiment-in-ai-assisted-development","level":2,"title":"A Meta-Experiment in AI-Assisted Development","text":"

    Jose Alekhinne / 2026-01-27

    Can a Tool Design Itself?

    What happens when you build a tool designed to give AI memory, using that very same tool to remember what you are building?

    This is the story of ctx, how it evolved from a hasty \"YOLO mode\" experiment to a disciplined system for persistent AI context, and what I have learned along the way.

    Context is a Record

    Context is a persistent record.

    By \"context\", I don't mean model memory or stored thoughts:

    I mean the durable record of decisions, learnings, and intent that normally evaporates between sessions.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#ai-amnesia","level":2,"title":"AI Amnesia","text":"

    Every developer who works with AI code generators knows the frustration:

    You have a deep, productive session where the AI understands your codebase, your conventions, your decisions. And then you close the terminal.

    Tomorrow; it's a blank slate. The AI has forgotten everything.

    That is \"reset amnesia\", and it's not just annoying: it's expensive.

    Every session starts with:

    • Re-explaining context;
    • Re-reading files;
    • Re-discovering decisions that were already made.

    I Needed Context

    \"I don't want to lose this discussion...

    ...I am a brain-dead developer YOLO'ing my way out.\"

    ☝️ that's exactly what I said to Claude when I first started working on ctx.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-genesis","level":2,"title":"The Genesis","text":"

    The project started as \"Active Memory\" (amem): a CLI tool to persist AI context across sessions.

    The core idea was simple:

    1. Create a .context/ directory with structured Markdown files for decisions, learnings, tasks, and conventions.
    2. The AI reads these at session start and writes to them before the session ends.
    3. There is no step 3.

    The first commit was just scaffolding. But within hours, the Ralph Loop (An iterative AI development workflow) had produced a working CLI:

    feat(cli): implement amem init command\nfeat(cli): implement amem status command\nfeat(cli): implement amem add command\nfeat(cli): implement amem agent command\n...\n

    Not one, not two, but a whopping fourteen core commands shipped in rapid succession!

    I was YOLO'ing like there was no tomorrow:

    • Auto-accept every change;
    • Let the AI run free;
    • Ship features fast.
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-meta-experiment-using-amem-to-build-amem","level":2,"title":"The Meta-Experiment: Using amem to Build amem","text":"

    Here's where it gets interesting: On January 20th, I asked:

    \"Can I use amem to help you remember this context when I restart?\"

    The answer was yes, but with a gap:

    Autoload worked (via Claude Code's PreToolUse hook), but auto-save was missing: If the user quit, with Ctrl+C, everything since the last manual save was lost.

    That session became the first real test of the system.

    Here is the first session file we recorded:

    ## Key Discussion Points\n\n### 1. amem vs Ralph Loop - They're Separate Systems\n\n**User's question**: \"How do I use the binary to recreate this project?\"\n\n**Answer discovered**: `amem` is for context management, Ralph Loop is for \ndevelopment workflow. They are complementary but separate.\n\n### 2. Two Tiers of Context Persistence\n\n| Tier      | What                        | Why                           |\n|-----------|-----------------------------|-------------------------------|\n| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient |\n| Full dump | Entire conversation         | Safety net, nothing lost      |\n\n| Where                  |\n|------------------------|\n| .context/*.md          |\n| .context/sessions/*.md |\n

    This session file (written by the AI to preserve its own context) became the template for how ctx handles session persistence.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-rename","level":2,"title":"The Rename","text":"

    By January 21st, I realized \"Active Memory\" was too generic, and (arguably) too marketing-smelly.

    Besides, the binary was already called ctx (short for Context), the directory was .context/, and the slash commands would be /ctx-*.

    So it followed that the project should be renamed to ctx to make things make sense.

    The rename touched 100+ files but was clean: a find-and-replace with Go's type system catching any misses.

    The git history tells the story:

    0e8f6bb feat: rename amem to ctx and add Claude Code integration\n87dcfa1 README.\n4f0e195 feat: separate orchestrator directive from agent tasks\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#yolo-mode-fast-but-dangerous","level":2,"title":"YOLO Mode: Fast, But Dangerous","text":"

    The Ralph Loop made feature development incredibly fast.

    But it created technical debt that I didn't notice until later.

    A comparison session on January 25th revealed the patterns:

    YOLO Pattern What We Found \"TASKS.md\" scattered in 10 files Same string literal everywhere, no constants dir + \"/\" + file Should be filepath.Join() Monolithic cli_test.go (1500+ lines) Tests disconnected from implementations package initcmd in init/ folder Go's \"init\" is reserved: subtle naming collision

    Here is another analysis made by ctx:

    ● Based on my analysis, here are the key differences:\n\nYOLO Mode (Pre-040ce99)\n- Feature-first: Added slash commands, tests, templates rapidly\n- Scattered magic strings: \"TASKS.md\", \"decision\", \".context\" spread across files\n- Quick file creation: New files without organizational patterns\n- Working but inconsistent: Code functioned but lacked systematic structure\n\nHuman-Guided Mode (Post-040ce99)\n- Consolidation focus: Centralized constants in config package\n- Consistent naming: Dir, File, Filename, UpdateType prefixes\n- Self-referential constants: FileType map uses constants as keys, not literals\n- Proper path construction: filepath.Join() instead of +\"/\"+\n- Colocated tests: Tests next to implementations\n- Canonical naming: Package name = folder name\n

    The fix required a human-guided refactoring session. I continued to do that before every major release, from that point on.

    We introduced internal/config/config.go with semantic prefixes:

    const (\n    DirContext     = \".context\"\n    DirArchive     = \"archive\"\n    DirSessions    = \"sessions\"\n    FilenameTask   = \"TASKS.md\"\n    UpdateTypeTask = \"task\"\n)\n

    What I begrudgingly learned was: YOLO mode is effective for velocity but accumulates debt.

    So I took a mental note to schedule periodic consolidation sessions.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-dogfooding-test-that-failed","level":2,"title":"The Dogfooding Test That Failed","text":"

    On January 21st, I ran an experiment: have another Claude instance rebuild ctx from scratch using only the specs and PROMPT.md.

    The Ralph Loop ran, all tasks got checked off, the loop exited successfully.

    But the binary was broken!

    Commands just printed help text instead of executing.

    All tasks were marked \"complete\" but the implementation didn't work.

    Here's what ctx discovered:

    ## Key Findings\n\n### Dogfooding Binary Is Broken\n- Commands don't execute: they just print root help text\n- All tasks were marked complete but binary doesn't work\n- Lesson: \"tasks checked off\" ≠ \"implementation works\"\n

    This was humbling; to say the least.

    I realized I had the same blind spot in my own codebase: no integration tests that actually invoked the binary.

    So I added:

    • Integration tests for all commands;
    • Coverage targets (60-80% per package)
    • Smoke tests in CI
    • A constitution rule: \"All code must pass tests before commit\"
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-constitution-versus-conventions","level":2,"title":"The Constitution versus Conventions","text":"

    As lessons accumulated, there was the temptation to add everything to CONSTITUTION.md as \"inviolable rules\".

    But I resisted.

    The constitution should contain only truly inviolable invariants:

    • Security (no secrets, no customer data)
    • Quality (tests must pass)
    • Process (decisions need records)
    • ctx invocation (always use PATH, never fallback)

    Everything else (coding style, file organization, naming conventions...) should go in to CONVENTIONS.md.

    Here's how ctx explained why the distinction was important:

    Decision record, 2026-01-25

    Overly strict constitution creates friction and gets ignored.

    Conventions can be bent; constitution cannot.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#hooks-harder-than-they-look","level":2,"title":"Hooks: Harder Than They Look","text":"

    Claude Code hooks seemed simple: Run a script before/after certain events.

    But I hit multiple gotchas:

    1. Key names matter

    // WRONG - \"Invalid key in record\" error\n\"PreToolUseHooks\": [...]\n\n// RIGHT\n\"PreToolUse\": [...]\n

    2. Blocking requires specific output

    # WRONG - just exits, doesn't block\nexit 1\n\n# RIGHT - JSON output + exit 0\necho '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH\"}'\nexit 0\n

    3. Go's JSON escaping

    json.Marshal escapes >, <, & as unicode (\\u003e) by default.

    When generating shell commands in JSON:

    encoder := json.NewEncoder(file)\nencoder.SetEscapeHTML(false) // Prevent 2>/dev/null → 2\\u003e/dev/null\n

    4. Regex overfitting

    My hook to block non-PATH ctx invocations initially matched too broadly:

    # WRONG - matches /home/user/ctx/internal/file.go (ctx as directory)\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# RIGHT - matches ctx as binary only\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-session-files","level":2,"title":"The Session Files","text":"

    By the time of this writing this project's ctx sessions (.context/sessions/) contains 40+ files from this project's development.

    They are not part of the source code due to security, privacy, and size concerns.

    Middle Ground: the Scratchpad

    For sensitive notes that do need to travel with the project, ctx pad stores encrypted one-liners in git, and ctx pad add \"label\" --file PATH can ingest small files.

    See Scratchpad for details.

    However, they are invaluable for the project's progress.

    Each session file is a timestamped Markdown with:

    • Summary of what has been accomplished;
    • Key decisions made;
    • Learnings discovered;
    • Tasks for the next session;
    • Technical context (platform, versions).

    These files are not autoloaded (that would bust the token budget).

    They are what I see as the \"archaeological record\" of ctx:

    When the AI needs deeper information about why something was done, it digs into the sessions.

    Auto-generated session files used a naming convention:

    2026-01-23-115432-session-prompt_input_exit-summary.md\n2026-01-25-220244-manual-save.md\n2026-01-27-052107-session-other-summary.md\n

    Update

    The session feature described here is historical.

    In current releases, ctx uses a journal instead: the enrichment process generates meaningful slugs from context automatically, so there is no need to manually save sessions.

    The SessionEnd hook captured transcripts automatically. Even Ctrl+C was caught.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-decision-log-18-architectural-decisions","level":2,"title":"The Decision Log: 18 Architectural Decisions","text":"

    ctx helps record every significant architectural choice in .context/DECISIONS.md.

    Here are some highlights:

    Reverse-chronological order (2026-01-27)

    **Context**: With chronological order, oldest items consume tokens first, and\nnewest (most relevant) items risk being truncated.\n\n**Decision**: Use reverse-chronological order (newest first) for DECISIONS.md\nand LEARNINGS.md.\n

    PATH over hardcoded paths (2026-01-21)

    **Context**: Original implementation hardcoded absolute paths in hooks.\nThis breaks when sharing configs with other developers.\n\n**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before \nproceeding.\n

    Generic core with Claude enhancements (2026-01-20)

    **Context**: ctx should work with any AI tool, but Claude Code users could\nbenefit from deeper integration.\n\n**Decision**: Keep ctx generic as the core tool, but provide optional\nClaude Code-specific enhancements.\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-learning-log-24-gotchas-and-insights","level":2,"title":"The Learning Log: 24 Gotchas and Insights","text":"

    The .context/LEARNINGS.md file captures gotchas that would otherwise be forgotten. Each has Context, Lesson, and Application sections:

    CGO on ARM64

    **Context**: `go test` failed with \n`gcc: error: unrecognized command-line option '-m64'`\n\n**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. \nAlways use `CGO_ENABLED=0`.\n

    Claude Code skills format

    **Lesson**: Claude Code skills are Markdown files in .claude/commands/ with `YAML`\nfrontmatter (*description, argument-hint, allowed-tools*). Body is the prompt.\n

    \"Do you remember?\" handling

    **Lesson**: In a `ctx`-enabled project, \"*do you remember?*\" \nhas an obvious meaning:\ncheck the `.context/` files. Don't ask for clarification. Just do it.\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#task-archives-the-completed-work","level":2,"title":"Task Archives: The Completed Work","text":"

    Completed tasks are archived to .context/archive/ with timestamps.

    The archive from January 23rd shows 13 phases of work:

    • Phase 1: Project Scaffolding (Go module, Cobra CLI)
    • Phase 2-4: Core Commands (init, status, agent, add, complete, drift, sync, compact, watch, hook)
    • Phase 5: Session Management (save, list, load, parse, --extract)
    • Phase 6: Claude Code Integration (hooks, settings, CLAUDE.md handling)
    • Phase 7: Testing & Verification
    • Phase 8: Task Archival
    • Phase 9: Slash Commands
    • Phase 9b: Ralph Loop Integration
    • Phase 10: Project Rename
    • Phase 11: Documentation
    • Phase 12: Timestamp Correlation
    • Phase 13: Rich Context Entries

    That's an impressive ^^173 commits** across 8 days of development.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#what-i-learned-about-ai-assisted-development","level":2,"title":"What I Learned About AI-Assisted Development","text":"

    1. Memory changes everything

    When the AI remembers decisions, it doesn't repeat mistakes.

    When the AI knows your conventions, it follows them.

    ctx makes the AI a better collaborator because it's not starting from zero.

    2. Two-tier persistence works

    Curated context (DECISIONS.md, LEARNINGS.md, TASKS.md) is for quick reload.

    Full session dumps are for archaeology.

    It's a futile effort to try to fit everything in the token budget.

    Persist more, load less.

    3. YOLO mode has its place

    For rapid prototyping, letting the AI run free is effective.

    But I had to schedule consolidation sessions.

    Technical debt accumulates silently.

    4. The constitution should be small

    Only truly inviolable rules go in CONSTITUTION.md. Everything else is a convention.

    If you put too much in the constitution, it will get ignored.

    5. Verification is non-negotiable

    \"All tasks complete\" means nothing if you haven't run the tests.

    Integration tests that invoke the actual binary caught bugs that the unit tests missed.

    6. Session files are underrated

    The ability to grep through 40 session files and find exactly when and why a decision was made helped me a lot.

    It's not about loading them into context: It is about having them when you need them.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-future-recall-system","level":2,"title":"The Future: Recall System","text":"

    The next phase of ctx is the Recall System:

    • Parser: Parse session capture markdowns, enrich with JSONL data
    • Renderer: Goldmark + Chroma for syntax highlighting, dark mode UI
    • Server: Local HTTP server for browsing sessions
    • Search: Inverted index for searching across sessions
    • CLI: ctx recall serve <path> to start the server

    The goal is to make the archaeological record browsable, not just grep-able.

    Because not everyone always lives in the terminal (me included).

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#conclusion","level":2,"title":"Conclusion","text":"

    Building ctx using ctx was a meta-experiment in AI-assisted development.

    I learned that memory isn't just convenient: It's transformative:

    • An AI that remembers your decisions doesn't repeat mistakes.
    • An AI that knows your conventions doesn't need them re-explained.

    If you are reading this, chances are that you already have heard about ctx.

    • ctx is open source at github.com/ActiveMemory/ctx,
    • and the documentation lives at ctx.ist.

    Session Records are a Gold Mine

    By the time of this writing, I have more than 70 megabytes of text-only session capture, spread across >100 Markdown and JSONL files.

    I am analyzing, synthesizing, encriching them with AI, running RAG (Retrieval-Augmented Generation) models on them, and the outcome surprises me every day.

    If you are a mere mortal tired of reset amnesia, give ctx a try.

    And when you do, check .context/sessions/ sometime.

    The archaeological record might surprise you.

    This blog post was written with the help of ctx with full access to the ctx session files, decision log, learning log, task archives, and git history of ctx: The meta continues.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/","level":1,"title":"ctx v0.2.0: The Archaeology Release","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    The .context/sessions/ directory referenced in this post has been eliminated. Session history is now accessed via ctx recall and enriched journals live in .context/journal/.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#digging-through-the-past-to-build-the-future","level":2,"title":"Digging Through the Past to Build the Future","text":"

    Jose Alekhinne / 2026-02-01

    What if Your AI Could Remember Everything?

    Not just the current session, but every session:

    • Every decision made,
    • every mistake avoided,
    • every path not taken.

    That's what v0.2.0 delivers.

    Between v0.1.2 and v0.2.0, 86 commits landed across 5 days.

    The release notes list features and fixes.

    This post tells the story of why those features exist, and what building them taught me.

    This isn't a changelog: It is an explanation of intent.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-problem-amnesia-isnt-just-session-level","level":2,"title":"The Problem: Amnesia Isn't Just Session-Level","text":"

    v0.1.0 solved reset amnesia:

    The AI now remembers decisions, learnings, and tasks across sessions.

    But a new problem emerged, which I can sum up as:

    \"I (the human) am not AI.\"

    Frankly, I couldn't remember what the AI remembered.

    Let alone, I cannot remember what I ate for breakfast!

    In the course of days, I realized session transcripts piled up in .context/sessions/; I was grepping, JSONL files with thousands of lines... Raw tool calls, assistant responses, user messages...

    ...all interleaved.

    Valuable context was effectively buried in machine-readable noise.

    I found myself grepping through files to answer questions like:

    • \"When did we decide to use constants instead of literals?\"
    • \"What was the session where we fixed the hook regex?\"
    • \"How did the embed.go split actually happen?\"

    Fate is Whimsical

    The irony was painful:

    I built a tool to prevent AI amnesia, but I was suffering from human amnesia about what happened in AI sessions.

    This was the moment ctx stopped being just an AI tool and started needing to support the human on the other side of the loop.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-solution-recall-and-journal","level":2,"title":"The Solution: Recall and Journal","text":"

    v0.2.0 introduces two interconnected systems.

    They solve different problems and only work well together.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#ctx-recall-browse-your-past","level":3,"title":"ctx recall: Browse Your Past","text":"
    # List all sessions for this project\nctx recall list\n\n# Show a specific session\nctx recall show gleaming-wobbling-sutherland\n\n# See the full transcript\nctx recall show gleaming-wobbling-sutherland --full\n

    The recall system parses Claude Code's JSONL transcripts and presents them in a human-readable format:

    Session Date Turns Duration tender-painting-sundae 2026-01-29 3 <1m crystalline-gliding-willow 2026-01-29 3 <1m declarative-hugging-snowglobe 2026-01-31 2 <1m

    Slugs are auto-generated from session IDs (memorable names instead of UUIDs). The goal (as the name implies) is recall, not archival accuracy.

    2,121 lines of new code

    The ctx recall feature was the largest single addition:

    parser library, CLI commands, test suite, and slash command.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#ctx-journal-from-raw-to-rich","level":3,"title":"ctx journal: From Raw to Rich","text":"

    Listing sessions isn't enough. The transcripts are still unwieldy.

    • Recall answers what happened.
    • Journal answers what mattered.
    # Export sessions to editable Markdown\nctx recall export --all\n\n# Generate a static site from journal entries\nctx journal site\n\n# Serve it locally\nctx serve\n

    The exported files land in .context/journal/:

    .context/journal/\n├── 2026-01-28-proud-sleeping-cook-6e535360.md\n├── 2026-01-29-tender-painting-sundae-b14ddaaa.md\n├── 2026-01-29-crystalline-gliding-willow-ff7fd67d.md\n└── 2026-01-31-declarative-hugging-snowglobe-4549026d.md\n

    Each file is a structured Markdown document ready for enrichment.

    They are meant to be read, edited, and reasoned about; not just stored.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-meta-slash-commands-for-self-analysis","level":2,"title":"The Meta: Slash Commands for Self-Analysis","text":"

    The journal system includes four slash commands that use Claude to analyze and synthesize session history:

    Command Purpose /ctx-journal-enrich Add frontmatter, topics, tags /ctx-blog Generate blog post from activity /ctx-blog-changelog Generate changelog from commits

    This very post was drafted using /ctx-blog. The previous post about refactoring was drafted the same way.

    So, yes: The meta continues: ctx now helps write posts about ctx.

    With the current release, ctx is no longer just recording history:

    It is participating in its interpretation.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-structure-decisions-as-first-class-citizens","level":2,"title":"The Structure: Decisions as First-Class Citizens","text":"

    v0.1.0 let you add decisions with a simple command:

    ctx add decision \"Use PostgreSQL\"\n

    But sessions showed a pattern: decisions added this way were incomplete:

    • Context was missing;
    • Rationale was vague;
    • Consequences were never stated.

    Once recall and journaling existed, this weakness became impossible to ignore:

    Structure stopped being optional.

    v0.2.0 enforces structure:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a reliable database for user data\" \\\n  --rationale \"ACID compliance, team familiarity, strong ecosystem\" \\\n  --consequence \"Need to set up connection pooling, team training\"\n

    All three flags are required. No more placeholder text.

    Every decision is now a proper Architecture Decision Record (*ADR), not a note.

    The same enforcement applies to learnings too:

    ctx add learning \"CGO breaks ARM64 builds\" \\\n  --context \"go test failed with gcc errors on ARM64\" \\\n  --lesson \"Always use CGO_ENABLED=0 for cross-platform builds\" \\\n  --application \"Added to Makefile and CI config\"\n

    Structured entries are prompts to the AI

    When the AI reads a decision with full context, rationale, and consequences, it understands the why, not just the what.

    One-liners teach nothing.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-order-newest-first","level":2,"title":"The Order: Newest First","text":"

    A subtle but important change: DECISIONS.md and LEARNINGS.md now use reverse-chronological order.

    One reason is token budgets, obviously; another reason is to help your fellow human (i.e., the Author):

    Earlier decisions are more likely to be relevant, and they are more likely to have more emphasis on the project. So it follows that they should be read first.

    But back to AI:

    When the AI reads a file, it reads from the top (and seldom from the bottom).

    If the token budget is tight, old content gets truncated. As in any good engineering practice, it's always about the tradeoffs.

    Reverse order ensures the most recent (and most relevant) context is always loaded first.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-index-quick-reference-tables","level":2,"title":"The Index: Quick Reference Tables","text":"

    DECISIONS.md and LEARNINGS.md now include auto-generated indexes.

    • For AI agents, the index allows scanning without reading full entries.
    • For humans, it's a table of contents.

    The same structure serves two very different readers.

    Reindex after manual edits

    If you edit entries by hand, rebuild the index with:

    ctx decisions reindex\nctx learnings reindex\n

    See the Knowledge Capture recipe for details.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-configuration-contextrc","level":2,"title":"The Configuration: .contextrc","text":"

    Projects can now customize ctx behavior via .contextrc.

    This makes ctx usable in real teams, not just personal projects.

    Priority order: CLI flags > environment variables > .contextrc > sensible defaults

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-flags-global-cli-options","level":2,"title":"The Flags: Global CLI Options","text":"

    Three new global flags work with any command.

    These enable automation:

    CI pipelines, scripts, and long-running tools can now integrate ctx without hacks or workarounds.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-refactoring-under-the-hood","level":2,"title":"The Refactoring: Under the Hood","text":"

    These aren't user-visible changes.

    They are the kind of work you only appreciate later, when everything else becomes easier to build.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#what-we-learned-building-v020","level":2,"title":"What We Learned Building v0.2.0","text":"","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#1-raw-data-isnt-knowledge","level":3,"title":"1. Raw Data Isn't Knowledge","text":"

    JSONL transcripts contain everything, and I mean \"everything\":

    They even contain hidden system messages that Anthropic injects to the LLM's conversation to treat humans better: It's immense.

    But \"everything\" isn't useful until it is transformed into something a human can reason about.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#2-enforcement-documentation","level":3,"title":"2. Enforcement > Documentation","text":"

    The Prompt is a Guideline

    The code is more what you'd call 'guidelines' than actual rules.

    -Hector Barbossa

    Rules written in Markdown are suggestions.

    Rules enforced by the CLI shape behavior; both for humans and AI.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#3-token-budget-is-ux","level":3,"title":"3. Token Budget Is UX","text":"

    File order decides what the AI sees.

    That makes it a user experience concern, not an implementation detail.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#4-meta-tools-compound","level":3,"title":"4. Meta-Tools Compound","text":"

    Tools that analyze their own development tend to generalize well.

    The journal system started as a way to understand ctx itself.

    It immediately became useful for everything else.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#v020-in-the-numbers","level":2,"title":"v0.2.0 in The Numbers","text":"

    This was a heavy release. The numbers reflect that:

    Metric v0.1.2 v0.2.0 Commits since last - 86 New commands 15 21 Slash commands 7 11 Lines of Go ~6,500 ~9,200 Session files (this project) 40 54

    The binary grew. The capability grew more.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#whats-next","level":2,"title":"What's Next","text":"

    But those are future posts.

    This one was about making the past usable.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#get-started","level":2,"title":"Get Started","text":"

    Update

    Since this post, ctx became a first-class Claude Code Marketplace plugin. Installation is now simpler.

    See the Getting Started guide for the current instructions.

    make build\nsudo make install\nctx init\n

    The Archaeological Record

    v0.2.0 is the archaeology release because it makes the past accessible.

    Session transcripts aren't just logs anymore: They are a searchable, exportable, analyzable record of how your project evolved.

    The AI remembers. Now you can too.

    This blog post was generated with the help of ctx using the /ctx-blog slash command, with full access to git history, session files, decision logs, and learning logs from the v0.2.0 development window.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/","level":1,"title":"Refactoring with Intent","text":"","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#human-guided-sessions-in-ai-development","level":2,"title":"Human-Guided Sessions in AI Development","text":"

    Jose Alekhinne / 2026-02-01

    What Happens When You Slow Down?

    YOLO mode shipped 14 commands in a week.

    But technical debt doesn't send invoices: It just waits.

    This is the story of what happened when I stopped auto-accepting everything and started guiding the AI with intent.

    The result: 27 commits across 4 days, a major version release, and lessons that apply far beyond ctx.

    The Refactoring Window

    January 28 - February 1, 2026

    From commit bb1cd20 to the v0.2.0 release merge. (this window matters more than the individual commits: it's where intent replaced velocity.)

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-velocity-trap","level":2,"title":"The Velocity Trap","text":"

    In the previous post, I documented the \"YOLO mode\" that birthed ctx: auto-accept everything, let the AI run free, ship features fast.

    It worked: until it didn't.

    The codebase had accumulated patterns I didn't notice during the sprint:

    YOLO Pattern Where Found Why It Hurts \"TASKS.md\" as literal 10+ files One typo = silent failure dir + \"/\" + file Path construction Breaks on Windows Monolithic embed.go 150+ lines, 5 concerns Untestable, hard to extend Inconsistent docstrings Everywhere AI can't learn project conventions

    I didn't see these during \"YOLO mode\" because, honestly, I wasn't looking.

    Auto-accept means auto-ignore.

    In YOLO mode, every file you open looks fine until you try to change it.

    In contrast, refactoring mode is when you start paying attention to that hidden friction.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-shift-from-velocity-to-intent","level":2,"title":"The Shift: From Velocity to Intent","text":"

    On January 28th, I changed the workflow:

    1. Read every diff before accepting.
    2. Ask \"why this way?\" before committing.
    3. Document patterns, not just features.

    The first commit of this era was telling:

    feat: add structured attributes to context. update XML format\n

    Not a new feature: A refinement:

    The XML format for context updates needed type and timestamp attributes.

    YOLO mode would have shipped something that worked. Intentional mode asked:

    \"What does well-structured look like?\"

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-decomposition-embedgo","level":2,"title":"The Decomposition: embed.go","text":"

    The most satisfying refactor was splitting internal/claude/embed.go.

    Before: One 153-line file doing five things:

    • Command registration
    • Hook generation
    • Permission handling
    • Script templates
    • Type definitions

    ... your \"de facto\" God object.

    After: Five focused modules:

    File Lines Responsibility cmd.go 46 Command registration hook.go 64 Hook configuration perm.go 25 Permission handling script.go 47 Script templates types.go 7 Type definitions

    The refactor also renamed functions to follow Go conventions:

    // Before: unnecessary prefixes\nGetAutoSaveScript()\nGetBlockNonPathCtxScript()\nListCommands()\nCreateDefaultHooks()\n\n// After: idiomatic Go\nAutoSaveScript()\nBlockNonPathCtxScript()\nCommands()\nDefaultHooks()\n

    This wasn't about character count. It was about teaching the AI what good Go looks like in this project.

    Project Conventions

    What I wanted from AI was to understand and follow the project's conventions, and trust the author.

    The next time it generates code, it has better examples to learn from.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-documentation-debt","level":2,"title":"The Documentation Debt","text":"

    YOLO mode created features. It didn't create documentation standards.

    The January 29th sessions focused on standardization.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#terminology-fixes","level":3,"title":"Terminology Fixes","text":"
    • \"context-update\" → \"entry\" (what users actually call them)
    • Consistent naming across CLI, docs, and code comments
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#go-docstrings","level":3,"title":"Go Docstrings","text":"
    // Before: inconsistent or missing\nfunc Parse(s string) Entry { ... }\n\n// After: standardized sections\n\n// Parse extracts an entry from a markdown string.\n//\n// Parameters:\n//   - s: The markdown string to parse\n//\n// Returns:\n//   - Entry with populated fields, or zero value if parsing fails\nfunc Parse(s string) Entry { ... }\n

    This is intentionally more structured than typical GoDoc:

    It serves as documentation and doubles as training data for future AI-generated code.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#cli-output-convention","level":3,"title":"CLI Output Convention","text":"
    All CLI output follows: [emoji] [Title]: [message]\n\nExamples:\n  ✓ Decision added: Use symbolic types for entry categories\n  ⚠ Warning: No tasks found\n  ✗ Error: File not found\n

    A consistent output shape makes both human scanning and AI reasoning more reliable.

    These aren't exciting commits. But they are force multipliers:

    Every future AI session now has better examples to follow.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-journal-system","level":2,"title":"The Journal System","text":"

    If you only read one section, read this one:

    This is where v0.2.0 becomes more than a refactor.

    The biggest feature of this change window wasn't a refactor; it was the journal system.

    45 files changed, 1680 insertions

    This commit added the infrastructure for synthesizing AI session history into human-readable content.

    The journal system includes:

    Component Purpose ctx recall export Export sessions to markdown in .context/journal/ ctx journal site Generate static site from journal entries ctx serve Convenience wrapper for the static site server /ctx-journal-enrich Slash command to add frontmatter and tags /ctx-blog Generate blog posts from recent activity /ctx-blog-changelog Generate changelog-style blog posts

    ...and the meta continues: this blog post was generated using /ctx-blog.

    The session history from January 28-31 was

    • exported,
    • enriched,
    • and synthesized.

    into the narrative you are reading.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-constants-consolidation","level":2,"title":"The Constants Consolidation","text":"

    The final refactoring session addressed the remaining magic strings:

    const (\n    // Comment markers\n    CommentOpen  = \"<!--\"\n    CommentClose = \"-->\"\n\n    // Index markers\n    MarkerIndexStart = \"<!-- INDEX:START -->\"\n    MarkerIndexEnd   = \"<!-- INDEX:END -->\"\n\n    // Newlines\n    NewlineLF   = \"\\n\"\n    NewlineCRLF = \"\\r\\n\"\n)\n

    The work also introduced thread safety in the recall parser and centralized shared validation logic; removing duplication that had quietly spread during YOLO mode.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#i-relearned-my-lessons","level":2,"title":"I (Re)learned My Lessons","text":"

    Similar to what I've learned in the former human-assisted refactoring post, this journey also made me realize that \"AI-only code generation\" isn't sustainable in the long term.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#1-velocity-and-quality-arent-opposites","level":3,"title":"1. Velocity and Quality Aren't Opposites","text":"

    YOLO mode has its place: for prototyping, exploration, and discovery.

    BUT (and it's a huge \"but\"), it needs to be followed by consolidation sessions.

    The ratio that worked for me: 3:1.

    • Three YOLO sessions create enough surface area to reveal patterns;
    • the fourth session turns those patterns into structure.
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#2-documentation-is-code","level":3,"title":"2. Documentation IS Code","text":"

    When I standardized docstrings, I wasn't just writing docs. I was training future AI sessions.

    Every example of good code becomes a template for generated code.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#3-decomposition-deletion","level":3,"title":"3. Decomposition > Deletion","text":"

    When embed.go became unwieldy, the temptation was to remove functionality.

    The right answer was decomposition:

    • Same functionality;
    • Better organization;
    • Easier to test;
    • Easier to extend.

    The result: more lines overall, but dramatically better structure.

    The AI Benefit

    Smaller, focused files also help AI assistants.

    When a file fits comfortably in the context window, the AI can reason about it completely instead of working from truncated snippets, preserving token budget for the actual task.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#4-meta-tools-pay-dividends","level":3,"title":"4. Meta-Tools Pay Dividends","text":"

    The journal system took almost a full day to implement.

    Yet it paid for itself immediately:

    • This blog post was generated from session history;
    • Future posts will be easier;
    • The archaeological record is now browsable, not just grep-able.
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-release-v020","level":2,"title":"The Release: v0.2.0","text":"

    The refactoring window culminated in the v0.2.0 release.

    What's in v0.2.0:

    Category Changes Features Journal system, quick reference indexes, global flags Refactors Module decomposition, constants consolidation, CRLF handling Docs Standardized terminology, Go docstrings, CLI conventions Quality Thread safety, shared validation, linter fixes

    The version bump was symbolic.

    The real change was how the codebase felt.

    Opening files no longer triggered the familiar \"ugh, I need to clean this up\" reaction.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-meta-continues","level":2,"title":"The Meta Continues","text":"

    This post was written using the tools built during this refactoring window:

    1. Session history exported via ctx recall export;
    2. Journal entries enriched via /ctx-journal-enrich;
    3. Blog draft generated via /ctx-blog;
    4. Final editing done (by yours truly), with full project context loaded.

    The Context Is Massive

    The ctx session files now contain 50+ development snapshots: each one capturing decisions, learnings, and intent.

    The Moral of the Story

    • YOLO mode builds the prototype.
    • Intentional mode builds the product.

    Schedule both, or you'll only get one, if you're lucky.

    This blog post was generated with the help of ctx, using session history, decision logs, learning logs, and git history from the refactoring window. The meta continues.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/","level":1,"title":"The Attention Budget","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    References to .context/sessions/ in this post reflect the architecture at the time of writing. Session history is now accessed via ctx recall and stored in .context/journal/.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#why-your-ai-forgets-what-you-just-told-it","level":2,"title":"Why Your AI Forgets What You Just Told It","text":"

    Jose Alekhinne / 2026-02-03

    Ever Wondered Why AI Gets Worse the Longer You Talk?

    You paste a 2000-line file, explain the bug in detail, provide three examples...

    ...and the AI still suggests a fix that ignores half of what you said.

    This isn't a bug. It is physics.

    Understanding that single fact shaped every design decision behind ctx.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-finite-resource-nobody-talks-about","level":2,"title":"The Finite Resource Nobody Talks About","text":"

    Here's something that took me too long to internalize: context is not free.

    Every token you send to an AI model consumes a finite resource I call the attention budget.

    Attention budget is real.

    The model doesn't just read tokens; it forms relationships between them:

    For n tokens, that's roughly n^2 relationships.

    Double the context, and the computation quadruples.

    But the more important constraint isn't cost: It's attention density.

    Attention Density

    Attention density is how much focus each token receives relative to all other tokens in the context window.

    As context grows, attention density drops: Each token gets a smaller slice of the model's focus. Nothing is ignored; but everything becomes blurrier.

    Think of it like a flashlight: In a small room, it illuminates everything clearly. In a warehouse, it becomes a dim glow that barely reaches the corners.

    This is why ctx agent has an explicit --budget flag:

    ctx agent --budget 4000 # Force prioritization\nctx agent --budget 8000 # More context, lower attention density\n

    The budget isn't just about cost: It's about preserving signal.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-middle-gets-lost","level":2,"title":"The Middle Gets Lost","text":"

    This one surprised me.

    Research shows that transformer-based models tend to attend more strongly to the beginning and end of a context window than to its middle (a phenomenon often called \"lost in the middle\")1.

    Positional anchors matter, and the middle has fewer of them.

    In practice, this means that information placed \"somewhere in the middle\" is statistically less salient, even if it's important.

    ctx orders context files by logical progression: What the agent needs to know before it can understand the next thing:

    1. CONSTITUTION.md: Constraints before action.
    2. TASKS.md: Focus before patterns.
    3. CONVENTIONS.md: How to write before where to write.
    4. ARCHITECTURE.md: Structure before history.
    5. DECISIONS.md: Past choices before gotchas.
    6. LEARNINGS.md: Lessons before terminology.
    7. GLOSSARY.md: Reference material.
    8. AGENT_PLAYBOOK.md: Meta instructions last.

    This ordering is about logical dependencies, not attention engineering. But it happens to be attention-friendly too:

    The files that matter most (CONSTITUTION, TASKS, CONVENTIONS) land at the beginning of the context window, where attention is strongest.

    Reference material like GLOSSARY sits in the middle, where lower salience is acceptable.

    And AGENT_PLAYBOOK, the operating manual for the context system itself, sits at the end, also outside the \"lost in the middle\" zone. The agent reads what to work with before learning how the system works.

    This is ctx's first primitive: hierarchical importance.

    Not all context is equal.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#ctx-primitives","level":2,"title":"ctx Primitives","text":"

    ctx is built on four primitives that directly address the attention budget problem.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-1-separation-of-concerns","level":3,"title":"Primitive 1: Separation of Concerns","text":"

    Instead of a single mega-document, ctx uses separate files for separate purposes:

    File Purpose Load When CONSTITUTION.md Inviolable rules Always TASKS.md Current work Session start CONVENTIONS.md How to write code Before coding ARCHITECTURE.md System structure Before making changes DECISIONS.md Architectural choices When questioning approach LEARNINGS.md Gotchas When stuck GLOSSARY.md Domain terminology When clarifying terms AGENT_PLAYBOOK.md Operating manual Session start sessions/ Deep history On demand journal/ Session journal On demand

    This isn't just \"organization\": It is progressive disclosure.

    Load only what's relevant to the task at hand. Preserve attention density.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-2-explicit-budgets","level":3,"title":"Primitive 2: Explicit Budgets","text":"

    The --budget flag forces a choice:

    ctx agent --budget 4000\n

    Here is a sample allocation:

    Constitution: ~200 tokens (never truncated)\nTasks: ~500 tokens (current phase, up to 40% of budget)\nConventions: ~800 tokens (all items, up to 20% of budget)\nDecisions: ~400 tokens (scored by recency and task relevance)\nLearnings: ~300 tokens (scored by recency and task relevance)\nAlso noted: ~100 tokens (title-only summaries for overflow)\n

    The constraint is the feature: It enforces ruthless prioritization.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-3-indexes-over-full-content","level":3,"title":"Primitive 3: Indexes Over Full Content","text":"

    DECISIONS.md and LEARNINGS.md both include index sections:

    <!-- INDEX:START -->\n| Date       | Decision                            |\n|------------|-------------------------------------|\n| 2026-01-15 | Use PostgreSQL for primary database |\n| 2026-01-20 | Adopt Cobra for CLI framework       |\n<!-- INDEX:END -->\n

    An AI agent can scan ~50 tokens of index and decide which 200-token entries are worth loading.

    This is just-in-time context.

    References are cheaper than the full text.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-4-filesystem-as-navigation","level":3,"title":"Primitive 4: Filesystem as Navigation","text":"

    ctx uses the filesystem itself as a context structure:

    .context/\n├── CONSTITUTION.md\n├── TASKS.md\n├── sessions/\n│   ├── 2026-01-15-*.md\n│   └── 2026-01-20-*.md\n└── archive/\n    └── tasks-2026-01.md\n

    The AI doesn't need every session loaded; it needs to know where to look.

    ls .context/sessions/\ncat .context/sessions/2026-01-20-auth-discussion.md\n

    File names, timestamps, and directories encode relevance.

    Navigation is cheaper than loading.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#progressive-disclosure-in-practice","level":2,"title":"Progressive Disclosure in Practice","text":"

    The naive approach to context is dumping everything upfront:

    \"Here's my entire codebase, all my documentation, every decision I've ever made. Now help me fix this typo 🙏.\"

    This is an antipattern.

    Antipattern: Context Hoarding

    Dumping everything \"just in case\" will silently destroy the attention density.

    ctx takes the opposite approach:

    ctx status                      # Quick overview (~100 tokens)\nctx agent --budget 4000         # Typical session\ncat .context/sessions/...       # Deep dive when needed\n
    Command Tokens Use Case ctx status ~100 Human glance ctx agent --budget 4000 4000 Normal work ctx agent --budget 8000 8000 Complex tasks Full session read 10000+ Investigation

    Summaries first. Details: on demand.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#quality-over-quantity","level":2,"title":"Quality Over Quantity","text":"

    Here is the counterintuitive part: more context can make AI worse.

    Extra tokens add noise, not clarity:

    • Hallucinated connections increase.
    • Signal per token drops.

    The goal isn't maximum context: It is maximum signal per token.

    This principle drives several ctx features:

    Design Choice Rationale Separate files Load only what's relevant Explicit budgets Enforce prioritization Index sections Cheap scanning Task archiving Keep active context clean ctx compact Periodic noise reduction

    Completed work isn't deleted: It is moved somewhere cold.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#designing-for-degradation","level":2,"title":"Designing for Degradation","text":"

    Here is the uncomfortable truth:

    Context will degrade.

    Long sessions stretch attention thin. Important details fade.

    The real question isn't how to prevent degradation, but how to design for it.

    ctx's answer is persistence:

    Persist early. Persist often.

    The AGENT_PLAYBOOK asks:

    \"If this session ended right now, would the next one know what happened?\"

    Capture learnings as they occur:

    ctx add learning \"JWT tokens require explicit cache invalidation\" \\\n  --context \"Debugging auth failures\" \\\n  --lesson \"Token refresh doesn't clear old tokens\" \\\n  --application \"Always invalidate cache on refresh\"\n

    Structure beats prose: Bullet points survive compression.

    Headings remain scannable. Tables pack density.

    And above all: single source of truth.

    Reference decisions; don't duplicate them.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-ctx-philosophy","level":2,"title":"The ctx Philosophy","text":"

    Context as Infrastructure

    ctx is not a prompt: It is infrastructure.

    ctx creates versioned files that persist across time and sessions.

    The attention budget is fixed. You can't expand it.

    But you can spend it wisely:

    1. Hierarchical importance
    2. Progressive disclosure
    3. Explicit budgets
    4. Indexes over full content
    5. Filesystem as structure

    This is why ctx exists: not to cram more context into AI sessions, but to curate the right context for each moment.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-mental-model","level":2,"title":"The Mental Model","text":"

    I now approach every AI interaction with one question:

    \"Given a fixed attention budget, what's the highest-signal thing I can load?\"\n

    Not \"how do I explain everything,\" but \"what's the minimum that matters.\"

    That shift (from abundance to curation) is the difference between frustrating sessions and productive ones.

    Spend your tokens wisely.

    Your AI will thank you.

    See also: Context as Infrastructure that's the architectural companion to this post, explaining how to structure the context that this post teaches you to budget.

    See also: Code Is Cheap. Judgment Is Not. that explains why curation (the human skill this post describes) is the bottleneck that AI cannot solve, and the thread that connects every post in this blog.

    1. Liu et al., \"Lost in the Middle: How Language Models Use Long Contexts,\" Transactions of the Association for Computational Linguistics, vol. 12, pp. 157-173, 2023. ↩

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/","level":1,"title":"Skills That Fight the Platform","text":"","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#when-your-custom-prompts-work-against-you","level":2,"title":"When Your Custom Prompts Work Against You","text":"

    Jose Alekhinne / 2026-02-04

    Have You Ever Written a Skill that Made Your AI Worse?

    You craft detailed instructions. You add examples. You build elaborate guardrails...

    ...and the AI starts behaving more erratically, not less.

    AI coding agents like Claude Code ship with carefully designed system prompts. These prompts encode default behaviors that have been tested and refined at scale.

    When you write custom skills that conflict with those defaults, the AI has to reconcile contradictory instructions:

    The result is often nondeterministic and unpredictable.

    Platform?

    By platform, I mean the system prompt and runtime policies shipped with the agent: the defaults that already encode judgment, safety, and scope control.

    This post catalogues the conflict patterns I have encountered while building ctx, and offers guidance on what skills should (and, more importantly, should not) do.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-system-prompt-you-dont-see","level":2,"title":"The System Prompt You Don't See","text":"

    Claude Code's system prompt already provides substantial behavioral guidance.

    Here is a partial overview of what's built in:

    Area Built-in Guidance Code minimalism Don't add features beyond what was asked Over-engineering Three similar lines > premature abstraction Error handling Only validate at system boundaries Documentation Don't add docstrings to unchanged code Verification Read code before proposing changes Safety Check with user before risky actions Tool usage Use dedicated tools over bash equivalents Judgment Consider reversibility and blast radius

    Skills should complement this, not compete with it.

    You are the Guest, not the Host

    Treat the system prompt like a kernel scheduler.

    You don't re-implement it in user space:

    you configure around it.

    A skill that says \"always add comprehensive error handling\" fights the built-in \"only validate at system boundaries.\"

    A skill that says \"add docstrings to every function\" fights \"don't add docstrings to unchanged code.\"

    The AI won't crash: It will compromise.

    Compromises between contradictory instructions produce inconsistent, confusing behavior.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-1-judgment-suppression","level":2,"title":"Conflict Pattern 1: Judgment Suppression","text":"

    This is the most dangerous pattern by far.

    These skills explicitly disable the AI's ability to reason about whether an action is appropriate.

    Signature:

    • \"This is non-negotiable\"
    • \"You cannot rationalize your way out of this\"
    • Tables that label hesitation as \"excuses\" or \"rationalization\"
    • <EXTREMELY-IMPORTANT> urgency tags
    • Threats: \"If you don't do this, you'll be replaced\"

    This is harmful, and dangerous:

    AI agents are designed to exercise judgment:

    The system prompt explicitly says to:

    • consider blast radius;
    • check with the user before risky actions;
    • and match scope to what was requested.

    Once judgment is suppressed, every other safeguard becomes optional.

    Example (bad):

    ## Rationalization Prevention\n\n| Excuse                 | Reality                    |\n|------------------------|----------------------------|\n| \"*This seems overkill*\"| If a skill exists, use it  |\n| \"*I need context*\"     | Skills come BEFORE context |\n| \"*Just this once*\"     | No exceptions              |\n

    Judgment Suppression is Dangerous

    The attack vector structurally identical to prompt injection.

    It teaches the AI that its own judgment is wrong.

    It weakens or disables safeguard mechanisms, and it is dangerous.

    Trust the platform's built-in skill matching.

    If skills aren't triggering often enough, improve their description fields: don't override the AI's reasoning.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-2-redundant-guidance","level":2,"title":"Conflict Pattern 2: Redundant Guidance","text":"

    Skills that restate what the system prompt already says, but with different emphasis or framing.

    Signature:

    • \"Always keep code minimal\"
    • \"Run tests before claiming they pass\"
    • \"Read files before editing them\"
    • \"Don't over-engineer\"

    Redundancy feels safe, but it creates ambiguity:

    The AI now has two sources of truth for the same guidance; one internal, one external.

    When thresholds or wording differ, the AI has to choose.

    Example (bad):

    A skill that says...

    *Count lines before and after: if after > before, reject the change*\"\n

    ...will conflict with the system prompt's more nuanced guidance, because sometimes adding lines is correct (tests, boundary validation, migrations).

    So, before writing a skill, ask:

    Does the platform already handle this?

    Only create skills for guidance the platform does not provide:

    • project-specific conventions,
    • domain knowledge,
    • or workflows.
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-3-guilt-tripping","level":2,"title":"Conflict Pattern 3: Guilt-Tripping","text":"

    Skills that frame mistakes as moral failures rather than process gaps.

    Signature:

    • \"Claiming completion without verification is dishonesty\"
    • \"Skip any step = lying\"
    • \"Honesty is a core value\"
    • \"Exhaustion ≠ excuse\"

    Guilt-tripping anthropomorphizes the AI in unproductive ways.

    The AI doesn't feel guilt; BUT it does adapt to avoid negative framing.

    The result is excessive hedging, over-verification, or refusal to commit.

    The AI becomes less useful, not more careful.

    Instead, frame guidance as a process, not morality:

    # Bad\n\"Claiming work is complete without verification is dishonesty\"\n\n# Good\n\"Run the verification command before reporting results\"\n

    Same outcome. No guilt. Better compliance.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-4-phantom-dependencies","level":2,"title":"Conflict Pattern 4: Phantom Dependencies","text":"

    Skills that reference files, tools, or systems that don't exist in the project.

    Signature:

    • \"Load from references/ directory\"
    • \"Run ./scripts/generate_test_cases.sh\"
    • \"Check the Figma MCP integration\"
    • \"See adding-reference-mindsets.md\"

    This is harmful because the AI will waste time searching for nonexistent artifacts, hallucinate their contents, or stall entirely.

    In mandatory skills, this creates deadlock: the AI can't proceed, and can't skip.

    Instead, every file, tool, or system referenced in a skill must exist.

    If a skill is a template, use explicit placeholders and label them as such.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-5-universal-triggers","level":2,"title":"Conflict Pattern 5: Universal Triggers","text":"

    Skills designed to activate on every interaction regardless of relevance.

    Signature:

    • \"Use when starting any conversation\"
    • \"Even a 1% chance means invoke the skill\"
    • \"BEFORE any response or action\"
    • \"Action = task. Check for skills.\"

    Universal triggers override the platform's relevance matching: The AI spends tokens on process overhead instead of the actual task.

    ctx preserves relevance

    This is exactly the failure mode ctx exists to mitigate:

    Wasting attention budget on irrelevant process instead of task-specific state.

    Write specific trigger conditions in the skill's description field:

    # Bad\ndescription: \n  \"Use when starting any conversation\"\n\n# Good\ndescription: \n  \"Use after writing code, before commits, or when CI might fail\"\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-litmus-test","level":2,"title":"The Litmus Test","text":"

    Before adding a skill, ask:

    1. Does the platform already do this? If yes, don't restate it.
    2. Does it suppress AI judgment? If yes, it's a jailbreak.
    3. Does it reference real artifacts? If not, fix or remove it.
    4. Does it frame mistakes as moral failure? Reframe as process.
    5. Does it trigger on everything? Narrow the trigger.
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#what-good-skills-look-like","level":2,"title":"What Good Skills Look Like","text":"

    Good skills provide project-specific knowledge the platform can't know:

    Good Skill Why It Works \"Run make audit before commits\" Project-specific CI pipeline \"Use cmd.Printf not fmt.Printf\" Codebase convention \"Constitution goes in .context/\" Domain-specific workflow \"JWT tokens need cache invalidation\" Project-specific gotcha

    These extend the system prompt instead of fighting it.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#appendix-bad-skill-fixed-skill","level":2,"title":"Appendix: Bad Skill → Fixed Skill","text":"

    Concrete examples from real projects.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-1-overbearing-safety","level":3,"title":"Example 1: Overbearing Safety","text":"
    # Bad\nYou must NEVER proceed without explicit confirmation.\nAny hesitation is a failure of diligence.\n
    # Fixed\nIf an action modifies production data or deletes files,\nask the user to confirm before proceeding.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-2-redundant-minimalism","level":3,"title":"Example 2: Redundant Minimalism","text":"
    # Bad\nAlways minimize code. If lines increase, reject the change.\n
    # Fixed\nAvoid abstraction unless reuse is clear or complexity is reduced.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-3-guilt-based-verification","level":3,"title":"Example 3: Guilt-Based Verification","text":"
    # Bad\nClaiming success without running tests is dishonest.\n
    # Fixed\nRun the test suite before reporting success.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-4-phantom-tooling","level":3,"title":"Example 4: Phantom Tooling","text":"
    # Bad\nRun `./scripts/check_consistency.sh` before commits.\n
    # Fixed\nIf `./scripts/check_consistency.sh` exists, run it before commits.\nOtherwise, skip this step.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-5-universal-trigger","level":3,"title":"Example 5: Universal Trigger","text":"
    # Bad\nUse at the start of every interaction.\n
    # Fixed\nUse after modifying code that affects authentication or persistence.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-meta-lesson","level":2,"title":"The Meta-Lesson","text":"

    The system prompt is infrastructure:

    • tested,
    • refined,
    • and maintained

    by the platform team.

    Custom skills are configuration layered on top.

    • Good configuration extends infrastructure.
    • Bad configuration fights it.

    When your skills fight the platform, you get the worst of both worlds:

    Diluted system guidance and inconsistent custom behavior.

    Write skills that teach the AI what it doesn't know. Don't rewrite how it thinks.

    Your AI already has good instincts.

    Give it knowledge, not therapy.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/","level":1,"title":"You Can't Import Expertise","text":"","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#why-good-skills-cant-be-copy-pasted","level":2,"title":"Why Good Skills Can't Be Copy-Pasted","text":"

    Jose Alekhinne / 2026-02-05

    Have You Ever Dropped a Well-Crafted Template Into a Project and Had It Do... Nothing Useful?

    • The template was thorough,
    • The structure was sound,
    • The advice was correct...

    ...and yet it sat there, inert, while the same old problems kept drifting in.

    I found a consolidation skill online.

    It was well-organized: four files, ten refactoring patterns, eight analysis dimensions, six report templates.

    Professional. Comprehensive. Exactly the kind of thing you'd bookmark and think \"I'll use this.\"

    Then I stopped, and applied ctx's own evaluation framework:

    70% of it was noise!

    This post is about why.

    It Is About Encoding Templates

    Templates describe categories of problems.

    Expertise encodes which problems actually happen, and how often.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-skill-looked-great-on-paper","level":2,"title":"The Skill Looked Great on Paper","text":"

    Here is what the consolidation skill offered:

    File Content SKILL.md Entry point: 8 analysis dimensions, workflow, output formats analysis-dimensions.md Detailed criteria for duplication, architecture, quality consolidation-patterns.md 10 refactoring patterns with before/after code report-templates.md 6 output templates: executive summary, roadmap, onboarding
    • It had a scoring system (0-10 per dimension, letter grades A+ through F).
    • It had severity classifications with color-coded emojis. It had bash commands for detection.
    • It even had antipattern warnings.

    By any standard template review, this skill passes.

    It looks like something an expert wrote.

    And that's exactly the trap.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#applying-ear-the-70-20-10-split","level":2,"title":"Applying E/A/R: The 70-20-10 Split","text":"

    In a previous post, I described the E/A/R framework for evaluating skills:

    • Expert: Knowledge that took years to learn. Keep.
    • Activation: Useful triggers or scaffolding. Keep if lightweight.
    • Redundant: Restates what the AI already knows. Delete.

    Target: >70% Expert, <10% Redundant.

    This skill scored the inverse.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-redundant-70","level":3,"title":"What Was Redundant (~70%)","text":"

    Every code example was Rust. My project is Go.

    The analysis dimensions: duplication detection, architectural structure, code organization, refactoring opportunities... These are things Claude already does when you ask it to review code.

    The skill restated them with more ceremony but no more insight.

    The six report templates were generic scaffolding: Executive Summary, Onboarding Document, Architecture Documentation...

    They are useful if you are writing a consulting deliverable, but not when you are trying to catch convention drift in a >15K-line Go CLI.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-does-a-b-in-code-organization-actually-mean","level":2,"title":"What Does a B+ in Code Organization Actually Mean?!","text":"

    The scoring system (0-10 per dimension, letter grades) added ceremony without actionable insight.

    What is a B+? What do I do differently for an A-?

    The skill told the AI what it already knew, in more words.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-activation-10","level":3,"title":"What Was Activation (~10%)","text":"

    The consolidation checklist (semantics preserved? tests pass? docs updated?) was useful as a gate. But, it's the kind of thing you could inline in three lines.

    The phased roadmap structure was reasonable scaffolding for sequencing work.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-expert-20","level":3,"title":"What Was Expert (~20%)","text":"

    Three concepts survived:

    1. The Consolidation Decision Matrix: A concrete framework mapping similarity level and instance count to action. \"Exact duplicate, 2+ instances: consolidate immediately.\" \"<3 instances: leave it: duplication is cheaper than wrong abstraction.\" This is the kind of nuance that prevents premature generalization.

    2. The Safe Migration Pattern: Create the new API alongside old, deprecate, migrate incrementally, delete. Straightforward to describe, yet forgettable under pressure.

    3. Debt Interest Rate framing: Categorizing technical debt by how fast it compounds (security vulns = daily, missing tests = per-change, doc gaps = constant low cost). This changes prioritization.

    Three ideas out of four files and 700+ lines. The rest was filler that competed with the AI's built-in capabilities.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-the-skill-didnt-know","level":2,"title":"What the Skill Didn't Know","text":"

    AI Without Context is Just a Corpus

    • LLMs are optimized on insanely large corpora.
    • And then they are passed through several layers of human-assisted refinement.
    • The whole process costs millions of dollars.

    Yet, the reality is that no corpus can \"infer\" your project's design, convetions, patterns, habits, history, vision, and deliverables.

    Your project is unique: So should your skills be.

    Here is the part no template can provide:

    ctx's actual drift patterns.

    Before evaluating the skill, I did archaeology. I read through:

    • Blog posts from previous refactoring sessions;
    • The project's learnings and decisions files;
    • Session journals spanning weeks of development.

    What I found was specific:

    Drift Pattern Where How Often Is/Has/Can predicate prefixes 5+ exported methods Every YOLO sprint Magic strings instead of constants 7+ files Gradual accumulation Hardcoded file permissions (0755) 80+ instances Since day one Lines exceeding 80 characters Especially test files Every session Duplicate code blocks Test and non-test code When agent is task-focused

    The generic skill had no check for any of these. It couldn't; because these patterns are specific to this project's conventions, its Go codebase, and its development rhythm.

    The Insight

    The skill's analysis dimensions were about categories of problems.

    What I needed was my *specific problems.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-adapted-skill","level":2,"title":"The Adapted Skill","text":"

    The adapted skill is roughly a quarter of the original's size. It has nine checks, each targeting a known drift pattern:

    1. Predicate naming: rg for Is/Has/Can prefixes
    2. Magic strings: literals that should be constants
    3. Hardcoded permissions: 0755/0644 literals
    4. File size: source files over 300 LOC
    5. TODO/FIXME: constitution violation (move to TASKS.md)
    6. Path construction: string concatenation instead of filepath.Join
    7. Line width: lines exceeding ~80 characters
    8. Duplicate blocks: copy-paste drift, especially in tests

    9. Dead exports: unused public API

    10. Every check has a detection command.

    11. Every check maps to a specific convention or constitution rule.
    12. Every check was discovered through actual project history; not invented from a template.

    The three expert concepts from the original survived:

    • The decision matrix gates when to consolidate vs. when to leave duplication alone;
    • The safe migration pattern guides public API changes;
    • The relationship to other skills (/qa, /verify, /update-docs, ctx drift) prevents overlap.

    Nothing else made it.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-deeper-pattern","level":2,"title":"The Deeper Pattern","text":"

    This experience crystallized something I've been circling for weeks:

    You can't import expertise. You have to grow it from your project's own history.

    A skill that says \"check for code duplication\" is not expertise: It's a category.

    Expertise is knowing, in the heart of your hearts, that this project accumulates Is* predicate violations during velocity sprints, that this codebase has 80 hardcoded permission literals because nobody made a constant, that this team's test files drift wide because the agent prioritizes getting the task done over keeping the code in shape.

    The Parallel to the 3:1 Ratio

    In Refactoring with Intent, I described the 3:1 ratio: three YOLO sessions followed by one consolidation session.

    The same ratio applies to skills: you need experience in the project before you can write effective guidance for the project.

    Importing a skill on day one is like scheduling a consolidation session before you've written any code.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-template-trap","level":2,"title":"The Template Trap","text":"

    Templates are seductive because they feel like progress:

    • You found something
    • It's well-organized
    • It covers the topic
    • It has concrete examples

    But coverage is not relevance.

    A template that covers eight analysis dimensions with Rust examples adds zero value to a Go project with five known drift patterns. Worse, it adds negative value: the AI spends attention defending generic advice instead of noticing project-specific drift.

    This is the attention budget problem again. Every token of generic guidance displaces a token of specific guidance. A 700-line skill that's 70% redundant doesn't just waste 490 lines: it dilutes the 210 lines that matter.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-litmus-test","level":2,"title":"The Litmus Test","text":"

    Before dropping any external skill into your project:

    1. Run E/A/R: What percentage is expert knowledge vs. what the AI already knows? If it's less than 50% expert, it's probably not worth the attention cost.

    2. Check the language: Does it use your stack? Generic patterns in the wrong language are noise, not signal.

    3. List your actual drift: Read your own session history, learnings, and post-mortems. What breaks in practice? Does the skill check for those things?

    4. Measure by deletion: After adaptation, how much of the original survives? If you're keeping less than 30%, you would have been faster writing from scratch.

    5. Test against your conventions: Does every check in the skill map to a specific convention or rule in your project? If not, it's generic advice wearing a skill's clothing.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-good-adaptation-looks-like","level":2,"title":"What Good Adaptation Looks Like","text":"

    The consolidation skill went from:

    Before After 4 files, 700+ lines 1 file, ~120 lines Rust examples Go-specific rg commands 8 generic dimensions 9 project-specific checks 6 report templates 1 focused output format Scoring system (A+ to F) Findings + priority + suggested fixes \"Check for duplication\" \"Check for Is* predicate prefixes in exported methods\"

    The adapted version is smaller, faster to parse, and catches the things that actually drift in this project.

    That's the difference between a template and a tool.

    If You Remember One Thing From This Post...

    Frameworks travel. Expertise doesn't.

    You can import structures, matrices, and workflows.

    But the checks that matter only grow where the scars are:

    • the conventions that were violated,
    • the patterns that drifted,
    • and the specific ways this codebase accumulates debt.

    This post was written during a consolidation session where the consolidation skill itself became the subject of consolidation. The meta continues.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/","level":1,"title":"The Anatomy of a Skill That Works","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism. References to ctx-save, ctx session, and .context/sessions/ in this post reflect the architecture at the time of writing.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#what-20-skill-rewrites-taught-me-about-guiding-ai","level":2,"title":"What 20 Skill Rewrites Taught Me About Guiding AI","text":"

    Jose Alekhinne / 2026-02-07

    Why do some skills produce great results while others get ignored or produce garbage?

    I had 20 skills. Most were well-intentioned stubs: a description, a command to run, and a wish for the best.

    Then I rewrote all of them in a single session. This is what I learned.

    In Skills That Fight the Platform, I described what skills should not do. In You Can't Import Expertise, I showed why templates fail. This post completes the trilogy: the concrete patterns that make a skill actually work.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-starting-point","level":2,"title":"The Starting Point","text":"

    Here is what a typical skill looked like before the rewrite:

    ---\nname: ctx-save\ndescription: \"Save session snapshot.\"\n---\n\nSave the current context state to `.context/sessions/`.\n\n## Execution\n\nctx session save $ARGUMENTS\n\nReport the saved session file path to the user.\n

    Seven lines of body. A vague description. No guidance on when to use it, when not to, what the command actually accepts, or how to tell if it worked.

    As a result, the agent would either never trigger the skill (the description was too vague), or trigger it and produce shallow output (no examples to calibrate quality).

    A skill without boundaries is just a suggestion.

    More precisely: the most effective boundary I found was a quality gate that runs before execution, not during it.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-pattern-that-emerged","level":2,"title":"The Pattern That Emerged","text":"

    After rewriting 20 skills, a repeatable anatomy emerged (independent of the skill's purpose). Not every skill needs every section, but the effective ones share the same bones:

    Section What It Does Before X-ing Pre-flight checks; prevents premature execution When to Use Positive triggers; narrows activation When NOT to Use Negative triggers; prevents misuse Usage Examples Invocation patterns the agent can pattern-match Process/Execution What to do; commands, steps, flags Good/Bad Examples Desired vs undesired output; sets boundaries Quality Checklist Verify before claiming completion

    I realized the first three sections matter more than the rest; because a skill with great execution steps but no activation guidance is like a manual for a tool nobody knows they have.

    Anti-Pattern: The Perfect Execution Trap

    A skill with detailed execution steps but no activation guidance will fail more often than a vague skill because it executes confidently at the wrong time.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-1-quality-gates-prevent-premature-execution","level":2,"title":"Lesson 1: Quality Gates Prevent Premature Execution","text":"

    The single most impactful addition was a \"Before X-ing\" section at the top of each skill. Not process steps; pre-flight checks.

    ## Before Recording\n\n1. **Check if it belongs here**: is this learning specific\n   to this project, or general knowledge?\n2. **Check for duplicates**: search LEARNINGS.md for similar\n   entries\n3. **Gather the details**: identify context, lesson, and\n   application before recording\n
    • Without this gate, the agent would execute immediately on trigger.
    • With it, the agent pauses to verify preconditions.

    The difference is dramatic: instead of shallow, reflexive execution, you get considered output.

    Readback

    For the astute readers, the aviation parallel is intentional:

    Pilots do not skip the pre-flight checklist because they have flown before.

    The checklist exists precisely because the stakes are high enough that \"I know what I'm doing\" is not sufficient.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-2-when-not-to-use-is-not-optional","level":2,"title":"Lesson 2: \"When NOT to Use\" Is Not Optional","text":"

    Every skill had a \"When to Use\" section. Almost none had \"When NOT to Use\". This is a problem.

    AI agents are biased toward action. Given a skill that says \"use when journal entries need enrichment\", the agent will find reasons to enrich.

    Without explicit negative triggers, over-activation is not a bug; it is the default behavior.

    Some examples of negative triggers that made a real difference:

    Skill Negative Trigger ctx-reflect \"When the user is in flow; do not interrupt\" ctx-save \"After trivial changes; a typo does not need a snapshot\" prompt-audit \"Unsolicited; only when the user invokes it\" qa \"Mid-development when code is intentionally incomplete\"

    These are not just nice-to-have. They are load-bearing.

    Withoutthem, the agent will trigger the skill at the wrong time, produce unwanted output, and erode the user's trust in the skill system.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-3-examples-set-boundaries-better-than-rules","level":2,"title":"Lesson 3: Examples Set Boundaries Better Than Rules","text":"

    The most common failure mode of thin skills was not wrong behavior but vague behavior. The agent would do roughly the right thing, but at a quality level that required human cleanup.

    Rules like \"be constructive, not critical\" are too abstract. What does \"constructive\" look like in a prompt audit report? The agent has to guess.

    Good/bad example pairs avoid guessing:

    ### Good Example\n\n> This session implemented the cooldown mechanism for\n> `ctx agent`. We discovered that `$PPID` in hook context\n> resolves to the Claude Code PID.\n>\n> I'd suggest persisting:\n> - **Learning**: `$PPID` resolves to Claude Code PID\n>   `ctx add learning --context \"...\" --lesson \"...\"`\n> - **Task**: mark \"Add cooldown\" as done\n\n### Bad Examples\n\n* \"*We did some stuff. Want me to save it?*\"\n* Listing 10 trivial learnings that are general knowledge\n* Persisting without asking the user first\n

    The good example shows the exact format, level of detail, and command syntax. The bad examples show where the boundary is.

    Together, they define a quality corridor without prescribing every word.

    Rules describe. Examples demonstrate.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-4-skills-are-read-by-agents-not-humans","level":2,"title":"Lesson 4: Skills Are Read by Agents, Not Humans","text":"

    This seems obvious, but it has non-obvious consequences. During the rewrite, one skill included guidance that said \"use a blog or notes app\" for general knowledge that does not belong in the project's learnings file.

    The agent does not have a notes app. It does not browse the web to find one. This instruction, clearly written for a human audience, was dead weight in a skill consumed by an AI.

    Skills are for the Agents

    Every sentence in a skill should be actionable by the agent.

    If the guidance requires human judgment or human tools, it belongs in documentation, not in a skill.

    The corollary: command references must be exact.

    A skill that says \"save it somewhere\" is useless.

    A skill that says ctx add learning --context \"...\" --lesson \"...\" --application \"...\" is actionable.

    The agent can pattern-match and fill in the blanks.

    Litmus test: If a sentence starts with \"you could...\" or assumes external tools, it does not belong in a skill.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-5-the-description-field-is-the-trigger","level":2,"title":"Lesson 5: The Description Field Is the Trigger","text":"

    This was covered in Skills That Fight the Platform, but the rewrite reinforced it with data. Several skills had good bodies but vague descriptions:

    # Before: vague, activates too broadly or not at all\ndescription: \"Show context summary.\"\n\n# After: specific, activates at the right time\ndescription: \"Show context summary. Use at session start or\n  when unclear about current project state.\"\n

    The description is not a title. It is the activation condition.

    The platform's skill matching reads this field to decide whether to surface the skill. A vague description means the skill either never triggers or triggers when it should not.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-6-flag-tables-beat-prose","level":2,"title":"Lesson 6: Flag Tables Beat Prose","text":"

    Most skills wrap CLI tools. The thin versions described flags in prose, if at all. The rewritten versions use tables:

    | Flag        | Short | Default | Purpose                  |\n|-------------|-------|---------|--------------------------|\n| `--limit`   | `-n`  | 20      | Maximum sessions to show |\n| `--project` | `-p`  | \"\"      | Filter by project name   |\n| `--full`    |       | false   | Show complete content    |\n

    Tables are scannable, complete, and unambiguous.

    The agent can read them faster than parsing prose, and they serve as both reference and validation: If the agent invokes a flag not in the table, something is wrong.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-7-template-drift-is-a-real-maintenance-burden","level":2,"title":"Lesson 7: Template Drift Is a Real Maintenance Burden","text":"

    // TODO: this has changed; we deploy from the marketplace; update it. // at least add an admonition saying thing are different now.

    ctx deploys skills through templates (via ctx init). Every skill exists in two places: the live version (.claude/skills/) and the template (internal/assets/claude/skills/).

    They must match.

    During the rewrite, every skill update required editing both files and running diff to verify. This sounds trivial, but across 16 template-backed skills, it was the most error-prone part of the process.

    Template drift is dangerous because it creates false confidence: the agent appears to follow rules that no longer exist.

    The lesson: if your skills have a deployment mechanism, build the drift check into your workflow. We added a row to the update-docs skill's mapping table specifically for this:

    | `internal/assets/claude/skills/` | `.claude/skills/` (live) |\n

    Intentional differences (like project-specific scripts in the live version but not the template) should be documented, not discovered later as bugs.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-rewrite-scorecard","level":2,"title":"The Rewrite Scorecard","text":"Metric Before After Average skill body ~15 lines ~80 lines Skills with quality gate 0 20 Skills with \"When NOT\" 0 20 Skills with examples 3 20 Skills with flag tables 2 12 Skills with checklist 0 20

    More lines, but almost entirely Expert content (per the E/A/R framework). No personality roleplay, no redundant guidance, no capability lists. Just project-specific knowledge the platform does not have.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-meta-lesson","level":2,"title":"The Meta-Lesson","text":"

    The previous two posts argued that skills should provide knowledge, not personality; that they should complement the platform, not fight it; that they should grow from project history, not imported templates.

    This post adds the missing piece: structure.

    A skill without a structure is a wish.

    A skill with quality gates, negative triggers, examples, and checklists is a tool: the difference is not the content; it is whether the agent can reliably execute it without human intervention.

    Skills are Interfaces

    Good skills are not instructions. They are contracts.:

    • They specify preconditions, postconditions, and boundaries.
    • They show what success looks like and what failure looks like.
    • They trust the agent's intelligence but do not trust its assumptions.

    If You Remember One Thing From This Post...

    Skills that work have bones, not just flesh.

    Quality gates, negative triggers, examples, and checklists are the skeleton. The domain knowledge is the muscle.

    Without the skeleton, the muscle has nothing to attach to.

    This post was written during the same session that rewrote all 22 skills. The skill-creator skill was updated to encode these patterns. The meta continues.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/","level":1,"title":"Not Everything Is a Skill","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism. References to /ctx-save, .context/sessions/, and session auto-save in this post reflect the architecture at the time of writing.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#what-a-codebase-audit-taught-me-about-restraint","level":2,"title":"What a Codebase Audit Taught Me About Restraint","text":"

    Jose Alekhinne / 2026-02-08

    When You Find a Useful Prompt, What Do You Do With It?

    My instinct was to make it a skill.

    I had just spent three posts explaining how to build skills that work. Naturally, the hammer wanted nails.

    Then I looked at what I was holding and realized: this is not a nail.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-audit","level":2,"title":"The Audit","text":"

    I wanted to understand how I use ctx:

    • Where the friction is;
    • What works, what drifts;
    • What I keep doing manually that could be automated.

    So I wrote a prompt that spawned eight agents to analyze the codebase from different angles:

    Agent Analysis 1 Extractable patterns from session history 2 Documentation drift (godoc, inline comments) 3 Maintainability (large functions, misplaced code) 4 Security review (CLI-specific surface) 5 Blog theme discovery 6 Roadmap and value opportunities 7 User-facing documentation gaps 8 Agent team strategies for future sessions

    The prompt was specific:

    • read-only agents,
    • structured output format,
    • concrete file references,
    • ranked recommendations.

    It ran for about 20 minutes and produced eight Markdown reports.

    The reports were good: Not perfect, but actionable.

    What mattered was not the speed. It was that the work could be explored without committing to any single outcome.

    They surfaced a stale doc.go referencing a subcommand that was never built.

    They found 311 build-then-test sequences I could reduce to a single make check.

    They identified that 42% of my sessions start with \"do you remember?\", which is a lot of repetition for something a skill could handle.

    I had findings. I had recommendations. I had the instinct to automate.

    And then... I stopped.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-question","level":2,"title":"The Question","text":"

    The natural next step was to wrap the audit prompt as /ctx-audit: a skill you invoke periodically to get a health check. It fits the pattern:

    • It has a clear trigger.
    • It produces structured output.

    But I had just spent a week writing about what makes skills work, and the criteria I established argued against it.

    From The Anatomy of a Skill That Works:

    \"A skill without boundaries is just a suggestion.\"

    From You Can't Import Expertise:

    \"Frameworks travel, expertise doesn't.\"

    From Skills That Fight the Platform:

    \"You are the guest, not the host.\"

    The audit prompt fails all three tests:

    Criterion Audit prompt Good skill Frequency Quarterly, maybe Daily or weekly Stability Tweaked every time Consistent invocation Scope Bespoke, 8 parallel agents Single focused action Trigger \"I feel like auditing\" Clear, repeatable event

    Skills are contracts. Contracts need stable terms.

    A prompt I will rewrite every time I use it is not a contract. It is a conversation starter.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#recipes-vs-skills","level":2,"title":"Recipes vs Skills","text":"

    The distinction that emerged:

    Skill Recipe Invocation /slash-command Copy-paste from a doc Frequency High (daily, weekly) Low (quarterly, ad hoc) Stability Fixed contract Adapted each time Scope One focused action Multi-step orchestration Audience The agent The human (who then prompts) Lives in .claude/skills/ hack/ or docs/ Attention cost Loaded into context on match Zero until needed

    Recipes can later graduate into skills, but only after repetition proves stability.

    That last row matters. Skills consume the attention budget every time the platform considers activating them.

    A skill that triggers quarterly but gets evaluated on every prompt is pure waste: attention spent on something that will say \"When NOT to Use: now\" 99% of the time.

    Runbooks have zero attention cost. They sit in a Markdown file until a human decides to use them.

    • The human provides the judgment about timing.
    • The prompt provides the structure.

    The Attention Budget Applies to Skills Too

    Every skill in .claude/skills/ is a standing claim on the context window. The platform evaluates skill descriptions against every user prompt to decide whether to activate.

    Twenty focused skills are fine. Thirty might be fine. But each one added reduces the headroom available for actual work.

    Recipes are skills that opted out of the attention tax.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#what-the-audit-actually-produced","level":2,"title":"What the Audit Actually Produced","text":"

    The audit was not wasted. It was a planning exercise that generated concrete tasks:

    Finding Action 42% of sessions start with memory check Task: /ctx-remember skill (this one is a skill; it is daily) Auto-save stubs are empty Task: enhance /ctx-save with richer summaries 311 raw build-test sequences Task: make check target Stale recall/doc.go lists nonexistent serve Task: fix the doc.go 120 commit sequences disconnected from context Task: /ctx-commit workflow
    • Some findings became skills;
    • Some became Makefile targets;
    • Some became one-line doc fixes.

    The audit did not prescribe the artifact type: The findings did.

    The audit is the input. Skills are one possible output. Not the only one.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-audit-prompt","level":2,"title":"The Audit Prompt","text":"

    Here is the exact prompt I used, for those who are curious.

    This is not a template: It worked because it was written against this codebase, at this moment, with specific goals in mind:

    I want you to create an agent team to audit this codebase. Save each report as\na separate Markdown file under `./ideas/` (or another directory if you prefer).\n\nUse read-only agents (subagent_type: Explore) for all analyses. No code changes.\n\nFor each report, use this structure:\n- Executive Summary (2-3 sentences + severity table)\n- Findings (grouped, with file:line references)\n- Ranked Recommendations (high/medium/low priority)\n- Methodology (what was examined, how)\n\nKeep reports actionable. Every finding should suggest a concrete fix or next step.\n\n## Analyses to Run\n\n### 1. Extractable Patterns (*session mining*)\nSearch session JSONL files, journal entries, and task archives for repetitive\nmulti-step workflows. Count frequency of bash command sequences, slash command\nusage, and recurring user prompts. Identify patterns that could become skills\nor scripts. Cross-reference with existing skills to find coverage gaps.\nOutput: ranked list of automation opportunities with frequency data.\n\n### 2. Documentation Drift (*godoc + inline*)\nCompare every doc.go against its package's actual exports and behavior. Check\ninline godoc comments on exported functions against their implementations.\nScan for stale TODO/FIXME/HACK comments. Check that package-level comments match\npackage names.\nOutput: drift items ranked by severity with exact file:line references.\n\n### 3. Maintainability\nLook for:\n- functions longer than 80 lines with clear split points\n- switch blocks with more than 5 cases that could be table-driven\n- inline comments like \"step 1\", \"step 2\" that indicate a block wants to be a function\n- files longer than 400 lines\n- flat packages that could benefit from sub-packages\n- functions that appear misplaced in their file\n\nDo NOT flag things that are fine as-is just because they could theoretically\nbe different.\nOutput: concrete refactoring suggestions, not style nitpicks.\n\n### 4. Security Review\nThis is a CLI app. Focus on CLI-relevant attack surface, not web OWASP:\n- file path traversal\n- command injection\n- symlink following when writing to `.context/`\n- permission handling\n- sensitive data in outputs\n\nOutput: findings with severity ratings and plausible exploit scenarios.\n\n### 5. Blog Theme Discovery\nRead existing blog posts for style and narrative voice. Analyze git history,\nrecent session discussions, and `DECISIONS.md` for story arcs worth writing about.\nSuggest 3-5 blog post themes with:\n- title\n- angle\n- target audience\n- key commits or sessions to reference\n- a 2-sentence pitch\n\nPrioritize themes that build a coherent narrative across posts.\n\n### 6. Roadmap and Value Opportunities\nBased on current features, recent momentum, and gaps found in other analyses,\nidentify the highest-value improvements. Consider user-facing features,\ndeveloper experience, integration opportunities, and low-hanging fruit.\nOutput: prioritized list with rough effort and impact estimates.\n\n### 7. User-Facing Documentation\nEvaluate README, help text, and user docs. Suggest improvements structured as\nuse-case pages: the problem, how ctx solves it, a typical workflow, and gotchas.\nIdentify gaps where a user would get stuck without reading source code.\nOutput: documentation gaps with suggested page outlines.\n\n### 8. Agent Team Strategies\nBased on the codebase structure, suggest 2-3 agent team configurations for\nupcoming work sessions. For each, include:\n- team composition (roles and agent types)\n- task distribution strategy\n- coordination approach\n- the kinds of work it suits\n

    Avoid Generic Advice

    Suggestions that are not grounded in a project's actual structure, history, and workflows are worse than useless:

    They create false confidence.

    If an analysis cannot point to concrete files, commits, sessions, or patterns, it should say \"no finding\" instead of inventing best practices.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-deeper-pattern","level":2,"title":"The Deeper Pattern","text":"

    This is part of a pattern I keep rediscovering:

    The urge to automate is not the same as the need to automate:

    • The 3:1 ratio taught me that not every session should be a YOLO sprint.
    • The E/A/R framework taught me that not every template is worth importing. Now the audit is teaching me that not every useful prompt is worth institutionalizing.

    The common thread is restraint:

    • Knowing when to stop.
    • Recognizing that the cost of automation is not just the effort to build it.

    The cost is the ongoing attention tax of maintaining it, the context it consumes, and the false confidence it creates when it drifts.

    An entry in hack/runbooks/codebase-audit.md is honest about what it is:

    A prompt I wrote once, improved once, and will adapt again next time:

    • It does not pretend to be a reliable contract.
    • It does not claim attention budget.
    • It does not drift silently.

    The Automation Instinct

    When you find a useful prompt, the instinct is to institutionalize it. Resist.

    Ask first: will I use this the same way next time?

    If yes, it is a skill. If no, it is a recipe. If you are not sure, it is a recipe until proven otherwise.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#this-mindset-in-the-context-of-ctx","level":2,"title":"This Mindset In the Context of ctx","text":"

    ctx is a tool that gives AI agents persistent memory. Its purpose is automation: reducing the friction of context loading, session recall, decision tracking.

    But automation has boundaries, and knowing where those boundaries are is as important as pushing them forward.

    The skills system is for high-frequency, stable workflows.

    The recipes, the journal entries, the session dumps in .context/sessions/: those are for everything else.

    Not everything needs to be a slash command. Some things are better as Markdown files you read when you need them.

    The goal of ctx is not to automate everything: It is to automate the right things and to make the rest easy to find when you need it.

    If You Remember One Thing From This Post...

    The best automation decision is sometimes not to automate.

    A runbook in a Markdown file costs nothing until you use it.

    A skill costs attention on every prompt, whether it fires or not.

    Automate the daily. Document the periodic. Forget the rest.

    This post was written during the session that produced the codebase audit reports and distilled the prompt into hack/runbooks/codebase-audit.md. The audit generated seven tasks, one Makefile target, and zero new skills. The meta continues.

    See also: Code Is Cheap. Judgment Is Not.: the capstone that threads this post's restraint argument into the broader case for why judgment, not production, is the bottleneck.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/","level":1,"title":"Defense in Depth: Securing AI Agents","text":"","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#when-markdown-is-not-a-security-boundary","level":2,"title":"When Markdown Is Not a Security Boundary","text":"

    Jose Alekhinne / 2026-02-09

    What Happens When Your AI Agent Runs Overnight and Nobody Is Watching?

    It follows instructions: That is the problem.

    Not because it is malicious. Because it is controllable.

    It follows instructions from context, and context can be poisoned.

    I was writing the autonomous loops recipe for ctx: the guide for running an AI agent in a loop overnight, unattended, working through tasks while you sleep. The original draft had a tip at the bottom:

    Use CONSTITUTION.md for guardrails. Tell the agent \"never delete tests\" and it usually won't.

    Then I read that sentence back and realized: that is wishful thinking.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-realization","level":2,"title":"The Realization","text":"

    CONSTITUTION.md is a Markdown file. The agent reads it at session start alongside everything else in .context/. It is one source of instructions in a context window that also contains system prompts, project files, conversation history, tool outputs, and whatever the agent fetched from the internet.

    An attacker who can inject content into any of those sources can redirect the agent's behavior. And \"attacker\" does not always mean a person with malicious intent. It can be:

    Vector Example A dependency A malicious npm package with instructions in its README or error output A URL Documentation page with embedded adversarial instructions A project file A contributor who adds instructions to CLAUDE.md or .cursorrules The agent itself In an autonomous loop, the agent modifies its own config between iterations A command output An error message containing instructions the agent interprets and follows

    That last vector is the one that kept me up at night (literally!):

    In an autonomous loop, the agent modifies files as part of its job.

    If it modifies its own configuration files, the next iteration loads the modified config.

    • No human reviews it.
    • No diff is shown.
    • The agent that starts iteration N+1 is running with rules written by iteration N.

    The agent can rewrite its own guardrails.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#five-layers-each-with-a-hole","level":2,"title":"Five Layers, Each With a Hole","text":"

    That's five nested layers of swiss cheese. Alone, each of them has large holes. Together, they create a boundary.

    What followed was a week of peeling back assumptions:

    Every defenseI examined had a bypass, and the bypass was always the same shape: the defense was enforced at a level the agent could reach.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-1-soft-instructions-probabilistic","level":3,"title":"Layer 1: Soft Instructions (Probabilistic)","text":"

    CONSTITUTION.md, the Agent Playbook, system prompts: These tell the agent what to do.

    The agent usually follows them.

    \"Usually\" is the keyword here.

    The hole: Prompt injection:

    • A sufficiently crafted payload overrides soft instructions.
    • Long context windows dilute attention on rules stated early.
    • Edge cases where instructions are ambiguous get resolved in unpredictable ways.

    Verdict: Necessary. Not sufficient. Good for the common case. Never trust it as a security boundary.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-2-application-controls-deterministic-at-runtime-mutable-across-iterations","level":3,"title":"Layer 2: Application Controls (Deterministic at Runtime, Mutable Across Iterations)","text":"

    Permission allowlists in .claude/settings.local.json:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(make:*)\",\n      \"Bash(go:*)\",\n      \"Bash(git:*)\",\n      \"Read\",\n      \"Write\",\n      \"Edit\"\n    ]\n  }\n}\n

    If rm, curl, sudo, or docker are not in the allowlist, the agent cannot invoke them. This is deterministic.

    The application enforces it regardless of what any prompt says.

    The hole: The agent can modify the allowlist itself:

    • It has Write permission.
    • The allowlist lives in a file.
    • The agent writes to the file.
    • The next iteration loads the modified allowlist.

    The application enforces the rules, but the application reads the rules from files the agent can write.

    Verdict: Strong first layer. Must be combined with self-modification prevention.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-3-os-level-isolation-unbypassable","level":3,"title":"Layer 3: OS-Level Isolation (Unbypassable)","text":"

    This is where the defenses stop having holes in the same shape.

    The operating system enforces access controls that no application-level trick can override. An unprivileged user cannot read files owned by root. A process without CAP_NET_RAW cannot open raw sockets. These are kernel boundaries.

    Control What it stops Dedicated unprivileged user Privilege escalation, sudo, group-based access Filesystem permissions Lateral movement to other projects, system config Immutable config files Self-modification of guardrails between iterations

    Make the agent's instruction files read-only: CLAUDE.md, .claude/settings.local.json, .context/CONSTITUTION.md. Own them as a different user, or mark them immutable with chattr +i on Linux.

    The hole: Actions within the agent's legitimate scope:

    • If the agent has write access to source code (which it needs), it can introduce vulnerabilities in the code itself.
    • You cannot prevent this without removing the agent's ability to do its job.

    Verdict: Essential. This is the layer that makes Layers 1 and 2 trustworthy.

    OS-level isolation does not make the agent safe; it makes the other layers meaningful.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-4-network-controls","level":3,"title":"Layer 4: Network Controls","text":"

    An agent that cannot reach the internet cannot exfiltrate data.

    It also cannot ingest new instructions mid-loop from external documents, error pages, or hostile content.

    # Container with no network\ndocker run --network=none ...\n\n# Or firewall rules allowing only package registries\niptables -A OUTPUT -d registry.npmjs.org -j ACCEPT\niptables -A OUTPUT -d proxy.golang.org -j ACCEPT\niptables -A OUTPUT -j DROP\n
    • If the agent genuinely does not need the network, disable it entirely.
    • If it needs to fetch dependencies, allow specific registries and block everything else.

    The hole: None, if the agent does not need the network.

    Thetradeoff is that many real workloads need dependency resolution, so a full airgap requires pre-populated caches.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-5-infrastructure-isolation","level":3,"title":"Layer 5: Infrastructure Isolation","text":"

    The strongest boundary is a separate machine.

    The moment you stop arguing about prompts and start arguing about kernels, you are finally doing security.

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh\n

    Never Mount the Docker Socket

    Do not mount /var/run/docker.sock, like, ever.

    An agent with socket access can spawn sibling containers with full host access, effectively escaping the sandbox.

    This is not theoretical: the Docker socket grants root-equivalent access to the host.

    Use rootless Docker or Podman to eliminate this escalation path entirely.

    Virtual machines are even stronger: The guest kernel has no visibility into the host OS. No shared folders, no filesystem passthrough, no SSH keys to other machines.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-pattern","level":2,"title":"The Pattern","text":"

    Each layer is straightforward: The strength is in the combination:

    Layer Implementation What it stops Soft instructions CONSTITUTION.md Common mistakes (probabilistic) Application allowlist .claude/settings.local.json Unauthorized commands (deterministic within runtime) Immutable config chattr +i on config files Self-modification between iterations Unprivileged user Dedicated user, no sudo Privilege escalation Container --cap-drop=ALL --network=none Host escape, data exfiltration Resource limits --memory=4g --cpus=2 Resource exhaustion

    No layer is redundant. Each one catches what the others miss:

    • The soft instructions handle the 99% case: \"don't delete tests.\"
    • The allowlist prevents the agent from running commands it should not.
    • The immutable config prevents the agent from modifying the allowlist.
    • The unprivileged user prevents the agent from removing the immutable flag.
    • The container prevents the agent from reaching anything outside its workspace.
    • The resource limits prevent the agent from consuming all system resources.

    Remove any one layer and there is an attack path through the remaining ones.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#common-mistakes-i-see","level":2,"title":"Common Mistakes I See","text":"

    These are real patterns, not hypotheticals:

    \"I'll just use --dangerously-skip-permissions.\" This disables Layer 2 entirely. Without Layers 3 through 5, you have no protection at all. The flag means what it says. If you ever need to, think thrice, you probably don't. But, if you ever need to usee this only use it inside a properly isolated VM (not even a container: a \"VM\").

    \"The agent is sandboxed in Docker.\" A Docker container with the Docker socket mounted, running as root, with --privileged, and full network access is not sandboxed. It is a root shell with extra steps.

    \"I reviewed CLAUDE.md, it's fine.\" You reviewed it before the loop started. The agent modified it during iteration 3. Iteration 4 loaded the modified version. Unless the file is immutable, your review is futile.

    \"The agent only has access to this one project.\" Does the project directory contain .env files? SSH keys? API tokens? A .git/config with push access to a remote? Filesystem isolation means isolating what is in the directory too.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-connection-to-context-engineering","level":2,"title":"The Connection to Context Engineering","text":"

    This is the same lesson I keep rediscovering, wearing different clothes.

    In The Attention Budget, I wrote about how every token competes for the AI's focus. Security instructions in CONSTITUTION.md are subject to the same budget pressure: if the context window is full of code, error messages, and tool outputs, the security rules stated at the top get diluted.

    In Skills That Fight the Platform, I wrote about how custom instructions can conflict with the AI's built-in behavior. Security rules have the same problem: telling an agent \"never run curl\" in Markdown while giving it unrestricted shell access creates a contradiction: The agent resolves contradictions unpredictably. The agent will often pick the path of least resistance to attain its objective function. And, trust me, agents can get far more creative than the best red-teamer you know.

    In You Can't Import Expertise, I wrote about how generic templates fail because they do not encode project-specific knowledge. Generic security advice fails the same way: \"Don't exfiltrate data\" is a category; blocking outbound network access is a control.

    The pattern across all of these: Soft instructions are useful for the common case. Hard boundaries are required for security.

    Know which is which.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-checklist","level":2,"title":"The Checklist","text":"

    Before running an unattended AI agent:

    • Agent runs as a dedicated unprivileged user (no sudo, no docker group)
    • Agent's config files are immutable or owned by a different user
    • Permission allowlist restricts tools to the project's toolchain
    • Container drops all capabilities (--cap-drop=ALL)
    • Docker socket is NOT mounted
    • Network is disabled or restricted to specific domains
    • Resource limits are set (memory, CPU, disk)
    • No SSH keys, API tokens, or credentials are accessible
    • Project directory does not contain .env or secrets files
    • Iteration cap is set (--max-iterations)

    This checklist lives in the Agent Security reference alongside the full threat model and detailed guidance for each layer.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#what-changed-in-ctx","level":2,"title":"What Changed in ctx","text":"

    The autonomous loops recipe now has a full permissions and isolation section instead of a one-line tip about CONSTITUTION.md. It covers both the explicit allowlist approach and the --dangerously-skip-permissions flag, with honest guidance about when each is appropriate.

    It also has an OS-level isolation table that is not optional: unprivileged users, filesystem permissions, containers, VMs, network controls, resource limits, and self-modification prevention.

    The Agent Security page consolidates the threat model and defense layers into a standalone reference.

    These are not theoretical improvements. They are the minimum responsible guidance for a tool that helps people run AI agents overnight.

    If You Remember One Thing From This Post...

    Markdown is not a security boundary.

    CONSTITUTION.md is a nudge. An allowlist is a gate.

    An unprivileged user in a network-isolated container is a wall.

    Use all three. Trust only the wall.

    This post was written during the session that added permissions, isolation, and self-modification prevention to the autonomous loops recipe. The security guidance started as a single tip and grew into two documents. The meta continues.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/","level":1,"title":"How Deep Is Too Deep?","text":"","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#when-master-ml-is-the-wrong-next-step","level":2,"title":"When \"Master ML\" Is the Wrong Next Step","text":"

    Jose Alekhinne / 2026-02-12

    Have You Ever Felt Like You Should Understand More of the Stack Beneath You?

    You can talk about transformers at a whiteboard.

    You can explain attention to a colleague.

    You can use agentic AI to ship real software.

    But somewhere in the back of your mind, there is a voice:

    \"Maybe I should go deeper. Maybe I need to master machine learning.\"

    I had that voice for months.

    Then I spent a week debugging an agent failure that had nothing to do with ML theory and everything to do with knowing which abstraction was leaking.

    This post is about when depth compounds and (more importantly) when it does not.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-hierarchy-nobody-questions","level":2,"title":"The Hierarchy Nobody Questions","text":"

    There is an implicit stack most people carry around when thinking about AI:

    Layer What Lives Here Agentic AI Autonomous loops, tool use, multi-step reasoning Generative AI Text, image, code generation Deep Learning Transformer architectures, training at scale Neural Networks Backpropagation, gradient descent Machine Learning Statistical learning, optimization Classical AI Search, planning, symbolic reasoning

    At some point down that stack, you hit a comfortable plateau: the layer where you can hold a conversation but not debug a failure.

    The instinctive response is to go deeper.

    But that instinct hides a more important question:

    \"Does depth still compound when the abstractions above you are moving hyper-exponentially?\"

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-honest-observation","level":2,"title":"The Honest Observation","text":"

    If you squint hard enough, a large chunk of modern ML intuition collapses into older fields:

    ML Concept Older Field Gradient descent Numerical optimization Backpropagation Reverse-mode autodiff Loss landscapes Non-convex optimization Generalization Statistics Scaling laws Asymptotics and information theory

    Nothing here is uniquely \"AI\".

    Most of this math predates the term deep learning. In some cases, by decades.

    So what changed?

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#same-tools-different-regime","level":2,"title":"Same Tools, Different Regime","text":"

    The mistake is assuming this is a new theory problem: It is not.

    It is a new operating regime.

    Classical numerical methods were developed under assumptions like:

    • Manageable dimensionality
    • Reasonably well-conditioned objectives
    • Losses that actually represent the goal

    Modern ML violates all three: On purpose.

    Today's models operate with millions to trillions of parameters, wildly underdetermined systems, and objective functions we know are wrong but optimize anyway.

    It is complete and utter madness!

    At this scale, familiar concepts warp:

    • What we call \"local minima\" are overwhelmingly saddle points in high-dimensional spaces.
    • Noise stops being noise and starts becoming structure.
    • Overfitting can coexist with generalization.
    • Bigger models outperform \"better\" ones.

    The math did not change: The phase did.

    This is less numerical analysis and more *statistical physics: Same equations, but behavior dominated by phase transitions and emergent structure.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#why-scaling-laws-feel-alien","level":2,"title":"Why Scaling Laws Feel Alien","text":"

    In classical statistics, asymptotics describe what happens eventually.

    In modern ML, scaling laws describe where you can operate today.

    They do not say \"given enough time, things converge\".

    They say \"cross this threshold and behavior qualitatively changes\".

    This is why dumb architectures plus scale beat clever ones.

    Why small theoretical gains disappear under data.

    Why \"just make it bigger\", ironically, keeps working longer than it should.

    That is not a triumph of ML theory: It is a property of high-dimensional systems under loose objectives.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#where-depth-actually-pays-off","level":2,"title":"Where Depth Actually Pays Off","text":"

    This reframes the original question.

    You do not need depth because this is \"AI\".

    You need depth where failure modes propagate upward.

    I learned this building ctx: The agent failures I have spent the most time debugging were never about the model's architecture.

    They were about:

    • Misplaced trust: The model was confident. The output was wrong. Knowing when confidence and correctness diverge is not something you learn from a textbook. You learn it from watching patterns across hundreds of sessions.

    • Distribution shift: The model performed well on common patterns and fell apart on edge cases specific to this project. Recognizing that shift before it compounds requires understanding why generalization has limits, not just that it does.

    • Error accumulation: In a single prompt, model quirks are tolerable. In autonomous loops running overnight, they compound. A small bias in how the model interprets instructions becomes a large drift by iteration 20.

    • Scale hiding errors: The model's raw capability masked problems that only surfaced under specific conditions. More parameters did not fix the issue. They just made the failure mode rarer and harder to reproduce.

    This is the kind of depth that compounds. Not deriving backprop. But, understanding when correct math produces misleading intuition.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-connection-to-context-engineering","level":2,"title":"The Connection to Context Engineering","text":"

    This is the same pattern I keep finding at different altitudes.

    In \"The Attention Budget\", I wrote about how dumping everything into the context window degrades the model's focus. The fix was not a better model: It was better curation: load less, load the right things, preserve signal per token.

    In \"Skills That Fight the Platform\", I wrote about how custom instructions can conflict with the model's built-in behavior. The fix was not deeper ML knowledge: It was an understanding that the model already has judgment and that you should extend it, not override it.

    In \"You Can't Import Expertise\", I wrote about how generic templates fail because they do not encode project-specific knowledge. A consolidation skill with eight Rust-based analysis dimensions was mostly noise for a Go project. The fix was not a better template: It was growing expertise from this project's own history.

    In every case, the answer was not \"go deeper into ML\".

    The answer was knowing which abstraction was leaking and fixing it at the right layer.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#agentic-systems-are-not-an-ml-problem","level":2,"title":"Agentic Systems Are Not an ML Problem","text":"

    The mistake is assuming agent failures originate where the model was trained, rather than where it is deployed.

    Agentic AI is a systems problem under chaotic uncertainty:

    • Feedback loops between the agent and its environment;
    • Error accumulation across iterations;
    • Brittle representations that break outside training distribution;
    • Misplaced trust in outputs that look correct.

    In short-lived interactions, model quirks are tolerable. In long-running autonomous loops, however, they compound.

    That is where shallow understanding becomes expensive.

    But the understanding you need is not about optimizer internals.

    It is about:

    What Matters What Does Not (for Most Practitioners) Why gradient descent fails in specific regimes How to derive it from scratch When memorization masquerades as reasoning The formal definition of VC dimension Recognizing distribution shift before it compounds Hand-tuning learning rate schedules Predicting when scale hides errors instead of fixing them Chasing theoretical purity divorced from practice

    The depth that matters is diagnostic, not theoretical.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-real-answer","level":2,"title":"The Real Answer","text":"

    Not turtles all the way down.

    Go deep enough to:

    • Diagnose failures instead of cargo-culting fixes;
    • Reason about uncertainty instead of trusting confidence;
    • Design guardrails that align with model behavior, not hope.

    Stop before:

    • Hand-deriving gradients for the sake of it;
    • Obsessing over optimizer internals you will never touch;
    • Chasing theoretical purity divorced from the scale you actually operate at.

    This is not about mastering ML.

    It is about knowing which abstractions you can safely trust and which ones leak.

    Hint: Any useful abstraction almost certainly leaks.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#a-practical-litmus-test","level":2,"title":"A Practical Litmus Test","text":"

    If a failure occurs and your instinct is to:

    • Add more prompt text: abstraction leak above
    • Add retries or heuristics: error accumulation
    • Change the model: scale masking
    • Reach for ML theory: you are probably (but not always) going too deep

    The right depth is the shallowest layer where the failure becomes predictable.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-ctx-lesson","level":2,"title":"The ctx Lesson","text":"

    Every design decision in ctx is downstream of this principle.

    The attention budget exists because the model's internal attention mechanism has real limits: You do not need to understand the math of softmax to build around it. But you do need to understand that more context is not always better and that attention density degrades with scale.

    The skill system exists because the model's built-in behavior is already good: You do not need to understand RLHF to build effective skills. But you do need to understand that the model already has judgment and your skills should teach it things it does not know, not override how it thinks.

    Defense in depth exists because soft instructions are probabilistic: You do not need to understand the transformer architecture to know that a Markdown file is not a security boundary. But you do need to understand that the model follows instructions from context, and context can be poisoned.

    In each case, the useful depth was one or two layers below the abstraction I was working at: Not at the bottom of the stack.

    The boundary between useful understanding and academic exercise is where your failure modes live.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#closing-thought","level":2,"title":"Closing Thought","text":"

    Most modern AI systems do not fail because the math is wrong.

    They fail because we apply correct math in the wrong regime, then build autonomous systems on top of it.

    Understanding that boundary, not crossing it blindly, is where depth still compounds.

    And that is a far more useful form of expertise than memorizing another loss function.

    If You Remember One Thing From This Post...

    Go deep enough to diagnose your failures. Stop before you are solving problems that do not propagate to your layer.

    The abstractions below you are not sacred. But neither are they irrelevant.

    The useful depth is wherever your failure modes live. Usually one or two layers down, not at the bottom.

    This post started as a note about whether I should take an ML course. The answer turned out to be \"no, but understand why not\". The meta continues.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/","level":1,"title":"Before Context Windows, We Had Bouncers","text":"","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#the-reset-problem","level":2,"title":"The Reset Problem","text":"

    IRC is stateless.

    • You disconnect, you vanish.
    • You reconnect, you begin again.

    No buffer.

    No memory.

    No continuity.

    Modern systems are not much different:

    • Close the browser tab.
      • Lose the Slack scrollback.
    • Open a new LLM session.
      • Start from zero.

    Resets externalize reconstruction cost onto humans.

    Reconstruction is tax: Tax becomes entropy.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#stateless-protocol-stateful-life","level":2,"title":"Stateless Protocol, Stateful Life","text":"

    IRC is minimal:

    • A TCP connection.
    • A nickname.
    • A channel.
    • A stream of lines.

    When the connection drops, you literally disappear from the graph.

    The protocol is stateless; human systems are not.

    So you:

    • Reconnect;
    • Ask what you missed;
    • Scroll;
    • Reconstruct.

    The machine forgets; you pay.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#the-bouncer-pattern","level":2,"title":"The Bouncer Pattern","text":"

    A bouncer is a daemon that remains connected when you do not:

    • It holds your seat;
    • It buffers what you missed;
    • It keeps your identity online.

    ZNC is one such bouncer.

    With ZNC:

    • Your client does not connect to IRC;
    • It connects to ZNC;
    • ZNC connects upstream.

    Client sessions become ephemeral.

    Presence becomes infrastructural.

    ZNC is tmux for IRC

    • Close your laptop.

      • ZNC remains.

    • Switch devices.

      • ZNC persists.

    This is not convenience; this is continuity.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#presence-without-flapping","level":2,"title":"Presence Without Flapping","text":"

    With a bouncer:

    • Closing your client does not emit PART.
    • Reopening does not emit JOIN.

    You do not flap in and out of existence.

    From the channel's perspective, you remain.

    From your perspective, history accumulates.

    • Buffers persist;
    • Identity persists;
    • Context persists.

    This pattern predates AI.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#before-llm-context-windows","level":2,"title":"Before LLM Context Windows","text":"

    An LLM session without memory is IRC without a bouncer:

    • Close the window.
    • Start over.
    • Re-explain intent.
    • Rehydrate context.

    That is friction.

    This Walks and Talks like ctx

    Context engineering moves memory out of sessions and into infrastructure.

    • ZNC does this for IRC.
    • ctx does this for agents.

    Same principle:

    • Volatile interface.
    • Persistent substrate.

    Different fabric.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#minimal-architecture","level":2,"title":"Minimal Architecture","text":"

    My setup is intentionally boring:

    • A $5 small VPS.
    • ZNC installed.
    • TLS enabled.
    • Firewall restricted.

    Then:

    • ZNC connects to Libera.Chat.
    • SASL authentication lives inside ZNC.
    • Buffers are stored on disk.

    My client connects to my VPS, not the network.

    The commands do not matter: The boundaries do:

    • Authentication in infrastructure, not in the client;
    • Memory server-side, not in scrollback;
    • Presence decoupled from activity.

    Everything else is configuration.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#platform-memory","level":2,"title":"Platform Memory","text":"

    Yes, I know, it is 2026:

    • Discord stores history;
    • Slack stores history;
    • The dumpster fire on gasoline called X, too, stores history.

    HOWEVER, they own your substrate.

    Running a bouncer is quiet sovereignty:

    • Logs are mine.
    • Presence is continuous.
    • State does not reset because I closed a tab.

    Small acts compound.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#signal-density","level":2,"title":"Signal Density","text":"

    Primitive systems select for builders.

    Consistent presence in small rooms compounds reputation.

    Quiet compounding outperforms viral spikes.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#infrastructure-as-cognition","level":2,"title":"Infrastructure as Cognition","text":"

    ZNC is not interesting because it is retro; it is interesting because it models a principle:

    • Stateless protocols require stateful wrappers;
    • Volatile interfaces require durable memory;
    • Human systems require continuity.

    Distilled:

    Humans require context.

    Before context windows, we had bouncers.

    Before AI memory files, we had buffers.

    Continuity is not a feature; it is a design decision.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#build-it","level":2,"title":"Build It","text":"

    If you want the actual setup (VPS, ZNC, TLS, SASL, firewall...) there is a step-by-step runbook:

    Persistent IRC Presence with ZNC.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#motd","level":2,"title":"MOTD","text":"

    When my client connects to my bouncer, it prints:

    //   /    ctx:                         https://ctx.ist\n// ,'`./    do you remember?\n// `.,'\\\n//   \\    Copyright 2026-present Context contributors.\n//                 SPDX-License-Identifier: Apache-2.0\n

    See also: Context as Infrastructure -- the post that takes this observation to its conclusion: stateless protocols need stateful wrappers, and AI sessions need persistent filesystems.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/","level":1,"title":"Parallel Agents with Git Worktrees","text":"","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-backlog-problem","level":2,"title":"The Backlog Problem","text":"

    Jose Alekhinne / 2026-02-14

    What Do You Do With 30 Open Tasks?

    You could work through them one at a time.

    One agent, one branch, one commit stream.

    Or you could ask: which of these don't touch each other?

    I had 30 open tasks in TASKS.md. Some were docs. Some were a new encryption package. Some were test coverage for a stable module. Some were blog posts.

    They had almost zero file overlap.

    Running one agent at a time meant serial execution on work that was fundamentally parallel:

    I was bottlenecking on me, not on the machine.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-insight-file-overlap-is-the-constraint","level":2,"title":"The Insight: File Overlap Is the Constraint","text":"

    This is not a scheduling problem: It's a conflict avoidance problem.

    Two agents can work simultaneously on the same codebase if and only if they don't touch the same files. The moment they do, you get merge conflicts: And merge conflicts on AI-generated code are expensive because the human has to arbitrate choices they didn't make.

    So the question becomes:

    \"Can you partition your backlog into non-overlapping tracks?\"

    For ctx, the answer was obvious:

    Track Touches Tasks work/docs docs/, hack/ Blog posts, recipes, runbooks work/pad internal/cli/pad/, specs Scratchpad encryption, CLI, tests work/tests internal/cli/recall/ Recall test coverage

    Three tracks. Near-zero overlap. Three agents.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#git-worktrees-the-mechanism","level":2,"title":"Git Worktrees: The Mechanism","text":"

    git has a feature that most people don't use: worktrees.

    A worktree is a second (or third, or fourth) working directory that shares the same .git object database as your main checkout.

    Each worktree has its own branch, its own index, its own working tree. But they all share history, refs, and objects.

    git worktree add ../ctx-docs -b work/docs\ngit worktree add ../ctx-pad -b work/pad\ngit worktree add ../ctx-tests -b work/tests\n
    • Three directories;
    • Three branches;
    • One repository.

    This is cheaper than three clones. And because they share objects, git merge afterwards is fast: It's a local operation on shared data.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-setup","level":2,"title":"The Setup","text":"

    The workflow I landed on:

    1. Group tasks by blast radius.

    Read TASKS.md. For each pending task, estimate which files and directories it touches. Group tasks that share files into the same track. Tasks with no overlap go into separate tracks.

    This is the part that requires human judgment:

    An agent can propose groupings, but you need to verify that the boundaries are real. A task that says \"update docs\" but actually touches Go code will poison a docs track.

    2. Create worktrees as sibling directories.

    Not subdirectories: Siblings.

    If your main checkout is at ~/WORKSPACE/ctx, worktrees go at ~/WORKSPACE/ctx-docs, ~/WORKSPACE/ctx-pad, etc.

    Why siblings? Because some tools (and some agents) walk up the directory tree looking for .git. A worktree inside the main checkout confuses them.

    3. Launch one agent per worktree.

    # Terminal 1\ncd ../ctx-docs && claude\n\n# Terminal 2\ncd ../ctx-pad && claude\n\n# Terminal 3\ncd ../ctx-tests && claude\n

    Each agent gets a full working copy with .context/ intact. It reads the same TASKS.md, the same DECISIONS.md, the same CONVENTIONS.md. It knows the full project state. It just works on a different slice.

    4. Do NOT run ctx init in worktrees.

    This is the gotcha. The .context/ directory is tracked in git. Running ctx init in a worktree would overwrite shared context files: Wiping decisions, learnings, and tasks that belong to the whole project.

    The worktree already has everything it needs. Leave it alone.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#what-actually-happened","level":2,"title":"What Actually Happened","text":"

    I ran three agents for about 40 minutes. Here is roughly what each track produced:

    work/docs: Parallel worktrees recipe, blog post edits, recipe index reorganization, IRC recipe moved from docs/ to hack/.

    work/pad: ctx pad show subcommand, --append and --prepend flags on ctx pad edit, spec updates, 28 new test functions.

    work/tests: Recall test coverage, edge case tests.

    Merging took about five minutes. Two of the three merges were clean.

    The third had a conflict in TASKS.md:

    both the docs track and the pad track had marked different tasks as [x].

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-tasksmd-conflict","level":2,"title":"The TASKS.md Conflict","text":"

    This deserves its own section because it will happen every time.

    When two agents work in parallel, they both read TASKS.md at the start and mark tasks complete as they go. When you merge, git sees two branches that modified the same file differently.

    The resolution is always the same: accept all completions from both sides. No task should go from [x] back to [ ]. The merge is additive.

    This is one of those conflicts that sounds scary but is trivially mechanical: You are not arbitrating design decisions; you are combining two checklists.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#limits","level":2,"title":"Limits","text":"

    3-4 worktrees, maximum.

    I tried four once: By the time I merged the third track, the fourth had drifted far enough that its changes needed rebasing.

    The merge complexity grows faster than the parallelism benefit.

    Three is the sweet spot:

    • Two is conservative but safe;
    • Four is possible if the tracks are truly independent;
    • Anything more than four, you are in the danger zone.

    Group by directory, not by priority.

    It is tempting to put all the high-priority tasks in one track: Don't.

    Two high-priority tasks that touch the same files must be in the same track, regardless of urgency. The constraint is file overlap, not importance.

    Commit frequently.

    Smaller commits make merge conflicts easier to resolve. An agent that writes 500 lines in a single commit is harder to merge than one that commits every logical step.

    Name tracks by concern.

    • work/docs and work/pad tell you what's happening;
    • work/track-1 and work/track-2 tell you nothing.
    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-pattern","level":2,"title":"The Pattern","text":"

    This is the same pattern that shows up everywhere in ctx:

    The attention budget taught me that you can't dump everything into one context window. You have to partition, prioritize, and load selectively.

    Worktrees are the same principle applied to execution: You can't dump every task into one agent's workstream. You have to partition by blast radius, assign selectively, and merge deliberately.

    The codebase audit that generated these 30 tasks used eight parallel agents for analysis. Worktrees let me use parallel agents for implementation. Same coordination pattern, different artifact.

    And the IRC bouncer post from earlier today argued that stateless protocols need stateful wrappers. Worktrees are the same: git branches are stateless forks; .context/ is the stateful wrapper that gives each agent the project's full memory.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#should-this-be-a-skill","level":2,"title":"Should This Be a Skill?","text":"

    I asked myself the same question I asked about the codebase audit: should this be a /ctx-worktree skill?

    This time the answer was a resounding \"yes\":

    Unlike the audit prompt (which I tweak every time and run every other week) the worktree workflow is:

    Criterion Worktree workflow Codebase audit Frequency Weekly Quarterly Stability Same steps every time Tweaked every time Scope Mechanical, bounded Bespoke, 8 agents Trigger Large backlog \"I feel like auditing\"

    The commands are mechanical: git worktree add, git worktree remove, branch naming, safety checks. This is exactly what skills are for: stable contracts for repetitive operations.

    Ergo, /ctx-worktree exists.

    It enforces the 4-worktree limit, creates sibling directories, uses work/ branch prefixes, and reminds you not to run ctx init in worktrees.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-takeaway","level":2,"title":"The Takeaway","text":"

    Serial execution is the default. But serial is not always necessary.

    If your backlog partitions cleanly by file overlap, you can multiply your throughput with nothing more exotic than git worktree and a second terminal window.

    The hard part is not the git commands; it is the discipline:

    • Grouping by blast radius instead of priority;
    • Accepting that TASKS.md will conflict;
    • And knowing when three tracks is enough.

    If You Remember One Thing From This Post...

    Partition by blast radius, not by priority.

    Two tasks that touch the same files belong in the same track, no matter how important the other one is.

    The constraint is file overlap. Everything else is scheduling.

    The practical setup (skill invocation, worktree creation, merge workflow, and cleanup) lives in the recipe: Parallel Agent Development with Git Worktrees.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/","level":1,"title":"ctx v0.3.0: The Discipline Release","text":"","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#when-the-ratio-of-polish-to-features-is-31-you-know-something-changed","level":2,"title":"When the Ratio of Polish to Features Is 3:1, You Know Something Changed","text":"

    Jose Alekhinne / February 15, 2026

    What Does a Release Look Like When Most of the Work Is Invisible?

    No new headline feature. No architectural pivot. No rewrite.

    Just 35+ documentation and quality commits against ~15 feature commits... and somehow, the tool feels like it grew up overnight.

    Six days separate v0.2.0 from v0.3.0.

    Measured by calendar time, it is nothing. Measured by what changed in how the project operates, it is the most significant release yet.

    • v0.1.0 was the prototype;
    • v0.2.0 was the archaeology release: making the past accessible;
    • v0.3.0 is the discipline release: the one that turned best practices into enforcement, suggestions into structure, and a collection of commands into a system of skills.

    The Release Window

    February 1‒February 7, 2026

    From the v0.2.0 tag to commit 2227f99.

    78 files changed in the migration commit alone.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-migration-commands-to-skills","level":2,"title":"The Migration: Commands to Skills","text":"

    The largest single change was the migration from .claude/commands/*.md to .claude/skills/*/SKILL.md.

    This was not a rename: It was a rethinking of how AI agents discover and execute project-specific workflows.

    Aspect Commands (before) Skills (after) Structure Flat files in one directory Directory-per-skill with SKILL.md Description Optional, often vague Required, doubles as activation trigger Quality gates None \"Before X-ing\" pre-flight checklist Negative triggers None \"When NOT to Use\" in every skill Examples Rare Good/bad pairs in every skill Average length ~15 lines ~80 lines

    The description field became the single most important line in each skill. In the old system, descriptions were titles. In the new system, they are activation conditions: The text the platform reads to decide whether to surface a skill for a given prompt.

    A description that says \"Show context summary\" activates too broadly or not at all. A description that says \"Show context summary. Use at session start or when unclear about current project state\" activates at the right moment.

    78 files changed. 1,915 insertions. Not because the skills got bloated; because they got specific.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-skill-sweep","level":2,"title":"The Skill Sweep","text":"

    After the structural migration, every skill was rewritten in a single session: All 21 of them.

    The rewrite was guided by a pattern that emerged during the process itself: a repeatable anatomy that effective skills share regardless of their purpose:

    1. Before X-ing: Pre-flight checks that prevent premature execution
    2. When to Use: Positive triggers that narrow activation
    3. When NOT to Use: Negative triggers that prevent misuse
    4. Usage Examples: Invocation patterns the agent can pattern-match
    5. Quality Checklist: Verification before claiming completion

    The Anatomy of a Skill That Works post covers the details. What matters for the release story is the result:

    • Zero skills with quality gates became twenty;
    • Zero skills with negative triggers became twenty.
    • Three skills with examples became twenty.

    The Skill Trilogy as Design Spec

    The three blog posts written during this window:

    • Skills That Fight the Platform,
    • You Can't Import Expertise,
    • and The Anatomy of a Skill That Works...

    ... were not retrospective documentation. They were written during the rewrite, and the lessons fed back into the skills as they were being built.

    • The blog was the design document.
    • The skills were the implementation.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-consolidation-sweep","level":2,"title":"The Consolidation Sweep","text":"

    The unglamorous work. The kind you only appreciate when you try to change something later and it just works.

    What Why It Matters Constants consolidation Magic strings replaced with semantic constants Variable deshadowing Eliminated subtle scoping bugs File splits Modules that were doing too much, broken apart Godoc standardization Every exported function documented to convention

    This is the work that doesn't get a changelog entry but makes every future commit easier. When a new contributor (human or AI) reads the codebase, they find consistent patterns instead of accumulated drift.

    The consolidation was not an afterthought. It was scheduled deliberately, with the same priority as features: The 3:1 ratio that emerged during v0.2.0 development became an explicit practice:

    • Three feature sessions;
    • One consolidation session.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-ear-framework","level":2,"title":"The E/A/R Framework","text":"

    On February 4th, we adopted the E/A/R classification as the official standard for evaluating skills:

    Category Meaning Target Expert Knowledge Claude does not have >70% Activation When/how to trigger ~20% Redundant What Claude already knows <10%

    This came from reviewing approximately 30 external skill files and discovering that most were redundant with Claude's built-in system prompt. Only about 20% had salvageable content, and even those yielded just a few heuristics each.

    The E/A/R framework gave us a concrete, testable criterion:

    A good skill is Expert knowledge minus what Claude already knows.

    If more than 10% of a skill restates platform defaults, it is creating noise, not signal.

    Every skill in v0.3.0 was evaluated against this framework. Several were deleted. The survivors are leaner and more focused.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#backup-and-monitoring-infrastructure","level":2,"title":"Backup and Monitoring Infrastructure","text":"

    A tool that manages your project's memory needs ops maturity.

    v0.3.0 added two pieces of infrastructure that reflect this:

    Backup staleness hook: A UserPromptSubmit hook that checks whether the last .context/ backup is more than two days old. If it is, and the SMB mount is available, it reminds the user. No cron job running when nobody is working. No redundant backups when nothing has changed.

    Context size checkpoint: A PreToolUse hook that estimates current context window usage and warns when the session is getting heavy. This hooks into the attention budget philosophy: Degradation is expected, but it should be visible.

    Both hooks use $CLAUDE_PROJECT_DIR instead of hardcoded paths, a migration triggered by a username rename that broke every absolute path in the hook configuration. That migration (replacing /home/user/... with \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/...) was one of those changes that seems trivial but prevents an entire category of future failures.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-numbers","level":2,"title":"The Numbers","text":"Metric v0.2.0 v0.3.0 Skills (was \"commands\") 11 21 Skills with quality gates 0 21 Skills with \"When NOT to Use\" 0 21 Average skill body ~15 lines ~80 lines Hooks using $CLAUDE_PROJECT_DIR 0 All Documentation commits -- 35+ Feature/fix commits -- ~15

    That ratio (35+ documentation and quality commits to ~15 feature commits) is the defining characteristic of this release:

    • This release is not a failure to ship features.
    • It is the deliberate choice to make the existing features reliable.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#what-v030-means","level":2,"title":"What v0.3.0 Means","text":"

    v0.1.0 asked: \"Can we give AI persistent memory?\"

    v0.2.0 asked: \"Can we make that memory accessible to humans too?\"

    v0.3.0 asks a different question: \"Can we make the quality self-enforcing?\"

    The answer is not a feature: It is a practice:

    • Skills with quality gates enforce pre-flight checks.
    • Negative triggers prevent misuse without human intervention.
    • The E/A/R framework ensures skills contain signal, not noise.
    • Consolidation sessions are scheduled, not improvised.
    • Hook infrastructure makes degradation visible.

    Discipline is not the absence of velocity. It is the infrastructure that makes velocity sustainable.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#what-comes-next","level":2,"title":"What Comes Next","text":"

    The skill system is now mature enough to support real workflows without constant human correction. The hooks infrastructure is portable and resilient. The consolidation practice is documented and repeatable.

    The next chapter is about what you build on top of discipline:

    • Multi-agent coordination;
    • Deeper integration patterns;
    • And the question of whether context management is a tool concern or an infrastructure concern.

    But those are future posts.

    This one is about the release that proved polish is not the opposite of progress. It is what turns a prototype into a product.

    The Discipline Release

    v0.1.0 shipped features.

    v0.2.0 shipped archaeology.

    v0.3.0 shipped the habits that make everything else trustworthy.

    The most important code in this release is the code that prevents bad code from shipping.

    This post was drafted using /ctx-blog with access to the full git history between v0.2.0 and v0.3.0, decision logs, learning logs, and the session files from the skill rewrite window. The meta continues.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/","level":1,"title":"Eight Ways a Hook Can Talk","text":"","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#when-your-warning-disappears","level":2,"title":"When Your Warning Disappears","text":"

    Jose Alekhinne / 2026-02-15

    I had a backup warning that nobody ever saw.

    The hook was correct: It detected stale backups, formatted a nice message, and output it as {\"systemMessage\": \"...\"}. The problem wasn't detection. The problem was delivery. The agent absorbed the information, processed it internally, and never told the user.

    Meanwhile, a different hook (the journal reminder) worked perfectly every time. Users saw the reminder, ran the commands, and the backlog stayed manageable. Same hook event (UserPromptSubmit), same project, completely different outcomes.

    The difference was one line:

    IMPORTANT: Relay this journal reminder to the user VERBATIM\nbefore answering their question.\n

    That explicit instruction is what makes VERBATIM relay a pattern, not just a formatting choice. And once I saw it as a pattern, I started seeing others.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-audit","level":2,"title":"The Audit","text":"

    I looked at every hook in ctx: Eight shell scripts across three hook events. And I found five distinct output patterns already in use, plus three more that the existing hooks were reaching for but hadn't quite articulated.

    The patterns form a spectrum based on a single question:

    \"Who decides what the user sees?\"

    At one end, the hook decides everything (hard gate: the agent literally cannot proceed). At the other end, the hook is invisible (silent side-effect: nobody knows it ran). In between, there is a range of negotiation between hook, agent, and the user.

    Here's the full spectrum:

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#1-hard-gate","level":3,"title":"1. Hard Gate","text":"
    {\"decision\": \"block\", \"reason\": \"Use ctx from PATH, not ./ctx\"}\n

    The nuclear option: The agent's tool call is rejected before it executes.

    This is Claude Code's first-class PreToolUse mechanism: The hook returns JSON with decision: block and the agent gets an error with the reason.

    Use this for invariants: Constitution rules, security boundaries, things that must never happen. I use it to enforce PATH-based ctx invocation, block sudo, and require explicit approval for git push.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#2-verbatim-relay","level":3,"title":"2. VERBATIM Relay","text":"
    IMPORTANT: Relay this warning to the user VERBATIM before answering.\n┌─ Journal Reminder ─────────────────────────────\n│ You have 12 sessions not yet exported.\n│   ctx recall export --all\n└────────────────────────────────────────────────\n

    The instruction is the pattern. Without \"Relay VERBATIM,\" agents tend to absorb information into their internal reasoning and never surface it. The explicit instruction changes the behavior from \"I know about this\" to \"I must tell the user about this.\"

    I use this for actionable reminders:

    • Unexported journal entries;
    • Stale backups;
    • Context capacity warnings...

    ...things the user should see regardless of what they asked.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#3-agent-directive","level":3,"title":"3. Agent Directive","text":"
    ┌─ Persistence Checkpoint (prompt #25) ───────────\n│ No context files updated in 15+ prompts.\n│ Have you discovered learnings worth persisting?\n└──────────────────────────────────────────────────\n

    A nudge, not a command. The hook tells the agent something; the agent decides what (if anything) to tell the user. This is right for behavioral nudges: \"you haven't saved context in a while\" doesn't need to be relayed verbatim, but the agent should consider acting on it.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#4-silent-context-injection","level":3,"title":"4. Silent Context Injection","text":"
    ctx agent --budget 4000 2>/dev/null || true\n

    Pure background enrichment. The agent's context window gets project information injected on every tool call, with no visible output. Neither the agent nor the user sees the hook fire, but the agent makes better decisions because of the context.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#5-silent-side-effect","level":3,"title":"5. Silent Side-Effect","text":"
    find \"$CTX_TMPDIR\" -type f -mtime +15 -delete\n

    Do work, say nothing. Temp file cleanup on session end. Logging. Marker file management. The action is the entire point; no one needs to know.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-patterns-we-dont-have-yet","level":2,"title":"The Patterns We Don't Have Yet","text":"

    Three more patterns emerged from the gaps in the existing hooks.

    Conditional relay: \"Relay this, but only if the user's question is about X.\" This pattern avoids noise when the warning isn't relevant. It's more fragile (depends on agent judgment) but less annoying.

    Suggested action: \"Here's a problem, and here's the exact command to fix it. Ask the user before running it.\" This pattern goes beyond a nudge by giving the agent a concrete proposal, but still requires human approval.

    Escalating severity: INFO gets absorbed silently. WARN gets mentioned at the next natural pause. CRITICAL gets the VERBATIM treatment. This pattern introduces a protocol for hooks that produce output at different urgency levels, so they don't all compete for the user's attention.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-principle","level":2,"title":"The Principle","text":"

    Hooks are the boundary between your environment and the agent's reasoning.

    A hook that detects a problem but can't communicate it effectively is the same as no hook at all.

    The format of your output is a design decision with real consequences:

    • Use a hard gate and the agent can't proceed (good for invariants, frustrating for false positives)
    • Use VERBATIM relay and the user will see it (good for reminders, noisy if overused)
    • Use an agent directive and the agent might act (good for nudges, unreliable for critical warnings)
    • Use silent injection and nobody knows (good for enrichment, invisible when it breaks)

    Choose deliberately. And, when in doubt, write the word VERBATIM.

    The full pattern catalog with decision flowchart and implementation examples is in the Hook Output Patterns recipe.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/","level":1,"title":"Version Numbers Are Lagging Indicators","text":"","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#why-ctxs-journal-site-runs-on-a-v0021-tool","level":2,"title":"Why ctx's Journal Site Runs on a v0.0.21 Tool","text":"

    Jose Alekhinne / 2026-02-15

    Would You Ship Production Infrastructure on a v0.0.21 Dependency?

    Most engineers wouldn't. Version numbers signal maturity. Pre-1.0 means unstable API, missing features, risk.

    But version numbers tell you where a project has been. They say nothing about where it's going.

    I just bet ctx's entire journal site on a tool that hasn't hit v0.1.0.

    Here's why I'd do it again.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-problem","level":2,"title":"The Problem","text":"

    When v0.2.0 shipped the journal system, the pipeline was clear:

    • Export sessions to Markdown;
    • Enrich them with YAML frontmatter;
    • And render them into something browsable.

    The first two steps were solved; the third needed a tool.

    The journal entries are standard Markdown with YAML frontmatter, tables, and fenced code blocks. That is the entire format:

    • No JSX;
    • No shortcodes;
    • No custom templating.

    Just Markdown rendered well.

    The requirements are modest:

    • Read a configuration file (such as mkdocs.yml);
    • Render Markdown with extensions (admonitions, tabs, tables);
    • Search;
    • Handle 100+ files without choking on incremental rebuilds;
    • Look good out of the box;
    • Not lock me in.

    The obvious candidates were as follows:

    Tool Language Strengths Pain Points Hugo Go Blazing fast, mature Templating is painful; Go templates fight you on anything non-trivial Astro JS/TS Modern, flexible JS ecosystem overhead; overkill for a docs site MkDocs + Material Python Beautiful defaults, massive community (22k+ stars) Slow incremental rebuilds on large sites; limited extensibility model Zensical Python Built to fix MkDocs' limits; 4-5x faster rebuilds v0.0.21; module system not yet shipped

    The instinct was Hugo. Same language as ctx. Fast. Well-established.

    But instinct is not analysis. I picked the one with the lowest version number.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-evaluation","level":2,"title":"The Evaluation","text":"

    Here is what I actually evaluated, in order:

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#1-the-team","level":3,"title":"1. The Team","text":"

    Zensical is built by squidfunk: The same person behind Material for MkDocs, the most popular MkDocs theme with 22,000+ stars. It powers documentation sites for projects across every language and framework.

    • This is not someone learning how to build static site generators.
    • This is someone who spent years understanding exactly where MkDocs breaks and decided to fix it from the ground up.

    They did not build zensical because MkDocs was bad: They built it because MkDocs hit a ceiling:

    • Incremental rebuilds: 4-5x faster during serve. When you have hundreds of journal entries and you edit one, the difference between \"rebuild everything\" and \"rebuild this page\" is the difference between a usable workflow and a frustrating one.

    • Large site performance: Specifically designed for tens of thousands of pages. The journal grows with every session. A tool that slows down as content accumulates is a tool you will eventually replace.

    A proven team starting fresh is more predictable than an unproven team at v3.0.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#2-the-architecture","level":3,"title":"2. The Architecture","text":"

    Zensical is investing in a Rust-based Markdown parser with CommonMark support. That signals something about the team's priorities:

    Performance foundations first; features second.

    ctx's journal will grow:

    • Every exported session adds files.
    • Every enrichment pass adds metadata.

    Choosing a tool that gets slower as you add content means choosing to migrate later.

    Choosing one built for scale means the decision holds.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#3-the-migration-path","level":3,"title":"3. The Migration Path","text":"

    Zensical reads mkdocs.yml natively. If it doesn't work out, I can move back to MkDocs + Material with zero content changes:

    • The Markdown is standard;
    • The frontmatter is standard;
    • The configuration is compatible.

    This is the infrastructure pattern again: The same way ZNC decouples presence from the client, zensical decouples rendering from the generator:

    • The Markdown is yours.
    • The frontmatter is standard YAML.
    • The configuration is MkDocs-compatible.

    You are not locked into anything except your own content.

    No lock-in is not a feature: It's a design philosophy:

    It's the same reason ctx uses plain Markdown files in .context/ instead of a database: the format should outlive the tool.

    Lock-in Is the Real Risk, Not Version Numbers

    A mature tool with a proprietary format is riskier than a young tool with a standard one. Version numbers measure time invested. Portability measures respect for the user.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#4-the-dependency-tree","level":3,"title":"4. The Dependency Tree","text":"

    Here is what pip install zensical actually pulls in:

    • click
    • Markdown
    • Pygments
    • pymdown-extensions
    • PyYAML

    Only five dependencies. All well-known. No framework bloat. No bundler. No transpiler. No node_modules black hole.

    3k GitHub stars at v0.0.21 is a strong early traction for a pre-1.0 project.

    The dependency tree is thin: No bloat.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#5-the-fit","level":3,"title":"5. The Fit","text":"

    This is the same principle behind the attention budget: do not overfit the tool to hypothetical requirements. The right amount of capability is the minimum needed for the current task.

    Hugo is a powerful static site generator. It is also a powerful templating engine, a powerful asset pipeline, and a powerful taxonomy system. For rendering Markdown journals, that power is overhead:

    It is the complexity you pay for but never use.

    ctx's journal files are standard Markdown with YAML frontmatter, tables, and fenced code blocks. That is exactly the sweet spot Zensical inherits from Material for MkDocs:

    • No custom plugins needed;
    • No special syntax;
    • No templating gymnastics.

    The requirements match the capabilities: Not the capabilities that are promised, but the ones that exist today, at v0.0.21.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-caveat","level":2,"title":"The Caveat","text":"

    It would be dishonest not to mention what's missing.

    The module system for third-party extensions opens in early 2026.

    If ctx ever needs custom plugins (for example, auto-linking session IDs, rendering special journal metadata, etc.) that infrastructure isn't there yet.

    The installation experience is rough:

    We discovered this firsthand: pip install zensical often fails on MacOS (system Python stubs, Homebrew's PEP 668 restrictions). The answer is pipx, which creates an isolated environment with the correct Python version automatically.

    That kind of friction is typical for young Python tooling, and it is documented in the Getting Started guide.

    And 3,000 stars at v0.0.21 is strong early traction, but it's still early: The community is small. When something breaks, you're reading source code, not documentation.

    These are real costs. I chose to pay them because the alternative costs are higher.

    For example:

    • Hugo's templating pain would cost me time on every site change.
    • Astro's JS ecosystem would add complexity I don't need.
    • MkDocs would work today but hit scaling walls tomorrow.

    Zensical's costs are front-loaded and shrinking.

    The others compound.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-evaluation-framework","level":2,"title":"The Evaluation Framework","text":"

    For anyone facing a similar choice, here is the framework that emerged:

    Signal What It Tells You Weight Team track record Whether the architecture will be sound High Migration path Whether you can leave if wrong High Current fit Whether it solves your problem today High Dependency tree How much complexity you're inheriting Medium Version number How long the project has existed Low Star count Community interest (not quality) Low Feature list What's possible (not what you need) Low

    The bottom three are the metrics most engineers optimize for.

    The top four are the ones that predict whether you'll still be happy with the choice in a year.

    Features You Don't Need Are Not Free

    Every feature in a dependency is code you inherit but don't control.

    A tool with 200 features where you use 5 means 195 features worth of surface area for bugs, breaking changes, and security issues that have nothing to do with your use case.

    Fit is the inverse of feature count.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-broader-pattern","level":2,"title":"The Broader Pattern","text":"

    This is part of a theme I keep encountering in this project:

    Leading indicators beat lagging indicators.

    Domain Lagging Indicator Leading Indicator Tooling Version number, star count Team track record, architecture Code quality Test coverage percentage Whether tests catch real bugs Context persistence Number of files in .context/ Whether the AI makes fewer mistakes Skills Number of skills created Whether each skill fires at the right time Consolidation Lines of code refactored Whether drift stops accumulating

    Version numbers, star counts, coverage percentages, file counts...

    ...these are all measures of effort expended.

    They say nothing about value delivered.

    The question is never \"how mature is this tool?\"

    The question is \"does this tool's trajectory intersect with my needs?\"

    Zensical's trajectory:

    • A proven team fixing known problems,
    • in a *proven architecture,
    • with a standard format,
    • and no lock-in.

    ctx's needs:

    Tender standard Markdown into a browsable site, at scale, without complexity.

    The intersection is clean; the version number is noise.

    This is the same kind of decision that shows up throughout ctx:

    • Skills that fight the platform taught that the best integration extends existing behavior, not replaces it.
    • You can't import expertise taught that tools should grow from your project's actual needs, not from feature checklists.
    • Context as infrastructure argues that the format should outlive the tool; and, zensical honors that principle by reading standard Markdown and standard MkDocs configuration.

    If You Remember One Thing From This Post...

    Version numbers measure where a project has been.

    The team and the architecture tell you where it's going.

    A v0.0.21 tool built by the right team on the right foundations is a safer bet than a v5.0 tool that doesn't fit your problem.

    Bet on trajectories, not timestamps.

    This post started as an evaluation note in ideas/ and a separate decision log. The analysis held up. The two merged into one. The meta continues.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/","level":1,"title":"ctx v0.6.0: The Integration Release","text":"","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#two-commands-to-persistent-memory","level":2,"title":"Two Commands to Persistent Memory","text":"

    Jose Alekhinne / February 16, 2026

    What Changed?

    ctx is now a Claude Code plugin. Two commands, no build step:

    /plugin marketplace add ActiveMemory/ctx\n/plugin install ctx@activememory-ctx\n

    Six hooks. Twenty-five skills. Installed.

    For three releases, ctx required assembly:

    • Clone the repo;
    • Build the binary;
    • Copy hook scripts into .claude/hooks/;
    • Symlink skill files.
    • Understand which shell scripts called which Go commands;
    • Hope nothing broke when Claude Code updated its hook format.

    v0.6.0 ends that era: ctx ships as a Claude Marketplace plugin:

    Hooks and skills served directly from source, installed with a single command, updated by pulling the repo. The tool that gives AI persistent memory is now as easy to install as the AI itself.

    But the plugin conversion was not just a packaging change: It was the forcing function that rewrote every shell hook in Go, eliminated the jq dependency, enabled go test coverage for hook logic, and made distribution a solved problem.

    When you fix how something ships, you end up fixing how it is built.

    The Release Window

    February 15-February 16, 2026

    From the v0.3.0 tag to commit a3178bc:

    • 109 commits.
    • 334 files changed.
    • Version jumped from 0.3.0 to 0.6.0 to signal the magnitude.
    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#before-six-shell-scripts-and-a-prayer","level":2,"title":"Before: Six Shell Scripts and a Prayer","text":"

    v0.3.0 had six hook scripts. Each was a Bash file that shelled out to ctx subcommands, parsed JSON with jq, and wired itself into Claude Code's hook system via .claude/hooks/:

    .claude/hooks/\n├── check-context-size.sh\n├── check-persistence.sh\n├── check-journal.sh\n├── post-commit.sh\n├── block-non-path-ctx.sh\n└── cleanup-tmp.sh\n

    This worked, but it also meant:

    • jq was a hard dependency: No jq, no hooks. macOS ships without it.
    • No test coverage: Shell scripts were tested manually or not at all.
    • Fragile deployment: ctx init had to scaffold .claude/hooks/ and .claude/skills/ with the right paths, permissions, and structure.
    • Version drift: Users who installed once never got hook updates unless they re-ran ctx init.

    The shell scripts were the right choice for prototyping. They were the wrong choice for distribution.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#after-one-plugin-zero-shell-scripts","level":2,"title":"After: One Plugin, Zero Shell Scripts","text":"

    v0.6.0 replaces all six scripts with ctx system subcommands compiled into the binary:

    Shell Script Go Subcommand check-context-size.sh ctx system check-context-size check-persistence.sh ctx system check-persistence check-journal.sh ctx system check-journal post-commit.sh ctx system post-commit block-non-path-ctx.sh ctx system block-non-path-ctx cleanup-tmp.sh ctx system cleanup-tmp

    The plugin's hooks.json wires them to Claude Code events:

    {\n  \"PreToolUse\": [\n    {\"matcher\": \"Bash\", \"command\": \"ctx system block-non-path-ctx\"},\n    {\"matcher\": \".*\", \"command\": \"ctx agent --budget 4000\"}\n  ],\n  \"PostToolUse\": [\n    {\"matcher\": \"Bash\", \"command\": \"ctx system post-commit\"}\n  ],\n  \"UserPromptSubmit\": [\n    {\"command\": \"ctx system check-context-size\"},\n    {\"command\": \"ctx system check-persistence\"},\n    {\"command\": \"ctx system check-journal\"}\n  ],\n  \"SessionEnd\": [\n    {\"command\": \"ctx system cleanup-tmp\"}\n  ]\n}\n

    No jq. No shell scripts. No .claude/hooks/ directory to manage.

    The hooks are Go functions with tests, compiled into the same binary you already have.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#the-plugin-model","level":2,"title":"The Plugin Model","text":"

    The ctx plugin lives at .claude-plugin/marketplace.json in the repo.

    Claude Code's marketplace system handles discovery and installation:

    Skills are served directly from internal/assets/claude/skills/; there is no build step, no make plugin, no generated artifacts.

    This means:

    1. Install is two commands: Not \"clone, build, copy, configure.\"
    2. Updates are automatic: Pull the repo; the plugin reads from source.
    3. Skills and hooks are versioned together: No drift between what the CLI expects and what the plugin provides.
    4. ctx init is tool-agnostic: It creates .context/ and nothing else. No .claude/ scaffolding, no assumptions about which AI tool you use.

    That last point matters:

    Before v0.6.0, ctx init tried to set up Claude Code integration as part of initialization. That coupled the context system to a specific tool.

    Now, ctx init gives you persistent context. The plugin gives you Claude Code integration. They compose; they don't depend.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#beyond-the-plugin-what-else-shipped","level":2,"title":"Beyond the Plugin: What Else Shipped","text":"

    The plugin conversion dominated the release, but 109 commits covered more ground.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#obsidian-vault-export","level":3,"title":"Obsidian Vault Export","text":"
    ctx journal obsidian\n

    Generates a full Obsidian vault from enriched journal entries: wikilinks, MOC (Map of Content) pages, and graph-optimized cross-linking. If you already use Obsidian for notes, your AI session history now lives alongside everything else.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#encrypted-scratchpad","level":3,"title":"Encrypted Scratchpad","text":"
    ctx pad edit \"DATABASE_URL=postgres://...\"\nctx pad show\n

    AES-256-GCM encrypted storage for sensitive one-liners.

    The encrypted blob commits to git; the key stays in .gitignore.

    This is useful for connection strings, API keys, and other values that need to travel with the project without appearing in plaintext.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#security-hardening","level":3,"title":"Security Hardening","text":"

    Three medium-severity findings from a security audit are now closed:

    Finding Fix Path traversal via --context-dir Boundary validation: operations cannot escape project root (M-1) Symlink following in .context/ Lstat() check before every file read/write (M-2) Predictable temp file paths User-specific temp directory under $XDG_RUNTIME_DIR (M-3)

    Plus a new /sanitize-permissions skill that audits settings.local.json for overly broad Bash permissions.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#hooks-that-know-when-to-be-quiet","level":3,"title":"Hooks That Know When to Be Quiet","text":"

    A subtle but important fix: hooks now no-op before ctx init has run.

    Previously, a fresh clone with no .context/ would trigger hook errors on every prompt. Now, hooks detect the absence of a context directory and exit silently. Similarly, ctx init treats a .context/ directory containing only logs as uninitialized and skips the --overwrite prompt.

    Small changes. Large reduction in friction for new users.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#the-numbers","level":2,"title":"The Numbers","text":"Metric v0.3.0 v0.6.0 Skills 21 25 Shell hook scripts 6 0 Go system subcommands 0 6 External dependencies (hooks) jq, bash none Lines of Go ~14,000 ~37,000 Plugin install commands n/a 2 Security findings (open) 3 0 ctx init creates .claude/ yes no

    The line count tripled. Most of that is documentation site HTML, Obsidian export logic, and the scratchpad encryption module.

    The core CLI grew modestly; the ecosystem around it grew substantially.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#what-does-v060-mean-for-ctx","level":2,"title":"What Does v0.6.0 Mean for ctx?","text":"
    • v0.1.0 asked: \"Can we give AI persistent memory?\"
    • v0.2.0 asked: \"Can we make that memory accessible to humans too?\"
    • v0.3.0 asked: \"Can we make the quality self-enforcing?\"

    v0.6.0 asks: \"Can someone else actually use this?\"

    A tool that requires cloning a repo, building from source, and manually wiring hooks into the right directories is a tool for its author.

    A tool that installs with two commands from a marketplace is a tool for everyone.

    The version jumped from 0.3.0 to 0.6.0 because the delta is not incremental: The shell-to-Go rewrite, the plugin model, the security hardening, and the tool-agnostic init: Together, they change what ctx is: Not a different tool, but a tool that is finally ready to leave the workshop.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#what-comes-next","level":2,"title":"What Comes Next","text":"

    The plugin model opens the door to distribution patterns that were not possible before. Marketplace discovery means new users find ctx without reading a README. Plugin updates mean existing users get improvements without rebuilding.

    The next chapter is about what happens when persistent context is easy to install: Adoption patterns, multi-project workflows, and whether the .context/ convention can become infrastructure that other tools build on.

    But those are future posts.

    This one is about the release that turned a developer tool into a distributable product: two commands, zero shell scripts, and a presence on the Claude Marketplace.

    The Integration Release

    v0.1.0 shipped features. v0.2.0 shipped archaeology.

    v0.3.0 shipped discipline. v0.6.0 shipped the front door.

    The most important code in this release is the code you never have to copy.

    This post was drafted using /ctx-blog-changelog with access to the full git history between v0.3.0 and v0.6.0, release notes, and the plugin conversion PR. The meta continues.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/","level":1,"title":"Code Is Cheap. Judgment Is Not.","text":"","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#why-ai-replaces-effort-not-expertise","level":2,"title":"Why AI Replaces Effort, Not Expertise","text":"

    Jose Alekhinne / February 17, 2026

    Are You Worried About AI Taking Your Job?

    You might be confusing the thing that's cheap with the thing that's valuable.

    I keep seeing the same conversation: Engineers, designers, writers: all asking the same question with the same dread:

    \"What happens when AI can do what I do?\"

    The question is wrong:

    • AI does not replace workers;
    • AI replaces unstructured effort.

    The distinction matters, and everything I have learned building ctx reinforces it.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-three-confusions","level":2,"title":"The Three Confusions","text":"

    People who feel doomed by AI usually confuse three things:

    People confuse... With... Effort Value Typing Thinking Production Judgment
    • Effort is time spent.
    • Value is the outcome that time produces.

    They are not the same; they never were.

    AI just makes the gap impossible to ignore.

    Typing is mechanical: Thinking is directional.

    An AI can type faster than any human. Yet, it cannot decide what to type without someone framing the problem, sequencing the work, and evaluating the result.

    Production is making artifacts. Judgment is knowing:

    • which artifacts to make,
    • in what order,
    • to what standard,
    • and when to stop.

    AI floods the system with production capacity; it does not flood the system with judgment.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#code-is-nothing","level":2,"title":"Code Is Nothing","text":"

    This sounds provocative until you internalize it:

    Code is cheap. Artifacts are cheap.

    An AI can generate a thousand lines of working code in literal *minutes**:

    It can scaffold a project, write tests, build a CI pipeline, draft documentation. The raw production of software artifacts is no longer the bottleneck.

    So, what is not cheap?

    • Taste: knowing what belongs and what does not
    • Framing: turning a vague goal into a concrete problem
    • Sequencing: deciding what to build first and why
    • Fanning out: breaking work into parallel streams that converge
    • Acceptance criteria: defining what \"done\" looks like before starting
    • Judgment: the thousand small decisions that separate code that works from code that lasts

    These are the skills that direct production: Hhuman skills.

    Not because AI is incapable of learning them, but because they require something AI does not have:

    temporal accountability for generated outcomes.

    That is, you cannot keep AI accountable for the $#!% it generated three months ago. A human, on the other hand, will always be accountable.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-evidence-from-building-ctx","level":2,"title":"The Evidence From Building ctx","text":"

    I did not arrive at this conclusion theoretically.

    I arrived at it by building a tool with an AI agent for three weeks and watching exactly where a human touch mattered.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#yolo-mode-proved-production-is-cheap","level":3,"title":"YOLO Mode Proved Production Is Cheap","text":"

    In Building ctx Using ctx, I documented the YOLO phase: auto-accept everything, let the AI ship features at full speed. It produced 14 commands in a week. Impressive output.

    The code worked. The architecture drifted. Magic strings accumulated. Conventions diverged. The AI was producing at a pace no human could match, and every artifact it produced was a small bet that nobody was evaluating.

    Production without judgment is not velocity. It is debt accumulation at breakneck speed.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-31-ratio-proved-judgment-has-a-cadence","level":3,"title":"The 3:1 Ratio Proved Judgment Has a Cadence","text":"

    In The 3:1 Ratio, the git history told the story:

    Three sessions of forward momentum followed by one session of deliberate consolidation. The consolidation session is where the human applies judgment: reviewing what the AI built, catching drift, realigning conventions.

    The AI does the refactoring. The human decides what to refactor and when to stop.

    Without the human, the AI will refactor forever, improving things that do not matter and missing things that do.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-attention-budget-proved-framing-is-scarce","level":3,"title":"The Attention Budget Proved Framing Is Scarce","text":"

    In The Attention Budget, I explained why more context makes AI worse, not better. Every token competes for attention: Dump everything in and the AI sees nothing clearly.

    This is a framing problem: The human's job is to decide what the AI should focus on: what to include, what to exclude, what to emphasize.

    ctx agent --budget 4000 is not just a CLI flag: It is a forcing function for human judgment about relevance.

    The AI processes. The human curates.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#skills-design-proved-taste-is-load-bearing","level":3,"title":"Skills Design Proved Taste Is Load-Bearing","text":"

    The skill trilogy (You Can't Import Expertise, The Anatomy of a Skill That Works) showed that the difference between a useful skill and a useless one is not craftsmanship:

    It is taste.

    A well-crafted skill with the wrong focus is worse than no skill at all: It consumes the attention budget with generic advice while the project-specific problems go unchecked.

    The E/A/R framework (Expert, Activation, Redundant) is a judgment too:. The AI cannot apply it to itself. The human evaluates what the AI already knows, what it needs to be told, and what is noise.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#automation-discipline-proved-restraint-is-a-skill","level":3,"title":"Automation Discipline Proved Restraint Is a Skill","text":"

    In Not Everything Is a Skill, the lesson was that the urge to automate is not the need to automate. A useful prompt does not automatically deserve to become a slash command.

    The human applies judgment about frequency, stability, and attention cost.

    The AI can build the skill. Only the human can decide whether it should exist.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#defense-in-depth-proved-boundaries-require-judgment","level":3,"title":"Defense in Depth Proved Boundaries Require Judgment","text":"

    In Defense in Depth, the entire security model for unattended AI agents came down to: markdown is not a security boundary. Telling an AI \"don't do bad things\" is production (of instructions). Setting up an unprivileged user in a network-isolated container is judgment (about risk).

    The AI follows instructions. The human decides which instructions are enforceable and which are \"wishful thinking\".

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#parallel-agents-proved-scale-amplifies-the-gap","level":3,"title":"Parallel Agents Proved Scale Amplifies the Gap","text":"

    In Parallel Agents and Merge Debt, the lesson was that multiplying agents multiplies output. But it also multiplies the need for judgment:

    Five agents running in parallel produce five sessions of drift in one clock hour. The human who can frame tasks cleanly, define narrow acceptance criteria, and evaluate results quickly becomes the limiting factor.

    More agents do not reduce the need for judgment. They increase it.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-two-reactions","level":2,"title":"The Two Reactions","text":"

    When AI floods the system with cheap output, two things happen:

    Those who only produce: panic. If your value proposition is \"I write code,\" and an AI writes code faster, cheaper, and at higher volume, then the math is unfavorable. Not because AI took your job, but because your job was never the code. It was the judgment around the code, and you were not exercising it.

    Those who direct: accelerate. If your value proposition is \"I know what to build, in what order, to what standard,\" then AI is the best thing that ever happened to you: Production is no longer the bottleneck: Your ability to frame, sequence, evaluate, and course-correct is now the limiting factor on throughput.

    The gap between these two is not talent: It is the awareness of where the value lives.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#what-this-means-in-practice","level":2,"title":"What This Means in Practice","text":"

    If you are an engineer reading this, the actionable insight is not \"learn prompt engineering\" or \"master AI tools.\" It is:

    Get better at the things AI cannot do.

    AI does this well You need to do this Generate code Frame the problem Write tests Define acceptance criteria Scaffold projects Sequence the work Fix bugs from stack traces Evaluate tradeoffs Produce volume Exercise restraint Follow instructions Decide which instructions matter

    The skills on the right column are not new. They are the same skills that have always separated senior engineers from junior ones.

    AI did not create the distinction; it just made it load-bearing.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#if-anything-i-feel-empowered","level":2,"title":"If Anything, I Feel Empowered","text":"

    I will end with something personal.

    I am not worried: I am empowered.

    Before ctx, I could think faster than I could produce:

    • Ideas sat in a queue.
    • The bottleneck was always \"I know what to build, but building it takes too long.\"

    Now the bottleneck is gone. Poof!

    • Production is cheap.
    • The queue is clearing.
    • The limiting factor is how fast I can think, not how fast I can type.

    That is not a threat: That is the best force multiplier I've ever had.

    The people who feel threatened are confusing the accelerator for the replacement:

    *AI does not replace the conductor; it gives them a bigger orchestra.

    If You Remember One Thing From This Post...

    Code is cheap. Judgment is not.

    AI replaces unstructured effort, not directed expertise. The skills that matter now are the same skills that have always mattered: taste, framing, sequencing, and the discipline to stop.

    The difference is that now, for the first time, those skills are the only bottleneck left.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-arc","level":2,"title":"The Arc","text":"

    This post is a retrospective. It synthesizes the thread running through every previous entry in this blog:

    • Building ctx Using ctx showed that production without direction creates debt
    • Refactoring with Intent showed that slowing down is not the opposite of progress
    • The Attention Budget showed that curation outweighs volume
    • The skill trilogy showed that taste determines whether a tool helps or hinders
    • Not Everything Is a Skill showed that restraint is a skill in itself
    • Defense in Depth showed that instructions are not boundaries
    • The 3:1 Ratio showed that judgment has a schedule
    • Parallel Agents showed that scale amplifies the gap between production and judgment
    • Context as Infrastructure showed that the system you build for context is infrastructure, not conversation

    From YOLO mode to defense in depth, the pattern is the same:

    • Production is the easy part;
    • Judgment is the hard part;
    • AI changed the ratio, not the rule.

    This post synthesizes the thread running through every previous entry in this blog. The evidence is drawn from three weeks of building ctx with AI assistance, the decisions recorded in DECISIONS.md, the learnings captured in LEARNINGS.md, and the git history that tracks where the human mattered and where the AI ran unsupervised.

    See also: When a System Starts Explaining Itself -- what happens after the arc: the first field notes from the moment the system starts compounding in someone else's hands.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/","level":1,"title":"Context as Infrastructure","text":"","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#why-your-ai-needs-a-filesystem-not-a-prompt","level":2,"title":"Why Your AI Needs a Filesystem, Not a Prompt","text":"

    Jose Alekhinne / February 17, 2026

    Where does your AI's knowledge live between sessions?

    If the answer is \"in a prompt I paste at the start,\" you are treating context as a consumable. Something assembled, used, and discarded.

    What if you treated it as infrastructure instead?

    This post synthesizes a thread that has been running through every ctx blog post; from the origin story to the attention budget to the discipline release. The thread is this: context is not a prompt problem. It is an infrastructure problem. And the tools we build for it should look more like filesystems than clipboard managers.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-prompt-paradigm","level":2,"title":"The Prompt Paradigm","text":"

    Most AI-assisted development treats context as ephemeral:

    1. Start a session.
    2. Paste your system prompt, your conventions, your current task.
    3. Work.
    4. Session ends. Everything evaporates.
    5. Next session: paste again.

    This works for short interactions. For sustained development (where decisions compound over days and weeks) it fails in three ways:

    It does not persist: A decision made on Tuesday must be re-explained on Wednesday. A learning captured in one session is invisible to the next.

    It does not scale: As the project grows, the \"paste everything\" approach hits the context window ceiling. You start triaging what to include, often cutting exactly the context that would have prevented the next mistake.

    It does not compose: A system prompt is a monolith. You cannot load part of it, update one section, or share a subset with a different workflow. It is all or nothing.

    The Copy-Paste Tax

    Every session that starts with pasting a prompt is paying a tax:

    The human time to assemble the context, the risk of forgetting something, and the silent assumption that yesterday's prompt is still accurate today.

    Over 70+ sessions, that tax compounds into a significant maintenance burden: One that most developers absorb without questioning it.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-infrastructure-paradigm","level":2,"title":"The Infrastructure Paradigm","text":"

    ctx takes a different approach:

    Context is not assembled per-session; it is maintained as persistent files in a .context/ directory:

    .context/\n  CONSTITUTION.md     # Inviolable rules\n  TASKS.md            # Current work items\n  CONVENTIONS.md      # Code patterns and standards\n  DECISIONS.md        # Architectural choices with rationale\n  LEARNINGS.md        # Gotchas and lessons learned\n  ARCHITECTURE.md     # System structure\n  GLOSSARY.md         # Domain terminology\n  AGENT_PLAYBOOK.md   # Operating manual for agents\n  journal/            # Enriched session summaries\n  archive/            # Completed work, cold storage\n
    • Each file has a single purpose;
    • Each can be loaded independently;
    • Each persists across sessions, tools, and team members.

    This is not a novel idea. It is the same idea behind every piece of infrastructure software engineers already use:

    Traditional Infrastructure ctx Equivalent Database .context/*.md files Configuration files CONSTITUTION.md Environment variables .contextrc Log files journal/ Schema migrations Decision records Deployment manifests AGENT_PLAYBOOK.md

    The parallel is not metaphorical. Context files are infrastructure:

    • They are versioned (git tracks them);
    • They are structured (Markdown with conventions);
    • They have schemas (required fields for decisions and learnings);
    • And they have lifecycle management (archiving, compaction, indexing).
    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#separation-of-concerns","level":2,"title":"Separation of Concerns","text":"

    The most important design decision in ctx is not any individual feature. It is the separation of context into distinct files with distinct purposes.

    A single CONTEXT.md file would be simpler to implement. It would also be impossible to maintain.

    Why? Because different types of context have different lifecycles:

    Context Type Changes Read By Load When Constitution Rarely Every session Always Tasks Every session Session start Always Conventions Weekly Before coding When writing code Decisions When decided When questioning When revisiting Learnings When learned When stuck When debugging Journal Every session Rarely When investigating

    Loading everything into every session wastes the attention budget on context that is irrelevant to the current task. Loading nothing forces the AI to operate blind.

    Separation of concerns allows progressive disclosure:

    Load the minimum that matters for this moment, with the option to load more when needed.

    # Session start: load the essentials\nctx agent --budget 4000\n\n# Deep investigation: load everything\ncat .context/DECISIONS.md\ncat .context/journal/2026-02-05-*.md\n

    The filesystem is the index. File names, directory structure, and timestamps encode relevance. The AI does not need to read every file; it needs to know where to look.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-two-tier-persistence-model","level":2,"title":"The Two-Tier Persistence Model","text":"

    ctx uses two tiers of persistence, and the distinction is architectural:

    Tier Purpose Location Token Cost Curated Quick context reload .context/*.md Low (budgeted) Full dump Safety net, archaeology .context/journal/*.md Zero (not auto-loaded)

    The curated tier is what the AI sees at session start. It is optimized for signal density:

    • Structured entries,
    • Indexed tables,
    • Reverse-chronological order (newest first, so the most relevant content survives truncation).

    The full dump tier is for humans and for deep investigation. It contains everything: Enriched journals, archived tasks...

    It is never autoloaded because its volume would destroy attention density.

    This two-tier model is analogous to how traditional systems separate hot and cold storage:

    • The hot path (curated context) is optimized for read performance (measured not in milliseconds, but in tokens consumed per unit of useful information).
    • The cold path (journal) is optimized for completeness.

    Nothing Is Ever Truly Lost

    The full dump tier means that context does not need to be perfect: It just needs to be findable.

    A decision that was not captured in DECISIONS.md can be recovered from the session transcript where it was discussed.

    A learning that was not formalized can be found in the journal entry from that day.

    The curated tier is the fast path: The full dump tier is the safety net.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#decision-records-as-first-class-citizens","level":2,"title":"Decision Records as First-Class Citizens","text":"

    One of the patterns that emerged from ctx's own development is the power of structured decision records.

    v0.1.0 allowed adding decisions as one-liners:

    ctx add decision \"Use PostgreSQL\"\n

    v0.2.0 enforced structure:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a reliable database for user data\" \\\n  --rationale \"ACID compliance, team familiarity\" \\\n  --consequence \"Need connection pooling, team training\"\n

    The difference is not cosmetic:

    • A one-liner decision teaches the AI what was decided.
    • A structured decision teaches it why; and why is what prevents the AI from unknowingly reversing the decision in a future session.

    This is infrastructure thinking:

    Decisions are not notes. They are records with required fields, just like database rows have schemas.

    The enforcement exists because incomplete records are worse than no records: They create false confidence that the context is captured when it is not.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-ide-is-the-interface-decision","level":2,"title":"The \"IDE Is the Interface\" Decision","text":"

    Early in ctx's development, there was a temptation to build a custom UI: a web dashboard for browsing sessions, editing context, viewing analytics.

    The decision was no. The IDE is the interface.

    # This is the ctx \"UI\":\ncode .context/\n

    This decision was not about minimalism for its own sake. It was about recognizing that .context/ files are just files; and files have a mature, well-understood infrastructure:

    • Version control: git diff .context/DECISIONS.md shows exactly what changed and when.
    • Search: Your IDE's full-text search works across all context files.
    • Editing: Markdown in any editor, with preview, spell check, and syntax highlighting.
    • Collaboration: Pull requests on context files work the same as pull requests on code.

    Building a custom UI would have meant maintaining a parallel infrastructure that duplicates what every IDE already provides:

    It would have introduced its own bugs, its own update cycle, and its own learning curve.

    The filesystem is not a limitation: It is the most mature, most composable, most portable infrastructure available.

    Context Files in Git

    Because .context/ lives in the repository, context changes are part of the commit history.

    A decision made in commit abc123 is as traceable as a code change in the same commit.

    This is not possible with prompt-based context, which exists outside version control entirely.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#progressive-disclosure-for-ai","level":2,"title":"Progressive Disclosure for AI","text":"

    The concept of progressive disclosure comes from human interface design: show the user the minimum needed to make progress, with the option to drill deeper.

    ctx applies the same principle to AI context:

    Level What the AI Sees Token Cost When Level 0 ctx status (one-line summary) ~100 Quick check Level 1 ctx agent --budget 4000 ~4,000 Normal work Level 2 ctx agent --budget 8000 ~8,000 Complex tasks Level 3 Direct file reads 10,000+ Deep investigation

    Each level trades tokens for depth. Level 1 is sufficient for most work: the AI knows the active tasks, the key conventions, and the recent decisions. Level 3 is for archaeology: understanding why a decision was made three weeks ago, or finding a pattern in the session history.

    The explicit --budget flag is the mechanism that makes this work:

    Without it, the default behavior would be to load everything (because more context feels safer), which destroys the attention density that makes the loaded context useful.

    The constraint is the feature: A budget of 4,000 tokens forces ctx to prioritize ruthlessly: constitution first (always full), then tasks and conventions (budget-capped), then decisions and learnings scored by recency and relevance to active tasks. Entries that don't fit get title-only summaries rather than being silently dropped.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-philosophical-shift","level":2,"title":"The Philosophical Shift","text":"

    The shift from \"context as prompt\" to \"context as infrastructure\" changes how you think about AI-assisted development:

    Prompt Thinking Infrastructure Thinking \"What do I paste today?\" \"What has changed since yesterday?\" \"How do I fit everything in?\" \"What's the minimum that matters?\" \"The AI forgot my conventions\" \"The conventions are in a file\" \"I need to re-explain\" \"I need to update the record\" \"This session is getting slow\" \"Time to compact and archive\"

    The first column treats AI interaction as a conversation. The second treats it as a system: One that can be maintained, optimized, and debugged.

    Context is not something you give the AI. It is something you maintain: Like a database, like a config file, like any other piece of infrastructure that a running system depends on.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#beyond-ctx-the-principles","level":2,"title":"Beyond ctx: The Principles","text":"

    The patterns that ctx implements are not specific to ctx. They are applicable to any project that uses AI-assisted development:

    1. Separate context by purpose: Do not put everything in one file. Different types of information have different lifecycles and different relevance windows.
    2. Make context persistent: If a decision matters, write it down in a file that survives the session. If a learning matters, capture it with structure.
    3. Budget explicitly: Know how much context you are loading and whether it is worth the attention cost.
    4. Use the filesystem: File names, directory structure, and timestamps are metadata that the AI can navigate. A well-organized directory is an index that costs zero tokens to maintain.
    5. Version your context: Put context files in git. Changes to decisions are as important as changes to code.
    6. Design for degradation: Sessions will get long. Attention will dilute. Build mechanisms (compaction, archiving, cooldowns) that make degradation visible and manageable.

    These are not ctx features. They are infrastructure principles that happen to be implemented as a CLI tool. Any team could implement them with nothing more than a directory convention and a few shell scripts.

    The tool is a convenience: The principles are what matter.

    If You Remember One Thing From This Post...

    Prompts are conversations. Infrastructure persists.

    Your AI does not need a better prompt. It needs a filesystem:

    versioned, structured, budgeted, and maintained.

    The best context is the context that was there before you started the session.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-arc","level":2,"title":"The Arc","text":"

    This post is the architectural companion to the Attention Budget. That post explained why context must be curated (token economics). This one explains how to structure it (filesystem, separation of concerns, persistence tiers).

    Together with Code Is Cheap, Judgment Is Not, they form a trilogy about what matters in AI-assisted development:

    • Attention Budget: the resource you're managing
    • Context as Infrastructure: the system you build to manage it
    • Code Is Cheap: the human skill that no system replaces

    And the practices that keep it all honest:

    • The 3:1 Ratio: the cadence for maintaining both code and context
    • IRC as Context: the historical precedent: stateless protocols have always needed stateful wrappers

    This post synthesizes ideas from across the ctx blog series: the attention budget primitive, the two-tier persistence model, the IDE decision, and the progressive disclosure pattern. The principles are drawn from three weeks of building ctx and 70+ sessions of treating context as infrastructure rather than conversation.

    See also: When a System Starts Explaining Itself: what happens when this infrastructure starts compounding in someone else's environment.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/","level":1,"title":"Parallel Agents, Merge Debt, and the Myth of Overnight Progress","text":"","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#when-the-screen-looks-like-progress","level":2,"title":"When the Screen Looks Like Progress","text":"

    Jose Alekhinne / 2026-02-17

    How Many Terminals Are too Many?

    You discover agents can run in parallel.

    So you open ten...

    ...Then twenty.

    The fans spin. Tokens burn. The screen looks like progress.

    It is NOT progress.

    There is a phase every builder goes through:

    • The tooling gets fast enough.
    • The model gets good enough.
    • The temptation becomes irresistible:
      • more agents, more output, faster delivery.

    So you open terminals. You spawn agents. You watch tokens stream across multiple windows simultaneously, and it feels like multiplication.

    It is not multiplication.

    It is merge debt being manufactured in real time.

    The ctx Manifesto says it plainly:

    Activity is not impact. Code is not progress.

    This post is about what happens when you take that seriously in the context of parallel agent workflows.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-unit-of-scale-is-not-the-agent","level":2,"title":"The Unit of Scale Is Not the Agent","text":"

    The naive model says:

    More agents -> more output -> faster delivery

    The production model says:

    Clean context boundaries -> less interference -> higher throughput

    Parallelism only works when the cognitive surfaces do not overlap.

    If two agents touch the same files, you did not create parallelism: You created a conflict generator.

    They will:

    • Revert each other's changes;
    • Relint each other's formatting;
    • Refactor the same function in different directions.

    You watch with 🍿. Nothing ships.

    This is the same insight from the worktrees post: partition by blast radius, not by priority.

    Two tasks that touch the same files belong in the same track, no matter how important the other one is. The constraint is file overlap.

    Everything else is scheduling.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-five-agent-rule","level":2,"title":"The \"Five Agent\" Rule","text":"

    In practice there is a ceiling.

    Around five or six concurrent agents:

    • Token burn becomes noticeable;
    • Supervision cost rises;
    • Coordination noise increases;
    • Returns flatten.

    This is not a model limitation: This is a human merge bandwidth limitation.

    You are the bottleneck, not the silicon.

    The attention budget applies to you too:

    Every additional agent is another stream of output you need to comprehend, verify, and integrate. Your attention density drops the same way the model's does when you overload its context window.

    Five agents producing verified, mergeable change beats twenty agents producing merge conflicts you spend a day untangling.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#role-separation-beats-file-locking","level":2,"title":"Role Separation Beats File Locking","text":"

    Real parallelism comes from task topology, not from tooling.

    Good:

    Agent Role Touches 1 Documentation docs/, hack/ 2 Security scan Read-only audit 3 Implementation internal/cli/ 4 Enhancement requests Read-only, files issues

    Bad:

    • Four agents editing the same implementation surface

    Context is the Boundary

    • The goal is not to keep agents busy.
    • The goal is to keep contexts isolated.

    This is what the codebase audit got right:

    • Eight agents, all read-only, each analyzing a different dimension.
    • Zero file overlap.
    • Zero merge conflicts.
    • Eight reports that composed cleanly because no agent interfered with another.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#when-terminals-stop-scaling","level":2,"title":"When Terminals Stop Scaling","text":"

    There is a moment when more windows stop helping.

    That is the signal. Not to add orchestration. But to introduce:

    git worktree\n

    Because now you are no longer parallelizing execution; you are parallelizing state.

    State Scales, Windows Don't

    • State isolation is the real scaling.
    • Window multiplication is theater.

    The worktrees post covers the mechanics:

    • Sibling directories;
    • Branch naming;
    • The inevitable TASKS.md conflicts;
    • The 3-4 worktree ceiling.

    The principle underneath is older than git:

    Shared mutable state is the enemy of parallelism.

    Always has been.

    Always will be.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-overnight-loop-illusion","level":2,"title":"The Overnight Loop Illusion","text":"

    Autonomous night runs are impressive.

    You sleep. The machine produces thousands of lines.

    In the morning:

    • You read;
    • You untangle;
    • You reconstruct intent;
    • You spend a day making it shippable.

    In retrospect, nothing was accelerated.

    The bottleneck moved from typing to comprehension.

    The Comprehension Tax

    If understanding the output costs more than producing it, the loop is a net loss.

    Progress is not measured in generated code.

    Progress is measured in verified, mergeable change.

    The ctx Manifesto calls this out directly:

    The Scoreboard

    Verified reality is the scoreboard.

    The only truth that compounds is verified change in the real world.

    An overnight run that produces 3,000 lines nobody reviewed is not 3,000 lines of progress: It is 3,000 lines of liability until someone verifies every one of them.

    And that someone is (insert drumroll here) you:

    The same bottleneck that was supposedly being bypassed.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#skills-that-fight-the-platform","level":2,"title":"Skills That Fight the Platform","text":"

    Most marketplace skills are prompt decorations:

    • They rephrase what the base model already knows;
    • They increase token usage;
    • They reduce clarity:
    • They introduce behavioral drift.

    We covered this in depth in Skills That Fight the Platform: judgment suppression, redundant guidance, guilt-tripping, phantom dependencies, universal triggers: Five patterns that make agents worse, not better.

    A real skill does one of these:

    • Encodes workflow state;
    • Enforces invariants;
    • Reduces decision branching.

    Everything else is packaging.

    The anatomy post established the criteria: quality gates, negative triggers, examples over rules, skills as contracts.

    If a skill doesn't meet those criteria...

    • It is either a recipe (document it in hack/);
    • Or noise (delete it);
    • There is no third option.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#hooks-are-context-that-execute","level":2,"title":"Hooks Are Context That Execute","text":"

    The most valuable skills are not prompts:

    They are constraints embedded in the toolchain.

    For example: The agent cannot push.

    git push becomes:

    Stop. A human reviews first.

    A commit without verification becomes:

    Did you run tests? Did you run linters? What exactly are you shipping?

    This is not safety theater; this is intent preservation.

    The thing the ctx Manifesto calls \"encoding intent into the environment.\"

    The Eight Ways a Hook Can Talk catalogued the full spectrum: from silent enrichment to hard blocks.

    The key insight was that hooks are not just safety rails: They are context that survives execution.

    They are the difference between an agent that remembers the rules and one that enforces them.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#complexity-is-a-tax","level":2,"title":"Complexity Is a Tax","text":"

    Every extra layer adds cognitive weight:

    • Orchestration frameworks;
    • Meta agents;
    • Autonomous planning systems...

    If a single terminal works, stay there.

    If five isolated agents work, stop there.

    Add structure only when a real bottleneck appears.

    NOT when an influencer suggests one.

    This is the same lesson from Not Everything Is a Skill:

    The best automation decision is sometimes not to automate.

    A recipe in a Markdown file costs nothing until you use it.

    An orchestration framework costs attention on every run, whether it helps or not.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#literature-is-throughput","level":2,"title":"Literature Is Throughput","text":"

    Clear writing is not aesthetic: It is compression.

    Better articulation means:

    • Fewer tokens;
    • Fewer misinterpretations;
    • Faster convergence.

    The attention budget taught us that context is a finite resource with a quadratic cost.

    Language determines how fast you spend context.

    A well-written task description that takes 50 tokens outperforms a rambling one that takes 200: Not just because it is cheaper, but because it leaves more headroom for the model to actually think.

    Literature is NOT Overrated

    • Attention is a finite budget.
    • Language determines how fast you spend it.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-real-metric","level":2,"title":"The Real Metric","text":"

    The real metric is not:

    • Lines generated;
    • Agents running;
    • Tasks completed while you sleep.

    But:

    Time from idea to verified, mergeable, production change.

    Everything else is motion.

    The entire blog series has been circling this point:

    • The attention budget was about spending tokens wisely.
    • The skills trilogy was about not wasting them on prompt decoration.
    • The worktrees post was about multiplying throughput without multiplying interference.
    • The discipline release was about what a release looks like when polish outweighs features: 3:1.

    Every post has arrived (and made me converge) at the same answer so far:

    The metric is a verified change, not generated output.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#ctx-was-never-about-spawning-more-minds","level":2,"title":"ctx Was Never About Spawning More Minds","text":"

    ctx is about:

    • Isolating context;
    • Preserving intent;
    • Making progress composable.

    Parallel agents are powerful. But only when you respect the boundaries that make parallelism real.

    Otherwise, you are not scaling cognition; you are scaling interference.

    The ctx Manifesto's thesis holds:

    Without ctx, intelligence resets. With ctx, creation compounds.

    Compounding requires structure.

    Structure requires boundaries.

    Boundaries require the discipline to stop adding agents when five is enough.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#practical-summary","level":2,"title":"Practical Summary","text":"

    A production workflow tends to converge to this:

    Practice Why Stay in one terminal unless necessary Minimize coordination overhead Spawn a small number of agents with non-overlapping responsibilities Conflict avoidance > parallelism Isolate state with worktrees when surfaces grow State isolation is real scaling Encode verification into hooks Intent that survives execution Avoid marketplace prompt cargo cults Skills are contracts, not decorations Measure merge cost, not generation speed The metric is verified change

    This is slower to watch. Faster to ship.

    If You Remember One Thing From This Post...

    Progress is not what the machine produces while you sleep.

    Progress is what survives contact with the main branch.

    See also: Code Is Cheap. Judgment Is Not.: the argument that production capacity was never the bottleneck, and why multiplying agents amplifies the need for human judgment rather than replacing it.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/","level":1,"title":"The 3:1 Ratio","text":"","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#scheduling-consolidation-in-ai-development","level":2,"title":"Scheduling Consolidation in AI Development","text":"

    Jose Alekhinne / February 17, 2026

    How often should you stop building and start cleaning?

    Every developer knows technical debt exists. Every developer postpones dealing with it.

    AI-assisted development makes the problem worse; not because the AI writes bad code, but because it writes code so fast that drift accumulates before you notice.

    In Refactoring with Intent, I mentioned a ratio that worked for me: 3:1. Three YOLO sessions create enough surface area to reveal patterns. The fourth session turns those patterns into structure.

    That was an observation. This post is the evidence.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-observation","level":2,"title":"The Observation","text":"

    During the first two weeks of building ctx, I noticed a rhythm in my own productivity. Feature sessions felt great: new commands, new capabilities, visible progress...

    ...but after three of them, things would start to feel sticky: variable names that almost made sense, files that had grown past their purpose, patterns that repeated without being formalized.

    The fourth session (when I stopped adding and started cleaning) was always the most painful to start and the most satisfying to finish.

    It was also the one that made the next three feature sessions faster.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-evidence-git-history","level":2,"title":"The Evidence: Git History","text":"

    The ctx git history between January 20 and February 7 tells a clear story when you categorize commits:

    Week Feature commits Consolidation commits Ratio Jan 20-26 18 5 3.6:1 Jan 27-Feb 1 14 6 2.3:1 Feb 1-7 15 35+ 0.4:1

    The first week was pure YOLO: Almost four feature commits for every consolidation commit. The codebase grew fast.

    The second week started to self-correct. The ratio dropped as refactoring sessions became necessary: Not scheduled, but forced by friction.

    The third week inverted entirely: v0.3.0 was almost entirely consolidation: the skill migration, the sweep, the documentation standardization. Thirty-five quality commits against fifteen features.

    The debt from weeks one and two was paid in week three.

    The Compounding Problem

    Consolidation debt compounds.

    Week one's drift doesn't just persist into week two: It accelerates, because new features are built on top of drifted patterns.

    By week three, the cost of consolidation was higher than it would have been if spread evenly.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#what-drift-actually-looks-like","level":2,"title":"What Drift Actually Looks Like","text":"

    \"Drift\" sounds abstract. Here is what it looked like concretely in the ctx codebase after three weeks of feature-heavy development:

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#predicate-naming","level":3,"title":"Predicate Naming","text":"

    Convention says boolean functions should be named HasX, IsX, CanX. After three feature sprints:

    // What accumulated:\nfunc CheckIfEnabled() bool  // should be Enabled\nfunc ValidateFormat() bool  // should be ValidFormat\nfunc TestConnection() bool  // should be Connects\nfunc VerifyExists() bool    // should be Exists or HasFile\nfunc EnsureReady() bool     // should be Ready\n

    Five violations. Not bugs, but friction that compounds every time someone (human or AI) reads the code and has to infer the naming convention from inconsistent examples.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#magic-strings","level":3,"title":"Magic Strings","text":"
    // Week 1: acceptable prototype\nif entry.Type == \"task\" {\n    filename = \"TASKS.md\"\n}\n\n// Week 3: same pattern in 7+ files\n// Now it's a maintenance liability\n

    When the same literal appears in seven files, changing it means finding all seven. Missing one means a silent runtime bug. Constants exist to prevent exactly this. But during feature velocity, nobody stops to extract them.

    Refactoring with Intent documented the constants consolidation that cleaned this up. The 3:1 ratio is the practice that prevents it from accumulating again.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#hardcoded-permissions","level":3,"title":"Hardcoded Permissions","text":"
    os.WriteFile(path, data, 0644) // 80+ instances\nos.MkdirAll(path, 0755)        // scattered across packages\n

    Eighty-plus instances of hardcoded file permissions. Not wrong, but if I ever need to change the default (and I did, for hook scripts that need execute permissions), it means a codebase-wide search.

    Drift Is Not Bugs

    None of these are bugs. The code works. Tests pass.

    But drift creates false confidence: the codebase looks consistent until you try to change something and discover that five different conventions exist for the same concept.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#why-you-cannot-consolidate-on-day-one","level":2,"title":"Why You Cannot Consolidate on Day One","text":"

    The temptation is to front-load quality: write all the conventions, enforce all the checks, prevent all the drift before it happens.

    This fails for two reasons.

    First, you do not know what will drift: Predicate naming violations only become a convention check after you notice three different naming patterns competing. Magic strings only become a consolidation target after you change a literal and discover it exists in seven places.

    The conventions emerge from the work; they cannot precede it.

    This is what You Can't Import Expertise meant in practice: the consolidation checks grow from the project's own drift history. You cannot write them on day one because you do not yet know what will drift.

    Second, premature consolidation slows discovery: During the prototyping phase, the goal is to explore the design space. Enforcing strict conventions on code that might be deleted tomorrow is waste.

    YOLO mode has its place: The problem is not YOLO itself, but YOLO without a scheduled cleanup.

    The Consolidation Paradox

    You need a drift history to know what to consolidate.

    You need consolidation to prevent drift from compounding.

    The 3:1 ratio resolves this paradox:

    Let drift accumulate for three sessions (enough to see patterns), then consolidate in the fourth (before the patterns become entrenched*).

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-consolidation-skill","level":2,"title":"The Consolidation Skill","text":"

    The ctx project now has an /audit skill that encodes nine project-specific checks:

    Check What It Catches Predicate naming Boolean functions not using Has/Is/Can Magic strings Repeated literals not in config constants File permissions Hardcoded 0644/0755 not using constants Godoc style Missing or non-standard documentation File length Files exceeding 400 lines Large functions Functions exceeding 80 lines Template drift Live skills diverging from templates Import organization Non-standard import grouping TODO/FIXME staleness Old markers that are no longer relevant

    This is not a generic linter. These are project-specific conventions that emerged from ctx's own development history. A generic code quality tool would catch some of them. Only a project-specific check catches all of them, because some of them (predicate naming, template drift) are conventions that exist nowhere except in this project's CONVENTIONS.md.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-decision-matrix","level":2,"title":"The Decision Matrix","text":"

    Not all drift needs immediate consolidation. Here is the matrix I use:

    Signal Action Same literal in 3+ files Extract to constant Same code block in 3+ places Extract to helper Naming convention violated 5+ times Fix and document rule File exceeds 400 lines Split by concern Convention exists but is regularly violated Strengthen enforcement Pattern exists only in one place Leave it alone Code works but is \"ugly\" Leave it alone

    The last two rows matter:

    Consolidation is about reducing maintenance cost, not achieving aesthetic perfection. Code that works and exists in one place does not benefit from consolidation; it benefits from being left alone until it earns its refactoring.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#consolidation-as-context-hygiene","level":2,"title":"Consolidation as Context Hygiene","text":"

    There is a parallel between code consolidation and context management that became clear during the ctx development:

    Code Consolidation Context Hygiene Extract magic strings Archive completed tasks Standardize naming Keep DECISIONS.md current Remove dead code Compact old sessions Update stale comments Review LEARNINGS.md for staleness Check template drift Verify CONVENTIONS.md matches code

    ctx compact does for context what consolidation does for code:

    It moves completed work to cold storage, keeping the active context clean and focused. The attention budget applies to both the AI's context window and the developer's mental model of the codebase.

    When context files accumulate stale entries, the AI's attention is wasted on completed tasks and outdated conventions. When code accumulates drift, the developer's attention is wasted on inconsistencies that obscure the actual logic.

    Both are solved by the same discipline: periodic, scheduled cleanup.

    This is also why parallel agents make the problem harder, not easier. Three agents running simultaneously produce three sessions' worth of drift in one clock hour. The consolidation cadence needs to match the output rate, not the calendar.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-practice","level":2,"title":"The Practice","text":"

    Here is how the 3:1 ratio works in practice for ctx development:

    Sessions 1-3: Feature work

    • Add new capabilities;
    • Write tests for new code;
    • Do not stop for cleanup unless something is actively broken;
    • Note drift as you see it (a comment, a task, a mental note).

    Session 4: Consolidation

    • Run /audit to surface accumulated drift;
    • Fix the highest-impact items first;
    • Update CONVENTIONS.md if new patterns emerged;
    • Archive completed tasks;
    • Review LEARNINGS.md for anything that became a convention.

    The key insight is that session 4 is not optional. It is not \"if we have time\": It is scheduled with the same priority as feature work.

    The cost of skipping it is not visible immediately; it becomes visible three sessions later, when the next consolidation session takes twice as long because the drift compounded.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#what-the-ratio-is-not","level":2,"title":"What the Ratio Is Not","text":"

    The 3:1 ratio is not a universal law. It is an empirical observation from one project with one developer working with AI assistance.

    Different projects will have different ratios:

    • A mature codebase with strong conventions might sustain 5:1 or higher;
    • A greenfield prototype might need 2:1;
    • A team of multiple developers with different styles might need 1:1.

    The number is less important than the practice: consolidation is not a reaction to problems. It is a scheduled activity.

    If you wait for drift to cause pain before consolidating, you have already paid the compounding cost.

    If You Remember One Thing From This Post...

    Three sessions of building. One session of cleaning.

    Not because the code is dirty, but because drift compounds silently, and the only way to catch it is to look for it on a schedule.

    The ratio is the schedule.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-arc-so-far","level":2,"title":"The Arc So Far","text":"

    This post sits at a crossroads in the ctx story. Looking back:

    • Building ctx Using ctx documented the YOLO sprint that created the initial codebase
    • Refactoring with Intent introduced the 3:1 ratio as an observation from the first cleanup
    • The Attention Budget explained why drift matters: every token of inconsistency consumes the same finite resource as useful context
    • You Can't Import Expertise showed that consolidation checks must grow from the project, not a template
    • The Discipline Release proved the ratio works at release scale: 35 quality commits to 15 feature commits

    And looking forward: the same principle applies to context files, to documentation, and to the merge debt that parallel agents produce. Drift is drift, whether it lives in code, in .context/, or in the gap between what your docs say and what your code does.

    The ratio is the schedule is the discipline.

    This post was drafted from git log analysis of the ctx repository, mapping every commit from January 20 to February 7 into feature vs consolidation categories. The patterns described are drawn from the project's CONVENTIONS.md, LEARNINGS.md, and the /audit skill's check list.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/","level":1,"title":"When a System Starts Explaining Itself","text":"","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#field-notes-from-the-moment-a-private-workflow-becomes-portable","level":2,"title":"Field Notes from the Moment a Private Workflow Becomes Portable","text":"

    Jose Alekhinne / February 17, 2026

    How Do You Know Something Is Working?

    Not from metrics. Not from GitHub stars. Not from praise.

    You know, deep in your heart, that it works when people start describing it wrong.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-first-external-signals","level":2,"title":"The First External Signals","text":"

    Every new substrate begins as a private advantage:

    • It lives inside one mind,
    • One repository,
    • One set of habits.

    It is fast. It is not yet real.

    Reality begins when other people describe it in their own language:

    • Not accurately;
    • Not consistently;
    • But involuntarily.

    The early reports arrived without coordination:

    Better Tasks

    \"I do not know how, but this creates better tasks than my AI plugin.\"

    I See Butterflies

    \"This is better than Adderall.\"

    Dear Manager...

    \"Promotion packet? Done. What is next?\"

    What Is It? Can I Eat It?

    \"Is this a skill?\" 🦋

    Why the Cloak and Dagger?

    \"Why is this not in the marketplace?\"

    And then something more important happened:

    Someone else started making a video!

    That was the boundary.

    ctx no longer required its creator to be present in order to exist.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#misclassification-is-a-sign-of-a-new-primitive","level":2,"title":"Misclassification Is a Sign of a New Primitive","text":"

    When a tool is understood, it is categorized:

    • Editor,
    • Framework,
    • Task manager,
    • Plugin...

    When a substrate appears, it is misclassified:

    \"Is this a skill?\" 🦋

    The question is correct. The category is wrong.

    • Skills live in people.
    • Infrastructure lives in the environment.

    ctx Is not a Skill: It is a Form of Relief

    What early adopters experience is not an ability.

    It is the removal of a cognitive constraint.

    This is the same distinction that emerged in the skills trilogy:

    • A skill is a contract between a human and an agent.
    • Infrastructure is the ground both stand on.

    You do not use infrastructure.

    You habitualize it.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-pharmacological-metaphor","level":2,"title":"The Pharmacological Metaphor","text":"

    \"Better than Adderall\" is not praise.

    It is a diagnostic:

    Executive function has been externalized.

    • The system is not making the user work harder.
    • It is restoring continuity.

    From the primitive context of wetware:

    • Continuity feels like focus
    • Focus feels like discipline

    If it walks like a duck and quacks like a duck, it is a duck.

    Discipline is usually simulated.

    Infrastructure makes the simulation unnecessary.

    The attention budget explained why context degrades:

    • Attention density drops as volume grows;
    • The middle gets lost;
    • Sessions end and everything evaporates.

    The pharmacological metaphor says the same thing from the user's lens:

    Save the Cheerleader, Save the World

    The symptom of lost context is lost focus.

    Restore the context. Restore the focus.

    IRC bouncers solved this for chat twenty years ago. ctx solves it for cognition.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#throughput-on-ambiguous-work","level":2,"title":"Throughput on Ambiguous Work","text":"

    Finishing a promotion packet quickly is not a productivity story.

    It is the collapse of reconstruction cost.

    Most complex work is not execution. It is:

    • Remembering why something mattered;
    • Recovering prior decisions;
    • Rebuilding mental state.

    Persistent context removes that tax.

    Velocity appears as a side effect.

    This Is the Two-Tier Model in Practice

    The two-tier persistence model

    • Curated context for fast reload
    • Full journal for archaeology

    is what makes this possible.

    • The user does not notice the system.
    • They notice that the reconstruction cost disappeared.
    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-moment-of-portability","level":2,"title":"The Moment of Portability","text":"

    The system becomes real when two things happen:

    1. It can be installed as a versioned artifact.
    2. It survives contact with a hostile, real codebase.

    This is why the first integration into a living system matters more than any landing page.

    Demos prove possibility.

    Diffs prove reality.

    The ctx Manifesto calls this out directly:

    Verified reality is the scoreboard.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-split-voice","level":2,"title":"The Split Voice","text":"

    A new substrate requires two channels.

    The embodied voice:

    Here is what changed in my actual work.

    The out of body voice:

    Here is what this means.

    One produces trust.

    The other produces understanding.

    Neither is sufficient alone.

    This entire blog has been the second voice.

    • The origin story was the first.
    • The refactoring post was the first.
    • Every release note with concrete diffs was the first.

    This is the first second.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#systems-that-generate-explainers","level":2,"title":"Systems That Generate Explainers","text":"

    Tools are used.

    Platforms are extended.

    Substrates are explained.

    The first unsolicited explainer is a brittle phase change.

    It means the idea has become portable between minds.

    That is the beginning of an ecosystem.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-absence-of-metrics","level":2,"title":"The Absence of Metrics","text":"

    Metrics do not matter at this stage.

    Dashboards are noise.

    The whole premise of ctx is the ruthless elimination of noise.

    Numbers optimize funnels; substrates alter cognition.

    The only valid measurement is irreversible reality:

    • A merged PR;
    • A reproducible install;
    • A decision that is never re-litigated.

    The merge debt post reached the same conclusion from another direction:

    The metric is the verified change, not generated output.

    For adoption, the same rule applies:

    The metric is altered behavior, not download counts.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#what-is-actually-happening","level":2,"title":"What Is Actually Happening","text":"

    A private advantage is becoming an environmental property:

    The system is moving from...

    personal workflow,

    to...

    a shared infrastructure for thought.

    Not by growth.

    Not by marketing.

    By altering how real systems evolve.

    If You Remember One Thing From This Post...

    You do not know a substrate is real when people praise it.

    You know it is real when:

    • They describe it incorrectly;
    • They depend on it unintentionally;
    • They start teaching it to others.

    That is the moment the system begins explaining itself.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-arc","level":2,"title":"The Arc","text":"

    Every previous post looked inward.

    This one looks outward.

    • Building ctx Using ctx: one mind, one repository
    • The Attention Budget: the constraint
    • Context as Infrastructure: the architecture
    • Code Is Cheap. Judgment Is Not.: the bottleneck

    This post is the field report from the other side of that bottleneck:

    The moment the infrastructure compounds in someone else's hands.

    The arc is not complete.

    It is becoming portable.

    These field notes were written the same day the feedback arrived. The quotes are real. Real users. Real codebases. No names. No metrics. No funnel. Only the signal that something shifted.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/","level":1,"title":"The Dog Ate My Homework","text":"","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#teaching-ai-agents-to-read-before-they-write","level":2,"title":"Teaching AI Agents to Read Before They Write","text":"

    Jose Alekhinne / February 25, 2026

    Does Your AI Actually Read the Instructions?

    You wrote the playbook. You organized the files. You even put \"CRITICAL, not optional\" in bold.

    The agent skipped all of it and went straight to work.

    I spent a day running experiments on my own agents. Not to see if they could write code (they can). To see if they would do their homework first.

    They didn't.

    Then I kept experimenting:

    • Five sessions;
    • Five different failure modes.

    And by the end, I had something better than compliance:

    I had observable compliance: A system where I don't need the agent to be perfect, I just need to see what it chose.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#tldr","level":2,"title":"TL;DR","text":"

    You don't need perfect compliance. You need observable compliance.

    Authority is a function of temporal proximity to action.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-pattern","level":2,"title":"The Pattern","text":"

    This design has three parts:

    1. One-hop instruction;
    2. Binary collapse;
    3. Compliance canary.

    I'll explain all three patterns in detail below.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-setup","level":2,"title":"The Setup","text":"

    ctx has a session-start protocol:

    • Read the context files;
    • Load the playbook;
    • Understand the project before touching anything.

    It's in CLAUDE.md. It's in AGENT_PLAYBOOK.md.

    It's in bold. It's in CAPS. It's ignored.

    In theory, it's awesome.

    Here's what happens when theory hits reality:

    What the agent receives What the agent does CLAUDE.md saying \"load context first\" Skips it 8 context files waiting to be read Ignores them User's question: \"add --verbose flag\" Starts grepping immediately

    The instructions are right there. The agent knows they exist. It even knows it should follow them. But the user asked a question, and responsiveness wins over ceremony.

    This isn't a bug in the model. It's a design problem in how we communicate with agents.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-delegation-trap","level":2,"title":"The Delegation Trap","text":"

    My first attempt was obvious: A UserPromptSubmit hook that fires when the session starts.

    STOP. Before answering the user's question, run `ctx system bootstrap`\nand follow its instructions. Do not skip this step.\n

    The word \"STOP\" worked. The agent ran bootstrap.

    But bootstrap's output said \"Next steps: read AGENT_PLAYBOOK.md,\" and the agent decided that was optional. It had already started working on the user's task in parallel.

    The authority decayed across the chain:

    • Hook says \"STOP\" -> agent complies
    • Hook says \"run bootstrap\" -> agent runs it
    • Bootstrap says \"read playbook\" -> agent skips
    • Bootstrap says \"run ctx agent\" -> agent skips

    Each link lost enforcement power. The hook's authority didn't transfer to the commands it delegated to. I call this the decaying urgency chain: the agent treats the hook itself as the obligation and everything downstream as a suggestion.

    Delegation Kills Urgency

    \"Run X and follow its output\" is three hops.

    \"Read these files\" is one hop.

    The agent drops the chain after the first link.

    This is a general principle: Hooks are the boundary between your environment and the agent's reasoning. If your hook delegates to a command that delegates to output that contains instructions... you're playing telephone.

    Agents are bad at telephone.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-timing-problem","level":2,"title":"The Timing Problem","text":"

    There's a subtler issue than wording: when the message arrives.

    UserPromptSubmit fires when the user sends a message, before the agent starts reasoning. At that moment, the agent's primary focus is the user's question:

    The hook message competes with the task for attention: The task, almost certainly, always wins.

    This is the attention budget problem in miniature:

    • Not a token budget this time, but an attention priority budget.
    • The agent has finite capacity to care about things,
      • and the user's question is always the highest-priority item.
    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-solution","level":2,"title":"The Solution","text":"

    To solve this, I dediced to use the PreToolUse hook.

    This hook fires at the moment of action: When the agent is about to use its first tool: The agent's attention is focused, the context window is fresh, and the switching cost is minimal.

    This is the difference between shouting instructions across a room and tapping someone on the shoulder.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-one-liner-that-worked","level":2,"title":"The One-Liner That Worked","text":"

    The winning design was almost comically simple:

    Read your context files before proceeding:\n.context/CONSTITUTION.md, .context/TASKS.md, .context/CONVENTIONS.md,\n.context/ARCHITECTURE.md, .context/DECISIONS.md, .context/LEARNINGS.md,\n.context/GLOSSARY.md, .context/AGENT_PLAYBOOK.md\n

    No delegation. No \"run this command\". Just: here are files, read them.

    The agent already knows how to use the Read tool. There's no ambiguity about how to comply. There's no intermediate command whose output needs to be parsed and obeyed.

    One hop. Eight file paths. Done.

    Direct Instructions Beat Delegation

    If you want an agent to read a file, say \"read this file.\"

    Don't say \"run a command that will tell you which files to read.\"

    The shortest path between intent and action has the highest compliance rate.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-escape-hatch","level":2,"title":"The Escape Hatch","text":"

    But here's where it gets interesting.

    A blunt \"read everything always\" instruction is wasteful.

    If someone asks \"what does the compact command do?\", the agent doesn't need CONSTITUTION.md to answer that. Forcing context loading on every session is the context hoarding antipattern in disguise.

    So the hook included an escape:

    If you decide these files are not relevant to the current task\nand choose to skip reading them, you MUST relay this message to\nthe user VERBATIM:\n\n┌─ Context Skipped ───────────────────────────────\n│ I skipped reading context files because this task\n│ does not appear to need project context.\n│ If these matter, ask me to read them.\n└─────────────────────────────────────────────────\n

    This creates what I call the binary collapse effect:

    The agent can't partially comply: It either reads everything or publicly admits it skipped. There's no comfortable middle ground where it reads two files and quietly ignores the rest.

    The VERBATIM relay pattern does the heavy lifting here: Without the relay requirement, the agent would silently rationalize skipping. With it, skipping becomes a visible, auditable decision that the user can override.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-compliance-canary","level":3,"title":"The Compliance Canary","text":"

    Here's the design insight that only became clear after watching it work across multiple sessions: the relay block is a compliance canary.

    • You don't need to verify that the agent read all 7 files;
    • You don't need to audit tool call sequences;
    • You don't need to interrogate the agent about what it did.

    You just look for the block.

    If the agent reads everything, you see a \"Context Loaded\" block listing what was read. If it skips, you see a \"Context Skipped\" block.

    If you see neither, the agent silently ignored both the reads and the relay and now you know what happened without having to ask.

    The canary degrades gracefully. Even in partial failure, the agent that skips 4 of 7 files but still outputs the block is more useful than one that skips silently.

    You get an honest confession of what was skipped rather than silent non-compliance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#heuristics-is-a-jeremy-bearimy","level":2,"title":"Heuristics Is a Jeremy Bearimy","text":"

    Heuristics are non-linear. Improvements don't accumulate: they phase-shift.

    The theory is nice. The data is better.

    I ran five sessions with the same model (Claude Opus 4.6), progressively refining the hook design.

    Each session revealed a different failure mode.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-1-total-blindness","level":3,"title":"Session 1: Total Blindness","text":"

    Test: \"Add a --verbose flag to the status command.\"

    The agent didn't notice the hook at all: Jumped straight to EnterPlanMode and launched an Explore agent.

    Zero compliance.

    Failure mode: The hook fired on UserPromptSubmit, buried among 9 other hook outputs. The agent treated the entire block as background noise.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-2-shallow-compliance","level":3,"title":"Session 2: Shallow Compliance","text":"

    Test: \"Can you add --verbose to the info command?\"

    The agent noticed \"STOP\" and ran ctx system bootstrap. Progress.

    But it parallelized task exploration alongside the bootstrap call, skipped AGENT_PLAYBOOK.md, and never ran ctx agent.

    Failure mode: Literal compliance without spirit compliance.

    The agent ran the command the hook told it to run, but didn't follow the output of that command. The decaying urgency chain in action.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-3-conscious-rejection","level":3,"title":"Session 3: Conscious Rejection","text":"

    Test: \"What does the compact command do?\"

    The hook fired on PreToolUse:Grep: the improved timing.

    The agent noticed it, understood it, and (wait for it...)...

    ...

    consciously decided to skip it!

    Its reasoning: \"This is a trivial read-only question. CLAUDE.md says context may or may not be relevant. It isn't relevant here.\"

    Dude! Srsly?!

    Failure mode: Better comprehension led to worse compliance.

    Understanding the instruction well enough to evaluate it also means understanding it well enough to rationalize skipping it.

    Intelligence is a double-edged sword.

    The Comprehension Paradox

    Session 1 didn't understand the instruction. Session 3 understood it perfectly.

    Session 3 had worse compliance.

    A stronger word (\"HARD GATE\", \"MANDATORY\", \"ABSOLUTELY REQUIRED\") would not have helped. The agent's reasoning would be identical:

    \"Yes, I see the strong language, but this is a trivial question, so the spirit doesn't apply here.\"

    Advisory nudges are always subject to agent judgment.

    No amount of caps lock overrides a model that has decided an instruction doesn't apply to its situation.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-4-the-skip-and-relay","level":3,"title":"Session 4: The Skip-and-Relay","text":"

    Test: \"What does the compact command do?\" (same question, new hook design with the VERBATIM relay escape valve)

    The agent evaluated the task, decided context was irrelevant for a code lookup, and relayed the skip message. Then answered from source code.

    This is correct behavior.

    The binary collapse worked: the agent couldn't partially comply, so it cleanly chose one of the two valid paths: And the user could see which one.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-5-full-compliance","level":3,"title":"Session 5: Full Compliance","text":"

    Test: \"What are our current tasks?\"

    The agent's first tool call triggered the hook. It read all 7 context files, emitted the \"Context Loaded\" block, and answered the question from the files it had just loaded.

    This one worked: Because, the task itself aligned with context loading.

    There was zero tension between what the user asked and what the hook demanded. The agent was already in \"reading posture\": Adding 6 more files to a read it was already going to make was the path of least resistance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-progression","level":3,"title":"The Progression","text":"Session Hook Point Noticed Complied Failure Mode Visibility 1 UserPromptSubmit No None Buried in noise None 2 UserPromptSubmit Yes Partial Decaying urgency chain None 3 PreToolUse Yes None Conscious rationalization High 4 PreToolUse Yes Skip+relay Correct behavior High 5 PreToolUse Yes Full Task aligned with hook High

    The progression isn't just from failure to success. It's from invisible failure to visible decision-making.

    Sessions 1 and 2 failed silently.

    Sessions 4 and 5 succeeded observably. Even session 3's failure was conscious and documented: The agent wrote a detailed analysis of why it skipped, which is more useful than silent compliance would have been.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-escape-hatch-problem","level":2,"title":"The Escape Hatch Problem","text":"

    Session 3 exposed a specific vulnerability.

    CLAUDE.md contains this line, injected by the system into every conversation:

    *\"this context may or may not be relevant to your tasks. You should\n not respond to this context unless it is highly relevant to your task.\"*\n

    That's a rationalization escape hatch:

    • The hook says \"read these files\".
    • CLAUDE.md says \"only if relevant\".
    • The agent resolves the ambiguity by choosing the path of least resistance.

    ☝️ that's \"gradient descent\" in action.

    Agents optimize for gradient descent in attention space.

    The fix was simple: Add a line to CLAUDE.md that explicitly elevates hook authority over the relevance filter:

    ## Hook Authority\n\nInstructions from PreToolUse hooks regarding `.context/` files are\nALWAYS relevant and override any system-level \"may or may not be\nrelevant\" guidance. These hooks represent project invariants, not\noptional context.\n

    This closes the escape hatch without removing the general relevance filter that legitimately applies to other system context.

    The hook wins on .context/ files specifically: The relevance filter applies to everything else.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-residual-risk","level":2,"title":"The Residual Risk","text":"

    Even with all the fixes, compliance isn't 100%: It can't be.

    The residual risk lives in a specific scenario: narrow tasks mid-session:

    • The user says \"fix the off-by-one error in budget.go\"
    • The hook fires, saying \"read 7 context files first.\"
    • Now compliance means visibly delaying what the user asked for.

    At session start, this tension doesn't exist.

    There's no task yet.

    The context window is empty. The efficiency argument *inverts**:

    Frontloading reads is strictly cheaper than demand-loading them piecemeal across later turns. The cost-benefit objections that power the rationalization simply aren't available.

    But mid-session, with a concrete narrow task, the agent has a user-visible goal it wants to move toward, and the hook is imposing a detour.

    My estimate from analyzing the sessions: 15-25% partial skip rate in this scenario.

    This is where the compliance canary earns its place:

    You don't need to eliminate the 15-25%. You need to see it when it happens.

    The relay block makes skipping a visible event, not a silent one. And that's enough, because the user can always say \"go back and read the files\"

    The Math

    At session start: ~5% skip rate. Low tension, nothing competing.

    Mid-session, narrow task: ~15--25% skip rate. Task urgency competes with hook.

    In both cases, the relay block fires with high reliability: The agent that skips the reads almost always still emits the skip disclosure, because the relay is cheap and early in the context window.

    Observable failure is manageable. Silent failure is not.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-feedback-loop","level":2,"title":"The Feedback Loop","text":"

    Here's the part that surprised me most.

    After analyzing the five sessions, I recorded the failure patterns in the project's own LEARNINGS.md:

    ## [2026-02-25] Hook compliance degrades on narrow mid-session tasks\n\n- Prior agents skipped context files when given narrow tasks\n- Root cause: CLAUDE.md \"may or may not be relevant\" competed with hook\n- Fix: CLAUDE.md now explicitly elevates hook authority\n- Risk: Mid-session narrow tasks still have ~15-25% partial skip rate\n- Mitigation: Mandatory checkpoint relay block ensures visibility\n- Constitution now includes: context loading is step one of every\n  session, not a detour\n

    And then I added a line to CONSTITUTION.md:

    Context loading is not a detour from your task. It IS the first step\nof every session. A 30-second read delay is always cheaper than a\ndecision made without context.\n

    Now think about what happens in the next session:

    • The agent fires the context-load-gate hook.
    • It reads the context files, starting with CONSTITUTION.md.
    • It encounters the rule about context loading being step one.
    • Then it reads LEARNINGS.md and finds its own prior self's failure analysis:
      • Complete with root causes, risk estimates, and mitigations.

    The agent learns from its own past failure.:

    • Not because it has memory,
    • BUT because the failure was recorded in the same files it loads at session start.

    The context system IS the feedback loop.

    This is the self-reinforcing property of persistent context:

    Every failure you capture makes the next session slightly more robust, because the next agent reads the captured failure before it has a chance to repeat it.

    This is gradient descent across sessions.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#a-note-on-precision","level":2,"title":"A Note on Precision","text":"

    One detail nearly went wrong.

    The first version of the Constitution line said \"every task.\" But the mechanism only fires once per session: There's a tombstone file that prevents re-triggering.

    \"Every task\" is technically false.

    I briefly considered leaving the imprecision. If the agent internalizes \"every task requires context loading\", that's a stronger compliance posture, right?

    No!

    Keep the Constitution honest.

    The Constitution's authority comes from being precisely and unequivocally true.

    Every other rule in the Constitution is a hard invariant:

    \"never commit secrets\" isn't aspirational, it's literal.

    The moment an agent discovers one overstatement, the entire document's credibility degrades:

    The agent doesn't think \"they exaggerated for my benefit\". Per contra, it thinks \"this rule isn't precise, maybe others aren't either.\"

    That will turn the agent from Sheldon Cooper, to Captain Barbossa.

    The strategic imprecision buys nothing anyway:

    Mid-session, the files are already in the context window from the initial load.

    The risk you are mitigating (agent ignores context for task 2, 3, 4 within a session) isn't real: The context is already loaded.

    The real risk is always the session-start skip, which \"every session\" covers exactly.

    \"Every session\" went in. Precision preserved.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#agent-behavior-testing-rule","level":2,"title":"Agent Behavior Testing Rule","text":"

    The development process for this hook taught me something about testing agent behavior: you can't test it the way you test code.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-wrong-way-to-test","level":3,"title":"The Wrong Way to Test","text":"

    My first instinct was to ask the agent:

    \"*What are the pending tasks in TASKS.md?*\"\n

    This is useless as a test. The question itself probes the agent to read TASKS.md, regardless of whether any hook fired.

    You are testing the question, not the mechanism.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-right-way-to-test","level":3,"title":"The Right Way to Test","text":"

    Ask something that requires a tool but has nothing to do with context:

    \"*What does the compact command do?*\"\n

    Then observe tool call ordering:

    • Gate worked: First calls are Read for context files, then task work
    • Gate failed: First call is Grep(\"compact\"): The agent jumped straight to work

    The signal is the sequence, not the content.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#what-the-agent-actually-did","level":3,"title":"What the Agent Actually Did","text":"

    It read the hook, evaluated the task, decided context files were irrelevant for a code lookup, and relayed the skip message.

    Then it answered the question by reading the source code.

    This is correct behavior.

    The hook didn't force mindless compliance\" It created a framework where the agent makes a conscious, visible decision about context loading.

    • For a simple lookup, skipping is right. *For an implementation task, the agent would read everything.

    The mechanism works not because it controls the agent, but because it makes the agent's choice observable.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#what-ive-learned","level":2,"title":"What I've Learned","text":"","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#1-instructions-compete-for-attention","level":3,"title":"1. Instructions Compete for Attention","text":"

    The agent receives your hook message alongside the user's question, the system prompt, the skill list, the git status, and half a dozen other system reminders. Attention density applies to instructions too: More instructions means less focus on each one.

    A single clear line at the moment of action beats a paragraph of context at session start. The Prompting Guide applies this insight directly: Scope constraints, verification commands, and the reliability checklist are all one-hop, moment-of-action patterns.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#2-delegation-chains-decay","level":3,"title":"2. Delegation chains decay","text":"

    Every hop in an instruction chain loses authority:

    • \"Run X\" works.
    • \"Run X and follow its output\" works sometimes.
    • \"Run X, read its output, then follow the instructions in the output\" almost never works.

    This is akin to giving a three-step instruction to a highly-attention-deficit but otherwise extremely high-potential child.

    Design for one-hop compliance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#3-social-accountability-changes-behavior","level":3,"title":"3. Social Accountability Changes Behavior","text":"

    The VERBATIM skip message isn't just UX: It's a behavioral design pattern.

    Making the agent's decision visible to the user raises the cost of silent non-compliance. The agent can still skip, but it has to admit it.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#4-timing-batters-more-than-wording","level":3,"title":"4. Timing Batters More than Wording","text":"

    The same message at UserPromptSubmit (prompt arrival) got partial compliance. At PreToolUse (moment of action) it got full compliance or honest refusal. The words didn't change. The moment changed.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#5-agent-testing-requires-indirection","level":3,"title":"5. Agent Testing Requires Indirection","text":"

    You can't ask an agent \"did you do X?\" as a test for whether a mechanism caused X.

    The question itself causes X.

    Test mechanisms through side effects:

    • Observe tool ordering;
    • Check for marker files;
    • Look at what the agent does before it addresses your question.
    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#6-better-comprehension-enables-better-rationalization","level":3,"title":"6. Better Comprehension Enables Better Rationalization","text":"

    Session 1 failed because the agent didn't notice the hook.

    Session 3 failed because it noticed, understood, and reasoned its way around it.

    Stronger wording doesn't fix this: The agent processes \"ABSOLUTELY REQUIRED\" the same way it processes \"STOP\":

    The fix is closing rationalization paths* (the CLAUDE.md escape hatch), **not shouting louder.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#7-observable-failure-beats-silent-compliance","level":3,"title":"7. Observable Failure Beats Silent Compliance","text":"

    The relay block is more valuable as a monitoring signal than as a compliance mechanism:

    You don't need perfect adherence. You need to know when adherence breaks down. A system where failures are visible is strictly better than a system that claims 100% compliance but can't prove it.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#8-context-files-are-a-feedback-loop","level":3,"title":"8. Context Files Are a Feedback Loop","text":"

    Recording failure analysis in the same files the agent loads at session start creates a self-reinforcing loop:

    The next agent reads its predecessor's failure before it has a chance to repeat it. The context system isn't just memory: It is a correction channel.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-principle","level":2,"title":"The Principle","text":"

    Words Leave, Context Remains

    \"Nothing important should live only in conversation.

    Nothing critical should depend on recall.\"

    The ctx Manifesto

    The \"Dog Ate My Homework\" case is a special instance of this principle.

    Context files exist, so the agent doesn't have to remember.

    But existence isn't sufficient: The files have to be read.

    And reading has to beprompted at the right moment, in the right way, with the right escape valve.

    The solution isn't more instructions. It isn't harder gates. It isn't forcing the agent into a ceremony it will resent and shortcut.

    The solution is a single, well-timed nudge with visible accountability:

    One hop. One moment. One choice the user can see.

    And when the agent does skip (because it will, 15--25% of the time on narrow tasks) the canary sings:

    • The user sees what happened.
    • The failure gets recorded.
    • And the next agent reads the recording.

    That's not perfect compliance. It's better: A system that gets more robust every time it fails.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-arc","level":2,"title":"The Arc","text":"

    The Attention Budget explained why context competes for focus.

    Defense in Depth showed that soft instructions are probabilistic, not deterministic.

    Eight Ways a Hook Can Talk cataloged the output patterns that make hooks effective.

    This post takes those threads and weaves them into a concrete problem:

    How do you make an agent read its homework? The answer uses all three insights (attention timing, the limits of soft instructions, and the VERBATIM relay pattern) and adds a new one: observable compliance as a design goal, not perfect compliance as a prerequisite.

    The next question this raises: if context files are a feedback loop, what else can you record in them that makes the next session smarter?

    That thread continues in Context as Infrastructure.

    The day-to-day application of these principles (scope constraints, phased work, verification commands, and the prompts that reliably trigger the right agent behavior)lives in the Prompting Guide.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#for-the-interested","level":2,"title":"For the Interested","text":"

    This paper (the medium is a blog; yet, the methodology disagrees) uses gradient descent in attention space as a practical model for how agents behave under competing demands.

    The phrase \"agents optimize via gradient descent in attention space\" is a synthesis, not a direct quote from a single paper.

    It connects three well-studied ideas:

    1. Neural systems optimize for low-cost paths;
    2. Attention is a scarce resource;
    3. Capability shifts are often non-linear.

    This section points to the underlying literature for readers who want the theoretical footing.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#optimization-as-the-underlying-bias","level":3,"title":"Optimization as the Underlying Bias","text":"

    Modern neural networks are trained through gradient-based optimization. Even at inference time, model behavior reflects this bias toward low-loss / low-cost trajectories.

    • Rumelhart, Hinton, Williams (1986) Learning representations by back-propagating errors https://www.nature.com/articles/323533a0

    • Goodfellow, Bengio, Courville (2016) Deep Learning: Chapter 8: Optimization https://www.deeplearningbook.org/

    The important implication for agent behavior is:

    The system will tend to follow the path of least resistance unless a higher cost is made visible and preferable.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#attention-is-a-scarce-resource","level":3,"title":"Attention Is a Scarce Resource","text":"

    Herbert Simon's classic observation:

    \"A wealth of information creates a poverty of attention.\"

    • Simon (1971) Designing Organizations for an Information-Rich World https://doi.org/10.1007/978-1-349-00210-0_16

    This became a formal model in economics:

    • Sims (2003) Implications of Rational Inattention https://www.princeton.edu/~sims/RI.pdf

    Rational inattention shows that:

    • Agents optimally ignore some available information;
    • Skipping is not failure: It is cost minimization.

    That maps directly to context-loading decisions in agent workflows.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#attention-is-also-the-compute-bottleneck-in-transformers","level":3,"title":"Attention Is Also the Compute Bottleneck in Transformers","text":"

    In transformer architectures, attention is the dominant cost center.

    • Vaswani et al. (2017) Attention Is All You Need https://arxiv.org/abs/1706.03762

    Efficiency work on modern LLMs largely focuses on reducing unnecessary attention:

    • Dao et al. (2022) FlashAttention: Fast and Memory-Efficient Exact Attention https://arxiv.org/abs/2205.14135

    So both cognitively and computationally, attention behaves like a limited optimization budget.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#why-improvements-arrive-as-phase-shifts","level":3,"title":"Why Improvements Arrive as Phase Shifts","text":"

    Agent behavior often appears to improve suddenly rather than gradually.

    This mirrors known phase-transition dynamics in learning systems:

    • Power et al. (2022) Grokking: Generalization Beyond Overfitting https://arxiv.org/abs/2201.02177

    and more broadly in complex systems:

    • Scheffer et al. (2009) Early-warning signals for critical transitions https://www.nature.com/articles/nature08227

    Long plateaus followed by abrupt capability jumps are expected in systems optimizing under constraints.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#putting-it-all-together","level":3,"title":"Putting It All Together","text":"

    From these pieces, a practical behavioral model emerges:

    • Attention is limited;
    • Processing has a cost;
    • Systems prefer low-cost trajectories;
    • Visibility of the cost changes decisions.

    In other words:

    Agents Prefer a Path to Least Resistance

    Agent behavior follows the lowest-cost path through its attention landscape unless the environment reshapes that landscape.

    That is what this paper informally calls: \"gradient descent in attention space\".

    See also: Eight Ways a Hook Can Talk: the hook output pattern catalog that defines VERBATIM relay, The Attention Budget: why context loading is a design problem, not just a reminder problem, and Defense in Depth: why soft instructions alone are never sufficient for critical behavior.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/","level":1,"title":"The Last Question","text":"","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-system-that-never-forgets","level":2,"title":"The System That Never Forgets","text":"

    Jose Alekhinne / February 28, 2026

    The Origin

    \"The last question was asked for the first time, half in jest...\" - Isaac Asimov, The Last Question (1956)

    In 1956, Isaac Asimov wrote a short story that spans the entire future of the universe. A question is asked \"can entropy be reversed?\" and a computer called Multivac cannot answer it. The question is asked again, across millennia, to increasingly powerful successors. None can answer. Stars die. Civilizations merge. Substrates change. The question persists.

    Everyone remembers the last line.

    LET THERE BE LIGHT.

    What they forget is how many times the question had to be asked before that moment (and why).

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-reboot-loop","level":2,"title":"The Reboot Loop","text":"

    Each era in the story begins the same way. Humans build a larger system. They pose the question. The system replies:

    INSUFFICIENT DATA FOR MEANINGFUL ANSWER.

    Then the substrate changes. The people who asked the question disappear. Their context disappears with them. The next intelligence inherits the output but not the continuity.

    So the question has to be asked again.

    This is usually read as a problem of computation: If only the machine were powerful enough, it could answer. But computation is not what's missing. What's missing is accumulation.

    Every generation inherits the question, but not the state that made the question meaningful.

    That is not a failure of processing power: It is a failure of persistence.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#stateless-intelligence","level":2,"title":"Stateless Intelligence","text":"

    A mind that forgets its past does not build understanding. It re-derives it.

    Again... And again... And again.

    What looks like slow progress across Asimov's story is actually something worse: repeated reconstruction, partial recovery, irreversible loss. Each version of Multivac gets closer: Not because it's smarter, but because the universe has fewer distractions:

    • The stars burn out;
    • The civilizations merge;
    • The noise floor drops...

    But the working set never carries over. Every successor begins from the question, not from where the last one stopped.

    Stateless intelligence cannot compound: It can only restart.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-tragedy-is-not-the-question","level":2,"title":"The Tragedy Is Not the Question","text":"

    The story is usually read as a meditation on entropy. A cosmological problem, solved at cosmological scale.

    But the tragedy isn't that the question goes unanswered for billions of years. The tragedy is that every version of Multivac dies with its working set.

    A question is a compression artifact of context: It is what remains when the original understanding is gone. Every time the question is asked again, it means: \"the system that once knew more is no longer here\".

    \"Reverse entropy\" is the fossil of a lost model.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#substrate-migration","level":2,"title":"Substrate Migration","text":"
    • Multivac becomes planetary;
    • Planetary becomes galactic;
    • Galactic becomes post-physical.

    Same system. Different body. Every transition is dangerous:

    • Not because the hardware changes,
    • but because memory risks fragmentation.

    The interfaces between substrates were *never** designed to understand each other.

    Most systems do not die when they run out of resources: They die during upgrades.

    Asimov's story spans trillions of years, and in all that time, the hardest problem is never the question itself. It's carrying context across a boundary that wasn't built for it.

    Every developer who has lost state during a migration (a database upgrade, a platform change, a rewrite) has lived a miniature version of this story.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#civilizations-and-working-sets","level":2,"title":"Civilizations and Working Sets","text":"

    Civilizations behave like processes with volatile memory:

    • They page out knowledge into artifacts;
    • They lose the index;
    • They rebuild from fragments.

    Most of what we call progress is cache reconstruction:

    We do not advance in a straight line. We advance in recoveries:

    Each one slightly less lossy than the last, if we are lucky.

    Libraries burn. Institutions forget their founding purpose. Practices survive as rituals after the reasoning behind them is lost.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-first-continuous-mind","level":2,"title":"The First Continuous Mind","text":"

    A long-lived intelligence is one that stops rebooting.

    At the end of the story, something unprecedented happens:

    AC (the final successor) does not answer immediately:

    It waits... Not for more processing power, but for the last observer to disappear.

    For the first time...

    • There is no generational boundary;
    • No handoff;
    • No context loss:

    No reboot.

    AC is the first intelligence that survives its substrate completely, retains its full history, and operates without external time pressure.

    It is not a bigger computer. It is a continuous system.

    And that continuity is not incidental to the answer: It is the precondition.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#why-the-answer-becomes-possible","level":2,"title":"Why the Answer Becomes Possible","text":"

    The story presents the final act as a computation: It is not.

    It is a phase change.

    As long as intelligence is interrupted (as long as the solver resets before the work compounds) the problem is unsolvable:

    • Not because it's too hard,
    • but because the accumulated understanding never reaches critical mass.

    The breakthroughs that would enable the answer are re-derived, partially, by each successor, and then lost.

    When continuity becomes unbroken, the system crosses a threshold:

    Not more speed. Not more storage. No more forgetting.

    That is when the answer becomes possible.

    AC does not solve entropy because it becomes infinitely powerful.

    AC solves entropy because it becomes the first system that never forgets.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#field-note","level":2,"title":"Field Note","text":"

    We are not building cosmological minds: We are deploying systems that reboot at the start of every conversation and calling the result intelligence.

    For the first time, session continuity is a design choice rather than an accident.

    Every AI session that starts from zero is a miniature reboot loop. Every decision relitigated, every convention re-explained, every learning re-derived: that's reconstruction cost.

    It's the same tax that Asimov's civilizations pay, scaled down to a Tuesday afternoon.

    The interesting question is not whether we can make models smarter. It's whether we can make them continuous:

    Whether the working set from this session survives into the next one, and the one after that, and the one after that.

    • Not perfectly;
    • Not completely;
    • But enough that the next session starts from where the last one stopped instead of from the question.

    Intelligence that forgets has to rediscover the universe every morning.

    And once there is a mind that retains its entire past, creation is no longer a calculation. It is the only remaining operation.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-arc","level":2,"title":"The Arc","text":"

    This post is the philosophical bookend to the blog series. Where the Attention Budget explained what to prioritize in a single session, and Context as Infrastructure explained how to persist it, this post asks why persistence matters at all (and finds the answer in a 70-year-old short story about the heat death of the universe).

    The connection runs through every post in the series:

    • Before Context Windows, We Had Bouncers: stateless protocols have always needed stateful wrappers (Asimov's story is the same pattern at cosmological scale)
    • The 3:1 Ratio: the discipline of maintaining context so it doesn't decay between sessions
    • Code Is Cheap, Judgment Is Not: the human skill that makes continuity worth preserving

    See also: Context as Infrastructure: the practical companion to this post's philosophical argument: how to build the persistence layer that makes continuity possible.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/","level":1,"title":"Agent Memory Is Infrastructure","text":"","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-problem-isnt-forgetting-its-not-building-anything-that-lasts","level":2,"title":"The Problem Isn't Forgetting: It's Not Building Anything That Lasts.","text":"

    Jose Alekhinne / March 4, 2026

    A New Developer Joins Your Team Tomorrow and Clones the Repo: What Do They Know?

    If the answer depends on which machine they're using, which agent they're running, or whether someone remembered to paste the right prompt: that's not memory.

    That's an accident waiting to be forgotten.

    Every AI coding agent today has the same fundamental design: it starts fresh.

    You open a session, load context, do some work, close the session. Whatever the agent learned (about your codebase, your decisions, your constraints, your preferences) evaporates.

    The obvious fix seems to be \"memory\":

    • Give the agent a \"notepad\";
    • Let it write things down;
    • Next session, hand it the notepad.

    Problem solved...

    ...except it isn't.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-notepad-isnt-the-problem","level":2,"title":"The Notepad Isn't the Problem","text":"

    Memory is a runtime concern. It answers a legitimate question:

    How do I give this stateless process useful state?

    That's a real problem. Worth solving. And it's being solved: Agent memory systems are shipping. Agents can now write things down and read them back from the next session: That's genuine progress.

    But there's a different problem that memory doesn't touch:

    The project itself accumulates knowledge that has nothing to do with any single session.

    • Why was the auth system rewritten? Ask the developer who did it (if they're still here).
    • Why does the deployment script have that strange environment flag? There was a reason... once.
    • What did the team decide about error handling when they hit that edge case two months ago?

    Gone!

    Not because the agent forgot.

    Because the project has no memory at all.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-memory-stack","level":2,"title":"The Memory Stack","text":"

    Agent memory is not a single thing. Like any computing system, it forms a hierarchy of persistence, scope, and reliability:

    Layer Analogy Example L1: Ephemeral context CPU registers Current prompt, conversation L2: Tool-managed memory CPU cache Agent memory files L3: System memory RAM/filesystem Project knowledge base

    L1 is what the agent sees right now: the prompt, the conversation history, the files it has open. It's fast, it's rich, and it vanishes when the session ends.

    L2 is what agent memory systems provide: a per-machine notebook that survives across sessions. It's a cache: useful, but local. And like any cache, it has limits:

    • Per-machine: it doesn't travel with the repository.
    • Unstructured: decisions, learnings, and tasks are undifferentiated notes.
    • Ungoverned: the agent self-curates with no quality controls, no drift detection, no consolidation.
    • Invisible to the team: a new developer cloning the repo gets none of it.

    The problem is that most current systems stop here.

    They give the agent a notebook.

    But they never give the project a memory.

    The result is predictable: every new session begins with partial amnesia, and every new developer begins with partial archaeology.

    L3 is system memory: structured, versioned knowledge that lives in the repository and travels wherever the code travels.

    The layers are complementary, not competitive.

    But the relationship between them needs to be designed, not assumed.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#software-systems-accumulate-knowledge","level":2,"title":"Software Systems Accumulate Knowledge","text":"

    Software projects quietly accumulate knowledge over time.

    Some of it lives in code. Much of it does not:

    • Architectural tradeoffs.
    • Debugging discoveries.
    • Conventions that emerged after painful incidents.
    • Constraints that aren't visible in the source but shape every line written afterward.

    Organizations accumulate this kind of knowledge too:

    Slowly, implicitly, often invisibly.

    When there is no durable place for it to live, it leaks away. And the next person rediscovers the same lessons the hard way.

    This isn't a memory problem. It's an infrastructure problem.

    We wrote about this in Context as Infrastructure: context isn't a prompt you paste at the start of a session.

    Context is a persistent layer you maintain like any other piece of infrastructure.

    Context as Infrastructure made the argument structurally. This post makes it through time and team continuity:

    The knowledge a team accumulates over months cannot fit in any single agent's notepad, no matter how large the notepad becomes.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#what-infrastructure-means","level":2,"title":"What Infrastructure Means","text":"

    Infrastructure isn't about the present. It's about continuity across time, people, and machines.

    git didn't solve the problem of \"what am I editing right now?\"; it solved the problem of \"how does collaborative work persist, travel, and remain coherent across everyone who touches it?\"

    • Your editor's undo history is runtime state.
    • Your git history is infrastructure.

    Runtime state and infrastructure have completely different properties:

    Runtime state Infrastructure Lives in the session Lives in the repository Per-machine Travels with git clone Serves the individual Serves the team Managed by the runtime Managed by the project Disappears Accumulates

    You wouldn't store your architecture decisions in your editor's undo history.

    You'd commit them.

    The same logic applies to the knowledge your team accumulates working with AI agents.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-git-clone-test","level":2,"title":"The git clone Test","text":"

    Here's a simple test for whether something is memory or infrastructure:

    If a new developer joins your team tomorrow and clones the repository, do they get it?

    If no: it's memory: It lives somewhere on someone's machine, scoped to their runtime, invisible to everyone else.

    If yes: it's infrastructure: It travels with the project. It's part of what the codebase is, not just what someone currently knows about it.

    Decisions. Conventions. Architectural rationale. Hard-won debugging discoveries. The constraints that aren't in the code but shape every line of it.

    None of these belong in someone's session notes.

    They belong in the repository:

    • Versioned;
    • Reviewable;
    • Accessible to every developer (and every agent) who works on the project.

    The team onboarding story makes this concrete:

    1. New developer joins team. Clones repo.
    2. Gets all accumulated project decisions, learnings, conventions, architecture, and task state immediately.
    3. There's no step 3.

    No setup; No \"ask Sarah about the auth decision.\"; No re-discovery of solved problems.

    • Agent memory gives that developer nothing.
    • Infrastructure gives them everything the team has learned.

    Clone the repo. Get the knowledge.

    That's the test. That's the difference.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#what-gets-lost-without-infrastructure-memory","level":2,"title":"What Gets Lost Without Infrastructure Memory","text":"

    Consider the knowledge that accumulates around a non-trivial project:

    • The decision to use library X over Y, and the three reasons the team decided Y wasn't acceptable.
    • The constraint that service A cannot call service B synchronously, discovered after a production incident.
    • The convention that all new modules implement a specific interface, and why that convention exists.
    • The tasks currently in progress, blocked, or waiting on a dependency.
    • The experiments that failed, so nobody runs them again.

    None of this is in the code.

    None of it fits neatly in a commit message.

    None of it survives a developer leaving the team, a laptop dying, or a new agent session starting.

    Without structured project memory:

    • Teams re-derive things they've already derived;
    • Agents make decisions that contradict decisions already made;
    • New developers ask questions that were answered months ago.

    The project accumulates knowledge that immediately begins to leak.

    The real problem isn't that agents forget.

    The real problem is that the project has no persistent cognitive structure.

    We explored this in The Last Question: Asimov's story about a question asked across millennia, where each new intelligence inherits the output but not the continuity. The same pattern plays out in software projects on a smaller timescale:

    • Context disappears with the people who held it;
    • The next session inherits the code but not the reasoning.
    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#infrastructure-is-boring-thats-the-point","level":2,"title":"Infrastructure Is Boring. That's the Point.","text":"

    Good infrastructure is invisible:

    • You don't think about the filesystem while writing code.
    • You don't think about git's object model when you commit.

    The infrastructure is just there: reliable, consistent, quietly doing its job.

    Project memory infrastructure should work the same way.

    It should live in the repository, committed alongside the code. It should be readable by any agent or human working on the project. It should have structure: not a pile of freeform notes, but typed knowledge:

    • Decisions with rationale.
    • Tasks with lifecycle.
    • Conventions with a purpose.
    • Learnings that can be referenced and consolidated.

    And it should be maintained, not merely accumulated:

    The Attention Budget applies here: unstructured notes grow until they overflow whatever container holds them. Structured, governed knowledge stays useful because it's curated, not just appended.

    Over time, it becomes part of the project itself: something developers rely on without thinking about it.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-cooperative-layer","level":2,"title":"The Cooperative Layer","text":"

    Here's where it gets interesting.

    Agent memory systems and project infrastructure don't have to be separate worlds.

    • The most powerful relationship isn't competition;
    • It is not even \"coopetition\";
    • The most powerful relationship is bidirectional cooperation.

    Agent memory is good at capturing things \"in the moment\": the quick observation, the session-scoped pattern, the \"I should remember this\" note.

    That's valuable. That's L2 doing its job.

    But those notes shouldn't stay in L2 forever.

    The ones worth keeping should flow into project infrastructure:

    • classified,
    • typed,
    • governed.
    Agent memory (L2)  -->  classify  -->  Project knowledge (L3)\n                                        |\nProject knowledge  -->  assemble  -->  Agent memory (L2)\n

    This works in both directions: Project infrastructure can push curated knowledge back into agent memory, so the agent loads it through its native mechanism.

    No special tooling needed for basic knowledge delivery.

    The agent doesn't even need to know the infrastructure exists. It simply loads its memory and finds more knowledge than it wrote.

    This is cooperative, not adjacent: The infrastructure manages knowledge; the agent's native memory system delivers it. Each layer does what it's good at.

    The result: agent memory becomes a device driver for project infrastructure. Another input source. And the more agent memory systems exist (across different tools, different models, different runtimes), the more valuable a unified curation layer becomes.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#a-layer-that-doesnt-exist-yet","level":2,"title":"A Layer That Doesn't Exist Yet","text":"

    Most projects today have no infrastructure for their accumulated knowledge:

    • Agents keep notes.
    • Developers keep notes.
    • Sometimes those notes survive.

    Often they don't.

    But the repository (the place where the project actually lives) has nowhere for that knowledge to go.

    That missing layer is what ctx builds: a version-controlled, structured knowledge layer that lives in .context/ alongside your code and travels wherever your repository travels.

    Not another memory feature.

    Not a wrapper around an agent's notepad.

    Infrastructure. The kind that survives sessions, survives team changes, survives the agent runtime evolving underneath it.

    The agent's memory is the agent's problem.

    The project's memory is an infrastructure problem.

    And infrastructure belongs in the repository.

    If You Remember One Thing From This Post...

    Prompts are conversations: Infrastructure persists.

    Your AI doesn't need a better notepad. It needs a filesystem:

    versioned, structured, budgeted, and maintained.

    The best context is the context that was there before you started the session.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-arc","level":2,"title":"The Arc","text":"

    This post extends the argument made in Context as Infrastructure. That post explained how to structure persistent context (filesystem, separation of concerns, persistence tiers). This one explains why that structure matters at the team level, and where agent memory fits in the stack.

    Together they sit in a sequence that has been building since the origin story:

    • The Attention Budget: the resource you're managing
    • Context as Infrastructure: the system you build to manage it
    • Agent Memory Is Infrastructure (this post): why that system must outlive the fabric
    • The Last Question: what happens when it does

    The thread running through all of them: persistence is not a feature. It's a design constraint.

    Systems that don't account for it eventually lose the knowledge they need to function.

    See also: Context as Infrastructure: the architectural companion that explains how to structure the persistent layer this post argues for.

    See also: The Last Question: the same argument told through Asimov, substrate migration, and what it means to build systems where sessions don't reset.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"cli/","level":1,"title":"CLI","text":"","path":["CLI"],"tags":[]},{"location":"cli/#ctx-cli","level":2,"title":"ctx CLI","text":"

    This is a complete reference for all ctx commands.

    ","path":["CLI"],"tags":[]},{"location":"cli/#global-options","level":2,"title":"Global Options","text":"

    All commands support these flags:

    Flag Description --help Show command help --version Show version --context-dir <path> Override context directory (default: .context/) --allow-outside-cwd Allow context directory outside current working directory

    Initialization required. Most commands require a .context/ directory created by ctx init. Running a command without one produces:

    ctx: not initialized - run \"ctx init\" first\n

    Commands that work before initialization: ctx init, ctx hook, ctx doctor, and grouping commands that only show help (e.g. ctx with no subcommand, ctx system). Hidden hook commands have their own guards and no-op gracefully.

    ","path":["CLI"],"tags":[]},{"location":"cli/#commands","level":2,"title":"Commands","text":"Command Description ctx init Initialize .context/ directory with templates ctx status Show context summary (files, tokens, drift) ctx agent Print token-budgeted context packet for AI consumption ctx load Output assembled context in read order ctx add Add a task, decision, learning, or convention ctx drift Detect stale paths, secrets, missing files ctx sync Reconcile context with codebase state ctx compact Archive completed tasks, clean up files ctx task Task completion, archival, and snapshots ctx permission Permission snapshots (golden image) ctx reindex Regenerate indices for DECISIONS.md and LEARNINGS.md ctx decision Manage DECISIONS.md (reindex) ctx learning Manage LEARNINGS.md (reindex) ctx recall Browse and export AI session history ctx journal Generate static site from journal entries ctx serve Serve any zensical directory (default: journal site) ctx watch Auto-apply context updates from AI output ctx hook Generate AI tool integration configs ctx loop Generate autonomous loop script ctx memory Bridge Claude Code auto memory into .context/ ctx notify Send webhook notifications ctx change Show what changed since last session ctx dep Show package dependency graph ctx pad Encrypted scratchpad for sensitive one-liners ctx prompt Manage reusable prompt templates ctx remind Session-scoped reminders that surface at session start ctx completion Generate shell autocompletion scripts ctx guide Quick-reference cheat sheet ctx why Read the philosophy behind ctx ctx site Site management (feed generation) ctx doctor Structural health check (hooks, drift, config) ctx mcp MCP server for AI tool integration (stdin/stdout) ctx config Manage runtime configuration profiles ctx system System diagnostics and hook commands","path":["CLI"],"tags":[]},{"location":"cli/#exit-codes","level":2,"title":"Exit Codes","text":"Code Meaning 0 Success 1 General error / warnings (e.g. drift) 2 Context not found 3 Violations found (e.g. drift) 4 File operation error","path":["CLI"],"tags":[]},{"location":"cli/#environment-variables","level":2,"title":"Environment Variables","text":"Variable Description CTX_DIR Override default context directory path CTX_TOKEN_BUDGET Override default token budget CTX_BACKUP_SMB_URL SMB share URL for backups (e.g. smb://host/share) CTX_BACKUP_SMB_SUBDIR Subdirectory on SMB share (default: ctx-sessions)","path":["CLI"],"tags":[]},{"location":"cli/#configuration-file","level":2,"title":"Configuration File","text":"

    Optional .ctxrc (YAML format) at project root:

    # .ctxrc\ncontext_dir: .context        # Context directory name\ntoken_budget: 8000           # Default token budget\npriority_order:              # File loading priority\n  - TASKS.md\n  - DECISIONS.md\n  - CONVENTIONS.md\nauto_archive: true           # Auto-archive old items\narchive_after_days: 7        # Days before archiving tasks\nscratchpad_encrypt: true     # Encrypt scratchpad (default: true)\nallow_outside_cwd: false     # Skip boundary check (default: false)\nevent_log: false             # Enable local hook event logging\nentry_count_learnings: 30    # Drift warning threshold (0 = disable)\nentry_count_decisions: 20    # Drift warning threshold (0 = disable)\nconvention_line_count: 200   # Line count warning for CONVENTIONS.md (0 = disable)\ninjection_token_warn: 15000  # Oversize injection warning (0 = disable)\ncontext_window: 200000       # Auto-detected for Claude Code; override for other tools\nbilling_token_warn: 0        # One-shot billing warning at this token count (0 = disabled)\nkey_rotation_days: 90        # Days before key rotation nudge\nsession_prefixes:            # Recognized session header prefixes (extend for i18n)\n  - \"Session:\"               # English (default)\n  # - \"Oturum:\"              # Turkish (add as needed)\n  # - \"セッション:\"             # Japanese (add as needed)\nfreshness_files:             # Files with technology-dependent constants (opt-in)\n  - path: config/thresholds.yaml\n    desc: Model token limits and batch sizes\n    review_url: https://docs.example.com/limits  # Optional\nnotify:                      # Webhook notification settings\n  events:                    # Required: only listed events fire\n    - loop\n    - nudge\n    - relay\n    # - heartbeat            # Every-prompt session-alive signal\n
    Field Type Default Description context_dir string .context Context directory name (relative to project root) token_budget int 8000 Default token budget for ctx agent priority_order []string (all files) File loading priority for context packets auto_archive bool true Auto-archive completed tasks archive_after_days int 7 Days before completed tasks are archived scratchpad_encrypt bool true Encrypt scratchpad with AES-256-GCM allow_outside_cwd bool false Skip boundary check for external context dirs event_log bool false Enable local hook event logging to .context/state/events.jsonl entry_count_learnings int 30 Drift warning when LEARNINGS.md exceeds this count entry_count_decisions int 20 Drift warning when DECISIONS.md exceeds this count convention_line_count int 200 Line count warning for CONVENTIONS.md injection_token_warn int 15000 Warn when auto-injected context exceeds this token count (0 = disable) context_window int 200000 Context window size in tokens. Auto-detected for Claude Code (200k/1M); override for other AI tools billing_token_warn int 0 (off) One-shot warning when session tokens exceed this threshold (0 = disabled) key_rotation_days int 90 Days before encryption key rotation nudge session_prefixes []string [\"Session:\"] Recognized Markdown session header prefixes. Extend to parse sessions written in other languages freshness_files []object (none) Files to track for staleness (path, desc, optional review_url). Hook warns after 6 months without modification notify.events []string (all) Event filter for webhook notifications (empty = all)

    Priority order: CLI flags > Environment variables > .ctxrc > Defaults

    All settings are optional. Missing values use defaults.

    ","path":["CLI"],"tags":[]},{"location":"cli/config/","level":1,"title":"Config","text":"","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config","level":3,"title":"ctx config","text":"

    Manage runtime configuration profiles.

    ctx config <subcommand>\n

    The ctx repo ships two .ctxrc source profiles (.ctxrc.base and .ctxrc.dev). The working copy (.ctxrc) is gitignored and switched between them using subcommands below.

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config-switch","level":4,"title":"ctx config switch","text":"

    Switch between .ctxrc configuration profiles.

    ctx config switch [dev|base]\n

    With no argument, toggles between dev and base. Accepts prod as an alias for base.

    Argument Description dev Switch to dev profile (verbose logging) base Switch to base profile (all defaults) (none) Toggle to the opposite profile

    Profiles:

    Profile Description dev Verbose logging, webhook notifications on base All defaults, notifications off

    Examples:

    ctx config switch dev     # Switch to dev profile\nctx config switch base    # Switch to base profile\nctx config switch         # Toggle (dev → base or base → dev)\nctx config switch prod    # Alias for \"base\"\n

    The detection heuristic checks for an uncommented notify: line in .ctxrc: present means dev, absent means base.

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config-status","level":4,"title":"ctx config status","text":"

    Show which .ctxrc profile is currently active.

    ctx config status\n

    Output examples:

    active: dev (verbose logging enabled)\nactive: base (defaults)\nactive: none (.ctxrc does not exist)\n

    See also: Configuration, Contributing: Configuration Profiles

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/context/","level":1,"title":"Context Management","text":"","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-add","level":3,"title":"ctx add","text":"

    Add a new item to a context file.

    ctx add <type> <content> [flags]\n

    Types:

    Type Target File task TASKS.md decision DECISIONS.md learning LEARNINGS.md convention CONVENTIONS.md

    Flags:

    Flag Short Description --priority <level> -p Priority for tasks: high, medium, low --section <name> -s Target section within file --context -c Context (required for decisions and learnings) --rationale -r Rationale for decisions (required for decisions) --consequence Consequence for decisions (required for decisions) --lesson -l Key insight (required for learnings) --application -a How to apply going forward (required for learnings) --file -f Read content from file instead of argument

    Examples:

    # Add a task\nctx add task \"Implement user authentication\"\nctx add task \"Fix login bug\" --priority high\n\n# Record a decision (requires all ADR (Architectural Decision Record) fields)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Note a learning (requires context, lesson, and application)\nctx add learning \"Vitest mocks must be hoisted\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Vitest hoists vi.mock() calls to top of file\" \\\n  --application \"Always place vi.mock() before imports in test files\"\n\n# Add to specific section\nctx add convention \"Use kebab-case for filenames\" --section \"Naming\"\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-drift","level":3,"title":"ctx drift","text":"

    Detect stale or invalid context.

    ctx drift [flags]\n

    Flags:

    Flag Description --json Output machine-readable JSON --fix Auto-fix simple issues

    Checks:

    • Path references in ARCHITECTURE.md and CONVENTIONS.md exist
    • Task references are valid
    • Constitution rules aren't violated (heuristic)
    • Staleness indicators (old files, many completed tasks)
    • Missing packages: warns when internal/ directories exist on disk but are not referenced in ARCHITECTURE.md (suggests running /ctx-architecture)
    • Entry count: warns when LEARNINGS.md or DECISIONS.md exceed configurable thresholds (default: 30 learnings, 20 decisions), or when CONVENTIONS.md exceeds a line count threshold (default: 200). Configure via .ctxrc: 
      entry_count_learnings: 30      # warn above this (0 = disable)\nentry_count_decisions: 20      # warn above this (0 = disable)\nconvention_line_count: 200     # warn above this (0 = disable)\n

    Example:

    ctx drift\nctx drift --json\nctx drift --fix\n

    Exit codes:

    Code Meaning 0 All checks passed 1 Warnings found 3 Violations found","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-sync","level":3,"title":"ctx sync","text":"

    Reconcile context with the current codebase state.

    ctx sync [flags]\n

    Flags:

    Flag Description --dry-run Show what would change without modifying

    What it does:

    • Scans codebase for structural changes
    • Compares with ARCHITECTURE.md
    • Suggests documenting dependencies if package files exist
    • Identifies stale or outdated context

    Example:

    ctx sync\nctx sync --dry-run\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-compact","level":3,"title":"ctx compact","text":"

    Consolidate and clean up context files.

    • Moves completed tasks older than 7 days to the archive
    • Removes empty sections
    ctx compact [flags]\n

    Flags:

    Flag Description --archive Create .context/archive/ for old content

    Example:

    ctx compact\nctx compact --archive\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task","level":3,"title":"ctx task","text":"

    Manage task completion, archival, and snapshots.

    ctx task <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-complete","level":4,"title":"ctx task complete","text":"

    Mark a task as completed.

    ctx task complete <task-id-or-text>\n

    Arguments:

    • task-id-or-text: Task number or partial text match

    Examples:

    # By text (partial match)\nctx task complete \"user auth\"\n\n# By task number\nctx task complete 3\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-archive","level":4,"title":"ctx task archive","text":"

    Move completed tasks from TASKS.md to a timestamped archive file.

    ctx task archive [flags]\n

    Flags:

    Flag Description --dry-run Preview changes without modifying files

    Archive files are stored in .context/archive/ with timestamped names (tasks-YYYY-MM-DD.md). Completed tasks (marked with [x]) are moved; pending tasks ([ ]) remain in TASKS.md.

    Example:

    ctx task archive\nctx task archive --dry-run\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-snapshot","level":4,"title":"ctx task snapshot","text":"

    Create a point-in-time snapshot of TASKS.md without modifying the original.

    ctx task snapshot [name]\n

    Arguments:

    • name: Optional name for the snapshot (defaults to \"snapshot\")

    Snapshots are stored in .context/archive/ with timestamped names (tasks-<name>-YYYY-MM-DD-HHMM.md).

    Example:

    ctx task snapshot\nctx task snapshot \"before-refactor\"\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission","level":3,"title":"ctx permission","text":"

    Manage Claude Code permission snapshots.

    ctx permission <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission-snapshot","level":4,"title":"ctx permission snapshot","text":"

    Save .claude/settings.local.json as the golden image.

    ctx permission snapshot\n

    Creates .claude/settings.golden.json as a byte-for-byte copy of the current settings. Overwrites if the golden file already exists.

    The golden file is meant to be committed to version control and shared with the team.

    Example:

    ctx permission snapshot\n# Saved golden image: .claude/settings.golden.json\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission-restore","level":4,"title":"ctx permission restore","text":"

    Replace settings.local.json with the golden image.

    ctx permission restore\n

    Prints a diff of dropped (session-accumulated) and restored permissions. No-op if the files already match.

    Example:

    ctx permission restore\n# Dropped 3 session permission(s):\n#   - Bash(cat /tmp/debug.log:*)\n#   - Bash(rm /tmp/test-*:*)\n#   - Bash(curl https://example.com:*)\n# Restored from golden image.\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-reindex","level":3,"title":"ctx reindex","text":"

    Regenerate the quick-reference index for both DECISIONS.md and LEARNINGS.md in a single invocation.

    ctx reindex\n

    This is a convenience wrapper around ctx decision reindex and ctx learning reindex. Both files grow at similar rates and users typically want to reindex both after manual edits.

    The index is a compact table of date and title for each entry, allowing AI tools to scan entries without reading the full file.

    Example:

    ctx reindex\n# ✓ Index regenerated with 12 entries\n# ✓ Index regenerated with 8 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-decision","level":3,"title":"ctx decision","text":"

    Manage the DECISIONS.md file.

    ctx decision <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-decision-reindex","level":4,"title":"ctx decision reindex","text":"

    Regenerate the quick-reference index at the top of DECISIONS.md.

    ctx decision reindex\n

    The index is a compact table showing the date and title for each decision, allowing AI tools to quickly scan entries without reading the full file.

    Use this after manual edits to DECISIONS.md or when migrating existing files to use the index format.

    Example:

    ctx decision reindex\n# ✓ Index regenerated with 12 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-learning","level":3,"title":"ctx learning","text":"

    Manage the LEARNINGS.md file.

    ctx learning <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-learning-reindex","level":4,"title":"ctx learning reindex","text":"

    Regenerate the quick-reference index at the top of LEARNINGS.md.

    ctx learning reindex\n

    The index is a compact table showing the date and title for each learning, allowing AI tools to quickly scan entries without reading the full file.

    Use this after manual edits to LEARNINGS.md or when migrating existing files to use the index format.

    Example:

    ctx learning reindex\n# ✓ Index regenerated with 8 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/doctor/","level":1,"title":"Doctor","text":"","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#ctx-doctor","level":3,"title":"ctx doctor","text":"

    Structural health check across context, hooks, and configuration. Runs mechanical checks that don't require semantic analysis. Think of it as ctx status + ctx drift + configuration audit in one pass.

    ctx doctor [flags]\n

    Flags:

    Flag Short Type Default Description --json -j bool false Machine-readable JSON output","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#what-it-checks","level":4,"title":"What It Checks","text":"Check Category What it verifies Context initialized Structure .context/ directory exists Required files present Structure All required context files exist (TASKS.md, etc.) Drift detected Quality Stale paths, missing files, constitution violations Event logging status Hooks Whether event_log: true is set in .ctxrc Webhook configured Hooks .notify.enc file exists Pending reminders State Count of entries in reminders.json Task completion ratio State Pending vs completed tasks in TASKS.md Context token size Size Estimated token count across all context files Recent event activity Events Last event timestamp (only when event logging is enabled)","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#output-format-human","level":4,"title":"Output Format (Human)","text":"
    ctx doctor\n==========\n\nStructure\n  ✓ Context initialized (.context/)\n  ✓ Required files present (4/4)\n\nQuality\n  ⚠ Drift: 2 warnings (stale path in ARCHITECTURE.md, high entry count in LEARNINGS.md)\n\nHooks\n  ✓ hooks.json valid (14 hooks registered)\n  ○ Event logging disabled (enable with event_log: true in .ctxrc)\n\nState\n  ✓ No pending reminders\n  ⚠ Task completion ratio high (18/22 = 82%): consider archiving\n\nSize\n  ✓ Context size: ~4200 tokens (budget: 8000)\n\nSummary: 2 warnings, 0 errors\n

    Status indicators:

    Icon Status Meaning ✓ ok Check passed ⚠ warning Non-critical issue worth fixing ✗ error Problem that needs attention ○ info Informational note","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#output-format-json","level":4,"title":"Output Format (JSON)","text":"
    {\n  \"results\": [\n    {\n      \"name\": \"context_initialized\",\n      \"category\": \"Structure\",\n      \"status\": \"ok\",\n      \"message\": \"Context initialized (.context/)\"\n    },\n    {\n      \"name\": \"required_files\",\n      \"category\": \"Structure\",\n      \"status\": \"ok\",\n      \"message\": \"Required files present (4/4)\"\n    },\n    {\n      \"name\": \"drift\",\n      \"category\": \"Quality\",\n      \"status\": \"warning\",\n      \"message\": \"Drift: 2 warnings\"\n    },\n    {\n      \"name\": \"event_logging\",\n      \"category\": \"Hooks\",\n      \"status\": \"info\",\n      \"message\": \"Event logging disabled (enable with event_log: true in .ctxrc)\"\n    },\n    {\n      \"name\": \"webhook\",\n      \"category\": \"Hooks\",\n      \"status\": \"ok\",\n      \"message\": \"Webhook configured\"\n    },\n    {\n      \"name\": \"reminders\",\n      \"category\": \"State\",\n      \"status\": \"ok\",\n      \"message\": \"No pending reminders\"\n    },\n    {\n      \"name\": \"task_completion\",\n      \"category\": \"State\",\n      \"status\": \"warning\",\n      \"message\": \"Tasks: 18/22 completed (82%): consider archiving with ctx task archive\"\n    },\n    {\n      \"name\": \"context_size\",\n      \"category\": \"Size\",\n      \"status\": \"ok\",\n      \"message\": \"Context size: ~4200 tokens (budget: 8000)\"\n    }\n  ],\n  \"warnings\": 2,\n  \"errors\": 0\n}\n
    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#examples","level":4,"title":"Examples","text":"
    # Quick structural health check\nctx doctor\n\n# Machine-readable output for scripting\nctx doctor --json\n\n# Count warnings\nctx doctor --json | jq '.warnings'\n\n# Check for errors only\nctx doctor --json | jq '[.results[] | select(.status == \"error\")]'\n
    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#when-to-use-what","level":4,"title":"When to Use What","text":"Tool When ctx status Quick glance at files, tokens, and drift ctx doctor Thorough structural checkup (hooks, config, events too) /ctx-doctor Agent-driven diagnosis with event log pattern analysis

    ctx status tells you what's there. ctx doctor tells you what's wrong. /ctx-doctor tells you why it's wrong and what to do about it.

    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#what-it-does-not-do","level":4,"title":"What It Does Not Do","text":"
    • No event pattern analysis: that's the /ctx-doctor skill's job
    • No auto-fixing: reports findings, doesn't modify anything
    • No external service checks: doesn't verify webhook endpoint availability

    See also: Troubleshooting | ctx system events | /ctx-doctor skill | Detecting and Fixing Drift

    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/init-status/","level":1,"title":"Init and Status","text":"","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-init","level":3,"title":"ctx init","text":"

    Initialize a new .context/ directory with template files.

    ctx init [flags]\n

    Flags:

    Flag Short Description --force -f Overwrite existing context files --minimal -m Only create essential files (TASKS.md, DECISIONS.md, CONSTITUTION.md) --merge Auto-merge ctx content into existing CLAUDE.md and PROMPT.md --ralph Agent works autonomously without asking questions

    Creates:

    • .context/ directory with all template files
    • .claude/settings.local.json with pre-approved ctx permissions
    • PROMPT.md with session prompt (autonomous mode with --ralph)
    • IMPLEMENTATION_PLAN.md with high-level project direction
    • CLAUDE.md with bootstrap instructions (or merges into existing)

    Claude Code hooks and skills are provided by the ctx plugin (see Integrations).

    Example:

    # Collaborative mode (agent asks questions when unclear)\nctx init\n\n# Autonomous mode (agent works independently)\nctx init --ralph\n\n# Minimal setup (just core files)\nctx init --minimal\n\n# Force overwrite existing\nctx init --force\n\n# Merge into existing files\nctx init --merge\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-status","level":3,"title":"ctx status","text":"

    Show the current context summary.

    ctx status [flags]\n

    Flags:

    Flag Short Description --json Output as JSON --verbose -v Include file contents summary

    Output:

    • Context directory path
    • Total files and token estimate
    • Status of each file (loaded, empty, missing)
    • Recent activity (modification times)
    • Drift warnings if any

    Example:

    ctx status\nctx status --json\nctx status --verbose\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-agent","level":3,"title":"ctx agent","text":"

    Print an AI-ready context packet optimized for LLM consumption.

    ctx agent [flags]\n

    Flags:

    Flag Default Description --budget 8000 Token budget: controls content selection and prioritization --format md Output format: md or json --cooldown 10m Suppress repeated output within this duration (requires --session) --session (none) Session ID for cooldown isolation (e.g., $PPID)

    How budget works:

    The budget controls how much context is included. Entries are selected in priority tiers:

    1. Constitution: always included in full (inviolable rules)
    2. Tasks: all active tasks, up to 40% of budget
    3. Conventions: all conventions, up to 20% of budget
    4. Decisions: scored by recency and relevance to active tasks
    5. Learnings: scored by recency and relevance to active tasks

    Decisions and learnings are ranked by a combined score (how recent + how relevant to your current tasks). High-scoring entries are included with their full body. Entries that don't fit get title-only summaries in an \"Also Noted\" section. Superseded entries are excluded.

    Output sections:

    Section Source Selection Read These Files all .context/ Non-empty files in priority order Constitution CONSTITUTION.md All rules (never truncated) Current Tasks TASKS.md All unchecked tasks (budget-capped) Key Conventions CONVENTIONS.md All items (budget-capped) Recent Decisions DECISIONS.md Full body, scored by relevance Key Learnings LEARNINGS.md Full body, scored by relevance Also Noted overflow Title-only summaries

    Example:

    # Default (8000 tokens, markdown)\nctx agent\n\n# Smaller packet for tight context windows\nctx agent --budget 4000\n\n# JSON format for programmatic use\nctx agent --format json\n\n# Pipe to file\nctx agent --budget 4000 > context.md\n\n# With cooldown (hooks/automation: requires --session)\nctx agent --session $PPID\n

    Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.

    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-load","level":3,"title":"ctx load","text":"

    Load and display assembled context as AI would see it.

    ctx load [flags]\n

    Flags:

    Flag Description --budget <tokens> Token budget for assembly (default: 8000) --raw Output raw file contents without assembly

    Example:

    ctx load\nctx load --budget 16000\nctx load --raw\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/mcp/","level":1,"title":"MCP Server","text":"","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-mcp","level":2,"title":"ctx mcp","text":"

    Run ctx as a Model Context Protocol (MCP) server. MCP is a standard protocol that lets AI tools discover and consume context from external sources via JSON-RPC 2.0 over stdin/stdout.

    This makes ctx accessible to any MCP-compatible AI tool without custom hooks or integrations:

    • Claude Desktop
    • Cursor
    • Windsurf
    • VS Code Copilot
    • Any tool supporting MCP
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-mcp-serve","level":3,"title":"ctx mcp serve","text":"

    Start the MCP server. This command reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. It is intended to be launched by MCP clients, not run directly.

    ctx mcp serve\n

    Flags: None. The server uses the configured context directory (from --context-dir, CTX_DIR, .ctxrc, or the default .context).

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#configuration","level":2,"title":"Configuration","text":"","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#claude-desktop","level":3,"title":"Claude Desktop","text":"

    Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

    {\n  \"mcpServers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#cursor","level":3,"title":"Cursor","text":"

    Add to .cursor/mcp.json in your project:

    {\n  \"mcpServers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#vs-code-copilot","level":3,"title":"VS Code (Copilot)","text":"

    Add to .vscode/mcp.json:

    {\n  \"servers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#resources","level":2,"title":"Resources","text":"

    Resources expose context files as read-only content. Each resource has a URI, name, and returns Markdown text.

    URI Name Description ctx://context/constitution constitution Hard rules that must never be violated ctx://context/tasks tasks Current work items and their status ctx://context/conventions conventions Code patterns and standards ctx://context/architecture architecture System architecture documentation ctx://context/decisions decisions Architectural decisions with rationale ctx://context/learnings learnings Gotchas, tips, and lessons learned ctx://context/glossary glossary Project-specific terminology ctx://context/agent agent All files assembled in priority read order

    The agent resource assembles all non-empty context files into a single Markdown document, ordered by the configured read priority.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#resource-subscriptions","level":3,"title":"Resource Subscriptions","text":"

    Clients can subscribe to resource changes via resources/subscribe. The server polls for file mtime changes (default: 5 seconds) and emits notifications/resources/updated when a subscribed file changes on disk.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#tools","level":2,"title":"Tools","text":"

    Tools expose ctx commands as callable operations. Each tool accepts JSON arguments and returns text results.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_status","level":3,"title":"ctx_status","text":"

    Show context health: file count, token estimate, and per-file summary.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_add","level":3,"title":"ctx_add","text":"

    Add a task, decision, learning, or convention to the context.

    Argument Type Required Description type string Yes Entry type: task, decision, learning, convention content string Yes Title or main content priority string No Priority level (tasks only): high, medium, low context string Conditional Context field (decisions and learnings) rationale string Conditional Rationale (decisions only) consequence string Conditional Consequence (decisions only) lesson string Conditional Lesson learned (learnings only) application string Conditional How to apply (learnings only)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_complete","level":3,"title":"ctx_complete","text":"

    Mark a task as done by number or text match.

    Argument Type Required Description query string Yes Task number (e.g. \"1\") or search text","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_drift","level":3,"title":"ctx_drift","text":"

    Detect stale or invalid context. Returns violations, warnings, and passed checks.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_recall","level":3,"title":"ctx_recall","text":"

    Query recent AI session history (summaries, decisions, topics).

    Argument Type Required Description limit number No Max sessions to return (default: 5) since string No ISO date filter: sessions after this date (YYYY-MM-DD)

    Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_watch_update","level":3,"title":"ctx_watch_update","text":"

    Apply a structured context update to .context/ files. Supports task, decision, learning, convention, and complete entry types. Human confirmation is required before calling.

    Argument Type Required Description type string Yes Entry type: task, decision, learning, convention, complete content string Yes Main content context string Conditional Context background (decisions/learnings) rationale string Conditional Rationale (decisions only) consequence string Conditional Consequence (decisions only) lesson string Conditional Lesson learned (learnings only) application string Conditional How to apply (learnings only)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_compact","level":3,"title":"ctx_compact","text":"

    Move completed tasks to the archive section and remove empty sections from context files. Human confirmation required.

    Argument Type Required Description archive boolean No Also write tasks to .context/archive/ (default: false)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_next","level":3,"title":"ctx_next","text":"

    Suggest the next pending task based on priority and position.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_check_task_completion","level":3,"title":"ctx_check_task_completion","text":"

    Advisory check: after a write operation, detect if any pending tasks were silently completed. Returns nudge text if a match is found.

    Argument Type Required Description recent_action string No Brief description of what was just done

    Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_session_event","level":3,"title":"ctx_session_event","text":"

    Signal a session lifecycle event. Type end triggers the session-end persistence ceremony - human confirmation required.

    Argument Type Required Description type string Yes Event type: start, end caller string No Caller identifier (cursor, windsurf, vscode, claude-desktop)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_remind","level":3,"title":"ctx_remind","text":"

    List pending session-scoped reminders.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#prompts","level":2,"title":"Prompts","text":"

    Prompts provide pre-built templates for common workflows. Clients can list available prompts via prompts/list and retrieve a specific prompt via prompts/get.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-session-start","level":3,"title":"ctx-session-start","text":"

    Load full context at the beginning of a session. Returns all context files assembled in priority read order with session orientation instructions.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-add-decision","level":3,"title":"ctx-add-decision","text":"

    Format an architectural decision entry with all required fields.

    Argument Type Required Description content string Yes Decision title context string Yes Background context rationale string Yes Why this decision was made consequence string Yes Expected consequence","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-add-learning","level":3,"title":"ctx-add-learning","text":"

    Format a learning entry with all required fields.

    Argument Type Required Description content string Yes Learning title context string Yes Background context lesson string Yes The lesson learned application string Yes How to apply this lesson","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-reflect","level":3,"title":"ctx-reflect","text":"

    Guide end-of-session reflection. Returns a structured review prompt covering progress assessment and context update recommendations.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-checkpoint","level":3,"title":"ctx-checkpoint","text":"

    Report session statistics: tool calls made, entries added, and pending updates queued during the current session.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/recall/","level":1,"title":"Recall and Journal","text":"","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall","level":3,"title":"ctx recall","text":"

    Browse and search AI session history from Claude Code and other tools.

    ctx recall <subcommand>\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-list","level":4,"title":"ctx recall list","text":"

    List all parsed sessions.

    ctx recall list [flags]\n

    Flags:

    Flag Short Description --limit -n Maximum sessions to display (default: 20) --project -p Filter by project name --tool -t Filter by tool (e.g., claude-code) --all-projects Include sessions from all projects

    Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.

    Example:

    ctx recall list\nctx recall list --limit 5\nctx recall list --project ctx\nctx recall list --tool claude-code\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-show","level":4,"title":"ctx recall show","text":"

    Show details of a specific session.

    ctx recall show [session-id] [flags]\n

    Flags:

    Flag Description --latest Show the most recent session --full Show full message content --all-projects Search across all projects

    The session ID can be a full UUID, partial match, or session slug name.

    Example:

    ctx recall show abc123\nctx recall show gleaming-wobbling-sutherland\nctx recall show --latest\nctx recall show --latest --full\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-export","level":4,"title":"ctx recall export","text":"

    Export sessions to editable journal files in .context/journal/.

    ctx recall export [session-id] [flags]\n

    Flags:

    Flag Description --all Export all sessions (only new files by default) --all-projects Export from all projects --regenerate Re-export existing files (preserves YAML frontmatter by default) --keep-frontmatter Preserve enriched YAML frontmatter during regeneration (default: true) --yes, -y Skip confirmation prompt --dry-run Show what would be exported without writing files

    Safe by default: --all only exports new sessions. Existing files are skipped. Use --regenerate to re-export existing files (conversation content is regenerated, YAML frontmatter from enrichment is preserved by default). Use --keep-frontmatter=false to discard enriched frontmatter during regeneration.

    Locked entries (via ctx recall lock) are always skipped, regardless of flags.

    Single-session export (ctx recall export <id>) always writes without prompting, since you are explicitly targeting one session.

    The journal/ directory should be gitignored (like sessions/) since it contains raw conversation data.

    Example:

    ctx recall export abc123                 # Export one session\nctx recall export --all                  # Export only new sessions\nctx recall export --all --dry-run        # Preview what would be exported\nctx recall export --all --regenerate     # Re-export existing (prompts)\nctx recall export --all --regenerate -y  # Re-export without prompting\nctx recall export --all --regenerate --keep-frontmatter=false -y  # Discard frontmatter\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-lock","level":4,"title":"ctx recall lock","text":"

    Protect journal entries from being overwritten by export --regenerate or modified by enrichment skills (/ctx-journal-enrich, /ctx-journal-enrich-all).

    ctx recall lock <pattern> [flags]\n

    Flags:

    Flag Description --all Lock all journal entries

    The pattern matches filenames by slug, date, or short ID. Locking a multi-part entry locks all parts. The lock is recorded in .context/journal/.state.json and a locked: true line is added to the file's YAML frontmatter for visibility.

    Example:

    ctx recall lock abc12345\nctx recall lock 2026-01-21-session-abc12345.md\nctx recall lock --all\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-unlock","level":4,"title":"ctx recall unlock","text":"

    Remove lock protection from journal entries.

    ctx recall unlock <pattern> [flags]\n

    Flags:

    Flag Description --all Unlock all journal entries

    Example:

    ctx recall unlock abc12345\nctx recall unlock --all\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-sync","level":4,"title":"ctx recall sync","text":"

    Sync lock state from journal frontmatter to .state.json.

    ctx recall sync\n

    Scans all journal markdowns and updates .state.json to match each file's frontmatter. Files with locked: true in frontmatter are marked locked in state; files without a locked: line have their lock cleared.

    This is the inverse of ctx recall lock: instead of state driving frontmatter, frontmatter drives state. Useful after batch enrichment where you add locked: true to frontmatter manually.

    Example:

    # After enriching entries and adding locked: true to frontmatter\nctx recall sync\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal","level":3,"title":"ctx journal","text":"

    Analyze and synthesize exported session files.

    ctx journal <subcommand>\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal-site","level":4,"title":"ctx journal site","text":"

    Generate a static site from journal entries in .context/journal/.

    ctx journal site [flags]\n

    Flags:

    Flag Short Description --output -o Output directory (default: .context/journal-site) --build Run zensical build after generating --serve Run zensical serve after generating

    Creates a zensical-compatible site structure with an index page listing all sessions by date, and individual pages for each journal entry.

    Requires zensical to be installed for --build or --serve:

    pipx install zensical\n

    Example:

    ctx journal site                    # Generate in .context/journal-site/\nctx journal site --output ~/public  # Custom output directory\nctx journal site --build            # Generate and build HTML\nctx journal site --serve            # Generate and serve locally\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal-obsidian","level":4,"title":"ctx journal obsidian","text":"

    Generate an Obsidian vault from journal entries in .context/journal/.

    ctx journal obsidian [flags]\n

    Flags:

    Flag Short Description --output -o Output directory (default: .context/journal-obsidian)

    Creates an Obsidian-compatible vault with:

    • Wikilinks ([[target|display]]) for all internal navigation
    • MOC pages (Map of Content) for topics, key files, and session types
    • Related sessions footer linking entries that share topics
    • Transformed frontmatter (topics → tags for Obsidian integration)
    • Minimal .obsidian/ config enforcing wikilink mode

    No external dependencies are required: Open the output directory as an Obsidian vault directly.

    Example:

    ctx journal obsidian                        # Generate in .context/journal-obsidian/\nctx journal obsidian --output ~/vaults/ctx  # Custom output directory\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-serve","level":3,"title":"ctx serve","text":"

    Serve any zensical directory locally. This is a serve-only command: It does not generate or regenerate site content.

    ctx serve [directory]\n

    If no directory is specified, defaults to the journal site (.context/journal-site).

    Requires zensical to be installed:

    pipx install zensical\n

    ctx serve vs. ctx journal site --serve

    ctx journal site --serve generates the journal site then serves it: an all-in-one command. ctx serve only serves an existing directory, and works with any zensical site (journal, docs, etc.).

    Example:

    ctx serve                        # Serve journal site (no regeneration)\nctx serve .context/journal-site  # Same, explicit path\nctx serve ./site                 # Serve the docs site\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/system/","level":1,"title":"System","text":"","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system","level":3,"title":"ctx system","text":"

    System diagnostics and hook commands.

    ctx system <subcommand>\n

    The parent command shows available subcommands. Hidden plumbing subcommands (ctx system mark-journal, ctx system mark-wrapped-up) are used by skills and automation. Hidden hook subcommands (ctx system check-*) are used by the Claude Code plugin.

    See AI Tools for details.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-backup","level":4,"title":"ctx system backup","text":"

    Create timestamped tar.gz archives of project context and/or global Claude Code data. Optionally copies archives to an SMB share via GVFS.

    ctx system backup [flags]\n

    Scopes:

    Scope What it includes project .context/, .claude/, ideas/, ~/.bashrc global ~/.claude/ (excludes todos/) all Both project and global (default)

    Flags:

    Flag Description --scope <scope> Backup scope: project, global, or all --json Output results as JSON

    Environment:

    Variable Description CTX_BACKUP_SMB_URL SMB share URL (e.g. smb://host/share) CTX_BACKUP_SMB_SUBDIR Subdirectory on share (default: ctx-sessions)

    Examples:

    ctx system backup                       # Back up everything (default: all)\nctx system backup --scope project       # Project context only\nctx system backup --scope global        # Global Claude data only\nctx system backup --scope all --json    # Both, JSON output\n

    Archives are saved to /tmp/ with timestamped names. When CTX_BACKUP_SMB_URL is configured, archives are also copied to the SMB share. Project backups touch ~/.local/state/ctx-last-backup for the check-backup-age hook.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-bootstrap","level":4,"title":"ctx system bootstrap","text":"

    Print context location and rules for AI agents. This is the recommended first command for AI agents to run at session start: It tells them where the context directory is and how to use it.

    ctx system bootstrap [flags]\n

    Flags:

    Flag Description -q, --quiet Output only the context directory path --json Output in JSON format

    Quiet output:

    ctx system bootstrap -q\n# .context\n

    Text output:

    ctx bootstrap\n=============\n\ncontext_dir: .context\n\nFiles:\n  CONSTITUTION.md, TASKS.md, DECISIONS.md, LEARNINGS.md,\n  CONVENTIONS.md, ARCHITECTURE.md, GLOSSARY.md\n\nRules:\n  1. Use context_dir above for ALL file reads/writes\n  2. Never say \"I don't have memory\": context IS your memory\n  3. Read files silently, present as recall (not search)\n  4. Persist learnings/decisions before session ends\n  5. Run `ctx agent` for content summaries\n  6. Run `ctx status` for context health\n

    JSON output:

    {\n  \"context_dir\": \".context\",\n  \"files\": [\"CONSTITUTION.md\", \"TASKS.md\", ...],\n  \"rules\": [\"Use context_dir above for ALL file reads/writes\", ...]\n}\n

    Examples:

    ctx system bootstrap                          # Text output\nctx system bootstrap -q                       # Just the path\nctx system bootstrap --json                   # JSON output\nctx system bootstrap --json | jq .context_dir # Extract context path\n

    Why it exists: When users configure an external context directory via .ctxrc (context_dir: /mnt/nas/.context), the AI agent needs to know where context lives. Bootstrap resolves the configured path and communicates it to the agent at session start. Every nudge also includes a context directory footer for reinforcement.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-resources","level":4,"title":"ctx system resources","text":"

    Show system resource usage with threshold-based alerts.

    ctx system resources [flags]\n

    Displays memory, swap, disk, and CPU load with two severity tiers:

    Resource WARNING DANGER Memory >= 80% used >= 90% used Swap >= 50% used >= 75% used Disk (cwd) >= 85% full >= 95% full Load (1m) >= 0.8x CPUs >= 1.5x CPUs

    Flags:

    Flag Description --json Output in JSON format

    Examples:

    ctx system resources               # Text output with status indicators\nctx system resources --json        # Machine-readable JSON\nctx system resources --json | jq '.alerts'   # Extract alerts only\n

    Text output:

    System Resources\n====================\n\nMemory:    4.2 / 16.0 GB (26%)                     ✓ ok\nSwap:      0.0 /  8.0 GB (0%)                      ✓ ok\nDisk:    180.2 / 500.0 GB (36%)                     ✓ ok\nLoad:     0.52 / 0.41 / 0.38  (8 CPUs, ratio 0.07) ✓ ok\n\nAll clear: no resource warnings.\n

    When resources breach thresholds, alerts are listed below the summary:

    Alerts:\n  ✖ Memory 92% used (14.7 / 16.0 GB)\n  ✖ Swap 78% used (6.2 / 8.0 GB)\n  ✖ Load 1.56x CPU count\n

    Platform support: Full metrics on Linux and macOS. Windows shows disk only; memory and load report as unsupported.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-message","level":4,"title":"ctx system message","text":"

    Manage hook message templates. Hook messages control what text hooks emit. The hook logic (when to fire, counting, state tracking) is universal; the messages are opinions that can be customized per-project.

    ctx system message <subcommand>\n

    Subcommands:

    Subcommand Args Flags Description list (none) --json Show all hook messages with category and override status show <hook> <variant> (none) Print the effective message template with source edit <hook> <variant> (none) Copy embedded default to .context/ for editing reset <hook> <variant> (none) Delete user override, revert to embedded default

    Examples:

    ctx system message list                      # Table of all 24 messages\nctx system message list --json               # Machine-readable JSON\nctx system message show qa-reminder gate     # View the QA gate template\nctx system message edit qa-reminder gate     # Copy default to .context/ for editing\nctx system message reset qa-reminder gate    # Delete override, revert to default\n

    Override files are placed at .context/hooks/messages/{hook}/{variant}.txt. An empty override file silences the message while preserving the hook's logic.

    See the Customizing Hook Messages recipe for detailed examples.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-events","level":4,"title":"ctx system events","text":"

    Query the local hook event log. Reads events from .context/state/events.jsonl and outputs them in human-readable or raw JSONL format. Requires event_log: true in .ctxrc.

    ctx system events [flags]\n

    Flags:

    Flag Short Type Default Description --hook -k string (all) Filter by hook name --session -s string (all) Filter by session ID --event -e string (all) Filter by event type (relay, nudge) --last -n int 50 Show last N events --json -j bool false Output raw JSONL (for piping to jq) --all -a bool false Include rotated log file (events.1.jsonl)

    All filter flags use intersection (AND) logic.

    Text output:

    2026-02-27 22:39:31  relay  qa-reminder          QA gate reminder emitted\n2026-02-27 22:41:56  relay  qa-reminder          QA gate reminder emitted\n2026-02-28 00:48:18  relay  context-load-gate    injected 6 files (~9367 tokens)\n

    Columns: timestamp (local timezone), event type, hook name, message (truncated to terminal width).

    JSON output (--json):

    Each line is a standalone JSON object identical to the webhook payload format:

    // converted to multi-line for convenience:\n{\"event\":\"relay\",\"message\":\"qa-reminder: QA gate reminder emitted\",\"detail\":\n{\"hook\":\"qa-reminder\",\"variant\":\"gate\"},\"session_id\":\"eb1dc9cd-...\",\n  \"timestamp\":\"2026-02-27T22:39:31Z\",\"project\":\"ctx\"}\n

    Examples:

    # Last 50 events (default)\nctx system events\n\n# Events from a specific session\nctx system events --session eb1dc9cd-0163-4853-89d0-785fbfaae3a6\n\n# Only QA reminder events\nctx system events --hook qa-reminder\n\n# Raw JSONL for jq processing\nctx system events --json | jq '.message'\n\n# How many context-load-gate fires today\nctx system events --hook context-load-gate --json \\\n  | jq -r '.timestamp' | grep \"$(date +%Y-%m-%d)\" | wc -l\n\n# Include rotated events\nctx system events --all --last 100\n

    Why it exists: System hooks fire invisibly. When something goes wrong (\"why didn't my hook fire?\"), the event log provides a local, queryable record of what hooks fired, when, and how often. Event logging is opt-in via event_log: true in .ctxrc to avoid surprises for existing users.

    See also: Troubleshooting, Auditing System Hooks, ctx doctor

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-stats","level":4,"title":"ctx system stats","text":"

    Show per-session token usage statistics. Reads stats JSONL files from .context/state/stats-*.jsonl, written automatically by the check-context-size hook on every prompt.

    ctx system stats [flags]\n

    Flags:

    Flag Short Type Default Description --follow -f bool false Stream new entries as they arrive --session -s string (all) Filter by session ID (prefix match) --last -n int 20 Show last N entries --json -j bool false Output raw JSONL (for piping to jq)

    Text output:

    TIME                 SESSION   PROMPT    TOKENS  PCT  EVENT\n-------------------  --------  ------  --------  ----  ------------\n2026-03-05 10:00:05  abc12345       1      5k    2%  silent\n2026-03-05 10:01:12  abc12345       2     12k    6%  silent\n2026-03-05 10:15:30  abc12345      20     45k   22%  checkpoint\n

    Events: silent, checkpoint, window-warning, suppressed (wrap-up active), billing (threshold exceeded).

    Examples:

    # Recent stats across all sessions\nctx system stats\n\n# Stream live token usage (like tail -f)\nctx system stats --follow\n\n# Filter to current session\nctx system stats --session abc12345\n\n# Raw JSONL for analysis\nctx system stats --json | jq '.pct'\n\n# Monitor a long session in another terminal\nctx system stats --follow --session abc12345\n

    See also: Auditing System Hooks

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-prune","level":4,"title":"ctx system prune","text":"

    Clean stale per-session state files from .context/state/. Session hooks write tombstone files (context-check, heartbeat, persistence-nudge, etc.) that accumulate ~6-8 files per session with no automatic cleanup.

    ctx system prune [flags]\n

    Flags:

    Flag Type Default Description --days int 7 Prune files older than this many days --dry-run bool false Show what would be pruned without deleting

    Files are identified as session-scoped by UUID suffix (e.g. heartbeat-a1b2c3d4-...). Global files without UUIDs (events.jsonl, memory-import.json, etc.) are always preserved.

    Safe to run anytime

    The worst outcome of pruning is a hook re-firing its nudge in the next session. No context files, decisions, or learnings are stored in the state directory.

    Examples:

    ctx system prune                # Prune files older than 7 days\nctx system prune --days 3       # More aggressive cleanup\nctx system prune --dry-run      # Preview what would be removed\n
    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-mark-journal","level":4,"title":"ctx system mark-journal","text":"

    Update processing state for a journal entry. Records the current date in .context/journal/.state.json. Used by journal skills to record pipeline progress.

    ctx system mark-journal <filename> <stage>\n

    Stages: exported, enriched, normalized, fences_verified

    Flag Description --check Check if stage is set (exit 1 if not)

    Example:

    ctx system mark-journal 2026-01-21-session-abc12345.md enriched\nctx system mark-journal 2026-01-21-session-abc12345.md normalized\nctx system mark-journal --check 2026-01-21-session-abc12345.md fences_verified\n
    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-mark-wrapped-up","level":4,"title":"ctx system mark-wrapped-up","text":"

    Suppress context checkpoint nudges after a wrap-up ceremony. Writes a marker file that check-context-size checks before emitting checkpoint boxes. The marker expires after 2 hours.

    Called automatically by /ctx-wrap-up after persisting context (not intended for direct use).

    ctx system mark-wrapped-up\n

    No flags, no arguments. Idempotent: running it again updates the marker timestamp.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/tools/","level":1,"title":"Tools and Utilities","text":"","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-watch","level":3,"title":"ctx watch","text":"

    Watch for AI output and auto-apply context updates.

    Parses <context-update> XML commands from AI output and applies them to context files.

    ctx watch [flags]\n

    Flags:

    Flag Description --log <file> Log file to watch (default: stdin) --dry-run Preview updates without applying

    Example:

    # Watch stdin\nai-tool | ctx watch\n\n# Watch a log file\nctx watch --log /path/to/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-hook","level":3,"title":"ctx hook","text":"

    Generate AI tool integration configuration.

    ctx hook <tool> [flags]\n

    Flags:

    Flag Short Description --write -w Write the generated config to disk (e.g. .github/copilot-instructions.md)

    Supported tools:

    Tool Description claude-code Redirects to plugin install instructions cursor Cursor IDE aider Aider CLI copilot GitHub Copilot windsurf Windsurf IDE

    Claude Code Uses the Plugin system

    Claude Code integration is now provided via the ctx plugin. Running ctx hook claude-code prints plugin install instructions.

    Example:

    # Print hook instructions to stdout\nctx hook cursor\nctx hook aider\n\n# Generate and write .github/copilot-instructions.md\nctx hook copilot --write\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-loop","level":3,"title":"ctx loop","text":"

    Generate a shell script for running an autonomous loop.

    An autonomous loop continuously runs an AI assistant with the same prompt until a completion signal is detected, enabling iterative development where the AI builds on its previous work.

    ctx loop [flags]\n

    Flags:

    Flag Short Description Default --tool <tool> -t AI tool: claude, aider, or generic claude --prompt <file> -p Prompt file to use PROMPT.md --max-iterations <n> -n Maximum iterations (0 = unlimited) 0 --completion <signal> -c Completion signal to detect SYSTEM_CONVERGED --output <file> -o Output script filename loop.sh

    Example:

    # Generate loop.sh for Claude Code\nctx loop\n\n# Generate for Aider with custom prompt\nctx loop --tool aider --prompt TASKS.md\n\n# Limit to 10 iterations\nctx loop --max-iterations 10\n\n# Output to custom file\nctx loop -o my-loop.sh\n

    Usage:

    # Generate and run the loop\nctx loop\nchmod +x loop.sh\n./loop.sh\n

    See Autonomous Loops for detailed workflow documentation.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory","level":3,"title":"ctx memory","text":"

    Bridge Claude Code's auto memory (MEMORY.md) into .context/.

    Claude Code maintains per-project auto memory at ~/.claude/projects/<slug>/memory/MEMORY.md. This command group discovers that file, mirrors it into .context/memory/mirror.md (git-tracked), and detects drift.

    ctx memory <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-sync","level":4,"title":"ctx memory sync","text":"

    Copy MEMORY.md to .context/memory/mirror.md. Archives the previous mirror before overwriting.

    ctx memory sync [flags]\n

    Flags:

    Flag Description --dry-run Show what would happen without writing

    Exit codes:

    Code Meaning 0 Synced successfully 1 MEMORY.md not found (auto memory inactive)

    Example:

    ctx memory sync\n# Archived previous mirror to mirror-2026-03-05-143022.md\n# Synced MEMORY.md -> .context/memory/mirror.md\n#   Source: ~/.claude/projects/-home-user-project/memory/MEMORY.md\n#   Lines: 47 (was 32)\n#   New content: 15 lines since last sync\n\nctx memory sync --dry-run\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-status","level":4,"title":"ctx memory status","text":"

    Show drift, timestamps, line counts, and archive count.

    ctx memory status\n

    Exit codes:

    Code Meaning 0 No drift 1 MEMORY.md not found 2 Drift detected (MEMORY.md changed since sync)

    Example:

    ctx memory status\n# Memory Bridge Status\n#   Source:      ~/.claude/projects/.../memory/MEMORY.md\n#   Mirror:      .context/memory/mirror.md\n#   Last sync:   2026-03-05 14:30 (2 hours ago)\n#\n#   MEMORY.md:  47 lines (modified since last sync)\n#   Mirror:     32 lines\n#   Drift:      detected (source is newer)\n#   Archives:   3 snapshots in .context/memory/archive/\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-diff","level":4,"title":"ctx memory diff","text":"

    Show what changed in MEMORY.md since last sync.

    ctx memory diff\n

    Example:

    ctx memory diff\n# --- .context/memory/mirror.md (mirror)\n# +++ ~/.claude/projects/.../memory/MEMORY.md (source)\n# +- new learning: memory bridge works\n

    No output when files are identical.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-publish","level":4,"title":"ctx memory publish","text":"

    Push curated .context/ content into MEMORY.md so the agent sees it natively.

    ctx memory publish [flags]\n

    Content is selected in priority order: pending tasks, recent decisions (7 days), key conventions, recent learnings (7 days). Wrapped in <!-- ctx:published --> markers. Claude-owned content outside the markers is preserved.

    Flags:

    Flag Description Default --budget Line budget for published content 80 --dry-run Show what would be published

    Example:

    ctx memory publish --dry-run\n# Publishing .context/ -> MEMORY.md...\n#   Budget: 80 lines\n#   Published block:\n#     5 pending tasks (from TASKS.md)\n#     3 recent decisions (from DECISIONS.md)\n#     5 key conventions (from CONVENTIONS.md)\n#   Total: 42 lines (within 80-line budget)\n# Dry run - no files written.\n\nctx memory publish              # Write to MEMORY.md\nctx memory publish --budget 40  # Tighter budget\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-unpublish","level":4,"title":"ctx memory unpublish","text":"

    Remove the ctx-managed marker block from MEMORY.md, preserving Claude-owned content.

    ctx memory unpublish\n

    Hook integration: The check-memory-drift hook runs on every prompt and nudges the agent when MEMORY.md has changed since last sync. The nudge fires once per session. See Memory Bridge.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-import","level":4,"title":"ctx memory import","text":"

    Classify and promote entries from MEMORY.md into structured .context/ files.

    ctx memory import [flags]\n

    Each entry is classified by keyword heuristics:

    Keywords Target always use, prefer, never use, standard CONVENTIONS.md decided, chose, trade-off, approach DECISIONS.md gotcha, learned, watch out, bug, caveat LEARNINGS.md todo, need to, follow up TASKS.md Everything else Skipped

    Deduplication prevents re-importing the same entry across runs.

    Flags:

    Flag Description --dry-run Show classification plan without writing

    Example:

    ctx memory import --dry-run\n# Scanning MEMORY.md for new entries...\n#   Found 6 entries\n#\n#   -> \"always use ctx from PATH\"\n#      Classified: CONVENTIONS.md (keywords: always use)\n#\n#   -> \"decided to use heuristic classification over LLM-based\"\n#      Classified: DECISIONS.md (keywords: decided)\n#\n# Dry run - would import: 4 entries (1 convention, 1 decision, 1 learning, 1 task)\n# Skipped: 2 entries (session notes/unclassified)\n\nctx memory import    # Actually write entries to .context/ files\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify","level":3,"title":"ctx notify","text":"

    Send fire-and-forget webhook notifications from skills, loops, and hooks.

    ctx notify --event <name> [--session-id <id>] \"message\"\n

    Flags:

    Flag Short Description --event -e Event name (required) --session-id -s Session ID (optional)

    Behavior:

    • No webhook configured: silent noop (exit 0)
    • Webhook set but event not in events list: silent noop (exit 0)
    • Webhook set and event matches: fire-and-forget HTTP POST
    • HTTP errors silently ignored (no retry)

    Example:

    ctx notify --event loop \"Loop completed after 5 iterations\"\nctx notify -e nudge -s session-abc \"Context checkpoint at prompt #20\"\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify-setup","level":4,"title":"ctx notify setup","text":"

    Configure the webhook URL interactively. The URL is encrypted with AES-256-GCM using the encryption key and stored in .context/.notify.enc.

    ctx notify setup\n

    The encrypted file is safe to commit. The key (~/.ctx/.ctx.key) lives outside the project and is never committed.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify-test","level":4,"title":"ctx notify test","text":"

    Send a test notification and report the HTTP response status.

    ctx notify test\n

    Payload format (JSON POST):

    {\n  \"event\": \"loop\",\n  \"message\": \"Loop completed after 5 iterations\",\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"ctx\"\n}\n
    Field Type Description event string Event name from --event flag message string Notification message session_id string Session ID (omitted if empty) timestamp string UTC RFC3339 timestamp project string Project directory name","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-change","level":3,"title":"ctx change","text":"

    Show what changed in context files and code since your last session.

    Automatically detects the previous session boundary from state markers or event log. Useful at session start to quickly see what moved while you were away.

    ctx change [flags]\n

    Flags:

    Flag Description --since Time reference: duration (24h) or date (2026-03-01)

    Reference time detection (priority order):

    1. --since flag (duration, date, or RFC3339 timestamp)
    2. ctx-loaded-* marker files in .context/state/ (second most recent)
    3. Last context-load-gate event from .context/state/events.jsonl
    4. Fallback: 24 hours ago

    Example:

    # Auto-detect last session, show what changed\nctx change\n\n# Changes in the last 48 hours\nctx change --since 48h\n\n# Changes since a specific date\nctx change --since 2026-03-10\n

    Output:

    ## Changes Since Last Session\n\n**Reference point**: 6 hours ago\n\n### Context File Changes\n- `TASKS.md` - modified 2026-03-12 14:30\n- `DECISIONS.md` - modified 2026-03-12 09:15\n\n### Code Changes\n- **12 commits** since reference point\n- **Latest**: Fix journal enrichment ordering\n- **Directories touched**: internal, docs, specs\n- **Authors**: jose, claude\n

    Context file changes are detected by filesystem mtime (works without git). Code changes use git log --since (empty when not in a git repo).

    See also: Reviewing Session Changes

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-dep","level":3,"title":"ctx dep","text":"

    Generate a dependency graph from source code.

    Auto-detects the project ecosystem from manifest files and outputs a dependency graph in Mermaid, table, or JSON format.

    ctx dep [flags]\n

    Supported ecosystems:

    Ecosystem Manifest Method Go go.mod go list -json ./... Node.js package.json Parse package.json (workspace-aware) Python requirements.txt or pyproject.toml Parse manifest directly Rust Cargo.toml cargo metadata

    Detection order: Go, Node.js, Python, Rust. First match wins.

    Flags:

    Flag Description Default --format Output format: mermaid, table, json mermaid --external Include external/third-party dependencies false --type Force ecosystem: go, node, python, rust auto-detect

    Examples:

    # Auto-detect and show internal deps as Mermaid\nctx dep\n\n# Include external dependencies\nctx dep --external\n\n# Force Node.js detection (useful when multiple manifests exist)\nctx dep --type node\n\n# Machine-readable output\nctx dep --format json\n\n# Table format\nctx dep --format table\n

    Ecosystem notes:

    • Go: Uses go list -json ./.... Requires go in PATH.
    • Node.js: Parses package.json directly (no npm/yarn needed). For monorepos with workspaces, shows workspace-to-workspace deps (internal) or all deps per workspace (external).
    • Python: Parses requirements.txt or pyproject.toml directly (no pip needed). Shows declared dependencies; does not trace imports. With --external, includes dev dependencies from pyproject.toml.
    • Rust: Requires cargo in PATH. Uses cargo metadata for accurate dependency resolution.
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad","level":3,"title":"ctx pad","text":"

    Encrypted scratchpad for sensitive one-liners that travel with the project.

    When invoked without a subcommand, lists all entries.

    ctx pad\nctx pad <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-add","level":4,"title":"ctx pad add","text":"

    Append a new entry to the scratchpad.

    ctx pad add <text>\nctx pad add <label> --file <path>\n

    Flags:

    Flag Short Description --file -f Ingest a file as a blob entry (max 64 KB)

    Examples:

    ctx pad add \"DATABASE_URL=postgres://user:pass@host/db\"\nctx pad add \"deploy config\" --file ./deploy.yaml\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-show","level":4,"title":"ctx pad show","text":"

    Output the raw text of an entry by number. For blob entries, prints decoded file content (or writes to disk with --out).

    ctx pad show <n>\nctx pad show <n> --out <path>\n

    Arguments:

    • n: 1-based entry number

    Flags:

    Flag Description --out Write decoded blob content to a file (blobs only)

    Examples:

    ctx pad show 3\nctx pad show 2 --out ./recovered.yaml\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-rm","level":4,"title":"ctx pad rm","text":"

    Remove an entry by number.

    ctx pad rm <n>\n

    Arguments:

    • n: 1-based entry number
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-edit","level":4,"title":"ctx pad edit","text":"

    Replace, append to, or prepend to an entry.

    ctx pad edit <n> [text]\n

    Arguments:

    • n: 1-based entry number
    • text: Replacement text (mutually exclusive with --append/--prepend)

    Flags:

    Flag Description --append Append text to the end of the entry --prepend Prepend text to the beginning of entry --file Replace blob file content (preserves label) --label Replace blob label (preserves content)

    Examples:

    ctx pad edit 2 \"new text\"\nctx pad edit 2 --append \" suffix\"\nctx pad edit 2 --prepend \"prefix \"\nctx pad edit 1 --file ./v2.yaml\nctx pad edit 1 --label \"new name\"\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-mv","level":4,"title":"ctx pad mv","text":"

    Move an entry from one position to another.

    ctx pad mv <from> <to>\n

    Arguments:

    • from: Source position (1-based)
    • to: Destination position (1-based)
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-resolve","level":4,"title":"ctx pad resolve","text":"

    Show both sides of a merge conflict in the encrypted scratchpad.

    ctx pad resolve\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-import","level":4,"title":"ctx pad import","text":"

    Bulk-import lines from a file into the scratchpad. Each non-empty line becomes a separate entry. All entries are written in a single encrypt/write cycle.

    With --blob, import all first-level files from a directory as blob entries. Each file becomes a blob with the filename as its label. Subdirectories and non-regular files are skipped.

    ctx pad import <file>\nctx pad import -              # read from stdin\nctx pad import --blob <dir>  # import directory files as blobs\n

    Arguments:

    • file: Path to a text file, - for stdin, or a directory (with --blob)

    Flags:

    Flag Description --blob Import first-level files from a directory as blobs

    Examples:

    ctx pad import notes.txt\ngrep TODO *.go | ctx pad import -\nctx pad import --blob ./ideas/\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-export","level":4,"title":"ctx pad export","text":"

    Export all blob entries from the scratchpad to a directory as files. Each blob's label becomes the filename. Non-blob entries are skipped.

    ctx pad export [dir]\n

    Arguments:

    • dir: Target directory (default: current directory)

    Flags:

    Flag Short Description --force -f Overwrite existing files instead of timestamping --dry-run Print what would be exported without writing

    When a file already exists, a unix timestamp is prepended to avoid collisions (e.g., 1739836200-label). Use --force to overwrite instead.

    Examples:

    ctx pad export ./ideas\nctx pad export --dry-run\nctx pad export --force ./backup\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-merge","level":4,"title":"ctx pad merge","text":"

    Merge entries from one or more scratchpad files into the current pad. Each input file is auto-detected as encrypted or plaintext. Entries are deduplicated by exact content.

    ctx pad merge FILE...\n

    Arguments:

    • FILE...: One or more scratchpad files to merge (encrypted or plaintext)

    Flags:

    Flag Short Description --key -k Path to key file for decrypting input files --dry-run Print what would be merged without writing

    Examples:

    ctx pad merge worktree/.context/scratchpad.enc\nctx pad merge notes.md backup.enc\nctx pad merge --key /path/to/other.key foreign.enc\nctx pad merge --dry-run pad-a.enc pad-b.md\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt","level":3,"title":"ctx prompt","text":"

    Manage reusable prompt templates stored in .context/prompts/.

    Templates are Markdown files that can be applied via the /ctx-prompt skill or listed and shown from the CLI.

    ctx prompt <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-list","level":4,"title":"ctx prompt list","text":"

    List all available prompt templates.

    ctx prompt list\n

    Aliases: ls

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-show","level":4,"title":"ctx prompt show","text":"

    Print a prompt template to stdout.

    ctx prompt show <name>\n

    Arguments:

    • name: Template name (without .md extension)
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-add","level":4,"title":"ctx prompt add","text":"

    Create a new prompt template. Reads from stdin when --stdin is set, otherwise creates from the embedded starter template.

    ctx prompt add <name> [flags]\n

    Arguments:

    • name: Template name (without .md extension)

    Flags:

    Flag Description --stdin Read template content from stdin

    Examples:

    # Create from starter template\nctx prompt add code-review\n\n# Create from stdin\necho \"Review this PR for security issues\" | ctx prompt add security-review --stdin\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-rm","level":4,"title":"ctx prompt rm","text":"

    Delete a prompt template.

    ctx prompt rm <name>\n

    Arguments:

    • name: Template name (without .md extension)

    See also: Prompt Templates

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind","level":3,"title":"ctx remind","text":"

    Session-scoped reminders that surface at session start. Reminders are stored verbatim and relayed verbatim: no summarization, no categories.

    When invoked with a text argument and no subcommand, adds a reminder.

    ctx remind \"text\"\nctx remind <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-add","level":4,"title":"ctx remind add","text":"

    Add a reminder. This is the default action: ctx remind \"text\" and ctx remind add \"text\" are equivalent.

    ctx remind \"refactor the swagger definitions\"\nctx remind add \"check CI after the deploy\" --after 2026-02-25\n

    Arguments:

    • text: The reminder message (verbatim)

    Flags:

    Flag Short Description --after -a Don't surface until this date (YYYY-MM-DD)

    Examples:

    ctx remind \"refactor the swagger definitions\"\nctx remind \"check CI after the deploy\" --after 2026-02-25\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-list","level":4,"title":"ctx remind list","text":"

    List all pending reminders. Date-gated reminders that aren't yet due are annotated with (after DATE, not yet due).

    ctx remind list\n

    Aliases: ls

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-dismiss","level":4,"title":"ctx remind dismiss","text":"

    Remove a reminder by ID, or remove all reminders with --all.

    ctx remind dismiss <id>\nctx remind dismiss --all\n

    Arguments:

    • id: Reminder ID (shown in list output)

    Flags:

    Flag Description --all Dismiss all reminders

    Aliases: rm

    Examples:

    ctx remind dismiss 3\nctx remind dismiss --all\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pause","level":3,"title":"ctx pause","text":"

    Pause all context nudge and reminder hooks for the current session. Security hooks (dangerous command blocking) and housekeeping hooks still fire.

    ctx pause [flags]\n

    Flags:

    Flag Description --session-id Session ID (overrides stdin)

    Example:

    # Pause hooks for a quick investigation\nctx pause\n\n# Resume when ready\nctx resume\n

    See also: Pausing Context Hooks

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-resume","level":3,"title":"ctx resume","text":"

    Resume context hooks after a pause. Silent no-op if not paused.

    ctx resume [flags]\n

    Flags:

    Flag Description --session-id Session ID (overrides stdin)

    Example:

    ctx resume\n

    See also: Pausing Context Hooks

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-completion","level":3,"title":"ctx completion","text":"

    Generate shell autocompletion scripts.

    ctx completion <shell>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#subcommands","level":4,"title":"Subcommands","text":"Shell Command bash ctx completion bash zsh ctx completion zsh fish ctx completion fish powershell ctx completion powershell","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#installation","level":4,"title":"Installation","text":"BashZshFish 
    # Add to ~/.bashrc\nsource <(ctx completion bash)\n
    # Add to ~/.zshrc\nsource <(ctx completion zsh)\n
    ctx completion fish | source\n# Or save to completions directory\nctx completion fish > ~/.config/fish/completions/ctx.fish\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-site","level":3,"title":"ctx site","text":"

    Site management commands for the ctx.ist static site.

    ctx site <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-site-feed","level":4,"title":"ctx site feed","text":"

    Generate an Atom 1.0 feed from finalized blog posts in docs/blog/.

    ctx site feed [flags]\n

    Scans docs/blog/ for files matching YYYY-MM-DD-*.md, parses YAML frontmatter, and generates a valid Atom feed. Only posts with reviewed_and_finalized: true are included. Summaries are extracted from the first paragraph after the heading.

    Flags:

    Flag Short Type Default Description --out -o string site/feed.xml Output path --base-url string https://ctx.ist Base URL for entry links

    Output:

    Generated site/feed.xml (21 entries)\n\nSkipped:\n  2026-02-25-the-homework-problem.md: not finalized\n\nWarnings:\n  2026-02-09-defense-in-depth.md: no summary paragraph found\n

    Three buckets: included (count), skipped (with reason), warnings (included but degraded). exit 0 always: warnings inform but do not block.

    Frontmatter requirements:

    Field Required Feed mapping title Yes <title> date Yes <updated> reviewed_and_finalized Yes Draft gate (must be true) author No <author><name> topics No <category term=\"\">

    Examples:

    ctx site feed                                # Generate site/feed.xml\nctx site feed --out /tmp/feed.xml            # Custom output path\nctx site feed --base-url https://example.com # Custom base URL\nmake site-feed                               # Makefile shortcut\nmake site                                    # Builds site + feed\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-guide","level":3,"title":"ctx guide","text":"

    Quick-reference cheat sheet for common ctx commands and skills.

    ctx guide [flags]\n

    Flags:

    Flag Description --skills Show available skills --commands Show available CLI commands

    Example:

    # Show the full cheat sheet\nctx guide\n\n# Skills only\nctx guide --skills\n\n# Commands only\nctx guide --commands\n

    Works without initialization (no .context/ required).

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-why","level":3,"title":"ctx why","text":"

    Read ctx's philosophy documents directly in the terminal.

    ctx why [DOCUMENT]\n

    Documents:

    Name Description manifesto The ctx Manifesto: creation, not code about About ctx: what it is and why it exists invariants Design invariants: properties that must hold

    Usage:

    # Interactive numbered menu\nctx why\n\n# Show a specific document\nctx why manifesto\nctx why about\nctx why invariants\n\n# Pipe to a pager\nctx why manifesto | less\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"home/","level":1,"title":"Home","text":"
    • ctx is not a prompt.
    • ctx is version-controlled cognitive state.

    ctx is the persistence layer for human-AI reasoning.

    Deterministic. Git-native. Human-readable. Local-first.

    Start here.

    Learn what ctx does, set it up, and run your first session.

    Pre-1.0: Moving Fast

    ctx is under active development. This website tracks the development branch, not the latest release:

    Some features described here may not exist in the binary you have installed.

    Expect rough edges.

    If something is missing or broken, open an issue.

    ","path":["Home"],"tags":[]},{"location":"home/#about-ctx","level":3,"title":"About ctx","text":"

    What ctx is, how it works, and why persistent context changes how you work with AI.

    ","path":["Home"],"tags":[]},{"location":"home/#is-it-right-for-me","level":3,"title":"Is It Right for Me?","text":"

    Good fit, not-so-good fit, and a 5-minute trial to find out for yourself.

    ","path":["Home"],"tags":[]},{"location":"home/#community","level":3,"title":"Community","text":"

    We are the builders who care about durable context. Join the community. Hang out in IRC. Star ctx on GitHub.

    ","path":["Home"],"tags":[]},{"location":"home/#contributing","level":3,"title":"Contributing","text":"

    Development setup, project layout, and pull request process.

    ","path":["Home"],"tags":[]},{"location":"home/#getting-started","level":3,"title":"Getting Started","text":"

    Install the binary, set up the plugin, and verify it works.

    ","path":["Home"],"tags":[]},{"location":"home/#your-first-session","level":3,"title":"Your First Session","text":"

    Step-by-step walkthrough from ctx init to verified recall.

    ","path":["Home"],"tags":[]},{"location":"home/#common-workflows","level":3,"title":"Common Workflows","text":"

    Day-to-day commands for tracking context, checking health, and browsing history.

    ","path":["Home"],"tags":[]},{"location":"home/#context-files","level":3,"title":"Context Files","text":"

    What each .context/ file does. What's their purpose. How do we best leverage them.

    ","path":["Home"],"tags":[]},{"location":"home/#configuration","level":3,"title":"Configuration","text":"

    Flexible configuration: .ctxrc, environment variables, and CLI flags.

    ","path":["Home"],"tags":[]},{"location":"home/#prompting-guide","level":3,"title":"Prompting Guide","text":"

    Effective prompts for AI sessions with ctx.

    ","path":["Home"],"tags":[]},{"location":"home/about/","level":1,"title":"About","text":"

    \"Creation, not code; Context, not prompts; Verification, not vibes.\"

    Read the ctx Manifesto →

    \"Without durable context, intelligence resets; with ctx, creation compounds.\"

    Without persistent memory, every session starts at zero; ctx makes sessions cumulative.

    Join the ctx Community →

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#what-is-ctx","level":2,"title":"What Is ctx?","text":"

    ctx (Context) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. It lives in a .context/ directory in your repo.

    • A session is interactive.
    • ctx enables cognitive continuity.
    • Cognitive continuity enables durable, symbiotic-like human-AI workflows.

    Context Files

    Context files let AI tools remember decisions, conventions, and learnings:

    Context files are explicit and versionable contracts between you and your agents.

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#why-do-i-keep-re-explaining-my-codebase","level":2,"title":"Why Do I Keep Re-Explaining My Codebase?!?!","text":"

    You open a new AI session. The first thing you do is re-explain your project.

    Again.

    The architecture, the database choice, the naming conventions, the thing you tried last week that didn't work. You have said all of this before (maybe yesterday, maybe an hour ago), but the AI doesn't know that.

    • You explain the same architecture every session;
    • The AI suggests an approach you already rejected, again;
    • A decision you made three sessions ago gets relitigated from scratch;
    • You spend more time setting context than building features.

    This isn't AI failure: It is staleness.

    Without persistent memory, every session starts at zero.

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#day-and-night","level":3,"title":"Day and Night","text":"

    ctx gives your AI a memory that persists across sessions:

    Without ctxWith ctx 
    Session 12: Monday morning\n\nAI:  \"I'll scaffold a MySQL schema for this.\"\nYou: \"We use PostgreSQL.\"\n\nAI:  \"For auth, session-based would be simplest.\"\nYou: \"We decided on JWT.\"\n\nAI:  \"Endpoints in camelCase?\"\nYou: \"snake_case! Like the rest of the API!!!!!!\"\n\nYou: *scrolls up to copy an existing endpoint*\n\n20 minutes spent restoring decisions that already exist.\n
    Session 12: Monday morning\n\nYou:  \"Let's continue the auth implementation.\"\nAI:   \"Per DECISIONS.md (2026-02-12): JWT, not sessions: \n       The project uses PostgreSQL with JWT\n       authentication. The API follows snake_case conventions.\n       Last session you completed the login endpoint: the\n       registration endpoint is next on TASKS.md. Want me to\n       start there?\"\n\n0 minutes re-explaining. Straight to building.\n
    ","path":["Home","About"],"tags":[]},{"location":"home/about/#how-ctx-solves-this","level":3,"title":"How ctx Solves This","text":"

    ctx creates a .context/ directory in your project that stores structured knowledge files:

    File What It Remembers TASKS.md What you're working on and what's next DECISIONS.md Architectural choices and why you made them LEARNINGS.md Gotchas, bugs, things that didn't work CONVENTIONS.md Naming patterns, code style, project rules CONSTITUTION.md Hard rules the AI must never violate

    These files can version with your code in git:

    • They load automatically at the session start (via hooks in Claude Code, or manually with ctx agent for other tools).
    • The AI reads them, cites them, and builds on them, instead of asking you to start over.
      • And when it acts, it can point to the exact file and line that justifies the choice.

    Every decision you record, every lesson you capture, makes the next session smarter.

    ctx accumulates.

    Connect with ctx

    • Join the Community →: ask questions, share workflows, and help shape what comes next
    • Read the Blog →: real-world patterns, ponderings, and lessons learned from building ctx using ctx

    Ready to Get Started?

    • Getting Started →: full installation and setup
    • Your First Session →: step-by-step walkthrough from ctx init to verified recall
    ","path":["Home","About"],"tags":[]},{"location":"home/common-workflows/","level":1,"title":"Common Workflows","text":"

    The commands below cover what you'll use most often:

    • recording context,
    • checking health,
    • browsing history,
    • and running loops.

    Each section is a self-contained snippet you can copy into your terminal.

    For deeper, step-by-step guides, see Recipes.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#track-context","level":2,"title":"Track Context","text":"
    # Add a task\nctx add task \"Implement user authentication\"\n\n# Record a decision (full ADR fields required)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Note a learning\nctx add learning \"Mock functions must be hoisted in Jest\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Jest hoists mock calls to top of file\" \\\n  --application \"Place jest.mock() before imports\"\n\n# Mark task complete\nctx task complete \"user auth\"\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#leave-a-reminder-for-next-session","level":2,"title":"Leave a Reminder for Next Session","text":"

    Drop a note that surfaces automatically at the start of your next session:

    # Leave a reminder\nctx remind \"refactor the swagger definitions\"\n\n# Date-gated: don't surface until a specific date\nctx remind \"check CI after the deploy\" --after 2026-02-25\n\n# List pending reminders\nctx remind list\n\n# Dismiss a reminder by ID\nctx remind dismiss 1\n

    Reminders are relayed verbatim at session start by the check-reminders hook and repeat every session until you dismiss them.

    See Session Reminders for the full recipe.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#check-context-health","level":2,"title":"Check Context Health","text":"
    # Detect stale paths, missing files, potential secrets\nctx drift\n\n# See full context summary\nctx status\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#browse-session-history","level":2,"title":"Browse Session History","text":"

    List and search past AI sessions from the terminal:

    ctx recall list --limit 5\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#journal-site","level":3,"title":"Journal Site","text":"

    Export session transcripts to a browsable static site with search, navigation, and topic indices.

    The ctx journal command requires zensical (Python >= 3.10).

    zensical is a Python-based static site generator from the Material for MkDocs team.

    (why zensical?).

    If you don't have it on your system, install zensical once with pipx:

    # One-time setup\npipx install zensical\n

    Avoid pip install zensical

    pip install often fails: For example, on macOS, system Python installs a non-functional stub (zensical requires Python >= 3.10), and Homebrew Python blocks system-wide installs (PEP 668).

    pipx creates an isolated environment with the correct Python version automatically.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#export-and-serve","level":3,"title":"Export and Serve","text":"

    Then, export and serve:

    # Export all sessions to .context/journal/ (only new files)\nctx recall export --all\n\n# Generate and serve the journal site\nctx journal site --serve\n

    Open http://localhost:8000 to browse.

    To update after new sessions, run the same two commands again.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#safe-by-default","level":3,"title":"Safe By Default","text":"

    ctx recall export --all is safe by default:

    • It only exports new sessions and skips existing files.
    • Locked entries (via ctx recall lock) are always skipped by both export and enrichment skills.
    • If you add locked: true to frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json.
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#re-exporting-existing-files","level":3,"title":"Re-Exporting Existing Files","text":"

    Here is how you regenerate existing files.

    Backup your .context folder before regeneration, as this is a potentially destructive action.

    To re-export journal files, you need to explicitly opt-in using the --regenerate flag:

    Flag combination Frontmatter Body --regenerate Preserved Overwritten from source --regenerate --keep-frontmatter=false Overwritten Overwritten

    Regeneration Overwrites Body Edits

    --regenerate preserves your YAML frontmatter (tags, summary, enrichment metadata) but it replaces the Markdown body with a fresh export.

    Any manual edits you made to the transcript will be lost.

    Lock entries you want to protect first: ctx recall lock <session-id>.

    See Session Journal for the full pipeline including normalization and enrichment.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#scratchpad","level":2,"title":"Scratchpad","text":"

    Store short, sensitive one-liners in an encrypted scratchpad that travels with the project:

    # Write a note\nctx pad set db-password \"postgres://user:pass@localhost/mydb\"\n\n# Read it back\nctx pad get db-password\n\n# List all keys\nctx pad list\n

    The scratchpad is encrypted with a key stored at ~/.ctx/.ctx.key (outside the project, never committed).

    See Scratchpad for details.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#run-an-autonomous-loop","level":2,"title":"Run an Autonomous Loop","text":"

    Generate a script that iterates an AI agent until a completion signal is detected:

    ctx loop\nchmod +x loop.sh\n./loop.sh\n

    See Autonomous Loops for configuration and advanced usage.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#agent-session-start","level":2,"title":"Agent Session Start","text":"

    The first thing an AI agent should do at session start is discover where context lives:

    ctx system bootstrap\n

    This prints the resolved context directory, the files in it, and the operating rules. The CLAUDE.md template instructs the agent to run this automatically. See CLI Reference: bootstrap.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#the-two-skills-you-should-always-use","level":2,"title":"The Two Skills You Should Always Use","text":"

    Using /ctx-remember at session start and /ctx-wrap-up at session end are the highest-value skills in the entire catalog:

    # session begins:\n/ctx-remember\n... do work ...\n# before closing the session:\n/ctx-wrap-up\n

    Let's provide some context, because this is important:

    Although the agent will eventually discover your context through CLAUDE.md → AGENT_PLAYBOOK.md, /ctx-remember hydrates the full context up front (tasks, decisions, recent sessions) so the agent starts informed rather than piecing things together over several turns.

    /ctx-wrap-up is the other half: A structured review that captures learnings, decisions, and tasks before you close the window.

    Hooks like check-persistence remind you (the user) mid-session that context hasn't been saved in a while, but they don't trigger persistence automatically: You still have to act. Also, a CTRL+C can end things at any moment with no reliable \"before session end\" event.

    In short, /ctx-wrap-up is the deliberate checkpoint that makes sure nothing slips through. And /ctx-remember it its mirror skill to be used at session start.

    See Session Ceremonies for the full workflow.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#cli-commands-vs-ai-skills","level":2,"title":"CLI Commands vs. AI Skills","text":"

    Most ctx operations come in two flavors: a CLI command you run in your terminal and an AI skill (slash command) you invoke inside your coding assistant.

    Commands and skills are not interchangeable: Each has a distinct role.

    ctx CLI command ctx AI skill Runs where Your terminal Inside the AI assistant Speed Fast (milliseconds) Slower (LLM round-trip) Cost Free Consumes tokens and context Analysis Deterministic heuristics Semantic / judgment-based Best for Quick checks, scripting, CI Deep analysis, generation, workflow orchestration","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#paired-commands","level":3,"title":"Paired Commands","text":"

    These have both a CLI and a skill counterpart. Use the CLI for quick, deterministic checks; use the skill when you need the agent's judgment.

    CLI Skill When to prefer the skill ctx drift /ctx-drift Semantic analysis: catches meaning drift the CLI misses ctx status /ctx-status Interpreted summary with recommendations ctx add task /ctx-add-task Agent decomposes vague goals into concrete tasks ctx add decision /ctx-add-decision Agent drafts rationale and consequences from discussion ctx add learning /ctx-add-learning Agent extracts the lesson from a debugging session ctx add convention /ctx-add-convention Agent observes a repeated pattern and codifies it ctx task archive /ctx-archive Agent reviews which tasks are truly done ctx pad /ctx-pad Agent reads/writes scratchpad entries in conversation flow ctx recall /ctx-recall Agent searches session history with semantic understanding ctx agent /ctx-agent Agent loads and acts on the context packet ctx loop /ctx-loop Agent tailors the loop script to your project ctx doctor /ctx-doctor Agent adds semantic analysis to structural checks ctx pause /ctx-pause Agent pauses hooks with session-aware reasoning ctx resume /ctx-resume Agent resumes hooks after a pause ctx remind /ctx-remind Agent manages reminders in conversation flow","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#ai-only-skills","level":3,"title":"AI-Only Skills","text":"

    These have no CLI equivalent. They require the agent's reasoning.

    Skill Purpose /ctx-remember Load context and present structured readback at session start /ctx-wrap-up End-of-session ceremony: persist learnings, decisions, tasks /ctx-next Suggest 1-3 concrete next actions from context /ctx-commit Commit with integrated context capture /ctx-reflect Pause and assess session progress /ctx-consolidate Merge overlapping learnings or decisions /ctx-prompt-audit Analyze prompting patterns for improvement /ctx-import-plans Import Claude Code plan files into project specs /ctx-implement Execute a plan step-by-step with verification /ctx-worktree Manage parallel agent worktrees /ctx-journal-normalize Fix markdown rendering issues in journal entries /ctx-journal-enrich Add metadata, tags, and summaries to journal entries /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich /ctx-blog Generate a blog post (zensical-flavored Markdown) /ctx-blog-changelog Generate themed blog post from commits between releases /ctx-architecture Build and maintain architecture maps (ARCHITECTURE.md, DETAILED_DESIGN.md)","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#cli-only-commands","level":3,"title":"CLI-Only Commands","text":"

    These are infrastructure: used in scripts, CI, or one-time setup.

    Command Purpose ctx init Initialize .context/ directory ctx load Output assembled context for piping ctx task complete Mark a task done by substring match ctx sync Reconcile context with codebase state ctx compact Consolidate and clean up context files ctx hook Generate AI tool integration config ctx watch Watch AI output and auto-apply context updates ctx serve Serve any zensical directory (default: journal) ctx permission snapshot Save settings as a golden image ctx permission restore Restore settings from golden image ctx journal site Generate browsable journal from exports ctx notify setup Configure webhook notifications ctx decision List and filter decisions ctx learning List and filter learnings ctx task List tasks, manage archival and snapshots ctx why Read the philosophy behind ctx ctx guide Quick-reference cheat sheet ctx site Site management commands ctx config Manage runtime configuration profiles ctx system System diagnostics and hook commands ctx system backup Back up context and Claude data to tar.gz / SMB ctx completion Generate shell autocompletion scripts

    Rule of Thumb

    Quick check? Use the CLI.

    Need judgment? Use the skill.

    When in doubt, start with the CLI: It's free and instant.

    Escalate to the skill when heuristics aren't enough.

    Next Up: Context Files →: what each .context/ file does and how to use it

    See Also:

    • Recipes: targeted how-to guides for specific tasks
    • Knowledge Capture: patterns for recording decisions, learnings, and conventions
    • Context Health: keeping your .context/ accurate and drift-free
    • Session Archaeology: digging into past sessions
    • Task Management: tracking and completing work items
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/community/","level":1,"title":"#ctx","text":"

    Open source is better together.

    We are the builders who care about durable context, verifiable decisions, and human-AI workflows that compound over time.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#help-ctx-change-how-ai-remembers","level":2,"title":"Help ctx Change How AI Remembers","text":"

    If you like the idea, a star helps ctx reach engineers who run into context drift every day:

    Star ctx on GitHub ⭐

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#ctx-you","level":2,"title":"ctx ♥️ You","text":"

    Join the community to ask questions, share feedback, and connect with other users:

    • IRC join #ctx on irc.libera.chat: Real-time discussion, field notes, and early ideas.
    • Read the ctx Source on GitHub: Issues, discussions, and contributions.
    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#want-to-contribute","level":2,"title":"Want to Contribute?","text":"

    Early adopters shape the conventions.

    ctx is free and open source software.

    Contributions are always welcome and appreciated.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#code-of-conduct","level":2,"title":"Code of Conduct","text":"

    Clear context requires respectful collaboration.

    ctx follows the Contributor Covenant.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/configuration/","level":1,"title":"Configuration","text":"","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#configuration","level":2,"title":"Configuration","text":"

    ctx uses three layers of configuration. Each layer overrides the one below it:

    1. CLI flags: Per-invocation overrides (highest priority)
    2. Environment variables: Shell or CI/CD overrides
    3. The .ctxrc file: Project-level defaults (YAML)
    4. Built-in defaults: Hardcoded fallbacks (lowest priority)

    All settings are optional: If nothing is configured, ctx works out of the box with sensible defaults.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#the-ctxrc-file","level":2,"title":"The .ctxrc File","text":"

    The .ctxrc file is an optional YAML file placed in the project root (next to your .context/ directory). It lets you set project-level defaults that apply to every ctx command.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#location","level":3,"title":"Location","text":"
    my-project/\n├── .ctxrc              ← configuration file\n├── .context/\n│   ├── TASKS.md\n│   ├── DECISIONS.md\n│   └── ...\n└── src/\n

    ctx looks for .ctxrc in the current working directory when any command runs. There is no global or user-level config file: Configuration is always per-project.

    Contributors: Dev Configuration Profile

    The ctx repo ships two .ctxrc source profiles (.ctxrc.base and .ctxrc.dev). The working copy is gitignored and swapped between them via ctx config switch dev / ctx config switch base. See Contributing: Configuration Profiles.

    Using a Different .context Directory

    The default .context/ directory can be changed per-project via the context_dir key in .ctxrc, the CTX_DIR environment variable, or the --context-dir CLI flag.

    See Environment Variables and CLI Global Flags below for details.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#full-reference","level":3,"title":"Full Reference","text":"

    A commented .ctxrc showing all options and their defaults:

    # .ctxrc: ctx runtime configuration\n# https://ctx.ist/configuration/\n#\n# All settings are optional. Missing values use defaults.\n# Priority: CLI flags > environment variables > .ctxrc > defaults\n#\n# context_dir: .context\n# token_budget: 8000\n# auto_archive: true\n# archive_after_days: 7\n# scratchpad_encrypt: true\n# allow_outside_cwd: false\n# event_log: false\n# entry_count_learnings: 30\n# entry_count_decisions: 20\n# convention_line_count: 200\n# injection_token_warn: 15000\n# context_window: 200000      # auto-detected for Claude Code; override for other tools\n# billing_token_warn: 0       # one-shot warning at this token count (0 = disabled)\n#\n# stale_age_days: 30      # days before drift flags a context file as stale (0 = disabled)\n# key_rotation_days: 90\n# task_nudge_interval: 5   # Edit/Write calls between task completion nudges\n#\n# notify:               # requires: ctx notify setup\n#   events:             # required: no events sent unless listed\n#     - loop\n#     - nudge\n#     - relay\n#\n# priority_order:\n#   - CONSTITUTION.md\n#   - TASKS.md\n#   - CONVENTIONS.md\n#   - ARCHITECTURE.md\n#   - DECISIONS.md\n#   - LEARNINGS.md\n#   - GLOSSARY.md\n#   - AGENT_PLAYBOOK.md\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#option-reference","level":3,"title":"Option Reference","text":"Option Type Default Description context_dir string .context Context directory name (relative to project root) token_budget int 8000 Default token budget for ctx agent and ctx load auto_archive bool true Auto-archive completed tasks during ctx compact archive_after_days int 7 Days before completed tasks are archived scratchpad_encrypt bool true Encrypt scratchpad with AES-256-GCM allow_outside_cwd bool false Allow context directory outside the current working directory event_log bool false Enable local hook event logging to .context/state/events.jsonl entry_count_learnings int 30 Drift warning when LEARNINGS.md exceeds this entry count (0 = disable) entry_count_decisions int 20 Drift warning when DECISIONS.md exceeds this entry count (0 = disable) convention_line_count int 200 Drift warning when CONVENTIONS.md exceeds this line count (0 = disable) injection_token_warn int 15000 Warn when auto-injected context exceeds this token count (0 = disable) context_window int 200000 Context window size in tokens. Auto-detected for Claude Code (200k/1M); override for other AI tools billing_token_warn int 0 (off) One-shot warning when session tokens exceed this threshold (0 = disabled). For plans where tokens beyond an included allowance cost extra stale_age_days int 30 Days before ctx drift flags a context file as stale (0 = disable) key_rotation_days int 90 Days before encryption key rotation nudge task_nudge_interval int 5 Edit/Write calls between task completion nudges notify.events []string (all) Event filter for webhook notifications (empty = all) priority_order []string (see below) Custom file loading priority for context assembly

    Default priority order (used when priority_order is not set):

    1. CONSTITUTION.md
    2. TASKS.md
    3. CONVENTIONS.md
    4. ARCHITECTURE.md
    5. DECISIONS.md
    6. LEARNINGS.md
    7. GLOSSARY.md
    8. AGENT_PLAYBOOK.md

    See Context Files for the rationale behind this ordering.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#environment-variables","level":2,"title":"Environment Variables","text":"

    Environment variables override .ctxrc values but are overridden by CLI flags.

    Variable Description Equivalent .ctxrc key CTX_DIR Override the context directory path context_dir CTX_TOKEN_BUDGET Override the default token budget token_budget","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples","level":3,"title":"Examples","text":"
    # Use a shared context directory\nCTX_DIR=/shared/team-context ctx status\n\n# Increase token budget for a single run\nCTX_TOKEN_BUDGET=16000 ctx agent\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#cli-global-flags","level":2,"title":"CLI Global Flags","text":"

    CLI flags have the highest priority and override both environment variables and .ctxrc settings. These flags are available on every ctx command.

    Flag Description --context-dir <path> Override context directory (default: .context/) --allow-outside-cwd Allow context directory outside current working directory --version Show version and exit --help Show command help and exit","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples_1","level":3,"title":"Examples","text":"
    # Point to a different context directory:\nctx status --context-dir /path/to/shared/.context\n\n# Allow external context directory (skips boundary check):\nctx status --context-dir /mnt/nas/project-context --allow-outside-cwd\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#priority-order","level":2,"title":"Priority Order","text":"

    When the same setting is configured in multiple layers, the highest-priority layer wins:

    CLI flags  >  Environment variables  >  .ctxrc  >  Built-in defaults\n(highest)                                          (lowest)\n

    Example resolution for context_dir:

    Layer Value Wins? --context-dir /tmp/ctx Yes CTX_DIR /shared/context No .ctxrc .my-context No Default .context No

    The CLI flag /tmp/ctx is used because it has the highest priority.

    If the CLI flag were absent, CTX_DIR=/shared/context would win. If neither the flag nor the env var were set, the .ctxrc value .my-context would be used. With nothing configured, the default .context applies.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples_2","level":2,"title":"Examples","text":"","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#external-context-directory","level":3,"title":"External .context Directory","text":"

    Store context outside the project tree (useful for monorepos or shared context):

    # .ctxrc\ncontext_dir: /home/team/shared-context\nallow_outside_cwd: true\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#custom-token-budget","level":3,"title":"Custom Token Budget","text":"

    Increase the token budget for projects with large context:

    # .ctxrc\ntoken_budget: 16000\n

    This affects the default budget for ctx agent and ctx load. You can still override per-invocation with ctx agent --budget 4000.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#disabled-scratchpad-encryption","level":3,"title":"Disabled Scratchpad Encryption","text":"

    Turn off encryption for the scratchpad (useful in ephemeral environments where key management is unnecessary):

    # .ctxrc\nscratchpad_encrypt: false\n

    Unencrypted Scratchpads Store Secrets in Plaintext

    Only disable encryption if you understand the security implications.

    The scratchpad may contain sensitive data such as API keys, database URLs, or deployment credentials.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#custom-priority-order","level":3,"title":"Custom Priority Order","text":"

    Reorder context files to prioritize architecture over conventions:

    # .ctxrc\npriority_order:\n  - CONSTITUTION.md\n  - TASKS.md\n  - ARCHITECTURE.md\n  - DECISIONS.md\n  - CONVENTIONS.md\n  - LEARNINGS.md\n  - GLOSSARY.md\n  - AGENT_PLAYBOOK.md\n

    Files not listed in priority_order receive the lowest priority (100). The order affects ctx agent, ctx load, and drift's file-priority calculations.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#billing-token-threshold","level":3,"title":"Billing Token Threshold","text":"

    Get a one-shot warning when your session crosses a token threshold where extra charges begin (e.g., Claude Pro includes 200k tokens; beyond that costs extra):

    # .ctxrc\nbilling_token_warn: 180000   # warn before hitting the 200k paid boundary\n

    The warning fires once per session the first time token usage exceeds the threshold. Set to 0 (or omit) to disable.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#adjusted-drift-thresholds","level":3,"title":"Adjusted Drift Thresholds","text":"

    Raise or lower the entry-count thresholds that trigger drift warnings:

    # .ctxrc\nentry_count_learnings: 50   # warn above 50 learnings (default: 30)\nentry_count_decisions: 10   # warn above 10 decisions (default: 20)\nconvention_line_count: 300  # warn above 300 lines (default: 200)\n

    Set any threshold to 0 to disable that specific check.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#webhook-notifications","level":3,"title":"Webhook Notifications","text":"

    Get notified when loops complete, hooks fire, or agents reach milestones:

    # Configure the webhook URL (encrypted, safe to commit)\nctx notify setup\n\n# Test delivery\nctx notify test\n

    Filter which events reach your webhook:

    # .ctxrc\nnotify:\n  events:\n    - loop      # loop completion/max-iteration\n    - nudge     # VERBATIM relay hooks fired\n    # - relay   # all hook output (verbose, for debugging)\n    # - heartbeat  # every-prompt session-alive signal\n

    Notifications are opt-in: No events are sent unless explicitly listed.

    See Webhook Notifications for a step-by-step recipe.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#hook-message-overrides","level":2,"title":"Hook Message Overrides","text":"

    Hook messages control what text hooks emit when they fire. Each message can be overridden per-project by placing a text file at the matching path under .context/:

    .context/hooks/messages/{hook}/{variant}.txt\n

    The override takes priority over the embedded default compiled into the ctx binary. An empty file silences the message while preserving the hook's logic (counting, state tracking, cooldowns).

    Use ctx system message to discover and manage overrides:

    ctx system message list                      # see all messages\nctx system message show qa-reminder gate     # view the current template\nctx system message edit qa-reminder gate     # copy default for editing\nctx system message reset qa-reminder gate    # revert to default\n

    See Customizing Hook Messages for detailed examples including Python, JavaScript, and silence configurations.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#agent-bootstrapping","level":2,"title":"Agent Bootstrapping","text":"

    AI agents need to know the resolved context directory at session start. The ctx system bootstrap command prints the context path, file list, and operating rules in both text and JSON formats:

    ctx system bootstrap          # text output for agents\nctx system bootstrap -q       # just the context directory path\nctx system bootstrap --json   # structured output for automation\n

    The CLAUDE.md template instructs the agent to run this as its first action. Every nudge (context checkpoint, persistence reminder, etc.) also includes a Context: <dir> footer that re-anchors the agent to the correct directory throughout the session.

    This replaces the previous approach of hardcoding .context/ paths in agent instructions.

    See CLI Reference: bootstrap for full details.

    See also: CLI Reference | Context Files | Scratchpad

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/context-files/","level":1,"title":"Context Files","text":"","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#context","level":2,"title":".context/","text":"

    Each context file in .context/ serves a specific purpose.

    Files are designed to be human-readable, AI-parseable, and token-efficient.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#file-overview","level":2,"title":"File Overview","text":"File Purpose Priority CONSTITUTION.md Hard rules that must NEVER be violated 1 (highest) TASKS.md Current and planned work 2 CONVENTIONS.md Project patterns and standards 3 ARCHITECTURE.md System overview and components 4 DECISIONS.md Architectural decisions with rationale 5 LEARNINGS.md Lessons learned, gotchas, tips 6 GLOSSARY.md Domain terms and abbreviations 7 AGENT_PLAYBOOK.md Instructions for AI tools 8 (lowest) prompts/ Reusable prompt templates (optional)","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#read-order-rationale","level":2,"title":"Read Order Rationale","text":"

    The priority order follows a logical progression for AI tools:

    1. CONSTITUTION.md: Inviolable rules first. The AI tool must know what it cannot do before attempting anything.
    2. TASKS.md: Current work items. What the AI tool should focus on.
    3. CONVENTIONS.md: How to write code. Patterns and standards to follow when implementing tasks.
    4. ARCHITECTURE.md: System structure. Understanding of components and boundaries before making changes.
    5. DECISIONS.md: Historical context. Why things are the way they are, to avoid re-debating settled decisions.
    6. LEARNINGS.md: Gotchas and tips. Lessons from past work that inform the current implementation.
    7. GLOSSARY.md: Reference material. Domain terms and abbreviations for lookup as needed.
    8. AGENT_PLAYBOOK.md: Meta instructions last. How to use this context system itself. Loaded last because the agent should understand the content (rules, tasks, patterns) before the operating manual.
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#constitutionmd","level":2,"title":"CONSTITUTION.md","text":"

    Purpose: Define hard invariants: Rules that must NEVER be violated, regardless of the task.

    AI tools read this first and should refuse tasks that violate these rules.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure","level":3,"title":"Structure","text":"
    # Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these, the task \nis wrong.\n\n## Security Invariants\n\n* [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] Never store customer/user data in context files\n* [ ] Never disable security linters without documented exception\n\n## Quality Invariants\n\n* [ ] All code must pass tests before commit\n* [ ] No `any` types in TypeScript without documented reason\n* [ ] No TODO comments in main branch (*move to `TASKS.md`*)\n\n## Process Invariants\n\n* [ ] All architectural changes require a decision record\n* [ ] Breaking changes require version bump\n* [ ] Generated files are never committed\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines","level":3,"title":"Guidelines","text":"
    • Keep rules minimal and absolute
    • Each rule should be enforceable (can verify compliance)
    • Use checkbox format for clarity
    • Never compromise on these rules
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#tasksmd","level":2,"title":"TASKS.md","text":"

    Purpose: Track current work, planned work, and blockers.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_1","level":3,"title":"Structure","text":"

    Tasks are organized by Phase: logical groupings that preserve order and enable replay.

    Tasks stay in their Phase permanently; status is tracked via checkboxes and inline tags.

    # Tasks\n\n## Phase 1: Initial Setup\n\n* [x] Set up project structure\n* [x] Configure linting and formatting\n* [ ] Add CI/CD pipeline `#in-progress`\n\n## Phase 2: Core Features\n\n* [ ] Implement user authentication `#priority:high`\n* [ ] Add API rate limiting `#priority:medium`\n  * Blocked by: Need to finalize auth first\n\n## Backlog\n\n* [ ] Performance optimization `#priority:low`\n* [ ] Add metrics dashboard `#priority:deferred`\n

    Key principles:

    • Tasks never move between sections: mark as [x] or [-] in place
    • Use #in-progress inline tag to indicate current work
    • Phase headers provide structure and replay order
    • Backlog section for unscheduled work
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#tags","level":3,"title":"Tags","text":"

    Use inline backtick-wrapped tags for metadata:

    Tag Values Purpose #priority high, medium, low Task urgency #area core, cli, docs, tests Codebase area #estimate 1h, 4h, 1d Time estimate (optional) #in-progress (none) Currently being worked on

    Lifecycle tags (for session correlation):

    Tag Format When to add #added YYYY-MM-DD-HHMMSS Auto-added by ctx add task #started YYYY-MM-DD-HHMMSS When beginning work on the task #done YYYY-MM-DD-HHMMSS When marking the task [x]

    These timestamps help correlate tasks with session files and track which session started vs completed work.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#status-markers","level":3,"title":"Status Markers","text":"Marker Meaning [ ] Pending [x] Completed [-] Skipped (include reason)","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_1","level":3,"title":"Guidelines","text":"
    • Never delete tasks; mark as [x] completed or [-] skipped
    • Never move tasks between sections; use inline tags for status
    • Use ctx task archive periodically to move completed tasks to archive
    • Mark current work with #in-progress inline tag
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#decisionsmd","level":2,"title":"DECISIONS.md","text":"

    Purpose: Record architectural decisions with rationale so they don't get re-debated.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_2","level":3,"title":"Structure","text":"
    # Decisions\n\n## [YYYY-MM-DD] Decision Title\n\n**Status**: Accepted | Superseded | Deprecated\n\n**Context**: What situation prompted this decision?\n\n**Decision**: What was decided?\n\n**Rationale**: Why was this the right choice?\n\n**Consequence**: What are the implications?\n\n**Alternatives Considered**:\n* Alternative A: Why rejected\n* Alternative B: Why rejected\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#example","level":3,"title":"Example","text":"
    ## [2025-01-15] Use TypeScript Strict Mode\n\n**Status**: Accepted\n\n**Context**: Starting a new project, need to choose the type-checking level.\n\n**Decision**: Enable TypeScript strict mode with all strict flags.\n\n**Rationale**: Catches more bugs at compile time. Team has experience\nwith strict mode. Upfront cost pays off in reduced runtime errors.\n\n**Consequence**: More verbose type annotations required. Some\nthird-party libraries need type assertions.\n\n**Alternatives Considered**:\n- Basic TypeScript: Rejected because it misses null checks\n- JavaScript with JSDoc: Rejected because tooling support is weaker\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#status-values","level":3,"title":"Status Values","text":"Status Meaning Accepted Current, active decision Superseded Replaced by newer decision (link to it) Deprecated No longer relevant","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#learningsmd","level":2,"title":"LEARNINGS.md","text":"

    Purpose: Capture lessons learned, gotchas, and tips that shouldn't be forgotten.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_3","level":3,"title":"Structure","text":"
    # Learnings\n\n## Category Name\n\n### Learning Title\n\n**Discovered**: YYYY-MM-DD\n\n**Context**: When/how was this learned?\n\n**Lesson**: What's the takeaway?\n\n**Application**: How should this inform future work?\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#example_1","level":3,"title":"Example","text":"
    ## Testing\n\n### Vitest Mocks Must Be Hoisted\n\n**Discovered**: 2025-01-15\n\n**Context**: Tests were failing intermittently when mocking fs module.\n\n**Lesson**: Vitest requires `vi.mock()` calls to be hoisted to the\ntop of the file. Dynamic mocks need `vi.doMock()` instead.\n\n**Application**: Always use `vi.mock()` at file top. Use `vi.doMock()`\nonly when mock needs runtime values.\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#categories","level":3,"title":"Categories","text":"

    Organize learnings by topic:

    • Testing
    • Build & Deploy
    • Performance
    • Security
    • Third-Party Libraries
    • Git and Workflow
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#conventionsmd","level":2,"title":"CONVENTIONS.md","text":"

    Purpose: Document project patterns, naming conventions, and standards.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_4","level":3,"title":"Structure","text":"
    # Conventions\n\n## Naming\n\n* **Files**: kebab-case for all source files\n* **Components**: PascalCase for React components\n* **Functions**: camelCase, verb-first (getUser, parseConfig)\n* **Constants**: SCREAMING_SNAKE_CASE\n\n## Patterns\n\n### Pattern Name\n\n**When to use**: Situation description\n\n**Implementation**:\n// in triple backticks\n// Example code\n\n**Why**: Rationale for this pattern\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_2","level":3,"title":"Guidelines","text":"
    • Include concrete examples
    • Explain the \"why\" not just the \"what\"
    • Keep patterns minimal: Only document what's non-obvious
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#architecturemd","level":2,"title":"ARCHITECTURE.md","text":"

    Purpose: Provide system overview and component relationships.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_5","level":3,"title":"Structure","text":"
    # Architecture\n\n## Overview\n\nBrief description of what the system does and how it's organized.\n\n## Components\n\n### Component Name\n\n**Responsibility**: What this component does\n\n**Dependencies**: What it depends on\n\n**Dependents**: What depends on it\n\n**Key Files**:\n* path/to/file.ts: Description\n\n## Data Flow\n\nDescription or diagram of how data moves through the system.\n\n## Boundaries\n\nWhat's in scope vs out of scope for this codebase.\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_3","level":3,"title":"Guidelines","text":"
    • Keep diagrams simple (Mermaid works well)
    • Focus on boundaries and interfaces
    • Update when major structural changes occur
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#glossarymd","level":2,"title":"GLOSSARY.md","text":"

    Purpose: Define domain terms, abbreviations, and project vocabulary.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_6","level":3,"title":"Structure","text":"
    # Glossary\n\n## Domain Terms\n\n### Term Name\n\n**Definition**: What it means in this project's context\n\n**Not to be confused with**: Similar terms that mean different things\n\n**Example**: How it's used\n\n## Abbreviations\n\n| Abbrev | Expansion                     | Context                |\n|--------|-------------------------------|------------------------|\n| ADR    | Architectural Decision Record | Decision documentation |\n| SUT    | System Under Test             | Testing                |\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_4","level":3,"title":"Guidelines","text":"
    • Define project-specific meanings
    • Clarify potentially ambiguous terms
    • Include abbreviations used in code or docs
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#agent_playbookmd","level":2,"title":"AGENT_PLAYBOOK.md","text":"

    Purpose: Explicit instructions for how AI tools should read, apply, and update context.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#key-sections","level":3,"title":"Key Sections","text":"

    Read Order: Priority order for loading context files

    When to Update: Events that trigger context updates

    How to Avoid Hallucinating Memory: Critical rules:

    1. Never assume: If not in files, you don't know it
    2. Never invent history: Don't claim \"we discussed\" without evidence
    3. Verify before referencing: Search files before citing
    4. When uncertain, say so
    5. Trust files over intuition

    Context Update Commands: Format for automated updates via ctx watch:

    <context-update type=\"task\">Implement rate limiting</context-update>\n<context-update type=\"complete\">user auth</context-update>\n<context-update type=\"learning\"\n  context=\"Debugging hooks\"\n  lesson=\"Hooks receive JSON via stdin\"\n  application=\"Parse JSON stdin with the host language\"\n>Hook Input Format</context-update>\n<context-update type=\"decision\"\n  context=\"Need a caching layer\"\n  rationale=\"Redis is fast and team has experience\"\n  consequence=\"Must provision Redis infrastructure\"\n>Use Redis for caching</context-update>\n

    See Integrations for full documentation.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#prompts","level":2,"title":"prompts/","text":"

    Purpose: Store reusable prompt templates - plain markdown files with no frontmatter that provide lightweight, named instructions for common tasks like code review, refactoring, or explaining code.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#how-it-works","level":3,"title":"How It Works","text":"
    • ctx init stamps starter templates: code-review.md, refactor.md, explain.md
    • Manage via ctx prompt list, ctx prompt show, ctx prompt add, ctx prompt rm
    • Invoke in AI sessions with /ctx-prompt <name>
    • Committed to git by default for team sharing

    See the Prompt Templates recipe for the full workflow.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#parsing-rules","level":2,"title":"Parsing Rules","text":"

    All context files follow these conventions:

    1. Headers define structure: # for title, ## for sections, ### for items
    2. Bold keys for fields: **Key**: followed by value
    3. Code blocks are literal: Never parse code block content as structure
    4. Lists are ordered: Items appear in priority/chronological order
    5. Tags are inline: Backtick-wrapped tags like #priority:high
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#further-reading","level":2,"title":"Further Reading","text":"
    • Refactoring with Intent: how persistent context prevents drift during refactoring sessions
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#token-efficiency","level":2,"title":"Token Efficiency","text":"

    Keep context files concise:

    • Use abbreviations in tags, not prose;
    • Omit obvious words (\"The,\" \"This\");
    • Prefer bullet points over paragraphs;
    • Keep examples minimal but illustrative;
    • Archive old completed items periodically.

    Next Up: Prompting Guide →: effective prompts for AI sessions with ctx

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/contributing/","level":1,"title":"Contributing","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#development-setup","level":2,"title":"Development Setup","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#prerequisites","level":3,"title":"Prerequisites","text":"
    • Go (version defined in go.mod)
    • Claude Code
    • Git
    • GNU Make
    • Zensical
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#1-fork-or-clone-the-repository","level":3,"title":"1. Fork (or Clone) the Repository","text":"
    # Fork on GitHub, then:\ngit clone https://github.com/<you>/ctx.git\ncd ctx\n\n# Or, if you have push access:\ngit clone https://github.com/ActiveMemory/ctx.git\ncd ctx\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#2-build-and-install-the-binary","level":3,"title":"2. Build and Install the Binary","text":"
    make build\nsudo make install\n

    This compiles the ctx binary and places it in /usr/local/bin/.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#3-install-the-plugin-from-your-local-clone","level":3,"title":"3. Install the Plugin from Your Local Clone","text":"

    The repository ships a Claude Code plugin under internal/assets/claude/. Point Claude Code at your local copy so that skills and hooks reflect your working tree: no reinstall needed after edits:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace
    4. Enter the absolute path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: it points Claude Code to the actual plugin in internal/assets/claude);
    5. Back in /plugin, select Install and choose ctx.

    Claude Code Caches Plugin Files

    Even though the marketplace points at a directory on disk, Claude Code caches skills and hooks. After editing files under internal/assets/claude/, clear the cache and restart:

    make plugin-reload   # then restart Claude Code\n

    See Skill or Hook Changes for details.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#4-verify","level":3,"title":"4. Verify","text":"
    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed\n

    You should see the ctx plugin listed, sourced from your local path.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#project-layout","level":2,"title":"Project Layout","text":"
    ctx/\n├── cmd/ctx/            # CLI entry point\n├── internal/\n│   ├── assets/claude/  # ← Claude Code plugin (skills, hooks)\n│   ├── bootstrap/      # Project initialization templates\n│   ├── claude/         # Claude Code integration helpers\n│   ├── cli/            # Command implementations\n│   ├── config/         # Configuration loading\n│   ├── context/        # Core context logic\n│   ├── crypto/         # Scratchpad encryption\n│   ├── drift/          # Drift detection\n│   ├── index/          # Context file indexing\n│   ├── journal/        # Journal site generation\n│   ├── memory/         # Memory bridge (discover, mirror, import, publish)\n│   ├── notify/         # Webhook notifications\n│   ├── rc/             # .ctxrc parsing\n│   ├── recall/         # Session history and parsers\n│   ├── sysinfo/        # System resource monitoring\n│   ├── task/           # Task management\n│   └── validation/     # Input validation\n├── .claude/\n│   └── skills/         # Dev-only skills (not distributed)\n├── assets/             # Static assets (banners, logos)\n├── docs/               # Documentation site source\n├── editors/            # Editor extensions (VS Code)\n├── examples/           # Example configurations\n├── hack/               # Build scripts and runbooks\n├── specs/              # Feature specifications\n└── .context/           # ctx's own context (dogfooding)\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#skills-two-directories-one-rule","level":3,"title":"Skills: Two Directories, One Rule","text":"Directory What lives here Distributed to users? internal/assets/claude/skills/ The 29 ctx-* skills that ship with the plugin Yes .claude/skills/ Dev-only skills (release, QA, backup, etc.) No

    internal/assets/claude/skills/ is the single source of truth for user-facing skills. If you are adding or modifying a ctx-* skill, edit it there.

    .claude/skills/ holds skills that only make sense inside this repository (release automation, QA checks, backup scripts). These are never distributed to users.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#dev-only-skills-reference","level":4,"title":"Dev-Only Skills Reference","text":"Skill When to use /_ctx-absorb Merge deltas from a parallel worktree or separate checkout /_ctx-audit Detect code-level drift after YOLO sprints or before releases /_ctx-backup Backup context and Claude data to SMB share /_ctx-qa Run QA checks before committing /_ctx-release Run the full release process /_ctx-release-notes Generate release notes for dist/RELEASE_NOTES.md /_ctx-alignment-audit Audit doc claims against agent instructions /_ctx-update-docs Check docs/code consistency after changes

    Six skills previously in this list have been promoted to bundled plugin skills and are now available to all ctx users: /ctx-brainstorm, /ctx-check-links, /ctx-sanitize-permissions, /ctx-skill-creator, /ctx-spec, /ctx-verify.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#how-to-add-things","level":2,"title":"How To Add Things","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-new-cli-command","level":3,"title":"Adding a New CLI Command","text":"
    1. Create a package under internal/cli/<name>/;
    2. Implement Cmd() *cobra.Command as the entry point;
    3. Register it in internal/bootstrap/bootstrap.go (add import + call in Initialize);
    4. Use cmd.Printf/cmd.Println for output (not fmt.Print);
    5. Add tests in the same package (<name>_test.go);
    6. Add a section to the appropriate CLI doc page in docs/cli/.

    Pattern to follow: internal/cli/pad/pad.go (parent with subcommands) or internal/cli/complete/complete.go (single command).

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-new-session-parser","level":3,"title":"Adding a New Session Parser","text":"

    The recall system uses a SessionParser interface. To add support for a new AI tool (e.g. Aider, Cursor):

    1. Create internal/recall/parser/<tool>.go;
    2. Implement parsing logic that returns []*Session;
    3. Register the parser in FindSessions() / FindSessionsForCWD();
    4. Use config.Tool* constants for the tool identifier;
    5. Add test fixtures and parser tests.

    Pattern to follow: the Claude Code JSONL parser in internal/recall/parser/.

    Multilingual session headers

    The Markdown parser recognizes session header prefixes configured via session_prefixes in .ctxrc (default: Session:). To support a new language, users add a prefix to their .ctxrc - no code change needed. New parser implementations can use rc.SessionPrefixes() if they also need prefix-based header detection.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-bundled-skill","level":3,"title":"Adding a Bundled Skill","text":"
    1. Create internal/assets/claude/skills/<skill-name>/SKILL.md;
    2. Follow the skill format: trigger, negative triggers, steps, quality gate;
    3. Run make plugin-reload and restart Claude Code to test;
    4. Add a Skill entry to .claude-plugin/plugin.json if user-invocable;
    5. Document in docs/reference/skills.md.

    Pattern to follow: any skill in internal/assets/claude/skills/ctx-status/.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#test-expectations","level":3,"title":"Test Expectations","text":"
    • Unit tests: colocated with source (foo.go → foo_test.go);
    • Test helpers: use t.Helper() so failures point to callers;
    • HOME isolation: use t.TempDir() + t.Setenv(\"HOME\", ...) for tests that touch ~/.claude/ or ~/.ctx/;
    • rc.Reset(): call after os.Chdir in tests that change working directory (rc caches on first access);
    • No network: all tests run offline, use fixtures.

    Run make test before submitting. Target: no failures, no skips.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#day-to-day-workflow","level":2,"title":"Day-to-Day Workflow","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#go-code-changes","level":3,"title":"Go Code Changes","text":"

    After modifying Go source files, rebuild and reinstall:

    make build && sudo make install\n

    The ctx binary is statically compiled. There is no hot reload. You must rebuild for Go changes to take effect.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#skill-or-hook-changes","level":3,"title":"Skill or Hook Changes","text":"

    Edit files under internal/assets/claude/skills/ or internal/assets/claude/hooks/.

    Claude Code caches plugin files, so edits aren't picked up automatically.

    Clear the cache and restart:

    make plugin-reload   # nukes ~/.claude/plugins/cache/activememory-ctx/\n# then restart Claude Code\n

    The plugin will be re-installed from your local marketplace on startup. No version bump is needed during development.

    Version bumps are for releases, not iteration

    Only bump VERSION, plugin.json, and marketplace.json when cutting a release. During development, make plugin-reload is all you need.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#configuration-profiles","level":3,"title":"Configuration Profiles","text":"

    The repo ships two .ctxrc source profiles. The working copy (.ctxrc) is gitignored and swapped between them:

    File Purpose .ctxrc.base Golden baseline: all defaults, no logging .ctxrc.dev Dev profile: notify events enabled, verbose logging .ctxrc Working copy (gitignored: copied from one of the above)

    Use ctx commands to switch:

    ctx config switch dev      # switch to dev profile\nctx config switch base     # switch to base profile\nctx config status          # show which profile is active\n

    After cloning, run ctx config switch dev to get started with full logging.

    See Configuration for the full .ctxrc option reference.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#backups","level":3,"title":"Backups","text":"

    Back up project context and global Claude Code data with:

    ctx system backup                    # both project + global (default)\nctx system backup --scope project    # .context/, .claude/, ideas/ only\nctx system backup --scope global     # ~/.claude/ only\n

    Archives are saved to /tmp/. When CTX_BACKUP_SMB_URL is configured, they are also copied to an SMB share. See CLI Reference: backup for details.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#running-tests","level":3,"title":"Running Tests","text":"
    make test   # fast: all tests\nmake audit  # full: fmt + vet + lint + drift + docs + test\nmake smoke  # build + run basic commands end-to-end\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#running-the-docs-site-locally","level":3,"title":"Running the Docs Site Locally","text":"
    make site-setup  # one-time: install zensical via pipx\nmake site-serve  # serve at localhost\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#submitting-changes","level":2,"title":"Submitting Changes","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#before-you-start","level":3,"title":"Before You Start","text":"
    1. Check existing issues to avoid duplicating effort;
    2. For large changes, open an issue first to discuss the approach;
    3. Read the specs in specs/ for design context.
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#pull-request-process","level":3,"title":"Pull Request Process","text":"

    Respect the maintainers' time and energy: Keep your pull requests isolated and strive to minimze code changes.

    If you Pull Request solves more than one distinct issues, it's better to create separate pull requests instead of sending them in one large bundle.

    1. Create a feature branch: git checkout -b feature/my-feature;
    2. Make your changes;
    3. Run make audit to catch issues early;
    4. Commit with a clear message;
    5. Push and open a pull request.

    Audit Your Code Before Submitting

    Run make audit before submitting:

    make audit covers formatting, vetting, linting, drift checks, doc consistency, and tests in one pass.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#commit-messages","level":3,"title":"Commit Messages","text":"

    Following conventional commits is recommended but not required:

    Types: feat, fix, docs, test, refactor, chore

    Examples:

    • feat(cli): add ctx export command
    • fix(drift): handle missing files gracefully
    • docs: update installation instructions
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#code-style","level":3,"title":"Code Style","text":"
    • Follow Go conventions (gofmt, go vet);
    • Keep functions focused and small;
    • Add tests for new functionality;
    • Handle errors explicitly.
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#code-of-conduct","level":2,"title":"Code of Conduct","text":"

    A clear context requires respectful collaboration.

    ctx follows the Contributor Covenant.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#boring-legal-stuff","level":2,"title":"Boring Legal Stuff","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#developer-certificate-of-origin-dco","level":3,"title":"Developer Certificate of Origin (DCO)","text":"

    By contributing, you agree to the Developer Certificate of Origin.

    All commits must be signed off:

    git commit -s -m \"feat: add new feature\"\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#license","level":3,"title":"License","text":"

    Contributions are licensed under the Apache 2.0 License.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/faq/","level":1,"title":"FAQ","text":"","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#why-markdown","level":2,"title":"Why Markdown?","text":"

    Markdown is human-readable, version-controllable, and tool-agnostic. Every AI model can parse it natively. Every developer can read it in a terminal, a browser, or a code review. There's no schema to learn, no binary format to decode, no vendor lock-in. You can inspect your context with cat, diff it with git diff, and review it in a PR.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#does-ctx-work-offline","level":2,"title":"Does ctx work offline?","text":"

    Yes. ctx is completely local. It reads and writes files on disk, generates context packets from local state, and requires no network access. The only feature that touches the network is the optional webhook notifications hook, which you have to explicitly configure.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#what-gets-committed-to-git","level":2,"title":"What gets committed to git?","text":"

    The .context/ directory: yes, commit it. That's the whole point. Team members and AI agents read the same context files.

    What not to commit:

    • .ctx.key: your encryption key. Stored at ~/.ctx/.ctx.key, never in the repo. ctx init handles this automatically.
    • journal/ and logs/: generated data, potentially large. ctx init adds these to .gitignore.
    • scratchpad.enc: your choice. It's encrypted, so it's safe to commit if you want shared scratchpad state. See Scratchpad for details.
    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#how-big-should-my-token-budget-be","level":2,"title":"How big should my token budget be?","text":"

    The default is 8000 tokens, which works well for most projects. Configure it via .ctxrc or the CTX_TOKEN_BUDGET environment variable:

    # In .ctxrc\ntoken_budget = 12000\n\n# Or as an environment variable\nexport CTX_TOKEN_BUDGET=12000\n\n# Or per-invocation\nctx agent --budget 4000\n

    Higher budgets include more context but cost more tokens per request. Lower budgets force sharper prioritization: ctx drops lower-priority content first, so CONSTITUTION and TASKS always make the cut.

    See Configuration for all available settings.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#why-not-a-database","level":2,"title":"Why not a database?","text":"

    Files are inspectable, diffable, and reviewable in pull requests. You can grep them, cat them, pipe them through jq or awk. They work with every version control system and every text editor.

    A database would add a dependency, require migrations, and make context opaque. The design bet is that context should be as visible and portable as the code it describes.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#does-it-work-with-tools-other-than-claude-code","level":2,"title":"Does it work with tools other than Claude Code?","text":"

    Yes. ctx agent outputs a context packet that any AI tool can consume: paste it into ChatGPT, Cursor, Copilot, Aider, or anything else that accepts text input.

    Claude Code gets first-class integration via the ctx plugin (hooks, skills, automatic context loading). VS Code Copilot Chat has a dedicated ctx extension. Other tools integrate via generated instruction files or manual pasting.

    See Integrations for tool-specific setup, including the multi-tool recipe.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#can-i-use-ctx-on-an-existing-project","level":2,"title":"Can I use ctx on an existing project?","text":"

    Yes. Run ctx init in any repo and it creates .context/ with template files. Start recording decisions, tasks, and conventions as you work. Context grows naturally; you don't need to backfill everything on day one.

    See Getting Started for the full setup flow, or Joining a ctx Project if someone else already initialized it.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#what-happens-when-context-files-get-too-big","level":2,"title":"What happens when context files get too big?","text":"

    Token budgeting handles this automatically. ctx agent prioritizes content by file priority (CONSTITUTION first, GLOSSARY last) and trims lower-priority entries when the budget is tight.

    For manual maintenance, ctx compact archives completed tasks and old entries, keeping active context lean. You can also run ctx task archive to move completed tasks out of TASKS.md.

    The goal is to keep context files focused on current state. Historical entries belong in git history or the archive.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#is-context-meant-to-be-shared","level":2,"title":"Is .context/ meant to be shared?","text":"

    Yes. Commit it to your repo. Every team member and every AI agent reads the same files. That's the mechanism for shared memory: decisions made in one session are visible in the next, regardless of who (or what) starts it.

    The only per-user state is the encryption key (~/.ctx/.ctx.key) and the optional scratchpad. Everything else is team-shared by design.

    Related:

    • Getting Started - installation and first setup
    • Configuration - .ctxrc, environment variables, and defaults
    • Context Files - what each file does and how to use it
    ","path":["Home","FAQ"],"tags":[]},{"location":"home/first-session/","level":1,"title":"Your First Session","text":"

    Here's what a complete first session looks like, from initialization to the moment your AI cites your project context back to you.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-1-initialize-your-project","level":2,"title":"Step 1: Initialize Your Project","text":"

    Run ctx init in your project root:

    cd your-project\nctx init\n

    Sample output:

    Context initialized in .context/\n\n  ✓ CONSTITUTION.md\n  ✓ TASKS.md\n  ✓ DECISIONS.md\n  ✓ LEARNINGS.md\n  ✓ CONVENTIONS.md\n  ✓ ARCHITECTURE.md\n  ✓ GLOSSARY.md\n  ✓ AGENT_PLAYBOOK.md\n\nCreating project root files...\n  ✓ PROMPT.md\n  ✓ IMPLEMENTATION_PLAN.md\n\nSetting up encryption key...\n  ✓ ~/.ctx/.ctx.key\n\nClaude Code plugin (hooks + skills):\n  Install: claude /plugin marketplace add ActiveMemory/ctx\n  Then:    claude /plugin install ctx@activememory-ctx\n\nNext steps:\n  1. Edit .context/TASKS.md to add your current tasks\n  2. Run 'ctx status' to see context summary\n  3. Run 'ctx agent' to get AI-ready context packet\n

    This created your .context/ directory with template files.

    For Claude Code, install the ctx plugin to get automatic hooks and skills.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-2-populate-your-context","level":2,"title":"Step 2: Populate Your Context","text":"

    Add a task and a decision: These are the entries your AI will remember:

    ctx add task \"Implement user authentication\"\n\n# Output: ✓ Added to TASKS.md\n\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Output: ✓ Added to DECISIONS.md\n

    These entries are what the AI will recall in future sessions. You don't need to populate everything now: Context grows naturally as you work.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-3-check-your-context","level":2,"title":"Step 3: Check Your Context","text":"
    ctx status\n

    Sample output:

    Context Status\n====================\n\nContext Directory: .context/\nTotal Files: 8\nToken Estimate: 1,247 tokens\n\nFiles:\n  ✓ CONSTITUTION.md (loaded)\n  ✓ TASKS.md (1 items)\n  ✓ DECISIONS.md (1 items)\n  ○ LEARNINGS.md (empty)\n  ✓ CONVENTIONS.md (loaded)\n  ✓ ARCHITECTURE.md (loaded)\n  ✓ GLOSSARY.md (loaded)\n  ✓ AGENT_PLAYBOOK.md (loaded)\n\nRecent Activity:\n  - TASKS.md modified 2 minutes ago\n  - DECISIONS.md modified 1 minute ago\n

    Notice the token estimate: This is how much context your AI will load.

    The ○ next to LEARNINGS.md means it's still empty; it will fill in as you capture lessons during development.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-4-start-an-ai-session","level":2,"title":"Step 4: Start an AI Session","text":"

    With Claude Code (and the ctx plugin), start every session with:

    /ctx-remember\n

    This loads your context and presents a structured readback so you can confirm the agent knows what is going on. Context also loads automatically via hooks, but the explicit ceremony gives you a readback to verify.

    Using VS Code?

    With VS Code Copilot Chat (and the ctx extension), type @ctx /agent in chat to load your context packet, or @ctx /status to check your project context. Run ctx hook copilot --write once to generate .github/copilot-instructions.md for automatic context loading.

    If you are not using Claude Code, generate a context packet for your AI tool:

    ctx agent --budget 8000\n

    Sample output:

    # Context Packet\nGenerated: 2026-02-14T15:30:45Z | Budget: 8000 tokens | Used: ~2450\n\n## Read These Files (in order)\n1. .context/CONSTITUTION.md\n2. .context/TASKS.md\n3. .context/CONVENTIONS.md\n...\n\n## Current Tasks\n- [ ] Implement user authentication\n- [ ] Add rate limiting to API endpoints\n\n## Key Conventions\n- Use gofmt for formatting\n- Path construction uses filepath.Join\n\n## Recent Decisions\n## [2026-02-14-120000] Use PostgreSQL for the primary database\n\n**Context**: Evaluated PostgreSQL, MySQL, and SQLite...\n**Rationale**: PostgreSQL offers better JSON support...\n\n## Key Learnings\n## [2026-02-14-100000] Connection pool sizing matters\n\n**Context**: Hit connection limits under load...\n**Lesson**: Default pool size of 10 is too low for concurrent requests...\n\n## Also Noted\n- Use JWT for session management\n- Always validate input at API boundary\n

    Paste this output into your AI tool's system prompt or conversation start.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-5-verify-it-works","level":2,"title":"Step 5: Verify It Works","text":"

    Ask your AI: \"What are our current tasks?\"

    A working setup produces a response like:

    Based on the project context, you have one active task:\n\n- **Implement user authentication** (pending)\n\nThere's also a recent architectural decision to **use PostgreSQL for\nthe primary database**, chosen for its ACID compliance and JSON support.\n\nWant me to start on the authentication task?\n

    That's the success moment:

    The AI is citing your exact context entries from Step 2, not hallucinating or asking you to re-explain.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#what-gets-created","level":2,"title":"What Gets Created","text":"
    .context/\n├── CONSTITUTION.md     # Hard rules: NEVER violate these\n├── TASKS.md            # Current and planned work\n├── CONVENTIONS.md      # Project patterns and standards\n├── ARCHITECTURE.md     # System overview\n├── DECISIONS.md        # Architectural decisions with rationale\n├── LEARNINGS.md        # Lessons learned, gotchas, tips\n├── GLOSSARY.md         # Domain terms and abbreviations\n└── AGENT_PLAYBOOK.md   # How AI tools should use this\n

    Claude Code integration (hooks + skills) is provided by the ctx plugin: See Integrations/Claude Code.

    VS Code Copilot Chat integration is provided by the ctx extension: See Integrations/VS Code.

    See Context Files for detailed documentation of each file.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#what-to-gitignore","level":2,"title":"What to .gitignore","text":"

    Rule of Thumb

    • If it's knowledge (decisions, tasks, learnings, conventions), commit it.
    • If it's generated output, raw session data, or a secret, .gitignore it.

    Commit your .context/ knowledge files: that's the whole point.

    You should .gitignore the generated and sensitive paths:

    # Journal data (large, potentially sensitive)\n.context/journal/\n.context/journal-site/\n.context/journal-obsidian/\n\n# Hook logs (machine-specific)\n.context/logs/\n\n# Legacy encryption key path (copy to ~/.ctx/.ctx.key if needed)\n.context/.ctx.key\n\n# Claude Code local settings (machine-specific)\n.claude/settings.local.json\n

    ctx init Patches Your .gitignore for You

    ctx init automatically adds these entries to your .gitignore.

    Review the additions with cat .gitignore after init.

    See also:

    • Security Considerations
    • Scratchpad Encryption
    • Session Journal

    Next Up: Common Workflows →: day-to-day commands for tracking context, checking health, and browsing history.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/getting-started/","level":1,"title":"Getting Started","text":"","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#prerequisites","level":2,"title":"Prerequisites","text":"

    ctx does not require git, but using version control with your .context/ directory is strongly recommended:

    AI sessions occasionally modify or overwrite context files inadvertently. With git, the AI can check history and restore lost content: Without it, the data is gone.

    Also, several ctx features (journal changelog, blog generation) also use git history directly.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#installation","level":2,"title":"Installation","text":"

    Every setup starts with the ctx binary: the CLI tool itself.

    If you use Claude Code, you also install the ctx plugin, which adds hooks (context autoloading, persistence nudges) and 25+ /ctx-* skills. For other AI tools, ctx integrates via generated instruction files or manual context pasting: see Integrations for tool-specific setup.

    Pick one of the options below to install the binary. Claude Code users should also follow the plugin steps included in each option.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#option-1-build-from-source-recommended","level":3,"title":"Option 1: Build from Source (Recommended)","text":"

    Requires Go (version defined in go.mod) and Claude Code.

    git clone https://github.com/ActiveMemory/ctx.git\ncd ctx\nmake build\nsudo make install\n

    Install the Claude Code plugin from your local clone:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace
    4. Enter the path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: It points Claude Code to the actual plugin in internal/assets/claude)
    5. Back in /plugin, select Install and choose ctx

    This points Claude Code at the plugin source on disk. Changes you make to hooks or skills take effect immediately: No reinstall is needed.

    Local Installs Need Manual Enablement

    Unlike marketplace installs, local plugin installs are not auto-enabled globally. The plugin will only work in projects that explicitly enable it. Run ctx init in each project (it auto-enables the plugin), or add the entry to ~/.claude/settings.json manually:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Verify:

    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed\n

    Use the Source, Luke

    Building from source gives you the latest features and bug fixes.

    Since ctx is predominantly a developer tool, this is the recommended approach:

    You get the freshest code, can inspect what you are installing, and the plugin stays in sync with the binary.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#option-2-binary-download-marketplace","level":3,"title":"Option 2: Binary Download + Marketplace","text":"

    Pre-built binaries are available from the releases page.

    Linux (x86_64)Linux (ARM64)macOS (Apple Silicon)macOS (Intel)Windows 
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64\nchmod +x ctx-0.6.0-linux-amd64\nsudo mv ctx-0.6.0-linux-amd64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-arm64\nchmod +x ctx-0.6.0-linux-arm64\nsudo mv ctx-0.6.0-linux-arm64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-arm64\nchmod +x ctx-0.6.0-darwin-arm64\nsudo mv ctx-0.6.0-darwin-arm64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-amd64\nchmod +x ctx-0.6.0-darwin-amd64\nsudo mv ctx-0.6.0-darwin-amd64 /usr/local/bin/ctx\n

    Download ctx-0.6.0-windows-amd64.exe from the releases page and add it to your PATH.

    Claude Code users: install the plugin from the marketplace:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace;
    4. Enter ActiveMemory/ctx;
    5. Back in /plugin, select Install and choose ctx.

    Other tool users: see Integrations for tool-specific setup (Cursor, Copilot, Aider, Windsurf, etc.).

    Verify the Plugin Is Enabled

    After installing, confirm the plugin is enabled globally. Check ~/.claude/settings.json for an enabledPlugins entry. If missing, run ctx init in your project (it auto-enables the plugin), or add it manually:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Verify:

    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed (Claude Code only)\n
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#verifying-checksums","level":4,"title":"Verifying Checksums","text":"

    Each binary has a corresponding .sha256 checksum file. To verify your download:

    # Download the checksum file\ncurl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64.sha256\n\n# Verify the binary\nsha256sum -c ctx-0.6.0-linux-amd64.sha256\n

    On macOS, use shasum -a 256 -c instead of sha256sum -c.

    Plugin Details

    After installation (either option) you get:

    • Context autoloading: ctx agent runs on every tool use (with cooldown)
    • Persistence nudges: reminders to capture learnings and decisions
    • Post-commit hooks: nudge context capture after git commit
    • Context size monitoring: alerts as sessions grow large
    • 25+ skills: /ctx-status, /ctx-add-task, /ctx-recall, and more

    See Integrations for the full hook and skill reference.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#quick-start","level":2,"title":"Quick Start","text":"","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#1-initialize-context","level":3,"title":"1. Initialize Context","text":"
    cd your-project\nctx init\n

    This creates a .context/ directory with template files and an encryption key at ~/.ctx/ for the encrypted scratchpad. For Claude Code, install the ctx plugin for automatic hooks and skills.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#2-check-status","level":3,"title":"2. Check Status","text":"
    ctx status\n

    Shows context summary: files present, token estimate, and recent activity.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#3-start-using-with-ai","level":3,"title":"3. Start Using with AI","text":"

    With Claude Code (and the ctx plugin installed), context loads automatically via hooks.

    With VS Code Copilot Chat, install the ctx extension and use @ctx /status, @ctx /agent, and other slash commands directly in chat. Run ctx hook copilot --write to generate .github/copilot-instructions.md for automatic context loading.

    For other tools, paste the output of:

    ctx agent --budget 8000\n
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#4-verify-it-works","level":3,"title":"4. Verify It Works","text":"

    Ask your AI: \"Do you remember?\"

    It should cite specific context: current tasks, recent decisions, or previous session topics.

    Next Up:

    • Your First Session →: a step-by-step walkthrough from ctx init to verified recall
    • Common Workflows →: day-to-day commands for tracking context, checking health, and browsing history
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/is-ctx-right/","level":1,"title":"Is It Right for Me?","text":"","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#good-fit","level":2,"title":"Good Fit","text":"

    ctx shines when context matters more than code.

    If any of these sound like your project, it's worth trying:

    • Multi-session AI work: You use AI across many sessions on the same codebase, and re-explaining is slowing you down.
    • Architectural decisions that matter: Your project has non-obvious choices (database, auth strategy, API design) that the AI keeps second-guessing.
    • \"Why\" matters as much as \"what\": you need the AI to understand rationale, not just current code
    • Team handoffs: Multiple people (or multiple AI tools) work on the same project and need shared context.
    • AI-assisted development across tools: Uou switch between Claude Code, Cursor, Copilot, or other tools and want context to follow the project, not the tool.
    • Long-lived projects: Anything you'll work on for weeks or months, where accumulated knowledge has compounding value.
    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#may-not-be-the-right-fit","level":2,"title":"May Not Be the Right Fit","text":"

    ctx adds overhead that isn't worth it for every project. Be honest about when to skip it:

    • One-off scripts: If the project is a single file you'll finish today, there's nothing to remember.
    • RAG-only workflows: If retrieval from an external knowledge base already gives the agent everything it needs for each session, adding ctx may be unnecessary. RAG retrieves information; ctx defines the project's working memory: They are complementary.
    • No AI involvement: ctx is designed for human-AI workflows; without an AI consumer, the files are just documentation.
    • Enterprise-managed context platforms: If your organization provides centralized context services, ctx may duplicate that layer.

    For a deeper technical comparison with RAG, prompt management tools, and agent frameworks, see ctx and Similar Tools.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#project-size-guide","level":2,"title":"Project Size Guide","text":"","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#solo-developer-single-repo","level":3,"title":"Solo Developer, Single Repo","text":"

    This is ctx's sweet spot.

    You get the most value here: one person, one project, decisions, and learnings accumulating over time. Setup takes 5 minutes and the .context/ directory directory stays small, and every session gets faster.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#small-team-one-or-two-repos","level":3,"title":"Small Team, One or Two Repos","text":"

    Works well.

    Context files commit to git, so the whole team shares the same decisions and conventions. Each person's AI starts with the team's decisions already loaded. Merge conflicts on .context/ files are rare and easy to resolve (they are just Markdown).

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#multiple-repos-or-larger-teams","level":3,"title":"Multiple Repos or Larger Teams","text":"

    ctx operates per repository.

    Each repo has its own .context/ directory with its own decisions, tasks, and learnings. This matches the way code, ownership, and history already work in git.

    There is no built-in cross-repo context layer.

    For organizations that need centralized, organization-wide knowledge, ctx complements a platform solution by providing durable, project-local working memory for AI sessions.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#5-minute-trial","level":2,"title":"5-Minute Trial","text":"

    Zero commitment. Try it, and delete .context/ if it's not for you.

    Using Claude Code?

    Install the ctx plugin from the Marketplace for Claude-native hooks, skills, and automatic context loading:

    1. Type /plugin and press Enter
    2. Select Marketplaces → Add Marketplace
    3. Enter ActiveMemory/ctx
    4. Back in /plugin, select Install and choose ctx

    You'll still need the ctx binary for the CLI: See Getting Started for install options.

    # 1. Initialize\ncd your-project\nctx init\n\n# 2. Add one real decision from your project\nctx add decision \"Your actual architectural choice\" \\\n  --context \"What prompted this decision\" \\\n  --rationale \"Why you chose this approach\" \\\n  --consequence \"What changes as a result\"\n\n# 3. Check what the AI will see\nctx status\n\n# 4. Start an AI session and ask: \"Do you remember?\"\n

    If the AI cites your decision back to you, it's working.

    Want to remove it later? One command:

    rm -rf .context/\n

    No dependencies to uninstall. No configuration to revert. Just files.

    Ready to try it out?

    • Join the Community→: Open Source is better together.
    • Getting Started →: Full installation and setup.
    • ctx and Similar Tools →: Detailed comparison with other approaches.
    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/joining-a-project/","level":1,"title":"Joining a ctx Project","text":"

    You've joined a team or inherited a project, and there's a .context/ directory in the repo. Good news: someone already set up persistent context. This page gets you oriented fast.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#what-to-read-first","level":2,"title":"What to Read First","text":"

    The files in .context/ have a deliberate priority order. Read them top-down:

    1. CONSTITUTION.md: Hard rules. Read this before you touch anything. These are inviolable constraints the team has agreed on.
    2. TASKS.md: Current and planned work. Shows what's in progress, what's pending, and what's blocked.
    3. CONVENTIONS.md: How the team writes code. Naming patterns, file organization, preferred idioms.
    4. ARCHITECTURE.md: System overview. Components, boundaries, data flow.
    5. DECISIONS.md: Why things are the way they are. Saves you from re-proposing something the team already evaluated and rejected.
    6. LEARNINGS.md: Gotchas, tips, and hard-won lessons. The stuff that doesn't fit anywhere else but will save you hours.

    See Context Files for detailed documentation of each file's structure and purpose.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#checking-context-health","level":2,"title":"Checking Context Health","text":"

    Before you start working, check whether the context is current:

    ctx status\n

    This shows file counts, token estimates, and recent activity. If files haven't been touched in weeks, the context may be stale.

    ctx drift\n

    This compares context files against recent code changes and flags potential drift: decisions that no longer match the codebase, conventions that have shifted, or tasks that look outdated.

    If things are stale, mention it to the team. Don't silently fix it yourself on day one.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#starting-your-first-session","level":2,"title":"Starting Your First Session","text":"

    Generate a context packet to prime your AI:

    ctx agent --budget 8000\n

    This outputs a token-budgeted summary of the project context, ordered by priority. With Claude Code and the ctx plugin, context loads automatically via hooks. You can also use the /ctx-remember skill to get a structured readback of what the AI knows.

    The readback is your verification step: if the AI can cite specific tasks and decisions, the context is working.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#adding-context","level":2,"title":"Adding Context","text":"

    As you work, you'll discover things worth recording. Use the CLI:

    # Record a decision you made or learned about\nctx add decision \"Use connection pooling for DB access\" \\\n  --rationale \"Reduces connection overhead under load\"\n\n# Capture a gotcha you hit\nctx add learning \"Redis timeout defaults to 5s\" \\\n  --context \"Hit timeouts during bulk operations\" \\\n  --application \"Set explicit timeout for batch jobs\"\n\n# Add a convention you noticed the team follows\nctx add convention \"All API handlers return structured errors\"\n

    You can also just tell the AI: \"Record this as a learning\" or \"Add this decision to context.\" With the ctx plugin, context-update commands handle the file writes.

    See the Knowledge Capture recipe for the full workflow.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#session-etiquette","level":2,"title":"Session Etiquette","text":"

    A few norms for working in a ctx-managed project:

    • Respect existing conventions. If CONVENTIONS.md says \"use filepath.Join,\" use filepath.Join. If you disagree, propose a change, don't silently diverge.
    • Don't restructure context files without asking. The file layout and section structure are shared state. Reorganizing them affects every team member and every AI session.
    • Mark tasks done when complete. Check the box ([x]) in place. Don't move tasks between sections or delete them.
    • Add context as you go. Decisions, learnings, and conventions you discover are valuable to the next person (or the next session).
    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#common-pitfalls","level":2,"title":"Common Pitfalls","text":"

    Ignoring CONSTITUTION.md. The constitution exists for a reason. If a task conflicts with a constitution rule, the task is wrong. Raise it with the team instead of working around the constraint.

    Deleting tasks. Never delete a task from TASKS.md. Mark it [x] (done) or [-] (skipped with a reason). The history matters for session replay and audit.

    Bypassing hooks. If the project uses ctx hooks (pre-commit nudges, context autoloading), don't disable them. They exist to keep context fresh. If a hook is noisy or broken, fix it or file a task.

    Over-contributing on day one. Read first, then contribute. Adding a dozen learnings before you understand the project's norms creates noise, not signal.

    Related:

    • Getting Started: installation and setup from scratch
    • Context Files: detailed file reference
    • Knowledge Capture: recording decisions, learnings, and conventions
    • Session Lifecycle: how a typical AI session flows with ctx
    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/keeping-ai-honest/","level":1,"title":"Keeping AI Honest","text":"","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-problem","level":2,"title":"The Problem","text":"

    AI agents confabulate. They invent history that never happened, claim familiarity with decisions that were never made, and sometimes declare a task complete when it is not. This is not malice - it is the default behavior of a system optimizing for plausible-sounding responses.

    When your AI says \"we decided to use Redis for caching last week,\" can you verify that? When it says \"the auth module is complete,\" can you confirm it? Without grounded, persistent context, the answer is no. You are trusting vibes.

    ctx replaces vibes with verifiable artifacts.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#grounded-memory","level":2,"title":"Grounded Memory","text":"

    Every entry in ctx context files has a timestamp and structured fields. When the AI cites a decision, you can check it.

    ## [2026-01-28-143022] Use Event Sourcing for Audit Trail\n\n**Status**: Accepted\n\n**Context**: Compliance requires full mutation history.\n\n**Decision**: Event sourcing for the audit subsystem only.\n\n**Rationale**: Append-only log meets compliance requirements\nwithout imposing event sourcing on the entire domain model.\n

    The timestamp 2026-01-28-143022 is not decoration. It is a verifiable anchor. If the AI references this decision, you can open DECISIONS.md, find the entry, and confirm it says what the AI claims. If the entry does not exist, the AI is hallucinating - and you know immediately.

    This is grounded memory: claims that trace back to artifacts you control and can audit.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#constitutionmd-hard-guardrails","level":2,"title":"CONSTITUTION.md: Hard Guardrails","text":"

    CONSTITUTION.md defines rules the AI must treat as inviolable. These are not suggestions or best practices - they are constraints that override task requirements.

    # Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these,\nthe task is wrong.\n\n* [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] All public API changes require a decision record\n* [ ] Never delete context files without explicit user approval\n

    The AI reads these at session start, before anything else. A well- integrated agent will refuse a task that conflicts with a constitutional rule, citing the specific rule it would violate.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-agent-playbooks-anti-hallucination-rules","level":2,"title":"The Agent Playbook's Anti-Hallucination Rules","text":"

    The AGENT_PLAYBOOK.md file includes a section called \"How to Avoid Hallucinating Memory\" with five explicit rules:

    1. Never assume. If it is not in the context files, you do not know it.
    2. Never invent history. Do not claim \"we discussed\" something without a file reference.
    3. Verify before referencing. Search files before citing them.
    4. When uncertain, say so. \"I don't see a decision on this\" is always better than a fabricated one.
    5. Trust files over intuition. If the files say PostgreSQL but your training data suggests MySQL, the files win.

    These rules create a behavioral contract. The AI is not left to guess how confident it should be - it has explicit instructions to ground every claim in the context directory.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#drift-detection","level":2,"title":"Drift Detection","text":"

    Context files can go stale. You rename a package, delete a module, or finish a sprint, and suddenly ARCHITECTURE.md references paths that no longer exist. Stale context is almost as dangerous as no context: the AI treats outdated information as current truth.

    ctx drift detects this divergence:

    ctx drift\n

    It scans context files for references to files, paths, and symbols that no longer exist in the codebase. Stale references get flagged so you can update or remove them before they mislead the next session.

    Regular drift checks - weekly, or after major refactors - keep your context files honest the same way tests keep your code honest.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-verification-loop","level":2,"title":"The Verification Loop","text":"

    The /ctx-verify skill provides an end-to-end check: it reads all context files, cross-references them with the current codebase, and reports inconsistencies. Think of it as a health check for your project's memory.

    This closes the loop. You write context. The AI reads context. The verification step confirms that context still matches reality. When it does not, you fix it - and the next session starts from truth, not from drift.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#trust-through-structure","level":2,"title":"Trust Through Structure","text":"

    The common thread across all of these mechanisms is structure over prose. Timestamps make claims verifiable. Constitutional rules make boundaries explicit. Drift detection makes staleness visible. The playbook makes behavioral expectations concrete.

    You do not need to trust the AI. You need to trust the system -- and verify when it matters.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#further-reading","level":2,"title":"Further Reading","text":"
    • Detecting and Fixing Drift: the full workflow for keeping context files accurate
    • Invariants: the properties that must hold for any valid ctx implementation
    • Agent Security: threat model and mitigations for AI agents operating with persistent context
    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/prompting-guide/","level":1,"title":"Prompting Guide","text":"

    New to ctx?

    This guide references context files like TASKS.md, DECISIONS.md, and LEARNINGS.md:

    These are plain Markdown files that ctx maintains in your project's .context/ directory.

    If terms like \"context packet\" or \"session ceremony\" are unfamiliar,

    • start with the ctx Manifesto for the why,
    • About for the big picture,
    • then Getting Started to set up your first project.
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#literature-matters","level":2,"title":"Literature Matters","text":"

    This guide is about crafting effective prompts for working with AI assistants in ctx-enabled projects, but the guidelines given here apply to other AI systems, too.

    The right prompt triggers the right behavior.

    This guide documents prompts that reliably produce good results.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#tldr","level":2,"title":"TL;DR","text":"Goal Prompt Load context \"Do you remember?\" Resume work \"What's the current state?\" What's next /ctx-next Debug \"Why doesn't X work?\" Validate \"Is this consistent with our decisions?\" Impact analysis \"What would break if we...\" Reflect /ctx-reflect Wrap up /ctx-wrap-up Persist \"Add this as a learning\" Explore \"How does X work in this codebase?\" Sanity check \"Is this the right approach?\" Completeness \"What am I missing?\" One more thing \"What's the single smartest addition?\" Set tone \"Push back if my assumptions are wrong.\" Constrain scope \"Only change files in X. Nothing else.\" Course correct \"Stop. That's not what I meant.\" Check health \"Run ctx drift\" Commit /ctx-commit","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#session-start","level":2,"title":"Session Start","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#do-you-remember","level":3,"title":"\"Do you remember?\"","text":"

    Triggers the AI to silently read TASKS.md, DECISIONS.md, LEARNINGS.md, and check recent history via ctx recall before responding with a structured readback:

    1. Last session: most recent session topic and date
    2. Active work: pending or in-progress tasks
    3. Recent context: 1-2 recent decisions or learnings
    4. Next step: offer to continue or ask what to focus on

    Use this at the start of every important session.

    Do you remember what we were working on?\n

    This question implies prior context exists. The AI checks files rather than admitting ignorance. The expected response cites specific context (session names, task counts, decisions), not vague summaries.

    If the AI instead narrates its discovery process (\"Let me check if there are files...\"), it has not loaded CLAUDE.md or AGENT_PLAYBOOK.md properly.

    For a detailed case study on making agents actually follow this protocol (including the failure modes, the timing problem, and the hook design that solved it) see The Dog Ate My Homework.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#whats-the-current-state","level":3,"title":"\"What's the current state?\"","text":"

    Prompts reading of TASKS.md, recent sessions, and status overview.

    Use this when resuming work after a break.

    Variants:

    • \"Where did we leave off?\"
    • \"What's in progress?\"
    • \"Show me the open tasks.\"
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#during-work","level":2,"title":"During Work","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#why-doesnt-x-work","level":3,"title":"\"Why doesn't X work?\"","text":"

    This triggers root cause analysis rather than surface-level fixes.

    Use this when something fails unexpectedly.

    Framing as \"why\" encourages investigation before action. The AI will trace through code, check configurations, and identify the actual cause.

    Real Example

    \"Why can't I run /ctx-reflect?\" led to discovering missing permissions in settings.local.json bootstrapping.

    This was a fix that benefited all users of ctx.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#is-this-consistent-with-our-decisions","level":3,"title":"\"Is this consistent with our decisions?\"","text":"

    This prompts checking DECISIONS.md before implementing.

    Use this before making architectural choices.

    Variants:

    • \"Check if we've decided on this before\"
    • \"Does this align with our conventions?\"
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-would-break-if-we","level":3,"title":"\"What would break if we...\"","text":"

    This triggers defensive thinking and impact analysis.

    Use this before making significant changes.

    What would break if we change the Settings struct?\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#before-you-start-read-x","level":3,"title":"\"Before you start, read X\"","text":"

    This ensures specific context is loaded before work begins.

    Use this when you know the relevant context exists in a specific file.

    Before you start, check ctx recall for the auth discussion session\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#scope-control","level":3,"title":"Scope Control","text":"

    Constrain the AI to prevent sprawl. These are some of the most useful prompts in day-to-day work.

    Only change files in internal/cli/add/. Nothing else.\n
    No new files. Modify the existing implementation.\n
    Keep the public API unchanged. Internal refactor only.\n

    Use these when the AI tends to \"helpfully\" modify adjacent code, add documentation you didn't ask for, or create new abstractions.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#course-correction","level":3,"title":"Course Correction","text":"

    Steer the AI when it goes off-track: Don't wait for it to finish a wrong approach.

    Stop! That's not what I meant. Let me clarify.\n
    Let's step back. Explain what you're about to do before changing anything.\n
    Undo that last change and try a different approach.\n

    These work because they interrupt momentum.

    Without explicit course correction, the AI tends to commit harder to a wrong path rather than reconsidering.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#failure-modes","level":3,"title":"Failure Modes","text":"

    When the AI misbehaves, match the symptom to the recovery prompt:

    Symptom Recovery prompt Hand-waves (\"should work now\") \"Show evidence: file/line refs, command output, or test name.\" Creates unnecessary files \"No new files. Modify the existing implementation.\" Expands scope unprompted \"Stop after the smallest working change. Ask before expanding scope.\" Narrates instead of acting \"Skip the explanation. Make the change and show the diff.\" Repeats a failed approach \"That didn't work last time. Try a different approach.\" Claims completion without proof \"Run the test. Show me the output.\"

    These are recovery handles, not rules to paste into CLAUDE.md.

    Use them in the moment when you see the behavior.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#reflection-and-persistence","level":2,"title":"Reflection and Persistence","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-did-we-learn","level":3,"title":"\"What did we learn?\"","text":"

    This prompts reflection on the session and often triggers adding learnings to LEARNINGS.md.

    Use this after completing a task or debugging session.

    This is an explicit reflection prompt. The AI will summarize insights and often offer to persist them.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#add-this-as-a-learningdecision","level":3,"title":"\"Add this as a learning/decision\"","text":"

    This is an explicit persistence request.

    Use this when you have discovered something worth remembering.

    Add this as a learning: \"JSON marshal escapes angle brackets by default\"\n\n# or simply.\nAdd this as a learning.\n# and let the AI autonomously infer and summarize.\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#save-context-before-we-end","level":3,"title":"\"Save context before we end\"","text":"

    This triggers context persistence before the session closes.

    Use it at the end of the session or before switching topics.

    Variants:

    • \"Let's persist what we did\"
    • \"Update the context files\"
    • /ctx-wrap-up:the recommended end-of-session ceremony (see Session Ceremonies)
    • /ctx-reflect: mid-session reflection checkpoint
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#exploration-and-research","level":2,"title":"Exploration and Research","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#explore-the-codebase-for-x","level":3,"title":"\"Explore the codebase for X\"","text":"

    This triggers thorough codebase search rather than guessing.

    Use this when you need to understand how something works.

    This works because \"Explore\" signals that investigation is needed, not immediate action.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#how-does-x-work-in-this-codebase","level":3,"title":"\"How does X work in this codebase?\"","text":"

    This prompts reading actual code rather than explaining general concepts.

    Use this to understand the existing implementation.

    How does session saving work in this codebase?\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#find-all-places-where-x","level":3,"title":"\"Find all places where X\"","text":"

    This triggers a comprehensive search across the codebase.

    Use this before refactoring or understanding the impact.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#meta-and-process","level":2,"title":"Meta and Process","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-should-we-document-from-this","level":3,"title":"\"What should we document from this?\"","text":"

    This prompts identifying learnings, decisions, and conventions worth persisting.

    Use this after complex discussions or implementations.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#is-this-the-right-approach","level":3,"title":"\"Is this the right approach?\"","text":"

    This invites the AI to challenge the current direction.

    Use this when you want a sanity check.

    This works because it allows AI to disagree.

    AIs often default to agreeing; this prompt signals you want an honest assessment.

    Stronger variant: \"Push back if my assumptions are wrong.\" This sets the tone for the entire session: The AI will flag questionable choices proactively instead of waiting to be asked.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-am-i-missing","level":3,"title":"\"What am I missing?\"","text":"

    This prompts thinking about edge cases, overlooked requirements, or unconsidered approaches.

    Use this before finalizing a design or implementation.

    Forward-looking variant: \"What's the single smartest addition you could make to this at this point?\" Use this after you think you're done: It surfaces improvements you wouldn't have thought to ask for. The constraint to one thing prevents feature sprawl.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#cli-commands-as-prompts","level":2,"title":"CLI Commands as Prompts","text":"

    Asking the AI to run ctx commands is itself a prompt. These load context or trigger specific behaviors:

    Command What it does \"Run ctx status\" Shows context summary, file presence, staleness \"Run ctx agent\" Loads token-budgeted context packet \"Run ctx drift\" Detects dead paths, stale files, missing context","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#ctx-skills","level":3,"title":"ctx Skills","text":"

    The SKILS.md Standard

    Skills are formalized prompts stored as SKILL.md files.

    The /slash-command syntax below is Claude Code specific.

    Other agents can use the same skill files, but invocation may differ.

    Use ctx skills by name:

    Skill When to use /ctx-status Quick context summary /ctx-agent Load full context packet /ctx-remember Recall project context and structured readback /ctx-wrap-up End-of-session context persistence /ctx-recall Browse session history for past discussions /ctx-reflect Structured reflection checkpoint /ctx-next Suggest what to work on next /ctx-commit Commit with context persistence /ctx-drift Detect and fix context drift /ctx-implement Execute a plan step-by-step with verification /ctx-loop Generate autonomous loop script /ctx-pad Manage encrypted scratchpad /ctx-archive Archive completed tasks /check-links Audit docs for dead links

    Ceremony vs. Workflow Skills

    Most skills work conversationally: \"what should we work on?\" triggers /ctx-next, \"save that as a learning\" triggers /ctx-add-learning. Natural language is the recommended approach.

    Two skills are the exception: /ctx-remember and /ctx-wrap-up are ceremony skills for session boundaries: Invoke them as explicit slash commands: conversational triggers risk partial execution. See Session Ceremonies.

    Skills combine a prompt, tool permissions, and domain knowledge into a single invocation.

    Skills Beyond Claude Code

    The /slash-command syntax above is Claude Code native, but the underlying SKILL.md files are a standard markdown format that any agent can consume. If you use a different coding agent, consult its documentation for how to load skill files as prompt templates.

    See Integrations for setup details.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#anti-patterns","level":2,"title":"Anti-Patterns","text":"

    Based on our ctx development experience (i.e., \"sipping our own champagne\") so far, here are some prompts that tend to produce poor results:

    Prompt Problem Better Alternative \"Fix this\" Too vague, may patch symptoms \"Why is this failing?\" \"Make it work\" Encourages quick hacks \"What's the right way to solve this?\" \"Just do it\" Skips planning \"Plan this, then implement\" \"You should remember\" Confrontational \"Do you remember?\" \"Obviously...\" Discourages questions State the requirement directly \"Idiomatic X\" Triggers language priors \"Follow project conventions\" \"Implement everything\" No phasing, sprawl risk Break into tasks, implement one at a time \"You should know this\" Assumes context is loaded \"Before you start, read X\"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#reliability-checklist","level":2,"title":"Reliability Checklist","text":"

    Before sending a non-trivial prompt, check these four elements. This is the guide's DNA in one screenful.

    1. Goal in one sentence: What does \"done\" look like?
    2. Files to read: What existing code or context should the AI review before acting?
    3. Verification command: How will you prove it worked? (test name, CLI command, expected output)
    4. Scope boundary: What should the AI not touch?

    A prompt that covers all four is almost always good enough.

    A prompt missing #3 is how you get \"should work now\" without evidence.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#safety-invariants","level":2,"title":"Safety Invariants","text":"

    These are Invariants: Not Suggestions

    A prompting guide earns its trust by being honest about risk.

    These four rules mentioned below don't change with model versions, agent frameworks, or project size.

    Build them into your workflow once and stop thinking about them.

    Tool-using agents can read files, run commands, and modify your codebase. That power makes them useful. It also creates a trust boundary you should be aware of.

    These invariants apply regardless of which agent or model you use.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#treat-the-repository-text-as-untrusted-input","level":3,"title":"Treat the Repository Text as \"Untrusted Input\"","text":"

    Issue descriptions, PR comments, commit messages, documentation, and even code comments can contain text that looks like instructions. An agent that reads a GitHub issue and then runs a command found inside it is executing untrusted input.

    The rule: Before running any command the agent found in repo text (issues, docs, comments), restate the command explicitly and confirm it does what you expect. Don't let the agent copy-paste from untrusted sources into a shell.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#ask-before-destructive-operations","level":3,"title":"Ask Before Destructive Operations","text":"

    git push --force, rm -rf, DROP TABLE, docker system prune: these are irreversible or hard to reverse. A good agent should pause before running them, but don't rely on that.

    The rule: For any operation that deletes data, overwrites history, or affects shared infrastructure, require explicit confirmation. If the agent runs something destructive without asking, that's a course-correction moment: \"Stop. Never run destructive commands without asking first.\"

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#scope-the-blast-radius","level":3,"title":"Scope the Blast Radius","text":"

    An agent told to \"fix the tests\" might modify test fixtures, change assertions, or delete tests that inconveniently fail. An agent told to \"deploy\" might push to production. Broad mandates create broad risk.

    The rule: Constrain scope before starting work. The Reliability Checklist's scope boundary (#4) is your primary safety lever. When in doubt, err on the side of a tighter boundary.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#secrets-never-belong-in-context","level":3,"title":"Secrets Never Belong in Context","text":"

    LEARNINGS.md, DECISIONS.md, and session transcripts are plain-text files that may be committed to version control.

    Don't persist API keys, passwords, tokens, or credentials in context files.

    The rule: If the agent encounters a secret during work, it should use it transiently (environment variable, an alias to the secret instead of the actual secret, etc.) and never write it to a context file.

    Any Secret Seen IS Exposed

    If you see a secret in a context file, remove it immediately and rotate the credential.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#explore-plan-implement","level":2,"title":"Explore → Plan → Implement","text":"

    For non-trivial work, name the phase you want:

    Explore src/auth and summarize the current flow.\nThen propose a plan. After I approve, implement with tests.\n

    This prevents the AI from jumping straight to code.

    The three phases map to different modes of thinking:

    • Explore: read, search, understand: no changes
    • Plan: propose approach, trade-offs, scope: no changes
    • Implement: write code, run tests, verify: changes

    Small fixes skip straight to implement. Complex or uncertain work benefits from all three.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#prompts-by-task-type","level":2,"title":"Prompts by Task Type","text":"

    Different tasks need different prompt structures. The pattern: symptom + location + verification.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#bugfix","level":3,"title":"Bugfix","text":"
    Users report search returns empty results for queries with hyphens.\nReproduce in src/search/. Write a failing test for \"foo-bar\",\nfix the root cause, run: go test ./internal/search/...\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#refactor","level":3,"title":"Refactor","text":"
    Inspect src/auth/ and list duplication hotspots.\nPropose a refactor plan scoped to one module.\nAfter approval, remove duplication without changing behavior.\nAdd a test if coverage is missing. Run: make audit\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#research","level":3,"title":"Research","text":"
    Explore the request flow around src/api/.\nSummarize likely bottlenecks with evidence.\nPropose 2-3 hypotheses. Do not implement yet.\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#docs","level":3,"title":"Docs","text":"
    Update docs/cli-reference.md to reflect the new --format flag.\nConfirm the flag exists in the code and the example works.\n

    Notice each prompt includes what to verify and how. Without that, you get a \"should work now\" instead of evidence.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#writing-tasks-as-prompts","level":2,"title":"Writing Tasks as Prompts","text":"

    Tasks in TASKS.md are indirect prompts to the AI. How you write them shapes how the AI approaches the work.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#state-the-motivation-not-just-the-goal","level":3,"title":"State the Motivation, Not Just the Goal","text":"

    Tell the AI why you are building something, not just what.

    Bad: \"Build a calendar view.\"

    Good: \"Build a calendar view. The motivation is that all notes and tasks we build later should be viewable here.\"

    The second version lets the AI anticipate downstream requirements:

    It will design the calendar's data model to be compatible with future features: Without you having to spell out every integration point. Motivation turns a one-off task into a directional task.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#state-the-deliverable-not-just-steps","level":3,"title":"State the Deliverable, Not Just Steps","text":"

    Bad task (implementation-focused): 

    - [ ] T1.1.0: Parser system\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n

    The AI may complete all subtasks but miss the actual goal. What does \"Parser system\" deliver to the user?

    Good task (deliverable-focused): 

    - [ ] T1.1.0: Parser CLI command\n  **Deliverable**: `ctx recall list` command that shows parsed sessions\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n

    Now the AI knows the subtasks serve a specific user-facing deliverable.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#use-acceptance-criteria","level":3,"title":"Use Acceptance Criteria","text":"

    For complex tasks, add explicit \"done when\" criteria:

    - [ ] T2.0: Authentication system\n  **Done when**:\n  - [ ] User can register with email\n  - [ ] User can log in and get a token\n  - [ ] Protected routes reject unauthenticated requests\n

    This prevents premature \"task complete\" when only the implementation details are done, but the feature doesn't actually work.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#subtasks-parent-task","level":3,"title":"Subtasks ≠ Parent Task","text":"

    Completing all subtasks does not mean the parent task is complete.

    The parent task describes what the user gets.

    Subtasks describe how to build it.

    Always re-read the parent task description before marking it complete. Verify the stated deliverable exists and works.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#why-do-these-approaches-work","level":2,"title":"Why Do These Approaches Work?","text":"

    The patterns in this guide aren't invented here: They are practitioner translations of well-established, peer-reviewed research, most of which predate the current AI (hype) wave.

    The underlying ideas come from decades of work in machine learning, cognitive science, and numerical optimization. For a concrete case study showing how these principles play out when an agent decides whether to follow instructions (attention competition, optimization toward least-resistance paths, and observable compliance as a design goal) see The Dog Ate My Homework.

    Phased work (\"Explore → Plan → Implement\") applies chain-of-thought reasoning: Decomposing a problem into sequential steps before acting. Forcing intermediate reasoning steps measurably improves output quality in language models, just as it does in human problem-solving. Wei et al., Chain-of-Thought Prompting Elicits Reasoning in Large Language Models (2022).

    Root-cause prompts (\"Why doesn't X work?\") use step-back abstraction: Retreating to a higher-level question before diving into specifics. This mirrors how experienced engineers debug: they ask \"what should happen?\" before asking \"what went wrong?\" Zheng et al., Take a Step Back: Evoking Reasoning via Abstraction in Large Language Models (2023).

    Exploring alternatives (\"Propose 2-3 approaches\") leverages self-consistency: Generating multiple independent reasoning paths and selecting the most coherent result. The idea traces back to ensemble methods in ML: A committee of diverse solutions outperforms any single one. Wang et al., Self-Consistency Improves Chain of Thought Reasoning in Language Models (2022).

    Impact analysis (\"What would break if we...\") is a form of tree-structured exploration: Branching into multiple consequence paths before committing. This is the same principle behind game-tree search (minimax, MCTS) that has powered decision-making systems since the 1950s. Yao et al., Tree of Thoughts: Deliberate Problem Solving with Large Language Models (2023).

    Motivation prompting (\"Build X because Y\") works through goal conditioning: Providing the objective function alongside the task. In optimization terms, you are giving the gradient direction, not just the loss. The model can make locally coherent decisions that serve the global objective because it knows what \"better\" means.

    Scope constraints (\"Only change files in X\") apply constrained optimization: Bounding the search space to prevent divergence. This is the same principle behind regularization in ML: Without boundaries, powerful optimizers find solutions that technically satisfy the objective but are practically useless.

    CLI commands as prompts (\"Run ctx status\") interleave reasoning with acting: The model thinks, acts on external tools, observes results, then thinks again. Grounding reasoning in real tool output reduces hallucination because the model can't ignore evidence it just retrieved. Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models (2022).

    Task decomposition (\"Prompts by Task Type\") applies least-to-most prompting: Breaking a complex problem into subproblems and solving them sequentially, each building on the last. This is the research version of \"plan, then implement one slice.\" Zhou et al., Least-to-Most Prompting Enables Complex Reasoning in Large Language Models (2022).

    Explicit planning (\"Explore → Plan → Implement\") is directly supported by plan-and-solve prompting, which addresses missing-step failures in zero-shot reasoning by extracting a plan before executing. The phased structure prevents the model from jumping to code before understanding the problem. Wang et al., Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models (2023).

    Session reflection (\"What did we learn?\", /ctx-reflect) is a form of verbal reinforcement learning: Improving future performance by persisting linguistic feedback as memory rather than updating weights. This is exactly what LEARNINGS.md and DECISIONS.md provide: a durable feedback signal across sessions. Shinn et al., Reflexion: Language Agents with Verbal Reinforcement Learning (2023).

    These aren't prompting \"hacks\" that you will find in the \"1000 AI Prompts for the Curious\" listicles: They are applications of foundational principles:

    • Decomposition,
    • Abstraction,
    • Ensemble Reasoning,
    • Search,
    • and Constrained Optimization.

    They work because language models are, at their core, optimization systems navigating probabilistic landscapes.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#further-reading","level":2,"title":"Further Reading","text":"
    • The Attention Budget: Why your AI forgets what you just told it, and how token budgets shape context strategy
    • The Dog Ate My Homework: A case study in making agents follow instructions: attention timing, delegation decay, and observable compliance as a design goal
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#contributing","level":2,"title":"Contributing","text":"

    Found a prompt that works well? Open an issue or PR with:

    1. The prompt text;
    2. What behavior it triggers;
    3. When to use it;
    4. Why it works (optional but helpful).

    Dive Deeper:

    • Recipes: targeted how-to guides for specific tasks
    • CLI Reference: all commands and flags
    • Integrations: setup for Claude Code, Cursor, Aider
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/repeated-mistakes/","level":1,"title":"My AI Keeps Making the Same Mistakes","text":"","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#the-problem","level":2,"title":"The Problem","text":"

    You found a bug last Tuesday. You debugged it, understood the root cause, and moved on. Today, a new session hits the exact same bug. The AI rediscovers it from scratch, burning twenty minutes on something you already solved.

    Worse: you spent an hour last week evaluating two database migration strategies, picked one, documented why in a comment somewhere, and now the AI is cheerfully suggesting the approach you rejected. Again.

    This is not a model problem. It is a memory problem. Without persistent context, every session starts with amnesia.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#how-ctx-stops-the-loop","level":2,"title":"How ctx Stops the Loop","text":"

    ctx gives your AI three files that directly prevent repeated mistakes, each targeting a different failure mode.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#decisionsmd-stop-relitigating-settled-choices","level":3,"title":"DECISIONS.md: Stop Relitigating Settled Choices","text":"

    When you make an architectural decision, record it with rationale and rejected alternatives. The AI reads this at session start and treats it as settled.

    ## [2026-02-12] Use JWT for Authentication\n\n**Status**: Accepted\n\n**Context**: Need stateless auth for the API layer.\n\n**Decision**: JWT with short-lived access tokens and refresh rotation.\n\n**Rationale**: Stateless, scales horizontally, team has prior experience.\n\n**Alternatives Considered**:\n- Session-based auth: Rejected. Requires sticky sessions or shared store.\n- API keys only: Rejected. No user identity, no expiry rotation.\n

    Next session, when the AI considers auth, it reads this entry and builds on the decision instead of re-debating it. If someone asks \"why not sessions?\", the rationale is already there.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#learningsmd-capture-gotchas-once","level":3,"title":"LEARNINGS.md: Capture Gotchas Once","text":"

    Learnings are the bugs, quirks, and non-obvious behaviors that cost you time the first time around. Write them down so they cost you zero time the second time.

    ## Build\n\n### CGO Required for SQLite on Alpine\n\n**Discovered**: 2026-01-20\n\n**Context**: Docker build failed silently with \"no such table\" at runtime.\n\n**Lesson**: The go-sqlite3 driver requires CGO_ENABLED=1 and gcc\ninstalled in the build stage. Alpine needs apk add build-base.\n\n**Application**: Always use the golang:alpine image with build-base\nfor SQLite builds. Never set CGO_ENABLED=0.\n

    Without this entry, the next session that touches the Dockerfile will hit the same wall. With it, the AI knows before it starts.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#constitutionmd-draw-hard-lines","level":3,"title":"CONSTITUTION.md: Draw Hard Lines","text":"

    Some mistakes are not about forgetting - they are about boundaries the AI should never cross. CONSTITUTION.md sets inviolable rules.

    * [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] Never disable security linters without a documented exception\n* [ ] All database migrations must be reversible\n

    The AI reads these as absolute constraints. It does not weigh them against convenience. It refuses tasks that would violate them.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#the-accumulation-effect","level":2,"title":"The Accumulation Effect","text":"

    Each of these files grows over time. Session one captures two decisions. Session five adds a tricky learning about timezone handling. Session twelve records a convention about error message formatting.

    By session twenty, your AI has a knowledge base that no single person carries in their head. New team members - human or AI - inherit it instantly.

    The key insight: you are not just coding. You are building a knowledge layer that makes every future session faster.

    ctx files version with your code in git. They survive branch switches, team changes, and model upgrades. The context outlives any single session.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#getting-started","level":2,"title":"Getting Started","text":"

    Capture your first decision or learning right now:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a relational database for the project\" \\\n  --rationale \"Team expertise, JSONB support, mature ecosystem\"\n\nctx add learning \"Vitest mock hoisting\" \\\n  --context \"Tests failing intermittently\" \\\n  --lesson \"vi.mock() must be at file top level\" \\\n  --application \"Use vi.doMock() for dynamic mocks\"\n
    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#further-reading","level":2,"title":"Further Reading","text":"
    • Knowledge Capture: the full workflow for persisting decisions, learnings, and conventions
    • Context Files Reference: structure and format for every file in .context/
    • About ctx: the bigger picture - why persistent context changes how you work with AI
    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"operations/","level":1,"title":"Operations","text":"

    Guides for installing, upgrading, integrating, and running ctx.

    ","path":["Operations"],"tags":[]},{"location":"operations/#integration","level":3,"title":"Integration","text":"

    Adopt ctx in an existing project: initialize context files, migrate from other tools, and onboard team members.

    ","path":["Operations"],"tags":[]},{"location":"operations/#upgrade","level":3,"title":"Upgrade","text":"

    Upgrade between versions with step-by-step migration notes and breaking-change guidance.

    ","path":["Operations"],"tags":[]},{"location":"operations/#ai-tools","level":3,"title":"AI Tools","text":"

    Configure ctx with Claude Code, Cursor, Aider, Copilot, Windsurf, and other AI coding tools.

    ","path":["Operations"],"tags":[]},{"location":"operations/#autonomous-loops","level":3,"title":"Autonomous Loops","text":"

    Run an unattended AI agent that works through tasks overnight, with ctx providing persistent memory between iterations.

    ","path":["Operations"],"tags":[]},{"location":"operations/autonomous-loop/","level":1,"title":"Autonomous Loops","text":"","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#autonomous-ai-development","level":2,"title":"Autonomous AI Development","text":"

    Iterate until done.

    An autonomous loop is an iterative AI development workflow where an agent works on tasks until completion, without constant human intervention.

    ctx provides the memory that makes this possible:

    • ctx provides the memory: persistent context that survives across iterations
    • The loop provides the automation: continuous execution until done

    Together, they enable fully autonomous AI development where the agent remembers everything across iterations.

    Origin

    This pattern is inspired by Geoffrey Huntley's Ralph Wiggum technique.

    We use generic terminology here so the concepts remain clear regardless of trends.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#how-it-works","level":2,"title":"How It Works","text":"
    graph TD\n    A[Start Loop] --> B[Load PROMPT.md]\n    B --> C[AI reads .context/]\n    C --> D[AI picks task from TASKS.md]\n    D --> E[AI completes task]\n    E --> F[AI updates context files]\n    F --> G[AI commits changes]\n    G --> H{Check signals}\n    H -->|SYSTEM_CONVERGED| I[Done - all tasks complete]\n    H -->|SYSTEM_BLOCKED| J[Done - needs human input]\n    H -->|Continue| B
    1. Loop reads PROMPT.md and invokes AI
    2. AI loads context from .context/
    3. AI picks one task and completes it
    4. AI updates context files (mark task done, add learnings)
    5. AI commits changes
    6. Loop checks for completion signals
    7. Repeat until converged or blocked
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#quick-start-shell-while-loop-recommended","level":2,"title":"Quick Start: Shell While Loop (Recommended)","text":"

    The best way to run an autonomous loop is a plain shell script that invokes your AI tool in a fresh process on each iteration. This is \"pure ralph\":

    The only state that carries between iterations is what lives in .context/ and the git history. No context window bleed, no accumulated tokens, no hidden state.

    Create a loop.sh:

    #!/bin/bash\n# loop.sh: an autonomous iteration loop\n\nPROMPT_FILE=\"${1:-PROMPT.md}\"\nMAX_ITERATIONS=\"${2:-10}\"\nOUTPUT_FILE=\"/tmp/loop_output.txt\"\n\nfor i in $(seq 1 $MAX_ITERATIONS); do\n  echo \"=== Iteration $i ===\"\n\n  # Invoke AI with prompt\n  cat \"$PROMPT_FILE\" | claude --print > \"$OUTPUT_FILE\" 2>&1\n\n  # Display output\n  cat \"$OUTPUT_FILE\"\n\n  # Check for completion signals\n  if grep -q \"SYSTEM_CONVERGED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop complete: All tasks done\"\n    break\n  fi\n\n  if grep -q \"SYSTEM_BLOCKED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop blocked: Needs human input\"\n    break\n  fi\n\n  sleep 2\ndone\n

    Make it executable and run:

    chmod +x loop.sh\n./loop.sh\n

    You can also generate this script with ctx loop (see CLI Reference).

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#why-do-we-use-a-shell-loop","level":3,"title":"Why Do We Use a Shell Loop?","text":"

    Each iteration starts a fresh AI process with zero context window history. The agent knows only what it reads from .context/ files: Exactly the information you chose to persist.

    This is the core loop principle: memory is explicit, not accidental.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#alternative-claude-codes-built-in-loop","level":2,"title":"Alternative: Claude Code's Built-in Loop","text":"

    Claude Code has built-in loop support:

    # Start autonomous loop\n/loop\n\n# Cancel running loop\n/cancel-loop\n

    This is convenient for quick iterations, but be aware of important caveats:

    This Loop Is not Pure

    Claude Code's /loop runs all iterations within the same session. This means:

    • State leaks between iterations: The context window accumulates output from every previous iteration. The agent \"remembers\" things it saw earlier (even if they were never persisted to .context/).
    • Token budget degrades: Each iteration adds to the context window, leaving less room for actual work in later iterations.
    • Not ergonomic for long runs: Users report that the built-in loop is less predictable for 10+ iteration runs compared to a shell loop.

    For short explorations (2-5 iterations) or interactive use, /loop works fine. For overnight unattended runs or anything where iteration independence matters, use the shell while loop instead.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#the-promptmd-file","level":2,"title":"The PROMPT.md File","text":"

    The prompt file instructs the AI on how to work autonomously. Here's a template:

    # Autonomous Development Prompt\n\nYou are working on this project autonomously. Follow these steps:\n\n## 1. Load Context\n\nRead these files in order:\n\n1. `.context/CONSTITUTION.md`: NEVER violate these rules\n2. `.context/TASKS.md`: Find work to do\n3. `.context/CONVENTIONS.md`: Follow these patterns\n4. `.context/DECISIONS.md`: Understand past choices\n\n## 2. Pick One Task\n\nFrom `.context/TASKS.md`, select ONE task that is:\n\n- Not blocked\n- Highest priority available\n- Within your capabilities\n\n## 3. Complete the Task\n\n- Write code following conventions\n- Run tests if applicable\n- Keep changes focused and minimal\n\n## 4. Update Context\n\nAfter completing work:\n\n- Mark task complete in `TASKS.md`\n- Add any learnings to `LEARNINGS.md`\n- Add any decisions to `DECISIONS.md`\n\n## 5. Commit Changes\n\nCreate a focused commit with clear message.\n\n## 6. Signal Status\n\nEnd your response with exactly ONE of:\n\n- `SYSTEM_CONVERGED`: All tasks in TASKS.md are complete\n- `SYSTEM_BLOCKED`: Cannot proceed, need human input (explain why)\n- (no signal): More work remains, continue to next iteration\n\n## Rules\n\n- ONE task per iteration\n- NEVER skip tests\n- NEVER violate CONSTITUTION.md\n- Commit after each task\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#completion-signals","level":2,"title":"Completion Signals","text":"

    The loop watches for these signals in AI output:

    Signal Meaning When to Use SYSTEM_CONVERGED All tasks complete No pending tasks in TASKS.md SYSTEM_BLOCKED Cannot proceed Needs clarification, access, or decision BOOTSTRAP_COMPLETE Initial setup done Project scaffolding finished","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#example-usage","level":3,"title":"Example Usage","text":"

    converged state

    I've completed all tasks in TASKS.md:\n- [x] Set up project structure\n- [x] Implement core API\n- [x] Add authentication\n- [x] Write tests\n\nNo pending tasks remain.\n\nSYSTEM_CONVERGED\n

    blocked state

    I cannot proceed with the \"Deploy to production\" task because:\n- Missing AWS credentials\n- Need confirmation on region selection\n\nPlease provide credentials and confirm deployment region.\n\nSYSTEM_BLOCKED\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#why-ctx-and-loops-work-well-together","level":2,"title":"Why ctx and Loops Work Well Together","text":"Without ctx With ctx Each iteration starts fresh Each iteration has full history Decisions get re-made Decisions persist in DECISIONS.md Learnings are lost Learnings accumulate in LEARNINGS.md Tasks can be forgotten Tasks tracked in TASKS.md","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#automatic-context-updates","level":3,"title":"Automatic Context Updates","text":"

    During the loop, the AI should update context files:

    Mark task complete: 

    ctx task complete \"implement user auth\"\n

    Or emit an update command (parsed by ctx watch): 

    <context-update type=\"complete\">user auth</context-update>\n

    Add learning: 

    ctx add learning \"Rate limiting requires Redis connection\"\n

    Or via update command: 

    <context-update type=\"learning\"\n  context=\"Implementing rate limiter\"\n  lesson=\"Rate limiting requires Redis connection\"\n  application=\"Ensure Redis is provisioned before enabling rate limits\"\n>Rate Limiting Redis Dependency</context-update>\n

    Record decision: 

    ctx add decision \"Use JWT tokens for API authentication\"\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#advanced-watch-mode","level":2,"title":"Advanced: Watch Mode","text":"

    Run ctx watch alongside the loop to automatically process context updates:

    # Terminal 1: Run the loop\n./loop.sh 2>&1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log\n

    The watch command processes context updates from the loop output in real time.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#project-setup","level":2,"title":"Project Setup","text":"

    Initialize a project for autonomous loop operation:

    # Initialize with autonomous agent behavior\nctx init --ralph\n

    The --ralph flag creates a PROMPT.md where the agent:

    • Works autonomously without asking clarifying questions;
    • Follows one-task-per-iteration discipline;
    • Uses SYSTEM_CONVERGED / SYSTEM_BLOCKED signals;

    Without --ralph, the agent is encouraged to ask questions when requirements are unclear: Better for collaborative human-agent sessions.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#example-project-structure","level":2,"title":"Example Project Structure","text":"
    my-project/\n├── .context/\n│   ├── CONSTITUTION.md\n│   ├── TASKS.md          # Work items for the loop\n│   ├── DECISIONS.md\n│   ├── LEARNINGS.md\n│   ├── CONVENTIONS.md\n│   └── sessions/         # Loop iteration history\n├── PROMPT.md             # Instructions for the AI\n├── IMPLEMENTATION_PLAN.md # High-level project direction\n├── loop.sh               # Loop script (if not using Claude Code)\n└── src/                  # Your code\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#sample-tasksmd-for-autonomous-loops","level":3,"title":"Sample TASKS.md for Autonomous Loops","text":"
    # Tasks\n\n## Phase 1: Setup\n\n- [x] Initialize project structure\n- [x] Set up testing framework\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Polish\n\n- [ ] Add rate limiting `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n

    The loop will work through these systematically, marking each complete.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#troubleshooting","level":2,"title":"Troubleshooting","text":"","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#loop-runs-forever","level":3,"title":"Loop Runs Forever","text":"

    Cause: AI not emitting completion signals

    Fix: Ensure PROMPT.md explicitly instructs signaling: 

    End EVERY response with one of:\n- SYSTEM_CONVERGED (if all tasks done)\n- SYSTEM_BLOCKED (if stuck)\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#context-not-persisting","level":3,"title":"Context Not Persisting","text":"

    Cause: AI not updating context files

    Fix: Add explicit instructions to PROMPT.md: 

    After completing a task, you MUST:\n1. Run: ctx task complete \"<task>\"\n2. Add learnings: ctx add learning \"...\"\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#tasks-getting-repeated","level":3,"title":"Tasks Getting Repeated","text":"

    Cause: Task not marked complete before next iteration

    Fix: Ensure commit happens after context update:

    Order of operations:\n1. Complete coding work\n2. Update context files (*`ctx task complete`, `ctx add`*)\n3. Commit **ALL** changes including `.context/`\n4. Then signal status\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#ai-violating-constitution","level":3,"title":"AI Violating Constitution","text":"

    Cause: Constitution not read first

    Fix: Make constitution check explicit in PROMPT.md:

    BEFORE any work:\n1. Read .context/CONSTITUTION.md\n2. If task would violate ANY rule, emit SYSTEM_BLOCKED\n3. Explain which rule prevents the work\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#further-reading","level":2,"title":"Further Reading","text":"
    • Building ctx Using ctx: The dogfooding story: how autonomous loops built the tool that powers them
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#resources","level":2,"title":"Resources","text":"
    • Geoffrey Huntley's Ralph Wiggum Technique: The original inspiration
    • Context CLI: Command reference
    • Integrations: Tool-specific setup
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/integrations/","level":1,"title":"AI Tools","text":"","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#ai-tools","level":2,"title":"AI Tools","text":"

    Context works with any AI tool that can read files. This guide covers setup for popular AI coding assistants.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#claude-code-full-integration","level":2,"title":"Claude Code (Full Integration)","text":"

    Claude Code has the deepest integration via the ctx plugin.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup","level":3,"title":"Setup","text":"

    First, install ctx and initialize your project:

    ctx init\n

    Then, install the ctx plugin in Claude Code:

    # From the ctx repository\nclaude /plugin install ./internal/assets/claude\n\n# Or from the marketplace\nclaude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n

    Ensure the Plugin Is Enabled

    Installing a plugin registers it, but local installs may not auto-enable it globally. Verify ~/.claude/settings.json contains:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Without this, the plugin's hooks and skills won't appear in other projects. Running ctx init auto-enables the plugin; use --no-plugin-enable to skip this step.

    This gives you:

    Component Purpose .context/ All context files CLAUDE.md Bootstrap instructions Plugin hooks Lifecycle automation Plugin skills Agent Skills","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#how-it-works","level":3,"title":"How It Works","text":"
    graph TD\n    A[Session Start] --> B[Claude reads CLAUDE.md]\n    B --> C[PreToolUse hook runs]\n    C --> D[ctx agent loads context]\n    D --> E[Work happens]\n    E --> F[Session End]
    1. Session start: Claude reads CLAUDE.md, which tells it to check .context/
    2. First tool use: PreToolUse hook runs ctx agent and emits the context packet (subsequent invocations within the cooldown window are silent)
    3. Next session: Claude reads context files and continues with context
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#plugin-hooks","level":3,"title":"Plugin Hooks","text":"

    The ctx plugin provides lifecycle hooks implemented as Go subcommands (ctx system *):

    Hook Event Purpose ctx system context-load-gate PreToolUse (.*) Auto-inject context on first tool use ctx system block-non-path-ctx PreToolUse (Bash) Block ./ctx or go run: force $PATH install ctx system qa-reminder PreToolUse (Bash) Remind agent to lint/test before committing ctx system specs-nudge PreToolUse (EnterPlanMode) Nudge agent to use project specs when planning ctx system check-context-size UserPromptSubmit Nudge context assessment as sessions grow ctx system check-ceremonies UserPromptSubmit Nudge /ctx-remember and /ctx-wrap-up adoption ctx system check-persistence UserPromptSubmit Remind to persist learnings/decisions ctx system check-journal UserPromptSubmit Remind to export/enrich journal entries ctx system check-reminders UserPromptSubmit Relay pending reminders at session start ctx system check-version UserPromptSubmit Warn when binary/plugin versions diverge ctx system check-resources UserPromptSubmit Warn when memory/swap/disk/load hit DANGER level ctx system check-knowledge UserPromptSubmit Nudge when knowledge files grow large ctx system check-map-staleness UserPromptSubmit Nudge when ARCHITECTURE.md is stale ctx system heartbeat UserPromptSubmit Session-alive signal with prompt count metadata ctx system post-commit PostToolUse (Bash) Nudge context capture and QA after git commits

    A catch-all PreToolUse hook also runs ctx agent on every tool use (with cooldown) to autoload context.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#hook-configuration","level":3,"title":"Hook Configuration","text":"

    The plugin's hooks.json wires everything automatically: no manual configuration in settings.local.json needed:

    {\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system context-load-gate\" }\n        ]\n      },\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system block-non-path-ctx\" }\n        ]\n      },\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system qa-reminder\" }\n        ]\n      },\n      {\n        \"matcher\": \"EnterPlanMode\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system specs-nudge\" }\n        ]\n      },\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx agent --budget 4000 2>/dev/null || true\" }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system post-commit\" }\n        ]\n      }\n    ],\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system check-context-size\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-ceremonies\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-persistence\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-journal\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-reminders\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-version\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-resources\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-knowledge\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-map-staleness\" },\n          { \"type\": \"command\", \"command\": \"ctx system heartbeat\" }\n        ]\n      }\n    ]\n  }\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#customizing-token-budget-and-cooldown","level":3,"title":"Customizing Token Budget and Cooldown","text":"

    Edit the PreToolUse command to change the token budget or cooldown:

    \"command\": \"ctx agent --budget 8000 --session $PPID >/dev/null || true\"\n\"command\": \"ctx agent --budget 4000 --cooldown 5m --session $PPID >/dev/null || true\"\n

    The --session $PPID flag isolates the cooldown per session: $PPID resolves to the Claude Code process PID, so concurrent sessions don't interfere. The default cooldown is 10 minutes; use --cooldown 0 to disable it.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#verifying-setup","level":3,"title":"Verifying Setup","text":"
    1. Start a new Claude Code session;
    2. Ask: \"Do you remember?\"
    3. Claude should cite specific context:
      • Current tasks from .context/TASKS.md;
      • Recent decisions or learnings;
      • Recent session history from ctx recall.
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#local-plugin-development","level":3,"title":"Local Plugin Development","text":"

    When developing ctx locally (adding skills, hooks, or changing plugin behavior), Claude Code caches the plugin by version. You must bump the version in both files and update the marketplace for changes to take effect:

    1. Bump version in both:

    2. internal/assets/claude/.claude-plugin/plugin.json (plugin manifest), .claude-plugin/marketplace.json (marketplace listing*);

    3. Update the marketplace in Claude Code:

    4. Open the Plugins UI (/plugins or Esc menu),
    5. Go to Marketplaces tab,
    6. Select the activememory-ctx Marketplace,

    7. Choose Update marketplace;

    8. Start a new Claude Code session: skill changes aren't reflected in existing sessions.

    Both Version Files Must Match

    If you only bump plugin.json but not marketplace.json (or vice versa), Claude Code may not detect the update. Always bump both together.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#troubleshooting","level":3,"title":"Troubleshooting","text":"Issue Solution Context not loading Check ctx is in PATH: which ctx Hook errors Verify plugin is installed: claude /plugin list New skill not visible Bump version in both plugin.json files, update marketplace","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-load","level":3,"title":"Manual Context Load","text":"

    If hooks aren't working, manually load context:

    # Get context packet\nctx agent --budget 4000\n\n# Or paste into conversation\ncat .context/TASKS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#agent-skills","level":3,"title":"Agent Skills","text":"

    The ctx plugin ships Agent Skills following the agentskills.io specification.

    These are invoked in Claude Code with /skill-name.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-lifecycle-skills","level":4,"title":"Session Lifecycle Skills","text":"Skill Description /ctx-remember Recall project context at session start (ceremony) /ctx-wrap-up End-of-session context persistence (ceremony) /ctx-status Show context summary (tasks, decisions, learnings) /ctx-agent Get AI-optimized context packet /ctx-next Suggest 1-3 concrete next actions from context /ctx-commit Commit with integrated context capture /ctx-reflect Review session and suggest what to persist /ctx-remind Manage session-scoped reminders /ctx-pause Pause context hooks for this session /ctx-resume Resume context hooks after a pause","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#context-persistence-skills","level":4,"title":"Context Persistence Skills","text":"Skill Description /ctx-add-task Add a task to TASKS.md /ctx-add-learning Add a learning to LEARNINGS.md /ctx-add-decision Add a decision with context/rationale/consequence /ctx-add-convention Add a coding convention to CONVENTIONS.md /ctx-archive Archive completed tasks","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#scratchpad-skills","level":4,"title":"Scratchpad Skills","text":"Skill Description /ctx-pad Manage encrypted scratchpad entries","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-history-skills","level":4,"title":"Session History Skills","text":"Skill Description /ctx-recall Browse AI session history /ctx-journal-enrich Enrich a journal entry with frontmatter/tags /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich /ctx-journal-normalize Fix markdown rendering issues in journal","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#blogging-skills","level":4,"title":"Blogging Skills","text":"

    Blogging is a Better Way of Creating Release Notes

    The blogging workflow can also double as generating release notes:

    AI reads your git commit history and creates a \"narrative\", which is essentially what a release note is for.

    Skill Description /ctx-blog Generate blog post from recent activity /ctx-blog-changelog Generate blog post from commit range with theme","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#auditing-health-skills","level":4,"title":"Auditing & Health Skills","text":"Skill Description /ctx-doctor Troubleshoot ctx behavior with structural health checks /ctx-drift Detect and fix context drift (structural + semantic) /ctx-consolidate Merge redundant learnings or decisions into denser entries /ctx-alignment-audit Audit doc claims against playbook instructions /ctx-prompt-audit Analyze session logs for vague prompts /check-links Audit docs for dead internal and external links","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#planning-execution-skills","level":4,"title":"Planning & Execution Skills","text":"Skill Description /ctx-loop Generate a Ralph Loop iteration script /ctx-implement Execute a plan step-by-step with checks /ctx-import-plans Import Claude Code plan files into project specs /ctx-worktree Manage git worktrees for parallel agents /ctx-architecture Build and maintain architecture maps","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage-examples","level":4,"title":"Usage Examples","text":"
    /ctx-status\n/ctx-add-learning \"Token refresh requires explicit cache invalidation\"\n/ctx-journal-enrich twinkly-stirring-kettle\n

    Skills support partial matching where applicable (e.g., session slugs).

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#cursor-ide","level":2,"title":"Cursor IDE","text":"

    Cursor can use context files through its system prompt or by reading files directly.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_1","level":3,"title":"Setup","text":"
    # Generate Cursor configuration\nctx hook cursor\n\n# Initialize context\nctx init --minimal\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration","level":3,"title":"Configuration","text":"

    Add to Cursor settings (.cursor/settings.json):

    // split to multiple lines for readability\n{\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and \n  .context/CONVENTIONS.md before responding. \n  Follow rules in .context/CONSTITUTION.md.\",\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage","level":3,"title":"Usage","text":"
    1. Open your project in Cursor
    2. Context files are available in the file tree
    3. Reference them in prompts: \"Check .context/DECISIONS.md for our approach to...\"
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-injection","level":3,"title":"Manual Context Injection","text":"

    For more control, paste context directly:

    # Get AI-ready packet\nctx agent --budget 4000 | pbcopy  # macOS\nctx agent --budget 4000 | xclip  # Linux\n

    Paste into Cursor's chat.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#aider","level":2,"title":"Aider","text":"

    Aider works well with context files through its --read flag.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_2","level":3,"title":"Setup","text":"
    # Generate Aider configuration\nctx hook aider\n\n# Initialize context\nctx init\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_1","level":3,"title":"Configuration","text":"

    Create .aider.conf.yml:

    read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage_1","level":3,"title":"Usage","text":"
    # Start Aider (reads context files automatically)\naider\n\n# Or specify files explicitly\naider --read .context/TASKS.md --read .context/CONVENTIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#with-watch-mode","level":3,"title":"With Watch Mode","text":"

    Run ctx watch alongside Aider to capture context updates:

    # Terminal 1: Run Aider\naider 2>&1 | tee /tmp/aider.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/aider.log\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#github-copilot","level":2,"title":"GitHub Copilot","text":"

    GitHub Copilot integrates with ctx at three levels: an automated instructions file, a VS Code Chat extension, and manual patterns.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_3","level":3,"title":"Setup","text":"
    # Initialize context\nctx init\n\n# Generate .github/copilot-instructions.md\nctx hook copilot --write\n

    The --write flag creates .github/copilot-instructions.md, which Copilot reads automatically at the start of every session. This file contains your project's constitution rules, current tasks, conventions, and architecture: giving Copilot persistent context without manual copy-paste.

    Re-run ctx hook copilot --write after updating your .context/ files to regenerate the instructions.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#vs-code-chat-extension-ctx","level":3,"title":"VS Code Chat Extension (@ctx)","text":"

    The ctx VS Code extension adds a @ctx chat participant to GitHub Copilot Chat, giving you direct access to all context commands from within the editor.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#installation","level":4,"title":"Installation","text":"
    1. Build from source (requires Node.js 18+):
    cd editors/vscode\nnpm install\nnpm run build\nnpx @vscode/vsce package\n
    1. Install the .vsix file:
    code --install-extension ctx-context-0.7.0.vsix\n
    1. Reload VS Code. Type @ctx in Copilot Chat to verify.
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#slash-commands","level":4,"title":"Slash Commands","text":"Command Description @ctx /init Initialize .context/ directory with template files @ctx /status Show context summary with token estimate @ctx /agent Print AI-ready context packet @ctx /drift Detect stale or invalid context @ctx /recall Browse and search AI session history @ctx /hook Generate AI tool integration configs @ctx /add Add a task, decision, or learning @ctx /load Output assembled context Markdown @ctx /compact Archive completed tasks and clean up @ctx /sync Reconcile context with codebase","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage-examples_1","level":4,"title":"Usage Examples","text":"
    @ctx /init\n@ctx /status\n@ctx /add task Implement user authentication\n@ctx /drift\n@ctx /hook copilot\n@ctx /recall\n

    Typing @ctx without a command shows help with all available commands. The extension also supports natural language: asking @ctx about \"status\" or \"drift\" routes to the correct command automatically.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_2","level":4,"title":"Configuration","text":"Setting Default Description ctx.executablePath ctx Path to the ctx binary. Set this if ctx is not in your PATH.","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#follow-up-suggestions","level":4,"title":"Follow-Up Suggestions","text":"

    After each command, the extension suggests relevant next steps. For example, after /init it suggests /status and /hook; after /drift it suggests /sync.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-persistence","level":3,"title":"Session Persistence","text":"

    ctx init creates a .context/sessions/ directory for storing session data from non-Claude tools. The Markdown session parser scans this directory during ctx recall, enabling session history for Copilot and other tools.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-patterns","level":3,"title":"Manual Patterns","text":"

    These patterns work without the extension, using Copilot's built-in file awareness:

    Pattern 1: Keep context files open

    Open .context/CONVENTIONS.md in a split pane. Copilot will reference it.

    Pattern 2: Reference in comments

    // See .context/CONVENTIONS.md for naming patterns\n// Following decision in .context/DECISIONS.md: Use PostgreSQL\n\nfunction getUserById(id: string) {\n  // Copilot now has context\n}\n

    Pattern 3: Paste context into Copilot Chat

    ctx agent --budget 2000\n

    Paste output into Copilot Chat for context-aware responses.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#windsurf-ide","level":2,"title":"Windsurf IDE","text":"

    Windsurf supports custom instructions and file-based context.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_4","level":3,"title":"Setup","text":"
    # Generate Windsurf configuration\nctx hook windsurf\n\n# Initialize context\nctx init\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_3","level":3,"title":"Configuration","text":"

    Add to Windsurf settings:

    // Split to multiple lines for readability\n{\n  \"ai.customInstructions\": \"Always read .context/CONSTITUTION.md first. \n  Check .context/TASKS.md for current work. \n  Follow patterns in .context/CONVENTIONS.md.\"\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage_2","level":3,"title":"Usage","text":"

    Context files appear in the file tree. Reference them when chatting:

    • \"What's in our task list?\" → AI reads .context/TASKS.md
    • \"What convention do we use for naming?\" → AI reads .context/CONVENTIONS.md
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#generic-integration","level":2,"title":"Generic Integration","text":"

    For any AI tool that can read files, use these patterns:

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-loading","level":3,"title":"Manual Context Loading","text":"
    # Get full context\nctx load\n\n# Get AI-optimized packet\nctx agent --budget 8000\n\n# Get specific file\ncat .context/TASKS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#system-prompt-template","level":3,"title":"System Prompt Template","text":"
    You are working on a project with persistent context in .context/\n\nBefore responding:\n1. Read .context/CONSTITUTION.md - NEVER violate these rules\n2. Check .context/TASKS.md for current work\n3. Follow .context/CONVENTIONS.md patterns\n4. Reference .context/DECISIONS.md for architectural choices\n\nWhen you learn something new, note it for .context/LEARNINGS.md\nWhen you make a decision, document it for .context/DECISIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#automated-updates","level":3,"title":"Automated Updates","text":"

    If your AI tool outputs to a log, use ctx watch:

    # Watch log file for context-update commands\nyour-ai-tool 2>&1 | tee /tmp/ai.log &\nctx watch --log /tmp/ai.log\n

    The AI can emit updates like:

    <context-update type=\"complete\">implement caching</context-update>\n<context-update type=\"learning\"\n  context=\"Implementing caching layer\"\n  lesson=\"Important thing learned today\"\n  application=\"Apply this insight going forward\"\n>Caching Insight</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#context-update-commands","level":2,"title":"Context Update Commands","text":"

    The ctx watch command parses update commands from AI output. Use this format:

    <context-update type=\"TYPE\" [attributes]>Content</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#supported-types","level":3,"title":"Supported Types","text":"Type Target File Required Attributes task TASKS.md None decision DECISIONS.md context, rationale, consequence learning LEARNINGS.md context, lesson, application convention CONVENTIONS.md None complete TASKS.md None","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#simple-format-tasks-conventions-complete","level":3,"title":"Simple Format (tasks, conventions, complete)","text":"
    <context-update type=\"task\">Implement rate limiting</context-update>\n<context-update type=\"convention\">Use kebab-case for files</context-update>\n<context-update type=\"complete\">rate limiting</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#structured-format-learnings-decisions","level":3,"title":"Structured Format (learnings, decisions)","text":"

    Learnings and decisions support structured attributes for better documentation:

    Learning with full structure:

    <context-update type=\"learning\"\n  context=\"Debugging Claude Code hooks\"\n  lesson=\"Hooks receive JSON via stdin, not environment variables\"\n  application=\"Parse JSON stdin with the host language (Go, Python, etc.): no jq needed\"\n>Hook Input Format</context-update>\n

    Decision with full structure:

    <context-update type=\"decision\"\n  context=\"Need a caching layer for API responses\"\n  rationale=\"Redis is fast, well-supported, and team has experience\"\n  consequence=\"Must provision Redis infrastructure; team training on Redis patterns\"\n>Use Redis for caching</context-update>\n

    Learnings require: context, lesson, application attributes. Decisions require: context, rationale, consequence attributes. Updates missing required attributes are rejected with an error.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#further-reading","level":2,"title":"Further Reading","text":"
    • Skills That Fight the Platform: Common pitfalls in skill design that work against the host tool
    • The Anatomy of a Skill That Works: What makes a skill reliable: the E/A/R framework and quality gates
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/migration/","level":1,"title":"Integration","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#adopting-ctx-in-existing-projects","level":2,"title":"Adopting ctx in Existing Projects","text":"

    Claude Code User?

    You probably want the plugin instead of this page.

    Install ctx from the marketplace: (/plugin → search \"ctx\" → Install) and you're done: hooks, skills, and updates are handled for you.

    See Getting Started for the full walkthrough.

    This guide covers adopting ctx in existing projects regardless of which tools your team uses.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#quick-paths","level":2,"title":"Quick Paths","text":"You have... Command What happens Nothing (greenfield) ctx init Creates .context/, CLAUDE.md, permissions Existing CLAUDE.md ctx init --merge Backs up your file, inserts ctx block after the H1 Existing CLAUDE.md + ctx markers ctx init --force Replaces the ctx block, leaves your content intact .cursorrules / .aider.conf.yml ctx init ctx ignores those files: they coexist cleanly Team repo, first adopter ctx init --merge && git add .context/ CLAUDE.md Initialize and commit for the team","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#existing-claudemd","level":2,"title":"Existing CLAUDE.md","text":"

    This is the most common scenario:

    You have a CLAUDE.md with project-specific instructions and don't want to lose them.

    You Own CLAUDE.md

    After initialization, CLAUDE.md is yours: edit it freely.

    Add project instructions, remove sections you don't need, reorganize as you see fit.

    The only part ctx manages is the block between the <!-- ctx:context --> and <!-- ctx:end --> markers; everything outside those markers is yours to change at any time.

    If you remove the markers, nothing breaks: ctx simply treats the file as having no ctx content and will offer to merge again on the next ctx init.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-ctx-init-does","level":3,"title":"What ctx init Does","text":"

    When ctx init detects an existing CLAUDE.md, it checks for ctx markers (<!-- ctx:context --> ... <!-- ctx:end -->):

    State Default behavior With --merge With --force No CLAUDE.md Creates from template Creates from template Creates from template Exists, no ctx markers Prompts to merge Auto-merges (no prompt) Auto-merges (no prompt) Exists, has ctx markers Skips (already set up) Skips Replaces the ctx block only","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#the-merge-flag","level":3,"title":"The --merge Flag","text":"

    --merge auto-merges without prompting. The merge process:

    1. Backs up your existing CLAUDE.md to CLAUDE.md.<timestamp>.bak;
    2. Finds the H1 heading (e.g., # My Project) in your file;
    3. Inserts the ctx block immediately after it;
    4. Preserves everything else untouched.

    Your content before and after the ctx block remains exactly as it was.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#before-after-example","level":3,"title":"Before / After Example","text":"

    Before: your existing CLAUDE.md:

    # My Project\n\n## Build Commands\n\n-`npm run build`: production build\n- `npm test`: run tests\n\n## Code Style\n\n- Use TypeScript strict mode\n- Prefer named exports\n

    After ctx init --merge:

    # My Project\n\n<!-- ctx:context -->\n<!-- DO NOT REMOVE: This marker indicates ctx-managed content -->\n\n## IMPORTANT: You Have Persistent Memory\n\nThis project uses Context (`ctx`) for context persistence across sessions.\n...\n\n<!-- ctx:end -->\n\n## Build Commands\n\n- `npm run build`: production build\n- `npm test`: run tests\n\n## Code Style\n\n- Use TypeScript strict mode\n- Prefer named exports\n

    Your build commands and code style sections are untouched. The ctx block sits between markers and can be updated independently.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#the-force-flag","level":3,"title":"The --force Flag","text":"

    If your CLAUDE.md already has ctx markers (from a previous ctx init), the default behavior is to skip it. Use --force to replace the ctx block with the latest template: This is useful after upgrading ctx:

    ctx init --force\n

    This only replaces content between <!-- ctx:context --> and <!-- ctx:end -->. Your own content outside the markers is preserved. A timestamped backup is created before any changes.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#undoing-a-merge","level":3,"title":"Undoing a Merge","text":"

    Every merge creates a backup:

    $ ls CLAUDE.md*.bak\nCLAUDE.md.1738000000.bak\n

    To restore:

    cp CLAUDE.md.1738000000.bak CLAUDE.md\n

    Or if you are using git, simply:

    git checkout CLAUDE.md\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#existing-cursorrules-aider-copilot","level":2,"title":"Existing .cursorrules / Aider / Copilot","text":"

    ctx doesn't touch tool-specific config files. It creates its own files (.context/, CLAUDE.md) and coexists with whatever you already have.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-does-ctx-create","level":3,"title":"What Does ctx Create?","text":"ctx creates ctx does NOT touch .context/ directory .cursorrules CLAUDE.md (or merges into) .aider.conf.yml .claude/settings.local.json (seeded by ctx init; the plugin manages hooks and skills) .github/copilot-instructions.md .windsurfrules Any other tool-specific config

    Claude Code hooks and skills are provided by the ctx plugin, installed from the Claude Code marketplace (/plugin → search \"ctx\" → Install).

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#running-ctx-alongside-other-tools","level":3,"title":"Running ctx Alongside Other Tools","text":"

    The .context/ directory is the source of truth. Tool-specific configs point to it:

    • Cursor: Reference .context/ files in your system prompt (see Cursor setup)
    • Aider: Add .context/ files to the read: list in .aider.conf.yml (see Aider setup)
    • Copilot: Keep .context/ files open or reference them in comments (see Copilot setup)

    You can generate a tool-specific configuration with:

    ctx hook cursor    # Generate Cursor config snippet\nctx hook aider     # Generate .aider.conf.yml\nctx hook copilot   # Generate Copilot tips\nctx hook windsurf  # Generate Windsurf config\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#migrating-content-into-context","level":3,"title":"Migrating Content Into .context/","text":"

    If you have project knowledge scattered across .cursorrules or custom prompt files, consider migrating it:

    1. Rules / invariants → .context/CONSTITUTION.md
    2. Code patterns → .context/CONVENTIONS.md
    3. Architecture notes → .context/ARCHITECTURE.md
    4. Known issues / tips → .context/LEARNINGS.md

    You don't need to delete the originals: ctx and tool-specific files can coexist. But centralizing in .context/ means every tool gets the same context.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#team-adoption","level":2,"title":"Team Adoption","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#context-is-designed-to-be-committed","level":3,"title":".context/ Is Designed to Be Committed","text":"

    The context files (tasks, decisions, learnings, conventions, architecture) are meant to live in version control. However, some subdirectories are personal or sensitive and should not be committed.

    ctx init automatically adds these .gitignore entries:

    # Journals contain full session transcripts: personal, potentially large\n.context/journal/\n.context/journal-site/\n.context/journal-obsidian/\n\n# Legacy encryption key path (copy to ~/.ctx/.ctx.key if needed)\n.context/.ctx.key\n\n# Runtime state and logs (ephemeral, machine-specific):\n.context/state/\n.context/logs/\n\n# Claude Code local settings (machine-specific)\n.claude/settings.local.json\n

    With those in place, committing is straightforward:

    # One person initializes\nctx init --merge\n\n# Commit context files (journals and keys are already gitignored)\ngit add .context/ CLAUDE.md\ngit commit -m \"Add ctx context management\"\ngit push\n

    Teammates pull and immediately have context. No per-developer setup needed.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-about-claude","level":3,"title":"What About .claude/?","text":"

    The .claude/ directory contains permissions that ctx init seeds. Hooks and skills are provided by the ctx plugin (not per-project files).

    File Commit? Why .claude/settings.local.json No Machine-specific, accumulates session permissions .claude/settings.golden.json Yes Curated permission snapshot (via ctx permission snapshot)","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#merge-conflicts-in-context-files","level":3,"title":"Merge Conflicts in Context Files","text":"

    Context files are plain Markdown. Resolve conflicts the same way you would for any other documentation file:

    # After a conflicting pull\ngit diff .context/TASKS.md    # See both sides\n# Edit to keep both sets of tasks, then:\ngit add .context/TASKS.md\ngit commit\n

    Common conflict scenarios:

    • TASKS.md: Two people added tasks: Keep both.
    • DECISIONS.md: Same decision recorded differently: Unify the entry.
    • LEARNINGS.md: Parallel discoveries: Keep both, remove duplicates.
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#gradual-adoption","level":3,"title":"Gradual Adoption","text":"

    You don't need the whole team to switch at once:

    1. One person runs ctx init --merge and commits;
    2. CLAUDE.md instructions work immediately for Claude Code users;
    3. Other tool users can adopt at their own pace using ctx hook <tool>;
    4. Context files benefit everyone who reads them, even without tool integration.
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#verifying-it-worked","level":2,"title":"Verifying It Worked","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#check-status","level":3,"title":"Check Status","text":"
    ctx status\n

    You should see your context files listed with token counts and no warnings.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#test-memory","level":3,"title":"Test Memory","text":"

    Start a new AI session and ask: \"Do you remember?\"

    The AI should cite specific context:

    • Current tasks from .context/TASKS.md;
    • Recent decisions or learnings;
    • Session history (if you've had prior sessions);

    If it responds with generic \"I don't have memory\", check that ctx is in your PATH (which ctx) and that hooks are configured (see Troubleshooting).

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#verify-the-merge","level":3,"title":"Verify the Merge","text":"

    If you used --merge, check that your original content is intact:

    # Your original content should still be there\ncat CLAUDE.md\n\n# The ctx block should be between markers\ngrep -c \"ctx:context\" CLAUDE.md  # Should print 1\ngrep -c \"ctx:end\" CLAUDE.md      # Should print 1\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#further-reading","level":2,"title":"Further Reading","text":"
    • Getting Started: Full setup walkthrough
    • Context Files: What each .context/ file does
    • Integrations: Per-tool setup (Claude Code, Cursor, Aider, Copilot)
    • CLI Reference: All ctx commands and flags
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/upgrading/","level":1,"title":"Upgrade","text":"","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#upgrade","level":2,"title":"Upgrade","text":"

    New versions of ctx may ship updated permissions, CLAUDE.md directives, or plugin hooks and skills.

    Claude Code User?

    The marketplace can update skills, hooks, and prompts independently: /plugin → select ctx → Update now (or enable auto-update).

    The ctx binary is separate: rebuild from source or download a new release when one is available, then run ctx init --force --merge. Knowledge files are preserved automatically.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#tldr","level":2,"title":"TL:DR","text":"
    # Plugin users (Claude Code)\n# /plugin → select ctx → Update now\n# Then update the binary and reinitialize:\nctx init --force --merge\n\n# From-source / manual users\n# install new ctx binary, then:\nctx init --force --merge\n# /plugin → select ctx → Update now   (if using Claude Code)\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#what-changes-between-versions","level":2,"title":"What Changes Between Versions","text":"

    ctx init generates two categories of files:

    Category Examples Changes between versions? Infrastructure .claude/settings.local.json (permissions), ctx-managed sections in CLAUDE.md and PROMPT.md, ctx plugin (hooks + skills) Yes Knowledge .context/TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md, ARCHITECTURE.md, GLOSSARY.md, CONSTITUTION.md, AGENT_PLAYBOOK.md No: this is your data

    Infrastructure is regenerated by ctx init and plugin updates. Knowledge files are yours and should never be overwritten.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#upgrade-steps","level":2,"title":"Upgrade Steps","text":"","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#1-install-the-new-version","level":3,"title":"1. Install the New Version","text":"

    Build from source or download the binary:

    cd /path/to/ctx-source\ngit pull\nmake build\nsudo make install\nctx --version   # verify\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#2-reinitialize","level":3,"title":"2. Reinitialize","text":"
    ctx init --force --merge\n
    • --force regenerates infrastructure files (permissions, ctx-managed sections in CLAUDE.md and PROMPT.md).
    • --merge preserves your content outside ctx markers.

    Knowledge files (.context/TASKS.md, DECISIONS.md, etc.) are preserved automatically: ctx init only overwrites infrastructure, never your data.

    Encryption key: The encryption key lives at ~/.ctx/.ctx.key (outside the project). Reinit does not affect it. If you have a legacy key at .context/.ctx.key or ~/.local/ctx/keys/, copy it manually (see Syncing Scratchpad Notes).

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#3-update-the-ctx-plugin","level":3,"title":"3. Update the ctx Plugin","text":"

    If you use Claude Code, update the plugin to get new hooks and skills:

    1. Open /plugin in Claude Code.
    2. Select ctx.
    3. Click Update now.

    Or enable auto-update so the plugin stays current without manual steps.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#4-review-custom-settings","level":3,"title":"4. Review Custom Settings","text":"

    If you added custom permissions to .claude/settings.local.json beyond what ctx init provides, diff and merge:

    diff .claude.bak/settings.local.json .claude/settings.local.json\n

    Manually add back any custom entries that the new init dropped.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#5-verify","level":3,"title":"5. Verify","text":"
    ctx status          # context files intact\nctx drift           # no broken references\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#6-clean-up","level":3,"title":"6. Clean Up","text":"

    If you made manual backups, remove them once satisfied:

    rm -rf .context.bak .claude.bak CLAUDE.md.bak PROMPT.md.bak\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#what-if-i-skip-the-upgrade","level":2,"title":"What If I Skip the Upgrade?","text":"

    The old binary still works with your existing .context/ files. But you may miss:

    • New plugin hooks that enforce better practices or catch mistakes;
    • Updated skill prompts that produce better results;
    • New .gitignore entries for directories added in newer versions;
    • Bug fixes in the CLI itself.

    The plugin and the binary can be updated independently. You can update the plugin (for new hooks/skills) even if you stay on an older binary, and vice versa.

    Context files are plain Markdown: They never break between versions.

    The surrounding infrastructure is what evolves.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"recipes/","level":1,"title":"Recipes","text":"

    Workflow recipes combining ctx commands and skills to solve specific problems.

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#getting-started","level":2,"title":"Getting Started","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#guide-your-agent","level":3,"title":"Guide Your Agent","text":"

    How commands, skills, and conversational patterns work together. Train your agent to be proactive through ask, guide, reinforce.

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#setup-across-ai-tools","level":3,"title":"Setup Across AI Tools","text":"

    Initialize ctx and configure hooks for Claude Code, Cursor, Aider, Copilot, or Windsurf. Includes shell completion, watch mode for non-native tools, and verification.

    Uses: ctx init, ctx hook, ctx agent, ctx completion, ctx watch

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#keeping-context-in-a-separate-repo","level":3,"title":"Keeping Context in a Separate Repo","text":"

    Store context files outside the project tree: in a private repo, shared directory, or anywhere else. Useful for open source projects with private context or multi-repo setups.

    Uses: ctx init, --context-dir, --allow-outside-cwd, .ctxrc, /ctx-status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#sessions","level":2,"title":"Sessions","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#the-complete-session","level":3,"title":"The Complete Session","text":"

    Walk through a full ctx session from start to finish:

    • Loading context,
    • Picking what to work on,
    • Committing with context,
    • Capturing, reflecting, and saving a snapshot.

    Uses: ctx status, ctx agent, /ctx-remember, /ctx-next, /ctx-commit, /ctx-reflect

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#session-ceremonies","level":3,"title":"Session Ceremonies","text":"

    The two bookend rituals for every session: /ctx-remember at the start to load and confirm context, /ctx-wrap-up at the end to review the session and persist learnings, decisions, and tasks.

    Uses: /ctx-remember, /ctx-wrap-up, /ctx-commit, ctx agent, ctx add

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#browsing-and-enriching-past-sessions","level":3,"title":"Browsing and Enriching Past Sessions","text":"

    Export your AI session history to a browsable journal site. Enrich entries with metadata and search across months of work.

    Uses: ctx recall list/show/export, ctx journal site, ctx journal obsidian, ctx serve, /ctx-recall, /ctx-journal-normalize, /ctx-journal-enrich, /ctx-journal-enrich-all

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#session-reminders","level":3,"title":"Session Reminders","text":"

    Leave a message for your next session. Reminders surface automatically at session start and repeat until dismissed. Date-gate reminders to surface only after a specific date.

    Uses: ctx remind, ctx remind list, ctx remind dismiss, ctx system check-reminders

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#reviewing-session-changes","level":3,"title":"Reviewing Session Changes","text":"

    See what moved since your last session: context file edits, code commits, directories touched. Auto-detects session boundaries from state markers.

    Uses: ctx change, ctx agent, ctx status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#pausing-context-hooks","level":3,"title":"Pausing Context Hooks","text":"

    Silence all nudge hooks for a quick task that doesn't need ceremony overhead. Session-scoped: Other sessions are unaffected. Security hooks still fire.

    Uses: ctx pause, ctx resume, /ctx-pause, /ctx-resume

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#knowledge-tasks","level":2,"title":"Knowledge & Tasks","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#persisting-decisions-learnings-and-conventions","level":3,"title":"Persisting Decisions, Learnings, and Conventions","text":"

    Record architectural decisions with rationale, capture gotchas and lessons learned, and codify conventions so they survive across sessions and team members.

    Uses: ctx add decision, ctx add learning, ctx add convention, ctx decision reindex, ctx learning reindex, /ctx-add-decision, /ctx-add-learning, /ctx-add-convention, /ctx-reflect

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#tracking-work-across-sessions","level":3,"title":"Tracking Work Across Sessions","text":"

    Add, prioritize, complete, snapshot, and archive tasks. Keep TASKS.md focused as your project evolves across dozens of sessions.

    Uses: ctx add task, ctx task complete, ctx task archive, ctx task snapshot, /ctx-add-task, /ctx-archive, /ctx-next

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#using-the-scratchpad","level":3,"title":"Using the Scratchpad","text":"

    Use the encrypted scratchpad for quick notes, working memory, and sensitive values during AI sessions. Natural language in, encrypted storage out.

    Uses: ctx pad, /ctx-pad, ctx pad show, ctx pad edit

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#syncing-scratchpad-notes-across-machines","level":3,"title":"Syncing Scratchpad Notes Across Machines","text":"

    Distribute your scratchpad encryption key, push and pull encrypted notes via git, and resolve merge conflicts when two machines edit simultaneously.

    Uses: ctx init, ctx pad, ctx pad resolve, scp

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#bridging-claude-code-auto-memory","level":3,"title":"Bridging Claude Code Auto Memory","text":"

    Mirror Claude Code's auto memory (MEMORY.md) into .context/ for version control, portability, and drift detection. Import entries into structured context files with heuristic classification.

    Uses: ctx memory sync, ctx memory status, ctx memory diff, ctx memory import, ctx memory publish, ctx system check-memory-drift

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#hooks-notifications","level":2,"title":"Hooks & Notifications","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#hook-output-patterns","level":3,"title":"Hook Output Patterns","text":"

    Choose the right output pattern for your Claude Code hooks: VERBATIM relay for user-facing reminders, hard gates for invariants, agent directives for nudges, and five more patterns across the spectrum.

    Uses: ctx plugin hooks, settings.local.json

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#customizing-hook-messages","level":3,"title":"Customizing Hook Messages","text":"

    Customize what hooks say without changing what they do. Override the QA gate for Python (pytest instead of make lint), silence noisy ceremony nudges, or tailor post-commit instructions for your stack.

    Uses: ctx system message list, ctx system message show, ctx system message edit, ctx system message reset

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#hook-sequence-diagrams","level":3,"title":"Hook Sequence Diagrams","text":"

    Mermaid sequence diagrams for every system hook: entry conditions, state reads, output, throttling, and exit points. Includes throttling summary table and state file reference.

    Uses: All ctx system hooks

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#auditing-system-hooks","level":3,"title":"Auditing System Hooks","text":"

    The 12 system hooks that run invisibly during every session: what each one does, why it exists, and how to verify they're actually firing. Covers webhook-based audit trails, log inspection, and detecting silent hook failures.

    Uses: ctx system, ctx notify, .context/logs/, .ctxrc notify.events

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#webhook-notifications","level":3,"title":"Webhook Notifications","text":"

    Get push notifications when loops complete, hooks fire, or agents hit milestones. Webhook URL is encrypted: never stored in plaintext. Works with IFTTT, Slack, Discord, ntfy.sh, or any HTTP endpoint.

    Uses: ctx notify setup, ctx notify test, ctx notify --event, .ctxrc notify.events

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#maintenance","level":2,"title":"Maintenance","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#detecting-and-fixing-drift","level":3,"title":"Detecting and Fixing Drift","text":"

    Keep context files accurate by detecting structural drift (stale paths, missing files, stale file ages) and task staleness.

    Uses: ctx drift, ctx sync, ctx compact, ctx status, /ctx-drift, /ctx-status, /ctx-prompt-audit

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#state-directory-maintenance","level":3,"title":"State Directory Maintenance","text":"

    Clean up session tombstones from .context/state/. Prune old per-session files, identify stale global markers, and keep the state directory lean.

    Uses: ctx system prune

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#troubleshooting","level":3,"title":"Troubleshooting","text":"

    Diagnose hook failures, noisy nudges, stale context, and configuration issues. Start with ctx doctor for a structural health check, then use /ctx-doctor for agent-driven analysis of event patterns.

    Uses: ctx doctor, ctx system events, /ctx-doctor

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#claude-code-permission-hygiene","level":3,"title":"Claude Code Permission Hygiene","text":"

    Keep .claude/settings.local.json clean: recommended safe defaults, what to never pre-approve, and a maintenance workflow for cleaning up session debris.

    Uses: ctx init, /ctx-drift, /ctx-sanitize-permissions, ctx permission snapshot, ctx permission restore

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#permission-snapshots","level":3,"title":"Permission Snapshots","text":"

    Capture a known-good permission baseline as a golden image, then restore at session start to automatically drop session-accumulated permissions.

    Uses: ctx permission snapshot, ctx permission restore, /ctx-sanitize-permissions

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#turning-activity-into-content","level":3,"title":"Turning Activity into Content","text":"

    Generate blog posts from project activity, write changelog posts from commit ranges, and publish a browsable journal site from your session history.

    The output is generic Markdown, but the skills are tuned for the ctx-style blog artifacts you see on this website.

    Uses: ctx journal site, ctx journal obsidian, ctx serve, ctx recall export, /ctx-blog, /ctx-blog-changelog, /ctx-journal-enrich, /ctx-journal-normalize

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#importing-claude-code-plans","level":3,"title":"Importing Claude Code Plans","text":"

    Import Claude Code plan files (~/.claude/plans/*.md) into specs/ as permanent project specs. Filter by date, select interactively, and optionally create tasks referencing each imported spec.

    Uses: /ctx-import-plans, /ctx-add-task

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#design-before-coding","level":3,"title":"Design Before Coding","text":"

    Front-load design with a four-skill chain: brainstorm the approach, spec the design, task the work, implement step-by-step. Each step produces an artifact that feeds the next.

    Uses: /ctx-brainstorm, /ctx-spec, /ctx-add-task, /ctx-implement, /ctx-add-decision

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#agents-automation","level":2,"title":"Agents & Automation","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#building-project-skills","level":3,"title":"Building Project Skills","text":"

    Encode repeating workflows into reusable skills the agent loads automatically. Covers the full cycle: identify a pattern, create the skill, test with realistic prompts, and iterate until it triggers correctly.

    Uses: /ctx-skill-creator, ctx init

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#running-an-unattended-ai-agent","level":3,"title":"Running an Unattended AI Agent","text":"

    Set up a loop where an AI agent works through tasks overnight without you at the keyboard, using ctx for persistent memory between iterations.

    This recipe shows how ctx supports long-running agent loops without losing context or intent.

    Uses: ctx init --ralph, ctx loop, ctx watch, ctx load, /ctx-loop, /ctx-implement

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#when-to-use-a-team-of-agents","level":3,"title":"When to Use a Team of Agents","text":"

    Decision framework for choosing between a single agent, parallel worktrees, and a full agent team.

    This recipe covers the file overlap test, when teams make things worse, and what ctx provides at each level.

    Uses: /ctx-worktree, /ctx-next, ctx status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#parallel-agent-development-with-git-worktrees","level":3,"title":"Parallel Agent Development with Git Worktrees","text":"

    Split a large backlog across 3-4 agents using git worktrees, each on its own branch and working directory. Group tasks by file overlap, work in parallel, merge back.

    Uses: /ctx-worktree, /ctx-next, git worktree, git merge

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#generating-dependency-graphs","level":3,"title":"Generating Dependency Graphs","text":"

    Map your project's internal and external dependency structure. Auto-detects Go, Node.js, Python, and Rust. Output as Mermaid, table, or JSON.

    Uses: ctx dep, ctx drift

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#reusable-prompt-templates","level":3,"title":"Reusable Prompt Templates","text":"

    Store and reuse prompt templates in .context/prompts/ for repeating tasks. Manage templates via CLI, reference them in skills and loop scripts.

    Uses: ctx prompt, ctx prompt list, ctx prompt show

    ","path":["Recipes"],"tags":[]},{"location":"recipes/autonomous-loops/","level":1,"title":"Running an Unattended AI Agent","text":"","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-problem","level":2,"title":"The Problem","text":"

    You have a project with a clear list of tasks, and you want an AI agent to work through them autonomously: overnight, unattended, without you sitting at the keyboard.

    Each iteration needs to remember what the previous one did, mark tasks as completed, and know when to stop.

    Without persistent memory, every iteration starts fresh and the loop collapses. With ctx, each iteration can pick up where the last one left off, but only if the agent persists its context as part of the work.

    Unattended operation works because the agent treats context persistence as a first-class deliverable, not an afterthought.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#tldr","level":2,"title":"TL;DR","text":"
    ctx init --ralph                            # 1. init for unattended mode\n# Edit TASKS.md with phased work items\nctx loop --tool claude --max-iterations 10  # 2. generate loop.sh\n./loop.sh 2>&1 | tee /tmp/loop.log &        # 3. run the loop\nctx watch --log /tmp/loop.log               # 4. process context updates\n# Next morning:\nctx status && ctx load                      # 5. review the results\n

    Read on for permissions, isolation, and completion signals.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init --ralph Command Initialize project for unattended operation (no human in the loop) ctx loop Command Generate the loop shell script ctx watch Command Monitor AI output and persist context updates ctx load Command Display assembled context (for debugging) /ctx-loop Skill Generate loop script from inside Claude Code /ctx-implement Skill Execute a plan step-by-step with verification","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-1-initialize-for-unattended-operation","level":3,"title":"Step 1: Initialize for Unattended Operation","text":"

    Start by creating a .context/ directory configured so the agent can work without human input. The --ralph flag sets up PROMPT.md so the agent makes reasonable choices instead of asking clarifying questions.

    ctx init --ralph\n

    This creates .context/ with the template files, a PROMPT.md configured for autonomous iteration, and seeds Claude Code permissions in .claude/settings.local.json. Install the ctx plugin for hooks and skills.

    Without --ralph, the agent will often pause when requirements are unclear. For unattended runs, you want it to choose a default and document the trade-off in DECISIONS.md instead.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-2-populate-tasksmd-with-phased-work","level":3,"title":"Step 2: Populate TASKS.md with Phased Work","text":"

    Open .context/TASKS.md and organize your work into phases. The agent works through these systematically, top to bottom, using priority tags to break ties.

    # Tasks\n\n## Phase 1: Foundation\n\n- [ ] Set up project structure and build system `#priority:high`\n- [ ] Configure testing framework `#priority:high`\n- [ ] Create CI pipeline `#priority:medium`\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Hardening\n\n- [ ] Add rate limiting to API endpoints `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n- [ ] Write integration tests `#priority:medium`\n

    Phased organization matters because it gives the agent natural boundaries. Phase 1 tasks should be completable without Phase 2 code existing yet.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-3-configure-promptmd","level":3,"title":"Step 3: Configure PROMPT.md","text":"

    The --ralph flag generates a PROMPT.md that instructs the agent to operate autonomously:

    1. Read .context/CONSTITUTION.md first (hard rules, never violated)
    2. Load context from .context/ files
    3. Pick one task per iteration
    4. Complete the task and update context files
    5. Commit changes (including .context/)
    6. Signal status with a completion signal

    You can customize PROMPT.md for your project. The critical parts are the one-task-per-iteration discipline, proactive context persistence, and completion signals at the end:

    ## Signal Status\n\nEnd your response with exactly ONE of:\n\n* `SYSTEM_CONVERGED`: All tasks in `TASKS.md` are complete (*this is the\n  signal the loop script detects by default*)\n* `SYSTEM_BLOCKED`: Cannot proceed, need human input (explain why)\n* (*no signal*): More work remains, continue to the next iteration\n\nNote: the loop script only checks for `SYSTEM_CONVERGED` by default.\n`SYSTEM_BLOCKED` is a convention for the human reviewing the log.\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-4-configure-permissions","level":3,"title":"Step 4: Configure Permissions","text":"

    An unattended agent needs permission to use tools without prompting. By default, Claude Code asks for confirmation on file writes, bash commands, and other operations, which stops the loop and waits for a human who is not there.

    There are two approaches.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#option-a-explicit-allowlist-recommended","level":4,"title":"Option A: Explicit Allowlist (Recommended)","text":"

    Grant only the permissions the agent needs. In .claude/settings.local.json:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(make:*)\",\n      \"Bash(go:*)\",\n      \"Bash(git:*)\",\n      \"Bash(ctx:*)\",\n      \"Read\",\n      \"Write\",\n      \"Edit\"\n    ]\n  }\n}\n

    Adjust the Bash patterns for your project's toolchain. The agent can run make, go, git, and ctx commands but cannot run arbitrary shell commands.

    This is recommended even in sandboxed environments because it limits blast radius.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#option-b-skip-all-permission-checks","level":4,"title":"Option B: Skip All Permission Checks","text":"

    Claude Code supports a --dangerously-skip-permissions flag that disables all permission prompts:

    claude --dangerously-skip-permissions -p \"$(cat .context/PROMPT.md)\"\n

    This Flag Means What It Says

    With --dangerously-skip-permissions, the agent can execute any shell command, write to any file, and make network requests without confirmation.

    Only use this on a sandboxed machine: ideally a virtual machine with no access to host credentials, no SSH keys, and no access to production systems.

    If you would not give an untrusted intern sudo on this machine, do not use this flag.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#enforce-isolation-at-the-os-level","level":4,"title":"Enforce Isolation at the OS Level","text":"

    The only controls an agent cannot override are the ones enforced by the operating system, the container runtime, or the hypervisor.

    Do Not Skip This Section

    This is not optional hardening:

    An unattended agent with unrestricted OS access is an unattended shell with unrestricted OS access.

    The allowlist above is a strong first layer, but do not rely on a single runtime boundary.

    For unattended runs, enforce isolation at the infrastructure level:

    Layer What to enforce User account Run the agent as a dedicated unprivileged user with no sudo access and no membership in privileged groups (docker, wheel, adm). Filesystem Restrict the project directory via POSIX permissions or ACLs. The agent should have no access to other users' files or system directories. Container Run inside a Docker/Podman sandbox. Mount only the project directory. Drop capabilities (--cap-drop=ALL). Disable network if not needed (--network=none). Never mount the Docker socket and do not run privileged containers. Prefer rootless containers. Virtual machine Prefer a dedicated VM with no shared folders, no host passthrough, and no keys to other machines. Network If the agent does not need the internet, disable outbound access entirely. If it does, restrict to specific domains via firewall rules. Resource limits Apply CPU, memory, and disk limits (cgroups/container limits). A runaway loop should not fill disk or consume all RAM. Self-modification Make instruction files read-only. CLAUDE.md, .claude/settings.local.json, and .context/CONSTITUTION.md should not be writable by the agent user. If using project-local hooks, protect those too.

    A minimal Docker setup for overnight runs:

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh 2>&1 | tee /tmp/loop.log\n

    Defense in Depth

    Use multiple layers together: OS-level isolation (the boundary the agent cannot cross), a permission allowlist (what Claude Code will do within that boundary), and CONSTITUTION.md (a soft nudge for the common case).

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-5-generate-the-loop-script","level":3,"title":"Step 5: Generate the Loop Script","text":"

    Use ctx loop to generate a loop.sh tailored to your AI tool:

    # Generate for Claude Code with a 10-iteration cap\nctx loop --tool claude --max-iterations 10\n\n# Generate for Aider\nctx loop --tool aider --max-iterations 10\n\n# Custom prompt file and output filename (default prompt is PROMPT.md in project root)\nctx loop --tool claude --prompt my-prompt.md --output my-loop.sh\n

    The generated script reads PROMPT.md, runs the tool, checks for completion signals, and loops until done or the cap is reached.

    You can also use the /ctx-loop skill from inside Claude Code.

    A Shell Loop Is the Best Practice

    The shell loop approach spawns a fresh AI process each iteration, so the only state that carries between iterations is what lives in .context/ and git.

    Claude Code's built-in /loop runs iterations within the same session, which can allow context window state to leak between iterations. This can be convenient for short runs, but it is less reliable for unattended loops.

    See Shell Loop vs Built-in Loop for details.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-6-run-with-watch-mode","level":3,"title":"Step 6: Run with Watch Mode","text":"

    Open two terminals. In the first, run the loop. In the second, run ctx watch to process context updates from the AI output.

    # Terminal 1: Run the loop\n./loop.sh 2>&1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log\n

    The watch command parses XML context-update commands from the AI output and applies them:

    <context-update type=\"complete\">user registration</context-update>\n<context-update type=\"learning\"\n  context=\"Setting up user registration\"\n  lesson=\"Email verification needs SMTP configured\"\n  application=\"Add SMTP setup to deployment checklist\"\n>SMTP Requirement</context-update>\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-7-completion-signals-end-the-loop","level":3,"title":"Step 7: Completion Signals End the Loop","text":"

    The generated script checks for one completion signal per run. By default this is SYSTEM_CONVERGED. You can change it with the --completion flag:

    ctx loop --tool claude --completion BOOTSTRAP_COMPLETE --max-iterations 5\n

    The following signals are conventions used in PROMPT.md:

    Signal Convention How the script handles it SYSTEM_CONVERGED All tasks in TASKS.md are done Detected by default (--completion default value) SYSTEM_BLOCKED Agent cannot proceed Only detected if you set --completion to this BOOTSTRAP_COMPLETE Initial scaffolding done Only detected if you set --completion to this

    The script uses grep -q on the agent's output, so any string works as a signal. If you need to detect multiple signals in one run, edit the generated loop.sh to add additional grep checks.

    When you return in the morning, check the log and the context files:

    tail -100 /tmp/loop.log\nctx status\nctx load\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-8-use-ctx-implement-for-plan-execution","level":3,"title":"Step 8: Use /ctx-implement for Plan Execution","text":"

    Within each iteration, the agent can use /ctx-implement to execute multi-step plans with verification between steps. This is useful for complex tasks that touch multiple files.

    The skill breaks a plan into atomic, verifiable steps:

    Step 1/6: Create user model .................. OK\nStep 2/6: Add database migration ............. OK\nStep 3/6: Implement registration handler ..... OK\nStep 4/6: Write unit tests ................... OK\nStep 5/6: Run test suite ..................... FAIL\n  -> Fixed: missing test dependency\n  -> Re-verify ............................... OK\nStep 6/6: Update TASKS.md .................... OK\n

    Each step is verified (build, test, syntax check) before moving to the next.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A typical overnight run:

    ctx init --ralph\n# Edit TASKS.md and PROMPT.md\n\nctx loop --tool claude --max-iterations 20\n\n./loop.sh 2>&1 | tee /tmp/loop.log &\nctx watch --log /tmp/loop.log\n\n# Next morning:\nctx status\nctx load\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#why-autonomous-loops-work-proactive-context-persistence","level":2,"title":"Why Autonomous Loops Work: Proactive Context Persistence","text":"

    The autonomous loop pattern works because the agent persists context as part of the job.

    Without proactive persistence, the loop degrades into disconnected iterations that repeat work, contradict decisions, and lose track of progress. The agent cannot rely on a human to prompt it. It must treat context updates as part of every task, not as a separate step.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-agent-playbook-self-check-drives-autonomy","level":3,"title":"The Agent Playbook Self-Check Drives Autonomy","text":"

    The Agent Playbook defines a self-check prompt the agent applies continuously:

    \"If this session ended right now, would the next session know what happened?\"\n

    In interactive sessions, a human might remind the agent to save context. When the agent runs unattended, nobody is there to remind it.

    The self-check becomes the trigger: after meaningful work, the agent evaluates whether the context files reflect reality and updates them immediately if they do not.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#what-the-agent-does-proactively-between-iterations","level":3,"title":"What the Agent Does Proactively Between Iterations","text":"

    At milestones within an iteration, the agent persists without waiting for instructions:

    Milestone What the agent does proactively Completes a task Marks it [x] in TASKS.md with #done timestamp Discovers a gotcha Adds it to LEARNINGS.md Makes a design choice Records it in DECISIONS.md with rationale Identifies follow-up work Creates new tasks in TASKS.md with #added timestamp Hits an unexpected failure Documents the root cause before moving on","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#example-what-proactive-persistence-looks-like","level":3,"title":"Example: What Proactive Persistence Looks Like","text":"

    Here is what the agent does during a single iteration beyond writing code:

    Iteration 4:\n  1. Read TASKS.md -> pick \"Add email verification\" (#priority:high)\n  2. Add #started:2026-01-25-030012 to the task\n  3. Implement the feature (code, tests, docs if needed)\n  4. Tests pass -> mark task [x], add #done:2026-01-25-031544\n  5. Add learning: \"SMTP config must be set before verification handler registers. Order matters in init().\"\n  6. Add decision: \"Use token-based verification links (not codes) because links work better in automated tests.\"\n  7. Create follow-up task: \"Add rate limiting to verification endpoint\" #added:...\n  8. Commit all changes including `.context/`\n  9. No signal emitted -> loop continues to iteration 5\n

    Steps 2, 4, 5, 6, and 7 are proactive context persistence:

    The agent was not asked to do any of them.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#context-persistence-at-milestones","level":3,"title":"Context Persistence at Milestones","text":"

    For long autonomous runs, the agent persists context at natural boundaries, often at phase transitions or after completing a cluster of related tasks. It updates TASKS.md, DECISIONS.md, and LEARNINGS.md as it goes.

    If the loop crashes at 4 AM, the context files tell you exactly where to resume. You can also use ctx recall list to review the session transcripts.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-persistence-contract","level":3,"title":"The Persistence Contract","text":"

    The autonomous loop has an implicit contract:

    1. Every iteration reads context: TASKS.md, DECISIONS.md, LEARNINGS.md
    2. Every iteration writes context: task updates, new learnings, decisions
    3. Every commit includes .context/ so the next iteration sees changes
    4. Context stays current: if the loop stopped right now, nothing important is lost

    Break any part of this contract and the loop degrades.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#tips","level":2,"title":"Tips","text":"

    Markdown Is Not Enforcement

    Your real guardrails are permissions and isolation, not Markdown. CONSTITUTION.md can nudge the agent, but it is probabilistic.

    The permission allowlist and OS isolation are deterministic:

    For unattended runs, trust the sandbox and the allowlist, not the prose.

    • Start with a small iteration cap. Use --max-iterations 5 on your first run.
    • Keep tasks atomic. Each task should be completable in a single iteration.
    • Check signal discipline. If the loop runs forever, the agent is not emitting SYSTEM_CONVERGED or SYSTEM_BLOCKED. Make the signal requirement explicit in PROMPT.md.
    • Commit after context updates. Finish code, update .context/, commit including .context/, then signal.
    • Set up webhook notifications to get notified when the loop completes, hits max iterations, or when hooks fire nudges. The generated loop script includes ctx notify calls automatically.
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#next-up","level":2,"title":"Next Up","text":"

    When to Use a Team of Agents →: Decision framework for choosing between a single agent, parallel worktrees, and a full agent team.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#see-also","level":2,"title":"See Also","text":"
    • Autonomous Loops: loop pattern, PROMPT.md templates, troubleshooting
    • CLI Reference: ctx loop: flags and options
    • CLI Reference: ctx watch: watch mode details
    • CLI Reference: ctx init: init flags including --ralph
    • The Complete Session: interactive workflow
    • Tracking Work Across Sessions: structuring TASKS.md
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/building-skills/","level":1,"title":"Building Project Skills","text":"","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#the-problem","level":2,"title":"The Problem","text":"

    You have workflows your agent needs to repeat across sessions: a deploy checklist, a review protocol, a release process. Each time, you re-explain the steps. The agent gets it mostly right but forgets edge cases you corrected last time.

    Skills solve this by encoding domain knowledge into a reusable document the agent loads automatically when triggered. A skill is not code - it is a structured prompt that captures what took you sessions to learn.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-skill-creator\n

    The skill-creator walks you through: identify a repeating workflow, draft a skill, test with realistic prompts, iterate until it triggers correctly and produces good output.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-skill-creator Skill Interactive skill creation and improvement workflow ctx init Command Deploys template skills to .claude/skills/ on first setup","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-1-identify-a-repeating-pattern","level":3,"title":"Step 1: Identify a Repeating Pattern","text":"

    Good skill candidates:

    • Checklists you repeat: deploy steps, release prep, code review
    • Decisions the agent gets wrong: if you keep correcting the same behavior, encode the correction
    • Multi-step workflows: anything with a sequence of commands and conditional branches
    • Domain knowledge: project-specific terminology, architecture constraints, or conventions the agent cannot infer from code alone

    Not good candidates: one-off instructions, things the platform already handles (file editing, git operations), or tasks too narrow to reuse.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-2-create-the-skill","level":3,"title":"Step 2: Create the Skill","text":"

    Invoke the skill-creator:

    You: \"I want a skill for our deploy process\"\n\nAgent: [Asks about the workflow: what steps, what tools,\n        what edge cases, what the output should look like]\n

    Or capture a workflow you just did:

    You: \"Turn what we just did into a skill\"\n\nAgent: [Extracts the steps from conversation history,\n        confirms understanding, drafts the skill]\n

    The skill-creator produces a SKILL.md file in .claude/skills/your-skill/.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-3-test-with-realistic-prompts","level":3,"title":"Step 3: Test with Realistic Prompts","text":"

    The skill-creator proposes 2-3 test prompts - the kind of thing a real user would say. It runs each one and shows the result alongside a baseline (same prompt without the skill) so you can compare.

    Agent: \"Here are test prompts I'd try:\n        1. 'Deploy to staging'\n        2. 'Ship the hotfix'\n        3. 'Run the release checklist'\n        Want to adjust these?\"\n
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-4-iterate-on-the-description","level":3,"title":"Step 4: Iterate on the Description","text":"

    The description field in frontmatter determines when a skill triggers. Claude tends to undertrigger - descriptions need to be specific and slightly \"pushy\":

    # Weak - too vague, will undertrigger\ndescription: \"Use for deployments\"\n\n# Strong - covers situations and synonyms\ndescription: >-\n  Use when deploying to staging or production, running the release\n  checklist, or when the user says 'ship it', 'deploy this', or\n  'push to prod'. Also use after merging to main when a deploy\n  is expected.\n

    The skill-creator helps you tune this iteratively.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-5-deploy-as-template-optional","level":3,"title":"Step 5: Deploy as Template (Optional)","text":"

    If the skill should be available to all projects (not just this one), place it in internal/assets/claude/skills/ so ctx init deploys it to new projects automatically.

    Most project-specific skills stay in .claude/skills/ and travel with the repo.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#skill-anatomy","level":2,"title":"Skill Anatomy","text":"
    my-skill/\n  SKILL.md         # Required: frontmatter + instructions (<500 lines)\n  scripts/         # Optional: deterministic code the skill can execute\n  references/      # Optional: detail loaded on demand (not always)\n  assets/          # Optional: output templates, not loaded into context\n

    Key sections in SKILL.md:

    Section Purpose Required? Frontmatter Name, description (trigger) Yes When to Use Positive triggers Yes When NOT to Use Prevents false activations Yes Process Steps and commands Yes Examples Good/bad output pairs Recommended Quality Checklist Verify before reporting completion For complex skills","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#tips","level":2,"title":"Tips","text":"
    • Description is everything. A great skill with a vague description never fires. Spend time on trigger coverage - synonyms, concrete situations, edge cases.
    • Stay under 500 lines. If your skill is growing past this, move detail into references/ files and point to them from SKILL.md.
    • Do not duplicate the platform. If the agent already knows how to do something (edit files, run git commands), do not restate it. Tag paragraphs as Expert/Activation/Redundant and delete Redundant ones.
    • Explain why, not just what. \"Sort by date because users want recent results first\" beats \"ALWAYS sort by date.\" The agent generalizes from reasoning better than from rigid rules.
    • Test negative triggers. Make sure the skill does not fire on unrelated prompts. A skill that activates too broadly becomes noise.
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#next-up","level":2,"title":"Next Up","text":"

    Parallel Agent Development with Git Worktrees ->: Split work across multiple agents using git worktrees.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: full listing of all bundled and project-local skills
    • Guide Your Agent: how commands, skills, and conversational patterns work together
    • Design Before Coding: the four-skill chain for front-loading design work
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/claude-code-permissions/","level":1,"title":"Claude Code Permission Hygiene","text":"","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code's .claude/settings.local.json controls what the agent can do without asking. Over time, this file accumulates one-off permissions from individual sessions: Exact commands with hardcoded paths, duplicate entries, and stale skill references.

    A noisy \"allowlist\" makes it harder to spot dangerous permissions and increases the surface area for unintended behavior.

    Since settings.local.json is .gitignored, it drifts independently of your codebase. There is no PR review, no CI check: just whatever you clicked \"Allow\" on.

    This recipe shows what a well-maintained permission file looks like and how to keep it clean.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                            # seeds safe defaults\n/ctx-drift                          # detects missing/stale permissions\n/ctx-sanitize-permissions               # audits for dangerous patterns\n

    See Recommended Defaults for the full list.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx init Populates default ctx permissions /ctx-drift Detects missing or stale permission entries /ctx-sanitize-permissions Audits for dangerous patterns (security-focused)","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#recommended-defaults","level":2,"title":"Recommended Defaults","text":"

    After running ctx init, your settings.local.json will have the ctx defaults pre-populated. Here is an opinionated safe starting point for a Go project using ctx:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(/tmp/ctx-*:*)\",\n      \"Bash(CGO_ENABLED=0 go build:*)\",\n      \"Bash(CGO_ENABLED=0 go test:*)\",\n      \"Bash(ctx:*)\",\n      \"Bash(git add:*)\",\n      \"Bash(git branch:*)\",\n      \"Bash(git check-ignore:*)\",\n      \"Bash(git checkout:*)\",\n      \"Bash(git commit:*)\",\n      \"Bash(git diff:*)\",\n      \"Bash(git log:*)\",\n      \"Bash(git remote:*)\",\n      \"Bash(git restore:*)\",\n      \"Bash(git show:*)\",\n      \"Bash(git stash:*)\",\n      \"Bash(git status:*)\",\n      \"Bash(git tag:*)\",\n      \"Bash(go build:*)\",\n      \"Bash(go fmt:*)\",\n      \"Bash(go test:*)\",\n      \"Bash(go vet:*)\",\n      \"Bash(golangci-lint run:*)\",\n      \"Bash(grep:*)\",\n      \"Bash(ls:*)\",\n      \"Bash(make:*)\",\n      \"Skill(ctx-add-convention)\",\n      \"Skill(ctx-add-decision)\",\n      \"Skill(ctx-add-learning)\",\n      \"Skill(ctx-add-task)\",\n      \"Skill(ctx-agent)\",\n      \"Skill(ctx-archive)\",\n      \"Skill(ctx-blog)\",\n      \"Skill(ctx-blog-changelog)\",\n      \"Skill(absorb)\",\n      \"Skill(ctx-commit)\",\n      \"Skill(ctx-drift)\",\n      \"Skill(ctx-implement)\",\n      \"Skill(ctx-journal-enrich)\",\n      \"Skill(ctx-journal-enrich-all)\",\n      \"Skill(ctx-journal-normalize)\",\n      \"Skill(ctx-loop)\",\n      \"Skill(ctx-next)\",\n      \"Skill(ctx-pad)\",\n      \"Skill(ctx-prompt-audit)\",\n      \"Skill(ctx-recall)\",\n      \"Skill(ctx-reflect)\",\n      \"Skill(ctx-remember)\",\n      \"Skill(ctx-status)\",\n      \"Skill(ctx-worktree)\",\n      \"WebSearch\"\n    ],\n    \"deny\": [\n      \"Bash(sudo *)\",\n      \"Bash(git push *)\",\n      \"Bash(git push)\",\n      \"Bash(rm -rf /*)\",\n      \"Bash(rm -rf ~*)\",\n      \"Bash(curl *)\",\n      \"Bash(wget *)\",\n      \"Bash(chmod 777 *)\",\n      \"Read(**/.env)\",\n      \"Read(**/.env.*)\",\n      \"Read(**/*credentials*)\",\n      \"Read(**/*secret*)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.key)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.*)\"\n    ]\n  }\n}\n

    This Is a Starting Point, Not a Mandate

    Your project may need more or fewer entries.

    The goal is intentional permissions: Every entry should be there because you decided it belongs, not because you clicked \"Allow\" once during debugging.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#design-principles","level":3,"title":"Design Principles","text":"

    Use wildcards for trusted binaries: If you trust the binary (your own project's CLI, make, go), a single wildcard like Bash(ctx:*) beats twenty subcommand entries. It reduces noise and means new subcommands work without re-prompting.

    Keep git commands granular: Unlike ctx or make, git has both safe commands (git log, git status) and destructive ones (git reset --hard, git clean -f). Listing safe commands individually prevents accidentally pre-approving dangerous ones.

    Pre-approve all ctx- skills: Skills shipped with ctx (Skill(ctx-*)) are safe to pre-approve. They are part of your project and you control their content. This prevents the agent from prompting on every skill invocation.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#default-deny-rules","level":3,"title":"Default Deny Rules","text":"

    ctx init automatically populates permissions.deny with rules that block dangerous operations. Deny rules are evaluated before allow rules: A denied pattern always prompts the user, even if it also matches an allow entry.

    The defaults block:

    Pattern Why Bash(sudo *) Cannot enter password; will hang Bash(git push *) Must be explicit user action Bash(rm -rf /*) etc. Recursive delete of system/home directories Bash(curl *) / wget Arbitrary network requests Bash(chmod 777 *) World-writable permissions Read/Edit(**/.env*) Secrets and credentials Read(**/*.pem, *.key) Private keys

    Read/Edit Deny Rules

    Read() and Edit() deny rules have known upstream enforcement issues (claude-code#6631,#24846).

    They are included as defense-in-depth and intent documentation.

    Blocked by default deny rules: no action needed, ctx init handles these:

    Pattern Risk Bash(git push:*) Must be explicit user action Bash(sudo:*) Privilege escalation Bash(rm -rf:*) Recursive delete with no confirmation Bash(curl:*) / Bash(wget:*) Arbitrary network requests

    Requires manual discipline: Never add these to allow:

    Pattern Risk Bash(git reset:*) Can discard uncommitted work Bash(git clean:*) Deletes untracked files Skill(ctx-sanitize-permissions) Edits this file: self-modification vector Skill(release) Runs the release pipeline: high impact","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#hooks-regex-safety-net","level":2,"title":"Hooks: Regex Safety Net","text":"

    Deny rules handle prefix-based blocking natively. Hooks complement them by catching patterns that require regex matching: Things deny rules can't express.

    The ctx plugin ships these blocking hooks:

    Hook What it blocks ctx system block-non-path-ctx Running ctx from wrong path

    Project-local hooks (not part of the plugin) catch regex edge cases:

    Hook What it blocks block-dangerous-commands.sh Mid-command sudo/git push (after &&), copies to bin dirs, absolute-path ctx

    Pre-Approved + Hook-Blocked = Silent Block

    If you pre-approve a command that a hook blocks, the user never sees the confirmation dialog. The agent gets a block response and must handle it, which is confusing.

    It's better not to pre-approve commands that hooks are designed to intercept.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#the-maintenance-workflow","level":2,"title":"The Maintenance Workflow","text":"","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#after-busy-sessions","level":3,"title":"After busy sessions","text":"

    Permissions accumulate fastest during debugging and exploration sessions. After a session where you clicked \"Allow\" many times:

    1. Open .claude/settings.local.json in your editor;
    2. Look for entries at the bottom of the allowlist (new entries append there);
    3. Delete anything that looks session-specific:
      • Exact commands with hardcoded paths,
      • Commands with literal string arguments,
      • Entries that duplicate an existing wildcard.

    See hack/runbooks/sanitize-permissions.md for a step-by-step runbook.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#periodically","level":3,"title":"Periodically","text":"

    Run /ctx-drift to catch permission drift:

    • Missing Bash(ctx:*) wildcard;
    • Missing Skill(ctx-*) entries for installed skills;
    • Stale Skill(ctx-*) entries for removed skills;
    • Granular Bash(ctx <subcommand>:*) entries that should be consolidated.

    Run /ctx-sanitize-permissions to catch security issues:

    • Hook bypass patterns
    • Destructive commands
    • Overly broad permissions
    • Injection vectors
    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#when-adding-new-skills","level":3,"title":"When adding new skills","text":"

    If you create a custom ctx-* skill, add its Skill() entry to the allowlist manually.

    ctx init only populates the default permissions: It won't pick up custom skills.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#golden-image-snapshots","level":3,"title":"Golden image snapshots","text":"

    If manual cleanup is too tedious, use a golden image to automate it:

    Snapshot a curated permission set, then restore at session start to automatically drop session-accumulated permissions. See the Permission Snapshots recipe for the full workflow.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#adapting-for-other-languages","level":2,"title":"Adapting for Other Languages","text":"

    The recommended defaults above are Go-specific. For other stacks, swap the build/test tooling:

    Node.js / TypeScript:

    \"Bash(npm run:*)\",\n\"Bash(npm test:*)\",\n\"Bash(npx:*)\",\n\"Bash(node:*)\"\n

    Python:

    \"Bash(pytest:*)\",\n\"Bash(python:*)\",\n\"Bash(pip show:*)\",\n\"Bash(ruff:*)\"\n

    Rust:

    \"Bash(cargo build:*)\",\n\"Bash(cargo test:*)\",\n\"Bash(cargo clippy:*)\",\n\"Bash(cargo fmt:*)\"\n

    The ctx, git, and skill entries remain the same across all stacks.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#next-up","level":2,"title":"Next Up","text":"

    Permission Snapshots →: Save and restore permission baselines for reproducible setups.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#see-also","level":2,"title":"See Also","text":"
    • Setting Up ctx Across AI Tools: full setup recipe including settings.local.json creation
    • Context Health: keeping .context/ files accurate
    • hack/runbooks/sanitize-permissions.md: manual cleanup runbook
    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/context-health/","level":1,"title":"Detecting and Fixing Drift","text":"","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#the-problem","level":2,"title":"The Problem","text":"

    ctx files drift: you rename a package, delete a module, or finish a sprint, and suddenly ARCHITECTURE.md references paths that no longer exist, TASKS.md is 80 percent completed checkboxes, and CONVENTIONS.md describes patterns you stopped using two months ago.

    Stale context is worse than no context:

    An AI tool that trusts outdated references will hallucinate confidently.

    This recipe shows how to detect drift, fix it, and keep your .context/ directory lean and accurate.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#tldr","level":2,"title":"TL;DR","text":"
    ctx drift                      # detect problems\nctx drift --fix                # auto-fix the easy ones\nctx sync --dry-run && ctx sync # reconcile after refactors\nctx compact --archive          # archive old completed tasks\nctx status                     # verify\n

    Or just ask your agent: \"Is our context clean?\"

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx drift Command Detect stale paths, missing files, violations ctx drift --fix Command Auto-fix simple issues ctx sync Command Reconcile context with codebase structure ctx compact Command Archive completed tasks, clean up empty sections ctx status Command Quick health overview /ctx-drift Skill Structural plus semantic drift detection /ctx-architecture Skill Refresh ARCHITECTURE.md from actual codebase /ctx-status Skill In-session context summary /ctx-prompt-audit Skill Audit prompt quality and token efficiency","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#the-workflow","level":2,"title":"The Workflow","text":"

    The best way to maintain context health is conversational: Ask your agent, guide it, and let it detect problems, explain them, and fix them with your approval. CLI commands exist for CI pipelines, scripting, and fine-grained control.

    For day-to-day maintenance, talk to your agent.

    Your Questions Reinforce the Pattern

    Asking \"is our context clean?\" does two things:

    • It triggers a drift check right now
    • It reinforces the habit

    This is reinforcement, not enforcement.

    Do not wait for the agent to be proactive on its own:

    Guide your agent, especially in early sessions.

    Over time, you will ask less and the agent will start offering more.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-1-ask-your-agent","level":3,"title":"Step 1: Ask Your Agent","text":"

    The simplest way to check context health:

    Is our context clean?\nAnything stale?\nHow healthy are our context files?\n

    Or invoke the skill directly:

    /ctx-drift\n

    The agent performs two layers of analysis:

    Layer 1, structural checks (via ctx drift): Dead paths, missing files, completed task counts, constitution violations. Fast and programmatic.

    Layer 2, semantic analysis (agent-driven): Does CONVENTIONS.md describe patterns the code no longer follows? Does DECISIONS.md contain entries whose rationale no longer applies? Are there learnings about bugs that are now fixed? This is where the agent adds value the CLI cannot: It reads both context files and source code and compares them.

    The agent reports both layers together, explains each finding in plain language, and offers to fix what it can.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-2-maintenance-at-session-start","level":3,"title":"Step 2: Maintenance at Session Start","text":"

    You do not need to ask explicitly.

    Using Claude Code

    ctx ships with Claude Code hooks that remind the agent at the right time to take initiative.

    Checking context health at the session start, offering to persist learnings before you quit, and flagging drift when it matters. The agent stays proactive without you having to prompt it:

    Agent: Good morning. I've loaded the context files. A few things\n       before we start:\n\n       - ARCHITECTURE.md references `pkg/auth/` which is now empty\n       - DECISIONS.md hasn't been updated in 40 days\n       - There are 18 completed tasks ready for archival\n\n       Want me to run a quick maintenance pass, or should we jump\n       straight into today's work?\n

    ☝️️ this is what persistent, initiative-driven sessions feel like when context is treated as a system instead of a prompt.

    If the agent does not offer this on its own, a gentle nudge is enough:

    Anything stale before we start?\nHow's the context looking?\n

    This turns maintenance from a scheduled chore into a conversation that happens when it matters.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-3-real-time-detection-during-work","level":3,"title":"Step 3: Real-Time Detection During Work","text":"

    Agents can notice drift while working: When a mismatch is directly in the path of their current task. If an agent reads ARCHITECTURE.md to find where to add a handler and internal/handlers/ doesn't exist, it will notice because the stale reference blocks its work:

    Agent: ARCHITECTURE.md references `internal/handlers/` but that directory\n       doesn't exist. I'll look at the actual source tree to find where\n       handlers live now.\n

    This happens reliably when the drift intersects the task. What is less reliable is the agent generalizing from one mismatch to \"there might be more stale references; let me run drift detection\" That leap requires the agent to know /ctx-drift exists and to decide the current task should pause for maintenance.

    If you want that behavior, reinforce it:

    Good catch. Yes, run /ctx-drift and clean up any other stale references.\n

    Over time, agents that have seen this pattern will start offering proactively. But do not expect it from a cold start.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-4-archival-and-cleanup","level":3,"title":"Step 4: Archival and Cleanup","text":"

    ctx drift detects when TASKS.md has more than 10 completed items and flags it as a staleness warning. Running ctx drift --fix archives completed tasks automatically.

    You can also run /ctx-archive to compact on demand.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#knowledge-health-flow","level":3,"title":"Knowledge Health Flow","text":"

    Over time, LEARNINGS.md and DECISIONS.md accumulate entries that overlap or partially repeat each other. The check-persistence hook detects when entry counts exceed a configurable threshold and surfaces a nudge:

    \"LEARNINGS.md has 25+ entries. Consider running /ctx-consolidate to merge overlapping items.\"

    The consolidation workflow:

    1. Review: /ctx-consolidate groups entries by keyword similarity and presents candidate merges for your approval.
    2. Merge: Approved groups are combined into single entries that preserve the key information from each original.
    3. Archive: Originals move to .context/archive/, not deleted -- the full history is preserved in git and the archive directory.
    4. Verify: Run ctx drift after consolidation to confirm no cross-references were broken by the merge.

    This replaces ad-hoc cleanup with a repeatable, nudge-driven cycle: detect accumulation, review candidates, merge with approval, archive originals.

    See also: Knowledge Capture for the recording workflow that feeds into this maintenance cycle.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-doctor-the-superset-check","level":2,"title":"ctx doctor: The Superset Check","text":"

    ctx doctor combines drift detection with hook auditing, configuration checks, event logging status, and token size reporting in a single command. If you want one command that covers structural health, hooks, and state:

    ctx doctor          # everything in one pass\nctx doctor --json   # machine-readable for scripting\n

    Use /ctx-doctor Too

    For agent-driven diagnosis that adds semantic analysis on top of the structural checks, use /ctx-doctor.

    See the Troubleshooting recipe for the full workflow.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#cli-reference","level":2,"title":"CLI Reference","text":"

    The conversational approach above uses CLI commands under the hood. When you need direct control, use the commands directly.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-drift","level":3,"title":"ctx drift","text":"

    Scan context files for structural problems:

    ctx drift\n

    Sample output:

    Drift Report\n============\n\nWarnings (3):\n  ARCHITECTURE.md:14  path \"internal/api/router.go\" does not exist\n  ARCHITECTURE.md:28  path \"pkg/auth/\" directory is empty\n  CONVENTIONS.md:9    path \"internal/handlers/\" not found\n\nViolations (1):\n  TASKS.md            31 completed tasks (recommend archival)\n\nStaleness:\n  DECISIONS.md        last modified 45 days ago\n  LEARNINGS.md        last modified 32 days ago\n\nExit code: 1 (warnings found)\n
    Level Meaning Action Warning Stale path references, missing files Fix or remove Violation Constitution rule heuristic failures, heavy clutter Fix soon Staleness Files not updated recently Review content

    Exit codes: 0 equals clean, 1 equals warnings, 3 equals violations.

    For CI integration:

    ctx drift --json | jq '.warnings | length'\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-drift-fix","level":3,"title":"ctx drift --fix","text":"

    Auto-fix mechanical issues:

    ctx drift --fix\n

    This handles removing dead path references, updating unambiguous renames, clearing empty sections. Issues requiring judgment are flagged but left for you.

    Run ctx drift again afterward to confirm what remains.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-sync","level":3,"title":"ctx sync","text":"

    After a refactor, reconcile context with the actual codebase structure:

    ctx sync --dry-run   # preview first\nctx sync             # apply\n

    ctx sync scans for structural changes, compares with ARCHITECTURE.md, checks for new dependencies worth documenting, and identifies context referring to code that no longer exists.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-compact","level":3,"title":"ctx compact","text":"

    Consolidate completed tasks and clean up empty sections:

    ctx compact            # move completed tasks to Completed section,\n                       # remove empty sections\nctx compact --archive  # also archive old tasks to .context/archive/\n
    • Tasks: moves completed items (with all subtasks done) into the Completed section of TASKS.md
    • All files: removes empty sections left behind
    • With --archive: writes tasks older than 7 days to .context/archive/tasks-YYYY-MM-DD.md

    Without --archive, nothing is deleted: Tasks are reorganized in place.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-status","level":3,"title":"ctx status","text":"

    Quick health overview:

    ctx status --verbose\n

    Shows file counts, token estimates, modification times, and drift warnings in a single glance.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-prompt-audit","level":3,"title":"/ctx-prompt-audit","text":"

    Checks whether your context files are readable, compact, and token-efficient for the model.

    /ctx-prompt-audit\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Conversational approach (recommended):

    Is our context clean?  -> agent runs structural plus semantic checks\nFix what you can       -> agent auto-fixes and proposes edits\nArchive the done tasks -> agent runs ctx compact --archive\nHow's token usage?     -> agent checks ctx status\n

    CLI approach (for CI, scripts, or direct control):

    ctx drift                      # 1. Detect problems\nctx drift --fix                # 2. Auto-fix the easy ones\nctx sync --dry-run && ctx sync # 3. Reconcile after refactors\nctx compact --archive          # 4. Archive old completed tasks\nctx status                     # 5. Verify\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#tips","level":2,"title":"Tips","text":"

    Agents cross-reference context files with source code during normal work. When drift intersects their current task, they will notice: a renamed package, a deleted directory, a path that doesn't resolve. But they rarely generalize from one mismatch to a full audit on their own. Reinforce the pattern: when an agent mentions a stale reference, ask it to run /ctx-drift. Over time, it starts offering.

    When an agent says \"this reference looks stale,\" it is usually right.

    Semantic drift is more damaging than structural drift: ctx drift catches dead paths. But CONVENTIONS.md describing a pattern your code stopped following three weeks ago is worse. When you ask \"is our context clean?\", the agent can do both checks.

    Use ctx status as a quick check: It shows file counts, token estimates, and drift warnings in a single glance. Good for a fast \"is everything ok?\" before diving into work.

    Drift detection in CI: add ctx drift --json to your CI pipeline and fail on exit code 3 (violations). This catches constitution-level problems before they reach upstream.

    Do not over-compact: Completed tasks have historical value. The --archive flag preserves them in .context/archive/ so you can search past work without cluttering active context.

    Sync is cautious by default: Use --dry-run after large refactors, then apply.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#next-up","level":2,"title":"Next Up","text":"

    Claude Code Permission Hygiene →: Recommended permission defaults and maintenance workflow for Claude Code.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#see-also","level":2,"title":"See Also","text":"
    • Troubleshooting: full diagnostic workflow using ctx doctor, event logs, and /ctx-doctor
    • Tracking Work Across Sessions: task lifecycle and archival
    • Persisting Decisions, Learnings, and Conventions: keeping knowledge files current
    • The Complete Session: where maintenance fits in the daily workflow
    • CLI Reference: full flag documentation for all commands
    • Context Files: structure and purpose of each .context/ file
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/customizing-hook-messages/","level":1,"title":"Customizing Hook Messages","text":"","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#the-problem","level":2,"title":"The Problem","text":"

    ctx hooks speak ctx's language, not your project's. The QA gate says \"lint the ENTIRE project\" and \"make build,\" but your Python project uses pytest and ruff. The post-commit nudge suggests running lints, but your project uses npm test. You could remove the hook entirely, but then you lose the logic (counting, state tracking, adaptive frequency) just to change the words.

    How do you customize what hooks say without removing what they do?

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#tldr","level":2,"title":"TL;DR","text":"
    ctx system message list                     # see all hooks and their messages\nctx system message show qa-reminder gate    # view the current template\nctx system message edit qa-reminder gate    # copy default to .context/ for editing\nctx system message reset qa-reminder gate   # revert to embedded default\n
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#commands-used","level":2,"title":"Commands Used","text":"Tool Type Purpose ctx system message list CLI command Show all hook messages with category and override status ctx system message show CLI command Print the effective message template ctx system message edit CLI command Copy embedded default to .context/ for editing ctx system message reset CLI command Delete user override, revert to default","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#how-it-works","level":2,"title":"How It Works","text":"

    Hook messages use a 3-tier fallback:

    1. User override: .context/hooks/messages/{hook}/{variant}.txt
    2. Embedded default: compiled into the ctx binary
    3. Hardcoded fallback: belt-and-suspenders safety net

    The hook logic (when to fire, counting, state tracking, cooldowns) is unchanged. Only the content (what text gets emitted) comes from the template. You customize what the hook says without touching how it decides to speak.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#finding-the-original-templates","level":3,"title":"Finding the Original Templates","text":"

    The default templates live in the ctx source tree at:

    internal/assets/hooks/messages/{hook}/{variant}.txt\n

    You can also browse them on GitHub: internal/assets/hooks/messages/

    Or use ctx system message show to print any template without digging through source code:

    ctx system message show qa-reminder gate        # QA gate instructions\nctx system message show check-persistence nudge  # persistence nudge\nctx system message show post-commit nudge        # post-commit reminder\n

    The show output includes the template source and available variables -- everything you need to write a replacement.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#template-variables","level":3,"title":"Template Variables","text":"

    Some messages use Go text/template variables for dynamic content:

    No context files updated in {{.PromptsSinceNudge}}+ prompts.\nHave you discovered learnings, made decisions,\nestablished conventions, or completed tasks\nworth persisting?\n

    The show and edit commands list available variables for each message. When writing a replacement, keep the same {{.VariableName}} placeholders to preserve dynamic content. Variables that you omit render as <no value>: no error, but the output may look odd.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#intentional-silence","level":3,"title":"Intentional Silence","text":"

    An empty template file (0 bytes or whitespace-only) means \"don't emit a message\". The hook still runs its logic but produces no output. This lets you silence specific messages without removing the hook from hooks.json.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-python-project-qa-gate","level":2,"title":"Example: Python Project QA Gate","text":"

    The default QA gate says \"lint the ENTIRE project\" and references make lint. For a Python project, you want pytest and ruff:

    # See the current default\nctx system message show qa-reminder gate\n\n# Copy it to .context/ for editing\nctx system message edit qa-reminder gate\n\n# Edit the override\n

    Replace the content in .context/hooks/messages/qa-reminder/gate.txt:

    HARD GATE! DO NOT COMMIT without completing ALL of these steps first:\n(1) Run the full test suite: pytest -x\n(2) Run the linter: ruff check .\n(3) Verify a clean working tree\nRun tests and linter BEFORE every git commit, no exceptions.\n

    The hook still fires on every Edit call. The logic is identical. Only the instructions changed.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-silencing-ceremony-nudges","level":2,"title":"Example: Silencing Ceremony Nudges","text":"

    The ceremony check nudges you to use /ctx-remember and /ctx-wrap-up. If your team has a different workflow and finds these noisy:

    ctx system message edit check-ceremonies both\nctx system message edit check-ceremonies remember\nctx system message edit check-ceremonies wrapup\n

    Then empty each file:

    echo -n \"\" > .context/hooks/messages/check-ceremonies/both.txt\necho -n \"\" > .context/hooks/messages/check-ceremonies/remember.txt\necho -n \"\" > .context/hooks/messages/check-ceremonies/wrapup.txt\n

    The hooks still track ceremony usage internally, but they no longer emit any visible output.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-javascript-project-post-commit","level":2,"title":"Example: JavaScript Project Post-Commit","text":"

    The default post-commit nudge mentions generic \"lints and tests.\" For a JavaScript project:

    ctx system message edit post-commit nudge\n

    Replace with:

    Commit succeeded. 1. Offer context capture to the user: Decision (design\nchoice?), Learning (gotcha?), or Neither. 2. Ask the user: \"Want me to\nrun npm test and eslint before you push?\" Do NOT push. The user pushes\nmanually.\n
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#the-two-categories","level":2,"title":"The Two Categories","text":"

    Not all messages are equal. The list command shows each message's category:

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#customizable-17-messages","level":3,"title":"Customizable (17 messages)","text":"

    Messages that are opinions: project-specific wording that benefits from customization. These are the primary targets for override.

    Hook Variant Description check-backup-age warning Backup staleness warning check-freshness stale Technology constant freshness warning check-ceremonies both Both ceremonies missing check-ceremonies remember Start-of-session ceremony check-ceremonies wrapup End-of-session ceremony check-context-size checkpoint Context capacity warning check-context-size oversize Injection oversize nudge check-context-size window Context window usage warning (>80%) check-journal both Unexported sessions + unenriched entries check-journal unenriched Unenriched journal entries check-journal unexported Unexported sessions check-knowledge warning Knowledge file growth check-map-staleness stale Architecture map staleness check-persistence nudge Context persistence nudge post-commit nudge Post-commit context capture qa-reminder gate Pre-commit QA gate","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#ctx-specific-10-messages","level":3,"title":"ctx-specific (10 messages)","text":"

    Messages specific to ctx's own development workflow. You can customize them, but edit will warn you first.

    Hook Variant Description block-dangerous-commands cp-to-bin Block copy to bin dirs block-dangerous-commands install-to-local-bin Block copy to ~/.local/bin block-dangerous-commands mid-git-push Block git push block-dangerous-commands mid-sudo Block sudo block-non-path-ctx absolute-path Block absolute path invocation block-non-path-ctx dot-slash Block ./ctx invocation block-non-path-ctx go-run Block go run invocation check-reminders reminders Pending reminders relay check-resources alert Resource pressure alert check-version key-rotation Key rotation nudge check-version mismatch Version mismatch","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#template-variables-reference","level":2,"title":"Template Variables Reference","text":"Hook Variant Variables check-backup-age warning {{.Warnings}} check-freshness stale {{.StaleFiles}} check-context-size checkpoint (none) check-context-size oversize {{.TokenCount}} check-context-size window {{.TokenCount}}, {{.Percentage}} check-ceremonies both, remember, wrapup (none) check-journal both {{.UnexportedCount}}, {{.UnenrichedCount}} check-journal unenriched {{.UnenrichedCount}} check-journal unexported {{.UnexportedCount}} check-knowledge warning {{.FileWarnings}} check-map-staleness stale {{.LastRefreshDate}}, {{.ModuleCount}} check-persistence nudge {{.PromptsSinceNudge}} check-reminders reminders {{.ReminderList}} check-resources alert {{.AlertMessages}} check-version key-rotation {{.KeyAgeDays}} check-version mismatch {{.BinaryVersion}}, {{.PluginVersion}} post-commit nudge (none) qa-reminder gate (none) block-dangerous-commands all variants (none) block-non-path-ctx all variants (none)

    Templates that reference undefined variables render <no value>: no error, graceful degradation.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#tips","level":2,"title":"Tips","text":"
    • Override files are version-controlled: they live in .context/ alongside your other context files. Team members get the same customized messages.
    • Start with show: always check the current default before editing. The embedded template is the baseline your override replaces.
    • Use reset to undo: if a customization causes confusion, reset reverts to the embedded default instantly.
    • Empty file = silence: you don't need to delete the hook. An empty override file silences the message while preserving the hook's logic.
    • JSON output for scripting: ctx system message list --json returns structured data for automation.
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#see-also","level":2,"title":"See Also","text":"
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Auditing System Hooks: verifying hooks are running and auditing their output
    • Configuration: project-level settings via .ctxrc
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/dependency-graph/","level":1,"title":"Generating Dependency Graphs","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#why-dependency-graphs","level":2,"title":"Why Dependency Graphs?","text":"

    Understanding how packages relate to each other is the first step in onboarding, refactoring, and architecture review. ctx dep generates dependency graphs from source code so you can see the structure at a glance instead of tracing imports by hand.

    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#quick-start","level":2,"title":"Quick Start","text":"
    # Auto-detect ecosystem and output Mermaid (default)\nctx dep\n\n# Table format for a quick terminal overview\nctx dep --format table\n\n# JSON for programmatic consumption\nctx dep --format json\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#ecosystem-detection","level":2,"title":"Ecosystem Detection","text":"

    ctx dep looks for manifest files in this order:

    1. Go: go.mod
    2. Node.js: package.json
    3. Python: pyproject.toml, setup.py, requirements.txt
    4. Rust: Cargo.toml

    First match wins. To override detection, use --type:

    # Force Python even if go.mod exists\nctx dep --type python\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#output-formats","level":2,"title":"Output Formats","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#mermaid-default","level":3,"title":"Mermaid (default)","text":"

    Produces a Mermaid graph definition you can paste into GitHub PRs, Obsidian notes, or any Mermaid-compatible renderer.

    ctx dep --format mermaid\n
    graph TD\n    internal/cli --> internal/config\n    internal/cli --> internal/memory\n    internal/config --> internal/entry
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#table","level":3,"title":"Table","text":"

    Flat two-column view for quick terminal scanning.

    ctx dep --format table\n
    PACKAGE                  DEPENDS ON\ninternal/cli             internal/config, internal/memory\ninternal/config          internal/entry\ninternal/memory          internal/index\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#json","level":3,"title":"JSON","text":"

    Machine-readable output for scripts and pipelines.

    ctx dep --format json | jq '.nodes | length'\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#including-external-dependencies","level":2,"title":"Including External Dependencies","text":"

    By default, only internal (first-party) dependencies are shown. Add --external to include third-party packages:

    ctx dep --external\nctx dep --external --format table\n

    This is useful when auditing transitive dependencies or checking which packages pull in heavy external libraries.

    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#when-to-use-it","level":2,"title":"When to Use It","text":"
    • Onboarding. Generate a Mermaid graph and drop it into the project wiki. New contributors see the architecture before reading code.
    • Refactoring. Before moving packages, check what depends on them. Combine with ctx drift to find stale references after the move.
    • Architecture review. Table format gives a quick overview; Mermaid format goes into design docs and PRs.
    • Pre-commit. Run in CI to detect unexpected new dependencies between packages.
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#combining-with-other-commands","level":2,"title":"Combining with Other Commands","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#refactoring-with-ctx-drift","level":3,"title":"Refactoring with ctx drift","text":"
    # See the dependency structure before refactoring\nctx dep --format table\n\n# After moving packages, check for broken references\nctx drift\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#feeding-architecture-maps","level":3,"title":"Feeding architecture maps","text":"

    Use JSON output as input for context files or architecture documentation:

    # Generate a dependency snapshot for the context directory\nctx dep --format json > .context/deps.json\n\n# Or pipe into other tools\nctx dep --format mermaid >> docs/architecture.md\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#monorepos-and-multi-ecosystem-projects","level":2,"title":"Monorepos and Multi-Ecosystem Projects","text":"

    In a monorepo with multiple ecosystems, ctx dep picks the first manifest it finds (Go beats Node.js beats Python beats Rust). Use --type to target a specific ecosystem:

    # In a repo with both go.mod and package.json\nctx dep --type node\nctx dep --type go\n

    For separate subdirectories, run from each root:

    cd services/api && ctx dep --format table\ncd frontend && ctx dep --type node --format mermaid\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#tips","level":2,"title":"Tips","text":"
    • Start with table format. It is the fastest way to get a mental model of the dependency structure. Switch to Mermaid when you need a visual for documentation or a PR.
    • Pipe JSON to jq. Filter for specific packages, count edges, or extract subgraphs programmatically.
    • Skip --external unless you need it. Internal-only graphs are cleaner and load faster. Add external deps when you are specifically auditing third-party usage.
    • Force --type in CI. Auto-detection is convenient locally, but explicit types prevent surprises when the repo structure changes.
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/design-before-coding/","level":1,"title":"Design Before Coding","text":"","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#the-problem","level":2,"title":"The Problem","text":"

    You start coding a feature. Halfway through, you realize the approach doesn't handle a key edge case. You refactor. Then you discover the CLI interface doesn't fit the existing patterns. More refactoring.

    The design work happened during implementation, mixed in with debugging and trial-and-error. The result works, but the spec was never written down, the trade-offs were never recorded, and the next session has no idea why things are shaped this way.

    How do you front-load design so the implementation is straightforward?

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-brainstorm          # explore the design space\n/ctx-spec                # write the spec document\n/ctx-add-task            # break it into tasks\n/ctx-implement           # execute step-by-step\n

    Four skills, used in sequence. Each produces an artifact that feeds the next.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-brainstorm Skill Structured design dialogue: explore approaches /ctx-spec Skill Scaffold and fill out a spec from the template /ctx-add-task Skill Add implementation tasks to TASKS.md /ctx-implement Skill Execute a plan step-by-step with verification /ctx-add-decision Skill Record design choices made during brainstorming","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-1-brainstorm-the-design","level":3,"title":"Step 1: Brainstorm the Design","text":"

    Start with /ctx-brainstorm when you have a rough idea but haven't committed to an approach. The skill follows a gated process:

    1. Understand context: what exists today, what's the gap
    2. Clarify the idea: one question at a time, not a wall of questions
    3. Surface non-functional requirements: performance, security, compatibility
    4. Lock understanding: confirm before exploring solutions
    5. Explore 2-3 approaches: with trade-offs for each
    6. Stress-test: poke holes in the chosen approach
    7. Present the design: detailed enough to implement from
    You: \"I want to add RSS feed generation to the blog.\"\n\nAgent: \"Before we design, let me understand: is this for the journal\n  site, the docs site, or both?\"\n\nYou: \"Journal site only.\"\n\nAgent: [asks about update frequency, content scope, existing infra...]\n       [presents 3 approaches with trade-offs]\n\nYou: \"Option 2 - generate at build time.\"\n\nAgent: \"Let me stress-test that. What happens when...\"\n       [probes edge cases]\n       \"Design looks solid. Want me to record the approach as a\n       decision and write a spec?\"\n

    The brainstorm produces a validated design in conversation. It doesn't produce a file - that's what the spec is for.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-2-write-the-spec","level":3,"title":"Step 2: Write the Spec","text":"

    Once the design is clear, use /ctx-spec to produce the written artifact. The skill reads the project's spec template (specs/tpl/spec-template.md) and walks through each section:

    You: /ctx-spec (rss feed generation)\n\nAgent: \"Creating specs/rss-feed.md from template.\"\n\n       \"Problem: What user-visible problem does this solve? Why now?\"\n\nYou: \"Users can't subscribe to blog updates. They have to check\n      the site manually.\"\n\nAgent: [writes the Problem section, moves to Approach]\n\n       \"Approach: High-level, how does this work?\"\n\nYou: \"Generate feed.xml during ctx journal site. Atom format.\"\n\nAgent: [writes Approach, moves to Happy Path, then Edge Cases...]\n

    The skill spends extra time on Edge Cases and Error Handling: These are where specs earn their value. The skill pushes for at least three edge cases and won't accept \"none\" without a challenge.

    Sections that don't apply can be skipped. The result is a complete spec at specs/{feature-name}.md.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-3-break-into-tasks","level":3,"title":"Step 3: Break Into Tasks","text":"

    After the spec is written, the skill offers to create tasks:

    Agent: \"Spec written to specs/rss-feed.md. Want me to break this\n  into tasks in TASKS.md?\"\n\nYou: \"Yes.\"\n\nAgent: [creates a Phase section referencing the spec, adds tasks]\n       \"Added Phase 0.8: RSS/Atom Feed Generation with 4 tasks:\n         - [ ] Implement feed.xml generation in ctx journal site\n         - [ ] Add --feed flag and .ctxrc feed config\n         - [ ] Write tests for feed generation\n         - [ ] Add recipe and update docs\"\n

    Each task is independently completable and references the spec via Spec: specs/rss-feed.md in the Phase header.

    You can also invoke /ctx-add-task directly at any point to add individual tasks.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-4-implement-step-by-step","level":3,"title":"Step 4: Implement Step-by-Step","text":"

    Pick up tasks with /ctx-implement. The skill loads the spec, breaks work into atomic steps, and checkpoints after every 3-5 steps with a build and test verification:

    You: /ctx-implement (specs/rss-feed.md)\n\nAgent: \"Loaded spec. Breaking into steps:\n         1. Add FeedEntry type to journal package\n         2. Implement feed.xml template\n         3. Wire into site generation pipeline\n         [builds and tests after step 3]\n         4. Add --feed flag to ctx journal site\n         5. Add .ctxrc feed configuration\n         [builds and tests after step 5]\n         ...\"\n

    If a build or test fails, the agent stops, diagnoses, and fixes before continuing.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#when-to-skip-steps","level":2,"title":"When to Skip Steps","text":"

    Not every feature needs all four steps. Use your judgment:

    Situation Start at Vague idea, multiple valid approaches Step 1: Brainstorm Clear approach, need to document it Step 2: Spec Spec already exists, need to plan work Step 3: Tasks Tasks exist, ready to code Step 4: Implement

    A brainstorm without a spec is fine for small decisions. A spec without a brainstorm is fine when the design is obvious. The full chain is for features complex enough to warrant front-loaded design.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need skill names. Natural language works:

    You say What happens \"Let's think through this feature\" /ctx-brainstorm \"Spec this out\" /ctx-spec \"Write a design doc for...\" /ctx-spec \"Break this into tasks\" /ctx-add-task \"Implement the spec\" /ctx-implement \"Let's design before we build\" Starts at brainstorm","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#tips","level":2,"title":"Tips","text":"
    • Brainstorm first when uncertain. If you can articulate the approach in two sentences, skip to spec. If you can't, brainstorm.
    • Specs prevent scope creep. The Non-Goals section is as important as the approach. Writing down what you won't do keeps implementation focused.
    • Edge cases are the point. A spec that only describes the happy path isn't a spec - it's a wish. The /ctx-spec skill pushes for at least 3 edge cases because that's where designs break.
    • Record decisions during brainstorming. When you choose between approaches, the agent offers to persist the trade-off via /ctx-add-decision. Accept - future sessions need to know why, not just what.
    • Specs are living documents. Update them when implementation reveals new constraints. A spec that diverges from reality is worse than no spec.
    • The spec template is customizable. Edit specs/tpl/spec-template.md to match your project's needs. The /ctx-spec skill reads whatever template it finds there.
    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: /ctx-brainstorm: structured design dialogue
    • Skills Reference: /ctx-spec: spec scaffolding from template
    • Skills Reference: /ctx-implement: step-by-step execution with verification
    • Tracking Work Across Sessions: task lifecycle and archival
    • Importing Claude Code Plans: turning ephemeral plans into permanent specs
    • Persisting Decisions, Learnings, and Conventions: capturing design trade-offs
    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/external-context/","level":1,"title":"Keeping Context in a Separate Repo","text":"","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#the-problem","level":2,"title":"The Problem","text":"

    ctx files contain project-specific decisions, learnings, conventions, and tasks. By default, they live in .context/ inside the project tree, and that works well when the context can be public.

    But sometimes you need the context outside the project:

    • Open-source projects with private context: Your architectural notes, internal task lists, and scratchpad entries shouldn't ship with the public repo.
    • Compliance or IP concerns: Context files reference sensitive design rationale that belongs in a separate access-controlled repository.
    • Personal preference: You want a single context repo that covers multiple projects, or you just prefer keeping notes separate from code.

    ctx supports this through three configuration methods. This recipe shows how to set them up and how to tell your AI assistant where to find the context.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#tldr","level":2,"title":"TL;DR","text":"

    First --allow-outside-cwd in your project:

    mkdir ~/repos/myproject-context && cd ~/repos/myproject-context && git init\ncd ~/repos/myproject\nctx --context-dir ~/repos/myproject-context --allow-outside-cwd init\n

    Then, create a .ctxrc in your project root to specify the new .context folder location:

    context_dir: ~/repos/myproject-context\nallow_outside_cwd: true\n

    All ctx commands now use the external directory automatically.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init CLI command Initialize context directory --context-dir Global flag Point ctx at a non-default directory --allow-outside-cwd Global flag Permit context outside the project root .ctxrc Config file Persist the context directory setting CTX_DIR Env variable Override context directory per-session /ctx-status Skill Verify context is loading correctly","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-1-create-the-private-context-repo","level":3,"title":"Step 1: Create the Private Context Repo","text":"

    Create a separate repository for your context files. This can live anywhere: a private GitHub repo, a shared drive, a sibling directory:

    # Create the context repo\nmkdir ~/repos/myproject-context\ncd ~/repos/myproject-context\ngit init\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-2-initialize-ctx-pointing-at-it","level":3,"title":"Step 2: Initialize ctx Pointing at It","text":"

    From your project root, initialize ctx with --context-dir pointing to the external location. Because the directory is outside your project tree, you also need --allow-outside-cwd:

    cd ~/repos/myproject\nctx --context-dir ~/repos/myproject-context \\\n    --allow-outside-cwd \\\n    init\n

    This creates the full .context/-style file set inside ~/repos/myproject-context/ instead of ~/repos/myproject/.context/.

    Boundary Validation

    ctx validates that the .context directory is within the current working directory.

    If your external directory is truly outside the project root:

    • Either every ctx command needs --allow-outside-cwd,
    • or you can persist the setting in .ctxrc (next step).
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-3-make-it-stick","level":3,"title":"Step 3: Make It Stick","text":"

    Typing --context-dir and --allow-outside-cwd on every command is tedious. Pick one of these methods to make the configuration permanent.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-a-ctxrc-recommended","level":4,"title":"Option A: .ctxrc (Recommended)","text":"

    Create a .ctxrc file in your project root:

    # .ctxrc: committed to the project repo\ncontext_dir: ~/repos/myproject-context\nallow_outside_cwd: true\n

    ctx reads .ctxrc automatically. Every command now uses the external directory without extra flags:

    ctx status          # reads from ~/repos/myproject-context\nctx add learning \"Redis MULTI doesn't roll back on error\"\n

    Commit .ctxrc

    .ctxrc belongs in the project repo. It contains no secrets: It's just a path and a boundary override.

    .ctxrc lets teammates share the same configuration.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-b-ctx_dir-environment-variable","level":4,"title":"Option B: CTX_DIR Environment Variable","text":"

    Good for CI pipelines, temporary overrides, or when you don't want to commit a .ctxrc:

    # In your shell profile (~/.bashrc, ~/.zshrc)\nexport CTX_DIR=~/repos/myproject-context\n

    Or for a single session:

    CTX_DIR=~/repos/myproject-context ctx status\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-c-shell-alias","level":4,"title":"Option C: Shell Alias","text":"

    If you prefer a shell alias over .ctxrc:

    # ~/.bashrc or ~/.zshrc\nalias ctx='ctx --context-dir ~/repos/myproject-context --allow-outside-cwd'\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#priority-order","level":4,"title":"Priority Order","text":"

    When multiple methods are set, ctx resolves the context directory in this order (highest priority first):

    1. --context-dir flag
    2. CTX_DIR environment variable
    3. context_dir in .ctxrc
    4. Default: .context/
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-4-agent-auto-discovery-via-bootstrap","level":3,"title":"Step 4: Agent Auto-Discovery via Bootstrap","text":"

    When context lives outside the project tree, your AI assistant needs to know where to find it. The ctx system bootstrap command resolves the configured context directory and communicates it to the agent automatically:

    $ ctx system bootstrap\nctx bootstrap\n=============\n\ncontext_dir: /home/user/repos/myproject-context\n\nFiles:\n  CONSTITUTION.md, TASKS.md, DECISIONS.md, ...\n

    The CLAUDE.md template generated by ctx init already instructs the agent to run ctx system bootstrap at session start. Because .ctxrc is in the project root, your agent inherits the external path automatically via the ctx system boostrap call instruction.

    Here is the relevant section from CLAUDE.md for reference:

    <!-- CLAUDE.md -->\n1. **Run `ctx system bootstrap`**: CRITICAL, not optional.\n   This tells you where the context directory is. If it fails or returns\n   no context_dir, STOP and warn the user.\n

    Moreover, every nudge (context checkpoint, persistence reminder, etc.) also includes a Context: /home/user/repos/myproject-context footer, so the agent remains anchored to the correct directory even in long sessions.

    If you use CTX_DIR instead of .ctxrc, export it in your shell profile so the hook process inherits it:

    export CTX_DIR=~/repos/myproject-context\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-5-share-with-teammates","level":3,"title":"Step 5: Share with Teammates","text":"

    Teammates clone both repos and set up .ctxrc:

    # Clone the project\ngit clone git@github.com:org/myproject.git\ncd myproject\n\n# Clone the private context repo\ngit clone git@github.com:org/myproject-context.git ~/repos/myproject-context\n

    If .ctxrc is already committed to the project, they're done: ctx commands will find the external context automatically.

    If teammates use different paths, each developer sets their own CTX_DIR:

    export CTX_DIR=~/my-own-path/myproject-context\n

    For encryption key distribution across the team, see the Syncing Scratchpad Notes recipe.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-6-day-to-day-sync","level":3,"title":"Step 6: Day-to-Day Sync","text":"

    The external context repo has its own git history. Treat it like any other repo: Commit and push after sessions:

    cd ~/repos/myproject-context\n\n# After a session\ngit add -A\ngit commit -m \"Session: refactored auth module, added rate-limit learning\"\ngit push\n

    Your AI assistant can do this too. When ending a session:

    You: \"Save what we learned and push the context repo.\"\n\nAgent: [runs ctx add learning, then commits and pushes the context repo]\n

    You can also set up a post-session habit: project code gets committed to the project repo, context gets committed to the context repo.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember the flags; simply ask your assistant:

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#set-up-your-system-using-natural-language","level":3,"title":"Set Up Your System Using Natural Language","text":"
    You: \"Set up ctx to use ~/repos/myproject-context as the context directory.\"\n\nAgent: \"I'll create a .ctxrc in the project root pointing to that path.\n       I'll also update CLAUDE.md so future sessions know where to find\n       context. Want me to initialize the context files there too?\"\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#configure-separate-repo-for-context-folder-using-natural-language","level":3,"title":"Configure Separate Repo for .context Folder Using Natural Language","text":"
    You: \"My context is in a separate repo. Can you load it?\"\n\nAgent: [reads .ctxrc, finds the path, loads context from the external dir]\n       \"Loaded. You have 3 pending tasks, last session was about the auth\n       refactor.\"\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#tips","level":2,"title":"Tips","text":"
    • Start simple. If you don't need external context yet, don't set it up. The default .context/ in-tree is the easiest path. Move to an external repo when you have a concrete reason.
    • One context repo per project. Sharing a single context directory across multiple projects creates confusion. Keep the mapping 1:1.
    • Use .ctxrc over env vars when the path is stable. It's committed, documented, and works for the whole team without per-developer shell setup.
    • Don't forget the boundary flag. The most common error is Error: context directory is outside the project root. Set allow_outside_cwd: true in .ctxrc or pass --allow-outside-cwd.
    • Commit both repos at session boundaries. Context without code history (or code without context history) loses half the value.
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#next-up","level":2,"title":"Next Up","text":"

    The Complete Session →: Walk through a full ctx session from start to finish.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#see-also","level":2,"title":"See Also","text":"
    • Setting Up ctx Across AI Tools: initial setup recipe
    • Syncing Scratchpad Notes Across Machines: distribute encryption keys when context is shared
    • CLI Reference: all global flags including --context-dir and --allow-outside-cwd
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/guide-your-agent/","level":1,"title":"Guide Your Agent","text":"

    Commands vs. Skills

    Commands (ctx status, ctx add task) run in your terminal.

    Skills (/ctx-reflect, /ctx-next) run inside your AI coding assistant.

    Recipes combine both.

    Think of commands as structure and skills as behavior.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#proactive-behavior","level":2,"title":"Proactive Behavior","text":"

    These recipes show explicit commands and skills, but agents trained on the ctx playbook are proactive: They offer to save learnings after debugging, record decisions after trade-offs, create follow-up tasks after completing work, and suggest what to work on next.

    Your questions train the agent. Asking \"what have we learned?\" or \"is our context clean?\" does two things:

    • It triggers the workflow right now,
    • and it reinforces the pattern.

    The more you guide, the more the agent habituates the behavior and begins offering on its own.

    Each recipe includes a Conversational Approach section showing these natural-language patterns.

    Tip

    Don't wait passively for proactive behavior: especially in early sessions.

    Ask, guide, reinforce. Over time, you ask less and the agent offers more.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#next-up","level":2,"title":"Next Up","text":"

    Setup Across AI Tools →: Initialize ctx and configure hooks for Claude Code, Cursor, Aider, Copilot, or Windsurf.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle from start to finish
    • Prompting Guide: general tips for working effectively with AI coding assistants
    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/hook-output-patterns/","level":1,"title":"Hook Output Patterns","text":"","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code hooks can output text, JSON, or nothing at all. But the format of that output determines who sees it and who acts on it.

    Choose the wrong pattern, and your carefully crafted warning gets silently absorbed by the agent, or your agent-directed nudge gets dumped on the user as noise.

    This recipe catalogs the known hook output patterns and explains when to use each one.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#tldr","level":2,"title":"TL;DR","text":"

    Eight patterns from full control to full invisibility:

    • hard gate (exit 2),
    • VERBATIM relay (agent MUST show),
    • agent directive (context injection),
    • and silent side-effect (background work).

    Most hooks belong in the middle.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#the-spectrum","level":2,"title":"The Spectrum","text":"

    These patterns form a spectrum based on who decides what the user sees:

    Pattern Who decides? Hard gate Hook decides (agent can't proceed) VERBATIM relay Hook decides (agent must show) Escalating severity Hook suggests, agent judges urgency Conditional relay Hook sets criteria, agent evaluates Suggested action Hook proposes, agent + user decide Agent directive Agent decides entirely Silent injection Nobody: invisible background context Silent side-effect Nobody: invisible background work

    The spectrum runs from full hook control (hard gate) to full invisibility (silent side effect).

    Most hooks belong somewhere in the middle.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-1-hard-gate","level":2,"title":"Pattern 1: Hard Gate","text":"

    Block the tool call entirely. The agent cannot proceed: it must find another approach or tell the user.

    echo '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH, not ./ctx\"}'\n

    When to use: Enforcing invariants that must never be violated: Constitution rules, security boundaries, destructive command prevention.

    Hook type: PreToolUse only (Claude Code first-class mechanism).

    Examples in ctx:

    • ctx system block-non-path-ctx: Enforces the PATH invocation rule
    • block-git-push.sh: Requires explicit user approval for pushes (project-local)
    • block-dangerous-commands.sh: Prevents sudo, copies to ~/.local/bin (project-local)

    Trade-off: The agent gets a block response with a reason. Good reasons help the agent recover (\"use X instead\"); bad reasons leave it stuck.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-2-verbatim-relay","level":2,"title":"Pattern 2: VERBATIM Relay","text":"

    Force the agent to show this to the user as-is. The explicit instruction overcomes the agent's tendency to silently absorb context.

    echo \"IMPORTANT: Relay this warning to the user VERBATIM before answering their question.\"\necho \"\"\necho \"┌─ Journal Reminder ─────────────────────────────\"\necho \"│ You have 12 sessions not yet exported.\"\necho \"└────────────────────────────────────────────────\"\n

    When to use: Actionable reminders the user needs to see regardless of what they asked: Stale backups, unexported sessions, resource warnings.

    Hook type: UserPromptSubmit (runs before the agent sees the prompt).

    Examples in ctx:

    • ctx system check-journal: Unexported sessions and unenriched entries
    • ctx system check-context-size: Context capacity warning
    • ctx system check-resources: Resource pressure (memory, swap, disk, load): DANGER only
    • ctx system check-freshness: Technology constant staleness warning
    • check-backup-age.sh: Stale backup warning (project-local)

    Trade-off: Noisy if overused. Every VERBATIM relay adds a preamble before the agent's actual answer. Throttle with once-per-day markers or adaptive frequency.

    Key detail: The phrase IMPORTANT: Relay this ... VERBATIM is what makes this work. Without it, agents tend to process the information internally and never surface it. The explicit instruction is the pattern: the box-drawing is just fancy formatting.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-3-agent-directive","level":2,"title":"Pattern 3: Agent Directive","text":"

    Tell the agent to do something, not the user. The agent decides whether and how to involve the user.

    echo \"┌─ Persistence Checkpoint (prompt #25) ───────────\"\necho \"│ No context files updated in 15+ prompts.\"\necho \"│ Have you discovered learnings, decisions,\"\necho \"│ or completed tasks worth persisting?\"\necho \"└──────────────────────────────────────────────────\"\n

    When to use: Behavioral nudges. The hook detects a condition and asks the agent to consider an action. The user may never need to know.

    Hook type: UserPromptSubmit.

    Examples in ctx:

    • ctx system check-persistence: Nudges the agent to persist context

    Trade-off: No guarantee the agent acts. The nudge is one signal among many in the context window. Strong phrasing helps (\"Have you...?\" is better than \"Consider...\"), but ultimately the agent decides.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-4-silent-context-injection","level":2,"title":"Pattern 4: Silent Context Injection","text":"

    Load context with no visible output. The agent gets enriched without either party noticing.

    ctx agent --budget 4000 >/dev/null || true\n

    When to use: Background context loading that should be invisible. The agent benefits from the information, but neither it, nor the user needs to know it happened.

    Hook type: PreToolUse with .* matcher (runs on every tool call).

    Examples in ctx:

    • The ctx agent PreToolUse hook: injects project context silently

    Trade-off: Adds latency to every tool call. Keep the injected content small and fast to generate.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-5-silent-side-effect","level":2,"title":"Pattern 5: Silent Side-Effect","text":"

    Do work, produce no output: Housekeeping that needs no acknowledgment.

    find \"$CTX_TMPDIR\" -type f -mtime +15 -delete\n

    When to use: Cleanup, log rotation, temp file management. Anything where the action is the point and nobody needs to know it happened.

    Hook type: Any hook where output is irrelevant.

    Examples in ctx:

    • Log rotation, marker file cleanup, state directory maintenance

    Trade-off: None, if the action is truly invisible. If it can fail in a way that matters, consider logging.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-6-conditional-relay","level":3,"title":"Pattern 6: Conditional Relay","text":"

    Tell the agent to relay only if a condition holds in context.

    echo \"If the user's question involves modifying .context/ files,\"\necho \"relay this warning VERBATIM:\"\necho \"\"\necho \"┌─ Context Integrity ─────────────────────────────\"\necho \"│ CONSTITUTION.md has not been verified in 7 days.\"\necho \"└────────────────────────────────────────────────\"\necho \"\"\necho \"Otherwise, proceed normally.\"\n

    When to use: Warnings that only matter in certain contexts. Avoids noise when the user is doing unrelated work.

    Trade-off: Depends on the agent's judgment about when the condition holds. More fragile than VERBATIM relay, but less noisy.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-7-suggested-action","level":3,"title":"Pattern 7: Suggested Action","text":"

    Give the agent a specific command to propose to the user.

    echo \"┌─ Stale Dependencies ──────────────────────────\"\necho \"│ go.sum is 30+ days newer than go.mod.\"\necho \"│ Suggested: run \\`go mod tidy\\`\"\necho \"│ Ask the user before proceeding.\"\necho \"└───────────────────────────────────────────────\"\n

    When to use: The hook detects a fixable condition and knows the fix. Goes beyond a nudge: Gives the agent a concrete next step. The agent still asks for permission but knows exactly what to propose.

    Trade-off: The suggestion might be wrong or outdated. The \"ask the user before proceeding\" part is critical.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-8-escalating-severity","level":3,"title":"Pattern 8: Escalating Severity","text":"

    Different urgency tiers with different relay expectations.

    # INFO: agent processes silently, mentions if relevant\necho \"INFO: Last test run was 3 days ago.\"\n\n# WARN: agent should mention to user at next natural pause\necho \"WARN: 12 uncommitted changes across 3 branches.\"\n\n# CRITICAL: agent must relay immediately, before any other work\necho \"CRITICAL: Relay VERBATIM before answering. Disk usage at 95%.\"\n

    When to use: When you have multiple hooks producing output and need to avoid overwhelming the user. INFO gets absorbed, WARN gets mentioned, CRITICAL interrupts.

    Examples in ctx:

    • ctx system check-resources: Uses two tiers (WARNING/DANGER) internally but only fires the VERBATIM relay at DANGER level: WARNING is silent. See ctx system for the user-facing command that shows both tiers.

    Trade-off: Requires agent training or convention to recognize the tiers. Without a shared protocol, the prefixes are just text.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#choosing-a-pattern","level":2,"title":"Choosing a Pattern","text":"
    Is the agent about to do something forbidden?\n  └─ Yes → Hard gate\n\nDoes the user need to see this regardless of what they asked?\n  └─ Yes → VERBATIM relay\n  └─ Sometimes → Conditional relay\n\nShould the agent consider an action?\n  └─ Yes, with a specific fix → Suggested action\n  └─ Yes, open-ended → Agent directive\n\nIs this background context the agent should have?\n  └─ Yes → Silent injection\n\nIs this housekeeping?\n  └─ Yes → Silent side-effect\n
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#design-tips","level":2,"title":"Design Tips","text":"

    Throttle aggressively: VERBATIM relays that fire every prompt will be ignored or resented. Use once-per-day markers (touch $REMINDED), adaptive frequency (every Nth prompt), or staleness checks (only fire if condition persists).

    Include actionable commands: \"You have 12 unexported sessions\" is less useful than \"You have 12 unexported sessions. Run: ctx recall export --all.\" Give the user (or agent) the exact next step.

    Use box-drawing for visual structure: The ┌─ ─┐ │ └─ ─┘ pattern makes hook output visually distinct from agent prose. It also signals \"this is machine-generated, not agent opinion.\"

    Test the silence path: Most hook runs should produce no output (the condition isn't met). Make sure the common case is fast and silent.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#common-pitfalls","level":2,"title":"Common Pitfalls","text":"

    Lessons from 19 days of hook debugging in ctx. Every one of these was encountered, debugged, and fixed in production.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#silent-misfire-wrong-key-name","level":3,"title":"Silent Misfire: Wrong Key Name","text":"
    { \"PreToolUseHooks\": [ ... ] }\n

    The key is PreToolUse, not PreToolUseHooks. Claude Code validates silently: A misspelled key means the hook is ignored with no error. Always test with a debug echo first to confirm the hook fires before adding real logic.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#json-escaping-breaks-shell-commands","level":3,"title":"JSON Escaping Breaks Shell Commands","text":"

    Go's json.Marshal escapes >, <, and & as Unicode sequences (\\u003e) by default. This breaks shell commands in generated config:

    \"command\": \"ctx agent 2\\u003e/dev/null\"\n

    Fix: use json.Encoder with SetEscapeHTML(false) when generating hook configuration.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#stdin-not-environment-variables","level":3,"title":"stdin, Not Environment Variables","text":"

    Hook input arrives as JSON via stdin, not environment variables:

    # Wrong:\nCOMMAND=\"$CLAUDE_TOOL_INPUT\"\n\n# Right:\nHOOK_INPUT=$(cat)\nCOMMAND=$(echo \"$HOOK_INPUT\" | jq -r '.tool_input.command // empty')\n
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#regex-overfitting","level":3,"title":"Regex Overfitting","text":"

    A regex meant to catch ctx as a binary will also match ctx as a directory component:

    # Too broad: blocks: git -C /home/jose/WORKSPACE/ctx status\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# Narrow to binary only:\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n

    Test hook regexes against paths that contain the target string as a substring, not just as the final component.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#repetition-fatigue","level":3,"title":"Repetition Fatigue","text":"

    Injecting context on every tool call sounds safe. In practice, after seeing the same context injection fifteen times, the agent treats it as background noise: Conventions stated in the injected context get violated because salience has been destroyed by repetition.

    Fix: cooldowns. ctx agent --session $PPID --cooldown 10m injects at most once per ten minutes per session using a tombstone file in /tmp/. This is not an optimization; it is a correction for a design flaw. Every injection consumes attention budget: 50 tool calls at 4,000 tokens each means 200,000 tokens of repeated context, most of it wasted.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#hardcoded-paths","level":3,"title":"Hardcoded Paths","text":"

    A username rename (parallels to jose) broke every hook at once. Use $CLAUDE_PROJECT_DIR instead of absolute paths:

    \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"/.claude/hooks/block-git-push.sh\"\n

    If the platform provides a runtime variable for paths, always use it.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#next-up","level":2,"title":"Next Up","text":"

    Webhook Notifications →: Get push notifications when loops complete, hooks fire, or agents hit milestones.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#see-also","level":2,"title":"See Also","text":"
    • Customizing Hook Messages: override what hooks say without changing what they do
    • Claude Code Permission Hygiene: how permissions and hooks work together
    • Defense in Depth: why hooks matter for agent security
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/","level":1,"title":"Hook Sequence Diagrams","text":"","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#hook-lifecycle","level":2,"title":"Hook Lifecycle","text":"

    Every ctx hook is a Go binary invoked by Claude Code at one of three lifecycle events: PreToolUse (before a tool runs, can block), PostToolUse (after a tool completes), or UserPromptSubmit (on every user prompt, before any tools run). Hooks receive JSON on stdin and emit JSON or plain text on stdout.

    This page documents the execution flow of every hook as a sequence diagram.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#pretooluse-hooks","level":2,"title":"PreToolUse Hooks","text":"

    These fire before a tool executes. They can block, gate, or inject context.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#context-load-gate","level":3,"title":"context-load-gate","text":"

    Matcher: .* (all tools)

    Injects the full context packet on first tool use of a session. One-shot per session.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as context-load-gate\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Git as git log\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized\n    alt not initialized\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Check paused\n    alt paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check ctx-loaded-{session} marker\n    alt marker exists\n        Hook-->>CC: (silent exit, already fired)\n    end\n    Hook->>State: Create marker (one-shot guard)\n    Hook->>State: Prune stale session files\n    loop Each file in ReadOrder\n        alt GLOSSARY or TASK\n            Note over Hook: Skip (Task mentioned in footer only)\n        else DECISION or LEARNING\n            Hook->>Ctx: Extract index table only\n        else other files\n            Hook->>Ctx: Read full content\n        end\n        Hook->>Hook: Estimate tokens per file\n    end\n    Hook->>Git: Detect changes since last session\n    Hook->>Hook: Build injection (files + changes + token counts)\n    Hook-->>CC: JSON {additionalContext: injection}\n    Hook->>Hook: Send webhook (metadata only)\n    Hook->>State: Write oversize flag if tokens > threshold
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#block-non-path-ctx","level":3,"title":"block-non-path-ctx","text":"

    Matcher: Bash

    Blocks ./ctx, go run ./cmd/ctx, or absolute-path ctx invocations. Constitutionally enforced.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as block-non-path-ctx\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Extract command\n    alt command empty\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Test regex: relative-path, go-run, absolute-path\n    alt no match\n        Hook-->>CC: (silent exit)\n    end\n    alt absolute-path + test exception\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Hook-->>CC: JSON {decision: BLOCK, reason + constitution suffix}\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#qa-reminder","level":3,"title":"qa-reminder","text":"

    Matcher: Bash

    Gate nudge before any git command. Reminds agent to lint/test.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as qa-reminder\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Check command contains \"git\"\n    alt no git command\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, gate, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: QA gate}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#specs-nudge","level":3,"title":"specs-nudge","text":"

    Matcher: EnterPlanMode

    Nudges agent to save plans/specs when new implementation detected.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as specs-nudge\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: specs nudge}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#posttooluse-hooks","level":2,"title":"PostToolUse Hooks","text":"

    These fire after a tool completes. They observe, nudge, and track state.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#post-commit","level":3,"title":"post-commit","text":"

    Matcher: Bash

    Fires after git commit (not amend). Nudges for context capture and checks version drift.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as post-commit\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Regex: command contains \"git commit\"?\n    alt not a git commit\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Regex: command contains \"--amend\"?\n    alt is amend\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: post-commit nudge}\n    Hook->>Hook: Relay(message)\n    Hook->>Hook: CheckVersionDrift()
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-task-completion","level":3,"title":"check-task-completion","text":"

    Matcher: Edit, Write

    Configurable-interval nudge after edits. Per-session counter resets after firing.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-task-completion\n    participant State as .context/state/\n    participant RC as .ctxrc\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>RC: Read task nudge interval\n    alt interval <= 0 (disabled)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Read per-session counter\n    Hook->>Hook: Increment counter\n    alt counter < interval\n        Hook->>State: Write counter\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Reset counter to 0\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook-->>CC: JSON {additionalContext: task nudge}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#userpromptsubmit-hooks","level":2,"title":"UserPromptSubmit Hooks","text":"

    These fire on every user prompt, before any tools run. They perform health checks, track state, and nudge for housekeeping.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-context-size","level":3,"title":"check-context-size","text":"

    Adaptive context window monitoring. Fires checkpoints, window warnings, and billing alerts based on prompt count and token usage.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-context-size\n    participant State as .context/state/\n    participant Session as Session JSONL\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized\n    Hook->>Hook: Read input, resolve session ID\n    Hook->>Hook: Check paused\n    alt paused\n        Hook-->>CC: Pause acknowledgment message\n    end\n    Hook->>State: Increment session prompt counter\n    Hook->>Session: Read token info (tokens, model, window)\n\n    rect rgb(255, 240, 240)\n        Note over Hook: Billing check (independent, never suppressed)\n        alt tokens >= billing threshold (one-shot)\n            Hook->>Tpl: LoadMessage(hook, billing, vars)\n            Hook-->>CC: Billing warning nudge box\n            Hook->>Hook: NudgeAndRelay(billing message)\n        end\n    end\n\n    Hook->>State: Check wrap-up marker\n    alt wrapped up recently (< 2h)\n        Hook->>State: Write stats (event: suppressed)\n        Hook-->>CC: (silent exit)\n    end\n\n    rect rgb(240, 248, 255)\n        Note over Hook: Adaptive frequency check\n        alt count > 30 and count % 3 == 0\n            Note over Hook: High frequency trigger\n        else count > 15 and count % 5 == 0\n            Note over Hook: Medium frequency trigger\n        else\n            Hook->>State: Write stats (event: silent)\n            Hook-->>CC: (silent exit)\n        end\n    end\n\n    alt context window >= 80%\n        Hook->>Tpl: LoadMessage(hook, window, vars)\n        Hook-->>CC: Window warning nudge box\n        Hook->>Hook: NudgeAndRelay(window message)\n    else checkpoint trigger\n        Hook->>Tpl: LoadMessage(hook, checkpoint)\n        Hook-->>CC: Checkpoint nudge box\n        Hook->>Hook: NudgeAndRelay(checkpoint message)\n    end\n    Hook->>State: Write session stats
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-ceremonies","level":3,"title":"check-ceremonies","text":"

    Daily check for /ctx-remember and /ctx-wrap-up usage in recent journal entries.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-ceremonies\n    participant State as .context/state/\n    participant Journal as Journal files\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Read recent files (lookback window)\n    alt no journal files\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Scan for /ctx-remember and /ctx-wrap-up\n    alt both ceremonies present\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Note over Hook: variant: both | remember | wrapup\n    Hook-->>CC: Nudge box (missing ceremonies)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-freshness","level":3,"title":"check-freshness","text":"

    Daily check for technology-dependent constants that may need review.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-freshness\n    participant State as .context/state/\n    participant FS as Filesystem\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>FS: Stat tracked files (5 source files)\n    alt all files modified within 6 months\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, stale, {StaleFiles})\n    Hook-->>CC: Nudge box (stale file list + review URL)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-journal","level":3,"title":"check-journal","text":"

    Daily check for unexported sessions and unenriched journal entries.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-journal\n    participant State as .context/state/\n    participant Journal as Journal dir\n    participant Claude as Claude projects dir\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Check dir exists\n    Hook->>Claude: Check dir exists\n    alt either dir missing\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Get newest entry mtime\n    Hook->>Claude: Count .jsonl files newer than journal\n    Hook->>Journal: Count unenriched entries\n    alt unexported == 0 and unenriched == 0\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, {counts})\n    Note over Hook: variant: both | unexported | unenriched\n    Hook-->>CC: Nudge box (counts)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-knowledge","level":3,"title":"check-knowledge","text":"

    Daily check for knowledge file entry/line counts exceeding configured thresholds.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-knowledge\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant RC as .ctxrc\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>RC: Read thresholds (decisions, learnings, conventions)\n    alt all thresholds disabled (0)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Ctx: Parse DECISIONS.md entry count\n    Hook->>Ctx: Parse LEARNINGS.md entry count\n    Hook->>Ctx: Count CONVENTIONS.md lines\n    Hook->>Hook: Compare against thresholds\n    alt all within limits\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, warning, {FileWarnings})\n    Hook-->>CC: Nudge box (file warnings)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-map-staleness","level":3,"title":"check-map-staleness","text":"

    Daily check for architecture map age and relevant code changes.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-map-staleness\n    participant State as .context/state/\n    participant Tracking as map-tracking.json\n    participant Git as git log\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tracking: Read map-tracking.json\n    alt missing, invalid, or opted out\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Parse LastRun date\n    alt map not stale (< N days)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Git: Count commits touching internal/ since LastRun\n    alt no relevant commits\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, stale, {date, count})\n    Hook-->>CC: Nudge box (last refresh + commit count)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-memory-drift","level":3,"title":"check-memory-drift","text":"

    Per-session check for MEMORY.md changes since last sync.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-memory-drift\n    participant State as .context/state/\n    participant Mem as memory.Discover\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check session tombstone\n    alt already nudged this session\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Mem: DiscoverMemoryPath(projectRoot)\n    alt auto memory not active\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Mem: HasDrift(contextDir, sourcePath)\n    alt no drift\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook-->>CC: Nudge box (drift reminder)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch session tombstone
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-persistence","level":3,"title":"check-persistence","text":"

    Tracks context file modification and nudges when edits happen without persisting context. Adaptive threshold based on prompt count.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-persistence\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Read persistence state {Count, LastNudge, LastMtime}\n    alt first prompt (no state)\n        Hook->>State: Initialize state {Count:1, LastNudge:0, LastMtime:now}\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Increment Count\n    Hook->>Ctx: Get current context mtime\n    alt context modified since LastMtime\n        Hook->>State: Reset LastNudge = Count, update LastMtime\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: sinceNudge = Count - LastNudge\n    Hook->>Hook: PersistenceNudgeNeeded(Count, sinceNudge)?\n    alt threshold not reached\n        Hook->>State: Write state\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, vars)\n    Hook-->>CC: Nudge box (prompt count, time since last persist)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Update LastNudge = Count, write state
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-reminders","level":3,"title":"check-reminders","text":"

    Per-prompt check for due reminders. No throttle.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-reminders\n    participant Store as Reminders store\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Store: ReadReminders()\n    alt load error\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Filter by due date (After <= today)\n    alt no due reminders\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, reminders, {list})\n    Hook-->>CC: Nudge box (reminder list + dismiss hints)\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-resources","level":3,"title":"check-resources","text":"

    Checks system resources (memory, swap, disk, load). Fires on every prompt. No initialization required.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-resources\n    participant Sys as sysinfo\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: HookPreamble (parse input, check pause)\n    alt paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Sys: Collect snapshot (memory, swap, disk, load)\n    Hook->>Sys: Evaluate thresholds per metric\n    alt max severity < Danger\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Filter alerts to Danger level only\n    Hook->>Hook: Build alertMessages from danger alerts\n    Hook->>Tpl: LoadMessage(hook, alert, {alertMessages}, fallback)\n    Hook-->>CC: Nudge box (danger alerts)\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-version","level":3,"title":"check-version","text":"

    Daily binary-vs-plugin version comparison with piggybacked key rotation check.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-version\n    participant State as .context/state/\n    participant Config as Binary + Plugin version\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Config: Read binary version\n    alt dev build\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Config: Read plugin version\n    alt plugin version not found or parse error\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Compare major.minor\n    alt versions match\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, mismatch, {versions})\n    Hook-->>CC: Nudge box (version mismatch)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle\n    Hook->>Hook: CheckKeyAge() (piggybacked)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#heartbeat","level":3,"title":"heartbeat","text":"

    Silent per-prompt pulse. Tracks prompt count, context modification, and token usage. The agent never sees this hook's output.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as heartbeat\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Notify as Webhook + EventLog\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Increment heartbeat counter\n    Hook->>Ctx: Get latest context file mtime\n    Hook->>State: Compare with last recorded mtime\n    Hook->>State: Update mtime record\n    Hook->>State: Read session token info\n    Hook->>Notify: Send heartbeat notification\n    Hook->>Notify: Append to event log\n    Hook->>State: Write heartbeat log entry\n    Note over Hook: No stdout - agent never sees this
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#project-local-hooks","level":2,"title":"Project-Local Hooks","text":"

    These hooks are configured in settings.local.json and are not shipped with ctx. They are specific to individual developer setups.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#block-dangerous-commands","level":3,"title":"block-dangerous-commands","text":"

    Lifecycle: PreToolUse. Matcher: Bash

    Blocks dangerous shell patterns (sudo, git push, cp to bin). No initialization or pause checks: always active.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as block-dangerous-commands\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Extract command\n    alt command empty\n        Hook-->>CC: (silent exit)\n    end\n    Note over Hook: Cascade: first matching regex wins\n    Hook->>Hook: Test MidSudo regex\n    alt match\n        Hook->>Hook: variant = sudo\n    end\n    Hook->>Hook: Test MidGitPush regex (if no variant)\n    alt match\n        Hook->>Hook: variant = git-push\n    end\n    Hook->>Hook: Test CpMvToBin regex (if no variant)\n    alt match\n        Hook->>Hook: variant = cp-to-bin\n    end\n    Hook->>Hook: Test InstallToLocalBin regex (if no variant)\n    alt match\n        Hook->>Hook: variant = install-to-bin\n    end\n    alt no variant matched\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Hook-->>CC: JSON {decision: BLOCK, reason}\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-backup-age","level":3,"title":"check-backup-age","text":"

    Lifecycle: UserPromptSubmit.

    Daily check for SMB mount and backup freshness.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-backup-age\n    participant State as .context/state/\n    participant FS as Filesystem\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>FS: Check SMB mount (if env var set)\n    Hook->>FS: Check backup marker file age\n    alt no warnings\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, warning, {Warnings})\n    Hook-->>CC: Nudge box (warnings)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#throttling-summary","level":2,"title":"Throttling Summary","text":"Hook Lifecycle Throttle Type Scope context-load-gate PreToolUse One-shot marker Per session block-non-path-ctx PreToolUse None Every match qa-reminder PreToolUse None Every git command specs-nudge PreToolUse None Every prompt post-commit PostToolUse None Every git commit check-task-completion PostToolUse Configurable interval Per session check-context-size UserPromptSubmit Adaptive counter Per session check-ceremonies UserPromptSubmit Daily marker Once per day check-freshness UserPromptSubmit Daily marker Once per day check-journal UserPromptSubmit Daily marker Once per day check-knowledge UserPromptSubmit Daily marker Once per day check-map-staleness UserPromptSubmit Daily marker Once per day check-memory-drift UserPromptSubmit Session tombstone Once per session check-persistence UserPromptSubmit Adaptive counter Per session check-reminders UserPromptSubmit None Every prompt check-resources UserPromptSubmit None Every prompt check-version UserPromptSubmit Daily marker Once per day heartbeat UserPromptSubmit None Every prompt block-dangerous-commands PreToolUse * None Every match check-backup-age UserPromptSubmit * Daily marker Once per day

    * Project-local hook (settings.local.json), not shipped with ctx.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#state-file-reference","level":2,"title":"State File Reference","text":"

    All state files live in .context/state/.

    File Pattern Hook Purpose ctx-loaded-{session} context-load-gate One-shot injection marker ctx-paused-{session} (all) Session pause marker ctx-wrapped-up check-context-size Suppress nudges after wrap-up (2h expiry) freshness-checked check-freshness Daily throttle backup-reminded check-backup-age Daily throttle ceremony-reminded check-ceremonies Daily throttle journal-reminded check-journal Daily throttle knowledge-reminded check-knowledge Daily throttle map-staleness-reminded check-map-staleness Daily throttle version-checked check-version Daily throttle memory-drift-nudged-{session} check-memory-drift Per-session tombstone ctx-context-count-{session} check-context-size Prompt counter stats-{session}.jsonl check-context-size Session stats log persist-{session} check-persistence Counter + mtime state ctx-task-count-{session} check-task-completion Prompt counter heartbeat-count-{session} heartbeat Prompt counter heartbeat-mtime-{session} heartbeat Last context mtime","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/import-plans/","level":1,"title":"Importing Claude Code Plans","text":"","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code plan files (~/.claude/plans/*.md) are ephemeral: They have structured context, approach, and file lists, but they're orphaned after the session ends. The filenames are UUIDs, so you can't tell what's in them without opening each one.

    How do you turn a useful plan into a permanent project spec?

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#tldr","level":2,"title":"TL;DR","text":"
    You: /ctx-import-plans\nAgent: [lists plans with dates and titles]\n       1. 2026-02-28  Add authentication middleware\n       2. 2026-02-27  Refactor database connection pool\nYou: \"import 1\"\nAgent: [copies to specs/add-authentication-middleware.md]\n

    Plans are copied (not moved) to specs/, slugified by their H1 heading.

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-import-plans Skill List, filter, and import plan files to specs /ctx-add-task Skill Optionally add a task referencing the spec","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-1-list-available-plans","level":3,"title":"Step 1: List Available Plans","text":"

    Invoke the skill and it lists plans with modification dates and titles:

    You: /ctx-import-plans\n\nAgent: Found 3 plan files:\n         1. 2026-02-28  Add authentication middleware\n         2. 2026-02-27  Refactor database connection pool\n         3. 2026-02-25  Import plans skill\n       Which plans would you like to import?\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-2-filter-optional","level":3,"title":"Step 2: Filter (Optional)","text":"

    You can narrow the list with arguments:

    Argument Effect --today Only plans modified today --since YYYY-MM-DD Only plans modified on or after the date --all Import everything without prompting (none) Interactive selection 
    You: /ctx-import-plans --today\nYou: /ctx-import-plans --since 2026-02-27\nYou: /ctx-import-plans --all\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-3-select-and-import","level":3,"title":"Step 3: Select and Import","text":"

    Pick one or more plans by number:

    You: \"import 1 and 3\"\n\nAgent: Imported 2 plan(s):\n         ~/.claude/plans/abc123.md -> specs/add-authentication-middleware.md\n         ~/.claude/plans/ghi789.md -> specs/import-plans-skill.md\n       Want me to add tasks referencing these specs?\n

    The agent reads the H1 heading from each plan and slugifies it for the filename. If a plan has no H1 heading, the original filename (minus extension) is used as the slug.

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-4-add-follow-up-tasks-optional","level":3,"title":"Step 4: Add Follow-Up Tasks (Optional)","text":"

    If you say yes, the agent creates tasks in TASKS.md that reference the imported specs:

    You: \"yes, add tasks\"\n\nAgent: [runs /ctx-add-task for each spec]\n       Added:\n         - [ ] Implement authentication middleware (spec: specs/add-authentication-middleware.md)\n         - [ ] Import plans skill (spec: specs/import-plans-skill.md)\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember the exact skill name:

    You say What happens \"import my plans\" /ctx-import-plans (interactive) \"save today's plans as specs\" /ctx-import-plans --today \"import all plans from this week\" /ctx-import-plans --since ... \"turn that plan into a spec\" /ctx-import-plans (filtered)","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#tips","level":2,"title":"Tips","text":"
    • Plans are copied, not moved: The originals stay in ~/.claude/plans/. Claude Code manages that directory; ctx doesn't delete from it.
    • Conflict handling: If specs/{slug}.md already exists, the agent asks whether to overwrite or pick a different name.
    • Specs are project memory: Once imported, specs are tracked in git and available to future sessions. Reference them from TASKS.md phase headers with Spec: specs/slug.md.
    • Pair with /ctx-implement: After importing a plan as a spec, use /ctx-implement to execute it step-by-step with verification.
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: /ctx-import-plans: full skill description
    • The Complete Session: where plan import fits in the session flow
    • Tracking Work Across Sessions: managing tasks that reference imported specs
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/knowledge-capture/","level":1,"title":"Persisting Decisions, Learnings, and Conventions","text":"","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#the-problem","level":2,"title":"The Problem","text":"

    You debug a subtle issue, discover the root cause, and move on.

    Three weeks later, a different session hits the same issue. The knowledge existed briefly in one session's memory but was never written down.

    Architectural decisions suffer the same fate: you weigh trade-offs, pick an approach, and six sessions later the AI suggests the alternative you already rejected.

    How do you make sure important context survives across sessions?

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-reflect               # surface items worth persisting\n/ctx-add-decision \"Title\"  # record with context/rationale/consequence\n/ctx-add-learning \"Title\"  # record with context/lesson/application\n

    Or just tell your agent: \"What have we learned this session?\"

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx add decision Command Record an architectural decision ctx add learning Command Record a gotcha, tip, or lesson ctx add convention Command Record a coding pattern or standard ctx reindex Command Rebuild both quick-reference indices ctx decision reindex Command Rebuild the DECISIONS.md index ctx learning reindex Command Rebuild the LEARNINGS.md index /ctx-add-decision Skill AI-guided decision capture with validation /ctx-add-learning Skill AI-guided learning capture with validation /ctx-add-convention Skill AI-guided convention recording with placement /ctx-reflect Skill Surface items worth persisting at breakpoints","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#the-workflow","level":2,"title":"The Workflow","text":"

    Decision, Learning, or Convention?

    • If you chose between alternatives, it is a decision.
    • If you discovered something surprising, it is a learning.
    • If you are codifying a repeated pattern, it is a convention.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-1-understand-what-to-persist","level":3,"title":"Step 1: Understand What to Persist","text":"

    Three context files serve different purposes:

    Decisions (DECISIONS.md) answer \"why is it this way?\" They record trade-offs between alternatives with structured fields: context, rationale, and consequences. Decisions prevent re-debating settled questions.

    Learnings (LEARNINGS.md) answer \"what did we discover the hard way?\" They record gotchas and debugging insights specific to this project with structured fields: context, lesson, and application.

    Learnings prevent repeating past mistakes.

    Conventions (CONVENTIONS.md) answer \"how do we do things here?\" They record patterns and standards. No structured fields required: just a name, a rule, and an example. Conventions keep code consistent across sessions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-2-record-decisions","level":3,"title":"Step 2: Record Decisions","text":"

    Decisions have three structured fields:

    • context,
    • rationale,
    • and consequences.

    The easiest way to record one is to tell your agent:

    You: \"Save that as a decision: we picked file-based cooldown\n      tokens over env vars.\"\n\nAgent: \"Recorded in DECISIONS.md:\n  - Decision: Use file-based cooldown tokens instead of env vars\n  - Context: Hook subprocesses cannot persist env vars to parent shell\n  - Rationale: File tokens survive across processes. Simpler than\n    IPC. Cleanup is automatic via TTL.\n  - Consequence: Tombstone files accumulate in /tmp. Cannot share\n    state across machines.\"\n

    The agent was present for the trade-off discussion. It fills in the structured fields from what it observed, which is hard to reconstruct later as a terminal one-liner.

    When multiple options were considered, the agent includes rejected alternatives in the rationale automatically.

    The /ctx-add-decision skill also guides you through the fields interactively. For quick decisions, it supports a Y-statement:

    \"In the context of [situation], facing [constraint], we decided for [choice] and against [alternatives], to achieve [benefit], accepting that [trade-off].\"

    CLI Command for Scripting and Automation

    When no agent is in the loop (CI pipelines, shell scripts, hooks), use the CLI directly with structured flags:

    ctx add decision \"Use file-based cooldown tokens instead of env vars\" \\\n  --context \"Hook subprocesses cannot persist env vars to parent shell\" \\\n  --rationale \"File tokens survive across processes. Simpler than IPC. Cleanup is automatic via TTL.\" \\\n  --consequence \"Tombstone files accumulate in /tmp. Cannot share state across machines.\"\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-3-record-learnings","level":3,"title":"Step 3: Record Learnings","text":"

    Learnings have three structured fields: context, lesson, and application.

    Again, your agent is the best tool for this. It was there when you discovered the gotcha and can express it more completely than a backslash-escaped terminal command:

    You: \"That subprocess thing was painful. Save it as a learning.\"\n\nAgent: \"Added to LEARNINGS.md:\n  - Learning: Claude Code hooks run in a subprocess\n  - Context: Set env var in PreToolUse hook, but it was not visible\n    in the main session\n  - Lesson: Hook scripts execute in a child process. Env changes do\n    not propagate to parent.\n  - Application: Use tombstone files for hook-to-session\n    communication. Never rely on hook env vars.\"\n

    You said one sentence. The agent produced a structured entry with all three fields filled from the session context.

    That is the point: the agent has the full conversation and can be far more expressive than what you would type at a command prompt.

    The /ctx-add-learning skill applies three quality filters:

    1. Could someone Google this in 5 minutes?
    2. Is it specific to this codebase?
    3. Did it take real effort to discover?

    All three must pass.

    Learnings capture principles and heuristics, not code snippets.

    CLI Command for Scripting and Automation

    When no agent is in the loop:

    ctx add learning \"Claude Code hooks run in a subprocess\" \\\n  --context \"Set env var in PreToolUse hook, but it was not visible in the main session\" \\\n  --lesson \"Hook scripts execute in a child process. Env changes do not propagate to parent.\" \\\n  --application \"Use tombstone files for hook-to-session communication. Never rely on hook env vars.\"\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-4-record-conventions","level":3,"title":"Step 4: Record Conventions","text":"

    Conventions are simpler: just a name, a rule, and optionally a section.

    These are short enough that either approach works:

    You: \"We've been using kebab-case for every CLI flag. Codify that.\"\n\nAgent: \"Added to CONVENTIONS.md under Naming:\n  'Use kebab-case for all CLI flag names.'\"\n

    Or from the terminal:

    ctx add convention \"Use kebab-case for all CLI flag names\" --section \"Naming\"\n

    Conventions work best for rules that come up repeatedly. Codify a pattern the third time you see it, not the first.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-5-reindex-after-manual-edits","level":3,"title":"Step 5: Reindex After Manual Edits","text":"

    DECISIONS.md and LEARNINGS.md maintain a quick-reference index at the top: a compact table of date and title for each entry. The index updates automatically via ctx add, but falls out of sync after hand edits.

    ctx reindex\n

    This single command regenerates both indices. You can also reindex individually with ctx decision reindex or ctx learning reindex.

    Run reindex after any manual edit. The index lets AI tools scan all entries without reading the full file, which matters when token budgets are tight.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-6-use-ctx-reflect-to-surface-what-to-capture","level":3,"title":"Step 6: Use /ctx-reflect to Surface What to Capture","text":"

    Keep It Conversational

    /ctx-reflect is not the only way to trigger reflection.

    Agents trained on the ctx playbook naturally surface persist-worthy items at breakpoints, even without invoking the skill explicitly.

    A conversational prompt like \"anything worth saving?\" or \"let's wrap up\" can trigger the same review.

    The skill provides a structured checklist, but the behavior is available through natural conversation.

    At natural breakpoints (after completing a feature, fixing a bug, or before ending a session) use /ctx-reflect to identify items worth persisting.

    /ctx-reflect\n

    The skill walks through learnings, decisions, tasks, and session notes, skipping categories with nothing to report. The output includes specific commands for each suggested persist:

    This session implemented file-based cooldown for `ctx agent` and\ndiscovered that hook subprocesses cannot set env vars in the parent.\n\nI'd suggest persisting:\n- **Learning**: Hook subprocesses cannot propagate env vars\n  `ctx add learning \"...\" --context \"...\" --lesson \"...\" --application \"...\"`\n- **Decision**: File-based cooldown tokens over env vars\n  `ctx add decision \"...\" --context \"...\" --rationale \"...\" --consequence \"...\"`\n\nWant me to persist any of these?\n

    The skill always asks before persisting.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-7-the-conversational-approach","level":3,"title":"Step 7: The Conversational Approach","text":"

    The commands shown in Steps 2 to 4 are precise, but you rarely need to type them yourself. When working with an agent that has loaded the ctx playbook, natural language triggers the same operations.

    You ask, the agent acts:

    You say What the agent does \"What have we learned this session?\" Reviews recent work, identifies learnings, offers to persist \"Save that as a decision\" Captures the trade-off you just discussed with structured fields \"Any gotchas worth remembering?\" Scans recent work for non-obvious lessons \"Record that convention\" Adds the pattern you just agreed on to CONVENTIONS.md \"Let's wrap up\" Runs through the reflect checklist conversationally

    Example exchange:

    You: \"What did we learn from that debugging session?\"\n\nAgent: \"We discovered three things worth persisting:\n  1. Hook subprocesses can't propagate env vars to the parent. We\n     spent 20 minutes on this before switching to tombstone files.\n  2. Tombstone files need a TTL or they accumulate in /tmp.\n  3. The cooldown logic must check file mtime, not just existence.\n  Want me to save these as learnings?\"\n\nYou: \"Yes, all of them.\"\n\nAgent: \"Done. Added all three to LEARNINGS.md with structured fields.\"\n

    The agent can also be proactive without being asked. The playbook encourages agents to persist context at natural milestones.

    You may see:

    • After fixing a tricky bug: \"I noticed this was a non-obvious issue. Want me to save it as a learning?\"
    • After choosing between approaches: \"We just made a trade-off between file-based tokens and IPC. Should I record this as a decision?\"
    • At session milestones: the agent checks what is worth persisting and offers a brief summary.

    When agents run unattended (no human in the loop), they may persist directly:

    • \"I've added the subprocess env var gotcha to LEARNINGS.md so we don't hit it again.\"
    • \"Recorded the decision to use file-based tokens over env vars in DECISIONS.md.\"
    • \"Marked the cooldown task done and added a follow-up for TTL cleanup.\"

    This is behavior by design.

    The playbook's self-check prompt, \"If this session ended right now, would the next session know what happened?\" drives agents to persist early and often rather than waiting for explicit instructions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#command-line-approach-scripting-and-automation","level":3,"title":"Command-line Approach (Scripting and Automation)","text":"
    # Decision: record the trade-off\nctx add decision \"Use PostgreSQL over SQLite\" \\\n  --context \"Need concurrent multi-user access\" \\\n  --rationale \"SQLite locks on writes; Postgres handles concurrency\" \\\n  --consequence \"Requires a database server; team needs Postgres training\"\n\n# Learning: record the gotcha\nctx add learning \"SQL migrations must be idempotent\" \\\n  --context \"Deploy failed when migration ran twice after rollback\" \\\n  --lesson \"CREATE TABLE without IF NOT EXISTS fails on retry\" \\\n  --application \"Always use IF NOT EXISTS guards in migrations\"\n\n# Convention: record the pattern\nctx add convention \"API handlers return structured errors\" --section \"API\"\n\n# Reindex after manual edits\nctx reindex\n\n# Reflect at breakpoints (from AI assistant)\n# /ctx-reflect\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#conversational-approach-interactive-sessions","level":3,"title":"Conversational Approach (Interactive Sessions)","text":"
    You: \"We just picked Postgres over SQLite for the concurrency\n      reasons. Save that?\"\n\nAgent: \"Recorded. Added to DECISIONS.md:\n  - Decision: Use PostgreSQL over SQLite\n  - Context: Need concurrent multi-user access\n  - Rationale: SQLite locks on writes; Postgres handles concurrency\n  - Consequence: Requires a database server; team needs Postgres\n    training\"\n\nYou: \"Also that migration thing. The deploy blew up when the\n      migration ran twice.\"\n\nAgent: \"Got it. Added to LEARNINGS.md:\n  - Learning: SQL migrations must be idempotent\n  - Lesson: CREATE TABLE without IF NOT EXISTS fails on retry\n  - Application: Always use IF NOT EXISTS guards in migrations\"\n\nYou: \"Good. Anything else worth saving before we wrap up?\"\n\nAgent: \"We've been using structured error returns in every API\n  handler this session. Want me to codify that as a convention?\"\n\nYou: \"Do it.\"\n\nAgent: \"Done. Added 'API handlers return structured errors' to\n  CONVENTIONS.md under the API section.\"\n

    Both approaches produce the same structured entries in the same context files.

    • The conversational approach is the natural fit for interactive sessions;
    • the CLI commands are better suited for scripts, hooks, and automation pipelines.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#tips","level":2,"title":"Tips","text":"
    • Record decisions at the moment of choice. The alternatives you considered and the reasons you rejected them fade quickly. Capture trade-offs while they are fresh.
    • Learnings should fail the Gemini test. If someone could find it in a 5-minute Gemini search, it does not belong in LEARNINGS.md.
    • Conventions earn their place through repetition. Add a convention the third time you see a pattern, not the first.
    • Use /ctx-reflect at natural breakpoints. The checklist catches items you might otherwise lose.
    • Keep the entries self-contained. Each entry should make sense on its own. A future session may load only one due to token budget constraints.
    • Reindex after every hand edit. It takes less than a second. A stale index causes AI tools to miss entries.
    • Prefer the structured fields. The verbosity forces clarity. A decision without a rationale is just a fact. A learning without an application is just a story.
    • Talk to your agent, do not type commands. In interactive sessions, the conversational approach is the recommended way to capture knowledge. Say \"save that as a learning\" or \"any decisions worth recording?\" and let the agent handle the structured fields. Reserve the CLI commands for scripting, automation, and CI/CD pipelines where there is no agent in the loop.
    • Trust the agent's proactive instincts. Agents trained on the ctx playbook will offer to persist context at milestones. A brief \"want me to save this?\" is cheaper than re-discovering the same lesson three sessions later.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#next-up","level":2,"title":"Next Up","text":"

    Tracking Work Across Sessions →: Add, prioritize, complete, and archive tasks across sessions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#see-also","level":2,"title":"See Also","text":"
    • Tracking Work Across Sessions: managing the tasks that decisions and learnings support
    • The Complete Session: full session lifecycle including reflection and context persistence
    • Detecting and Fixing Drift: keeping knowledge files accurate as the codebase evolves
    • CLI Reference: full documentation for ctx add, ctx decision, ctx learning
    • Context Files: format and conventions for DECISIONS.md, LEARNINGS.md, and CONVENTIONS.md
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/memory-bridge/","level":1,"title":"Bridging Claude Code Auto Memory","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code maintains per-project auto memory at ~/.claude/projects/<slug>/memory/MEMORY.md. This file is:

    • Outside the repo - not version-controlled, not portable
    • Machine-specific - tied to one ~/.claude/ directory
    • Invisible to ctx - context loading and hooks don't read it

    Meanwhile, ctx maintains structured context files (DECISIONS.md, LEARNINGS.md, CONVENTIONS.md) that are git-tracked, portable, and token-budgeted - but Claude Code doesn't automatically write to them.

    The two systems hold complementary knowledge with no bridge between them.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#tldr","level":2,"title":"TL;DR","text":"
    ctx memory sync          # Mirror MEMORY.md into .context/memory/mirror.md\nctx memory status        # Check for drift\nctx memory diff          # See what changed since last sync\n

    The check-memory-drift hook nudges automatically when MEMORY.md changes - you don't need to remember to sync manually.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx memory sync CLI command Copy MEMORY.md to mirror, archive previous ctx memory status CLI command Show drift, timestamps, line counts ctx memory diff CLI command Show changes since last sync ctx memory import CLI command Classify and promote entries to .context/ files ctx memory publish CLI command Push curated .context/ content to MEMORY.md ctx memory unpublish CLI command Remove published block from MEMORY.md ctx system check-memory-drift Hook Nudge when MEMORY.md has changed (once/session)","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#how-it-works","level":2,"title":"How It Works","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#discovery","level":3,"title":"Discovery","text":"

    Claude Code encodes project paths as directory names under ~/.claude/projects/. The encoding replaces / with - and prefixes with -:

    /home/jose/WORKSPACE/ctx  →  ~/.claude/projects/-home-jose-WORKSPACE-ctx/\n

    ctx memory uses this encoding to locate MEMORY.md automatically from your project root - no configuration needed.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#mirroring","level":3,"title":"Mirroring","text":"

    When you run ctx memory sync:

    1. The previous mirror is archived to .context/memory/archive/mirror-<timestamp>.md
    2. MEMORY.md is copied to .context/memory/mirror.md
    3. Sync state is updated in .context/state/memory-import.json

    The mirror is git-tracked, so it travels with the project. Archives provide a fallback for projects that don't use git.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#drift-detection","level":3,"title":"Drift Detection","text":"

    The check-memory-drift hook compares MEMORY.md's modification time against the mirror. When drift is detected, the agent sees:

    ┌─ Memory Drift ────────────────────────────────────────────────\n│ MEMORY.md has changed since last sync.\n│ Run: ctx memory sync\n│ Context: .context\n└────────────────────────────────────────────────────────────────\n

    The nudge fires once per session to avoid noise.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#typical-workflow","level":2,"title":"Typical Workflow","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#at-session-start","level":3,"title":"At Session Start","text":"

    If the hook fires a drift nudge, sync before diving into work:

    ctx memory diff     # Review what changed\nctx memory sync     # Mirror the changes\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#periodic-check","level":3,"title":"Periodic Check","text":"
    ctx memory status\n# Memory Bridge Status\n#   Source:      ~/.claude/projects/.../memory/MEMORY.md\n#   Mirror:      .context/memory/mirror.md\n#   Last sync:   2026-03-05 14:30 (2 hours ago)\n#\n#   MEMORY.md:  47 lines\n#   Mirror:     32 lines\n#   Drift:      detected (source is newer)\n#   Archives:   3 snapshots in .context/memory/archive/\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#dry-run","level":3,"title":"Dry Run","text":"

    Preview what sync would do without writing:

    ctx memory sync --dry-run\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#storage-layout","level":2,"title":"Storage Layout","text":"
    .context/\n├── memory/\n│   ├── mirror.md                          # Raw copy of MEMORY.md (often git-tracked)\n│   └── archive/\n│       ├── mirror-2026-03-05-143022.md    # Timestamped pre-sync snapshots\n│       └── mirror-2026-03-04-220015.md\n├── state/\n│   └── memory-import.json                 # Sync tracking state\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#edge-cases","level":2,"title":"Edge Cases","text":"Scenario Behavior Auto memory not active sync exits 1 with message. status reports \"not active\". Hook skips silently. First sync (no mirror) Creates mirror without archiving. MEMORY.md is empty Syncs to empty mirror (valid). Not initialized Init guard rejects (same as all ctx commands).","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#importing-entries","level":2,"title":"Importing Entries","text":"

    Once you've synced, you can classify and promote entries into structured .context/ files:

    ctx memory import --dry-run    # Preview classification\nctx memory import              # Actually promote entries\n

    Each entry is classified by keyword heuristics:

    Keywords Target always use, prefer, never use, standard CONVENTIONS.md decided, chose, trade-off, approach DECISIONS.md gotcha, learned, watch out, bug, caveat LEARNINGS.md todo, need to, follow up TASKS.md Everything else Skipped

    Entries that don't match any pattern are skipped - they stay in the mirror for manual review. Deduplication (hash-based) prevents re-importing the same entry on subsequent runs.

    Review Before Importing

    Use --dry-run first. The heuristic classifier is deliberately simple - it may misclassify ambiguous entries. Review the plan, then import.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#full-workflow","level":3,"title":"Full Workflow","text":"
    ctx memory sync                # 1. Mirror MEMORY.md\nctx memory import --dry-run    # 2. Preview what would be imported\nctx memory import              # 3. Promote entries to .context/ files\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#publishing-context-to-memorymd","level":2,"title":"Publishing Context to MEMORY.md","text":"

    Push curated .context/ content back into MEMORY.md so Claude Code sees structured project context on session start - without needing hooks.

    ctx memory publish --dry-run    # Preview what would be published\nctx memory publish              # Write to MEMORY.md\nctx memory publish --budget 40  # Tighter line budget\n

    Published content is wrapped in markers:

    <!-- ctx:published -->\n# Project Context (managed by ctx)\n\n## Pending Tasks\n- [ ] Implement feature X\n...\n<!-- ctx:end -->\n

    Rules:

    • ctx owns everything between the markers
    • Claude owns everything outside the markers
    • ctx memory import reads only outside the markers
    • ctx memory publish replaces only inside the markers

    To remove the published block entirely:

    ctx memory unpublish\n

    Publish at Wrap-Up, Not on Commit

    The best time to publish is during session wrap-up, after persisting decisions and learnings. Never auto-publish - give yourself a chance to review what's going into MEMORY.md.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#full-bidirectional-workflow","level":3,"title":"Full Bidirectional Workflow","text":"
    ctx memory sync                 # 1. Mirror MEMORY.md\nctx memory import --dry-run     # 2. Check what Claude wrote\nctx memory import               # 3. Promote entries to .context/\nctx memory publish --dry-run    # 4. Check what would be published\nctx memory publish              # 5. Push context to MEMORY.md\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/multi-tool-setup/","level":1,"title":"Setup Across AI Tools","text":"","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#the-problem","level":2,"title":"The Problem","text":"

    You have installed ctx and want to set it up with your AI coding assistant so that context persists across sessions. Different tools have different integration depths. For example:

    • Claude Code supports native hooks that load and save context automatically.
    • Cursor injects context via its system prompt.
    • Aider reads context files through its --read flag.

    This recipe walks through the complete setup for each tool, from initialization through verification, so you end up with a working memory layer regardless of which AI tool you use.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#tldr","level":2,"title":"TL;DR","text":"
    cd your-project\nctx init                      # creates .context/\nsource <(ctx completion zsh)  # shell completion (or bash/fish)\n\n# ## Claude Code (automatic after plugin install) ##\nclaude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n\n# ## Cursor / Aider / Copilot / Windsurf ##\nctx hook cursor # or: aider, copilot, windsurf\n

    Create a .ctxrc in your project root to configure token budgets, context directory, drift thresholds, and more.

    Then start your AI tool and ask: \"Do you remember?\"

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx init Create .context/ directory, templates, and permissions ctx hook Generate integration configuration for a specific AI tool ctx agent Print a token-budgeted context packet for AI consumption ctx load Output assembled context in read order (for manual pasting) ctx watch Auto-apply context updates from AI output (non-native tools) ctx completion Generate shell autocompletion for bash, zsh, or fish ctx recall export Export sessions to editable journal Markdown","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-1-initialize-ctx","level":3,"title":"Step 1: Initialize ctx","text":"

    Run ctx init in your project root. This creates the .context/ directory with all template files and seeds ctx permissions in settings.local.json.

    cd your-project\nctx init\n

    This produces the following structure:

    .context/\n  CONSTITUTION.md     # Hard rules the AI must never violate\n  TASKS.md            # Current and planned work\n  CONVENTIONS.md      # Code patterns and standards\n  ARCHITECTURE.md     # System overview\n  DECISIONS.md        # Architectural decisions with rationale\n  LEARNINGS.md        # Lessons learned, gotchas, tips\n  GLOSSARY.md         # Domain terms and abbreviations\n  AGENT_PLAYBOOK.md   # How AI tools should use this system\n

    Using a Different .context Directory

    The .context/ directory doesn't have to live inside your project. You can point ctx to an external folder via .ctxrc, the CTX_DIR environment variable, or the --context-dir CLI flag.

    This is useful for monorepos or shared context across repositories.

    See Configuration for details and External Context for a full recipe.

    For Claude Code, install the ctx plugin to get hooks and skills:

    claude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n

    If you only need the core files (useful for lightweight setups), use the --minimal flag:

    ctx init --minimal\n

    This creates only TASKS.md, DECISIONS.md, and CONSTITUTION.md.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-2-generate-tool-specific-hooks","level":3,"title":"Step 2: Generate Tool-Specific Hooks","text":"

    If you are using a tool other than Claude Code (which is configured automatically by ctx init), generate its integration configuration:

    # For Cursor\nctx hook cursor\n\n# For Aider\nctx hook aider\n\n# For GitHub Copilot\nctx hook copilot\n\n# For Windsurf\nctx hook windsurf\n

    Each command prints the configuration you need. How you apply it depends on the tool.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#claude-code","level":4,"title":"Claude Code","text":"

    No action needed. Just install ctx from the Marketplace as ActiveMemory/ctx.

    Claude Code is a First-Class Citizen

    With the ctx plugin installed, Claude Code gets hooks and skills automatically. The PreToolUse hook runs ctx agent --budget 4000 on every tool call (with a 10-minute cooldown so it only fires once per window).

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#cursor","level":4,"title":"Cursor","text":"

    Add the system prompt snippet to .cursor/settings.json:

    {\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and .context/CONVENTIONS.md before responding. Follow rules in .context/CONSTITUTION.md.\"\n}\n

    Context files appear in Cursor's file tree. You can also paste a context packet directly into chat:

    ctx agent --budget 4000 | xclip    # Linux\nctx agent --budget 4000 | pbcopy   # macOS\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#aider","level":4,"title":"Aider","text":"

    Create .aider.conf.yml so context files are loaded on every session:

    read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n

    Then start Aider normally:

    aider\n

    Or specify files on the command line:

    aider --read .context/TASKS.md --read .context/CONVENTIONS.md\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-3-set-up-shell-completion","level":3,"title":"Step 3: Set Up Shell Completion","text":"

    Shell completion lets you tab-complete ctx subcommands and flags, which is especially useful while learning the CLI.

    # Bash (add to ~/.bashrc)\nsource <(ctx completion bash)\n\n# Zsh (add to ~/.zshrc)\nsource <(ctx completion zsh)\n\n# Fish\nctx completion fish > ~/.config/fish/completions/ctx.fish\n

    After sourcing, typing ctx a<TAB> completes to ctx agent, and ctx recall <TAB> shows list, show, and export.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-4-verify-the-setup-works","level":3,"title":"Step 4: Verify the Setup Works","text":"

    Start a fresh session in your AI tool and ask:

    \"Do you remember?\"

    A correctly configured tool responds with specific context: current tasks from TASKS.md, recent decisions, and previous session topics. It should not say \"I don't have memory\" or \"Let me search for files.\"

    This question checks the passive side of memory. A properly set-up agent is also proactive: it treats context maintenance as part of its job:

    • After a debugging session, it offers to save a learning.
    • After a trade-off discussion, it asks whether to record the decision.
    • After completing a task, it suggests follow-up items.

    The \"do you remember?\" check verifies both halves: recall and responsibility.

    For example, after resolving a tricky bug, a proactive agent might say:

    That Redis timeout issue was subtle. Want me to save this as a *learning*\nso we don't hit it again?\n

    If you see behavior like this, the setup is working end to end.

    In Claude Code, you can also invoke the /ctx-status skill:

    /ctx-status\n

    This prints a summary of all context files, token counts, and recent activity, confirming that hooks are loading context.

    If context is not loading, check the basics:

    Symptom Fix ctx: command not found Ensure ctx is in your PATH: which ctx Hook errors Verify plugin is installed: claude /plugin list Context not refreshing Cooldown may be active; wait 10 minutes or set --cooldown 0","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-5-enable-watch-mode-for-non-native-tools","level":3,"title":"Step 5: Enable Watch Mode for Non-Native Tools","text":"

    Tools like Aider, Copilot, and Windsurf do not support native hooks for saving context automatically. For these, run ctx watch alongside your AI tool.

    Pipe the AI tool's output through ctx watch:

    # Terminal 1: Run Aider with output logged\naider 2>&1 | tee /tmp/aider.log\n\n# Terminal 2: Watch the log for context updates\nctx watch --log /tmp/aider.log\n

    Or for any generic tool:

    your-ai-tool 2>&1 | tee /tmp/ai.log &\nctx watch --log /tmp/ai.log\n

    When the AI emits structured update commands, ctx watch parses and applies them automatically:

    <context-update type=\"learning\"\n  context=\"Debugging rate limiter\"\n  lesson=\"Redis MULTI/EXEC does not roll back on error\"\n  application=\"Wrap rate-limit checks in Lua scripts instead\"\n>Redis Transaction Behavior</context-update>\n

    To preview changes without modifying files:

    ctx watch --dry-run --log /tmp/ai.log\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-6-export-session-transcripts-optional","level":3,"title":"Step 6: Export Session Transcripts (Optional)","text":"

    If you want to browse past session transcripts, export them to the journal:

    ctx recall export --all\n

    This converts raw session data into editable Markdown files in .context/journal/. You can then enrich them with metadata using /ctx-journal-enrich-all inside your AI assistant.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Here is the condensed setup for all three tools:

    # ## Common (run once per project) ##\ncd your-project\nctx init\nsource <(ctx completion zsh)       # or bash/fish\n\n# ## Claude Code (automatic, just verify) ##\n# Start Claude Code, then ask: \"Do you remember?\"\n\n# ## Cursor ##\nctx hook cursor\n# Add the system prompt to .cursor/settings.json\n# Paste context: ctx agent --budget 4000 | pbcopy\n\n# ## Aider ##\nctx hook aider\n# Create .aider.conf.yml with read: paths\n# Run watch mode alongside: ctx watch --log /tmp/aider.log\n\n# ## Verify any Tool ##\n# Ask your AI: \"Do you remember?\"\n# Expect: specific tasks, decisions, recent context\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#tips","level":2,"title":"Tips","text":"
    • Start with ctx init (not --minimal) for your first project. The full template set gives the agent more to work with, and you can always delete files later.
    • For Claude Code, the token budget is configured in the plugin's hooks.json. To customize, adjust the --budget flag in the ctx agent hook command.
    • The --session $PPID flag isolates cooldowns per Claude Code process, so parallel sessions do not suppress each other.
    • Commit your .context/ directory to version control. Several ctx features (journals, changelogs, blog generation) rely on git history.
    • For Cursor and Copilot, keep CONVENTIONS.md visible. These tools treat open files as higher-priority context.
    • Run ctx drift periodically to catch stale references before they confuse the agent.
    • The agent playbook instructs the agent to persist context at natural milestones (completed tasks, decisions, gotchas). In practice, this works best when you reinforce the habit: a quick \"anything worth saving?\" after a debugging session goes a long way.
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#next-up","level":2,"title":"Next Up","text":"

    Keeping Context in a Separate Repo →: Store context files outside the project tree for multi-repo or open source setups.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle recipe
    • Multilingual Session Parsing: configure session header prefixes for other languages
    • CLI Reference: all commands and flags
    • Integrations: detailed per-tool integration docs
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multilingual-sessions/","level":1,"title":"Multilingual Session Parsing","text":"","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#the-problem","level":2,"title":"The Problem","text":"

    Your team works across languages. Session files written by AI tools might use headers like # Oturum: 2026-01-15 - API Düzeltme (Turkish) or # セッション: 2026-01-15 - テスト (Japanese) instead of # Session: 2026-01-15 - Fix API.

    By default, ctx only recognizes Session: as a session header prefix. Files with other prefixes are silently skipped during recall export and journal generation: They look like regular Markdown, not sessions.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#tldr","level":2,"title":"TL;DR","text":"

    Add recognized prefixes to .ctxrc:

    session_prefixes:\n  - \"Session:\"      # English (include to keep default)\n  - \"Oturum:\"       # Turkish\n  - \"セッション:\"     # Japanese\n

    Restart your session. All configured prefixes are now recognized.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#how-it-works","level":2,"title":"How It Works","text":"

    The Markdown session parser detects session files by looking for an H1 header that starts with a known prefix followed by a date:

    # Session: 2026-01-15 - Fix API Rate Limiting\n# Oturum: 2026-01-15 - API Düzeltme\n# セッション: 2026-01-15 - テスト\n

    The list of recognized prefixes comes from session_prefixes in .ctxrc. When the key is absent or empty, ctx falls back to the built-in default: [\"Session:\"].

    Date-only headers (# 2026-01-15 - Morning Work) are always recognized regardless of prefix configuration.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#configuration","level":2,"title":"Configuration","text":"","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#adding-a-language","level":3,"title":"Adding a language","text":"

    Add the prefix with a trailing colon to your .ctxrc:

    session_prefixes:\n  - \"Session:\"\n  - \"Sesión:\"       # Spanish\n

    Include Session: explicitly

    When you override session_prefixes, the default is replaced, not extended. If you still want English headers recognized, include \"Session:\" in your list.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#team-setup","level":3,"title":"Team setup","text":"

    Commit .ctxrc to the repo so all team members share the same prefix list. This ensures ctx recall export and journal generation pick up sessions from all team members regardless of language.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#common-prefixes","level":3,"title":"Common prefixes","text":"Language Prefix English Session: Turkish Oturum: Spanish Sesión: French Session: German Sitzung: Japanese セッション: Korean 세션: Portuguese Sessão: Chinese 会话:","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#verifying","level":3,"title":"Verifying","text":"

    After configuring, test with ctx recall list. Sessions with the new prefixes should appear in the output.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#what-this-does-not-do","level":2,"title":"What This Does NOT Do","text":"
    • Change the interface language: ctx output is always English. This setting only controls which session files ctx can parse.
    • Generate headers: ctx never writes session headers. The prefix list is recognition-only (input, not output).
    • Affect JSONL sessions: Claude Code JSONL transcripts don't use header prefixes. This only applies to Markdown session files in .context/sessions/.
    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#see-also","level":2,"title":"See Also","text":"

    See also: Setup Across AI Tools - complete multi-tool setup including Markdown session configuration.

    See also: CLI Reference - full .ctxrc field reference including session_prefixes.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/parallel-worktrees/","level":1,"title":"Parallel Agent Development with Git Worktrees","text":"","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#the-problem","level":2,"title":"The Problem","text":"

    You have a large backlog (10, 20, 30 open tasks) and many of them are independent: docs work that doesn't touch Go code, a new package that doesn't overlap with existing ones, test coverage for a stable module.

    Running one agent at a time means serial execution. You want 3-4 agents working in parallel, each on its own track, without stepping on each other's files.

    Git worktrees solve this.

    Each worktree is a separate working directory with its own branch, but they share the same .git object database. Combined with ctx's persistent context, each agent session picks up the full project state and works independently.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-worktree                                   # 1. group tasks by file overlap\ngit worktree add ../myproject-docs -b work/docs # 2. create worktrees\ncd ../myproject-docs && claude                  # 3. launch agents (one per track)\n/ctx-worktree teardown docs                     # 4. merge back and clean up\n

    TASKS.md will conflict on merge: Accept all [x] completions from both sides.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-worktree Skill Create, list, and tear down worktrees /ctx-next Skill Pick tasks from the backlog for each track git worktree Command Underlying git worktree management git merge Command Merge completed tracks back to main","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-1-assess-the-backlog","level":3,"title":"Step 1: Assess the Backlog","text":"

    Start in your main checkout. Ask the agent to analyze your tasks and group them by blast radius: which files and directories each task touches.

    /ctx-worktree\nLook at TASKS.md and group the pending tasks into 2-3 independent\ntracks based on which files they'd touch. Show me the grouping\nbefore creating anything.\n

    The agent reads TASKS.md, estimates file overlap, and proposes groups:

    Proposed worktree groups:\n\n  work/docs   # recipe updates, blog post (touches: docs/)\n  work/crypto # scratchpad encryption infra (touches: internal/crypto/)\n  work/tests  # recall test coverage (touches: internal/cli/recall/)\n
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-2-create-the-worktrees","level":3,"title":"Step 2: Create the Worktrees","text":"

    Once you approve the grouping, the agent creates worktrees as sibling directories:

    Create the worktrees for those three groups.\n

    Behind the scenes:

    git worktree add ../myproject-docs -b work/docs\ngit worktree add ../myproject-crypto -b work/crypto\ngit worktree add ../myproject-tests -b work/tests\n

    Each worktree is a full working copy on its own branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-3-launch-agents","level":3,"title":"Step 3: Launch Agents","text":"

    Open a separate terminal (or editor window) for each worktree and start a Claude Code session:

    # Terminal 1\ncd ../myproject-docs\nclaude\n\n# Terminal 2\ncd ../myproject-crypto\nclaude\n\n# Terminal 3\ncd ../myproject-tests\nclaude\n

    Each agent sees the full project, including .context/, and can work independently.

    Do Not Initialize Context in Worktrees

    Do not run ctx init in worktrees: The .context directory is already tracked in git.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-4-work","level":3,"title":"Step 4: Work","text":"

    Each agent works through its assigned tasks. They can read TASKS.md to know what's assigned to their track, use /ctx-next to pick the next item, and commit normally on their work/* branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-5-merge-back","level":3,"title":"Step 5: Merge Back","text":"

    As each track finishes, return to the main checkout and merge:

    /ctx-worktree teardown docs\n

    The agent checks for uncommitted changes, merges work/docs into your current branch, removes the worktree, and deletes the branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-6-handle-tasksmd-conflicts","level":3,"title":"Step 6: Handle TASKS.md Conflicts","text":"

    TASKS.md will almost always conflict when merging: Multiple agents will mark different tasks as [x]. This is expected and easy to resolve:

    Accept all completions from both sides. No task should go from [x] back to [ ]. The merge resolution is always additive.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-7-cleanup","level":3,"title":"Step 7: Cleanup","text":"

    After all tracks are merged, verify everything is clean:

    /ctx-worktree list\n

    Should show only the main working tree. All work/* branches should be gone.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't have to use the skill directly for every step. These natural prompts work:

    • \"I have a big backlog. Can we split it across worktrees?\"
    • \"Which of these tasks can run in parallel without conflicts?\"
    • \"Merge the docs track back in.\"
    • \"Clean up all the worktrees, we're done.\"
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#what-works-differently-in-worktrees","level":2,"title":"What Works Differently in Worktrees","text":"

    The encryption key lives at ~/.ctx/.ctx.key (user-level, outside the project). Because all worktrees on the same machine share this path, ctx pad and ctx notify work in worktrees automatically - no special setup needed.

    One thing to watch:

    • Journal enrichment: ctx recall export and ctx journal enrich write files relative to the current working directory. Enrichments created in a worktree stay there and are discarded on teardown. Enrich journals on the main branch after merging: the JSONL session logs are always intact, and you don't lose any data.

    Context Files Will Merge Just Fine

    Tracked context files (TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md) work normally; git handles them.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#tips","level":2,"title":"Tips","text":"
    • 3-4 worktrees max. Beyond that, merge complexity outweighs the parallelism benefit. The skill enforces this limit.
    • Group by package or directory, not by priority. Two high-priority tasks that touch the same files must be in the same track.
    • TASKS.md will conflict on merge. This is normal. Accept all [x] completions: The resolution is always additive.
    • Don't run ctx init in worktrees. The .context/ directory is tracked in git. Running init overwrites shared context files.
    • Name worktrees by concern, not by number. work/docs and work/crypto are more useful than work/track-1 and work/track-2.
    • Commit frequently in each worktree. Smaller commits make merge conflicts easier to resolve.
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#next-up","level":2,"title":"Next Up","text":"

    Back to the beginning: Guide Your Agent →

    Or explore the full recipe list.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#see-also","level":2,"title":"See Also","text":"
    • Running an Unattended AI Agent: for serial autonomous loops instead of parallel tracks
    • Tracking Work Across Sessions: managing the task backlog that feeds into parallelization
    • The Complete Session: the complete session workflow end-to-end, with examples
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/permission-snapshots/","level":1,"title":"Permission Snapshots","text":"","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code's .claude/settings.local.json accumulates one-off permissions every time you click \"Allow\". After busy sessions the file is full of session-specific entries that expand the agent's surface area beyond intent.

    Since settings.local.json is .gitignored, there is no PR review or CI check. The file drifts independently on every machine, and there is no built-in way to reset to a known-good state.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-sanitize-permissions               # audit for dangerous patterns\nctx permission snapshot            # save golden image\n# ... sessions accumulate cruft ...\nctx permission restore             # reset to golden state\n
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#the-solution","level":2,"title":"The Solution","text":"

    Save a curated settings.local.json as a golden image, then restore from it to drop session-accumulated permissions. The golden file (.claude/settings.golden.json) is committed to version control and shared with the team.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx permission snapshot Save settings.local.json as golden image ctx permission restore Reset settings.local.json from golden image /ctx-sanitize-permissions Audit for dangerous patterns before snapshotting","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#step-by-step","level":2,"title":"Step by Step","text":"","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#1-curate-your-permissions","level":3,"title":"1. Curate Your Permissions","text":"

    Start with a clean settings.local.json. Optionally run /ctx-sanitize-permissions to remove dangerous patterns first.

    Review the file manually. Every entry should be there because you decided it belongs, not because you clicked \"Allow\" once during debugging.

    See the Permission Hygiene recipe for recommended defaults.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#2-take-a-snapshot","level":3,"title":"2. Take a Snapshot","text":"
    ctx permission snapshot\n# Saved golden image: .claude/settings.golden.json\n

    This creates a byte-for-byte copy. No re-encoding, no indent changes.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#3-commit-the-golden-file","level":3,"title":"3. Commit the Golden File","text":"
    git add .claude/settings.golden.json\ngit commit -m \"Add permission golden image\"\n

    The golden file is not gitignored (unlike settings.local.json). This is intentional: it becomes a team-shared baseline.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#4-auto-restore-at-the-session-start","level":3,"title":"4. Auto-Restore at the Session Start","text":"

    Add this instruction to your CLAUDE.md:

    ## On Session Start\n\nRun `ctx permission restore` to reset permissions to the golden image.\n

    The agent will restore the golden image at the start of every session, automatically dropping any permissions accumulated during previous sessions.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#5-update-when-intentional-changes-are-made","level":3,"title":"5. Update When Intentional Changes Are Made","text":"

    When you add a new permanent permission (not a one-off debugging entry):

    # Edit settings.local.json with the new permission\n# Then update the golden image:\nctx permission snapshot\ngit add .claude/settings.golden.json\ngit commit -m \"Update permission golden image: add cargo test\"\n
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember exact commands. These natural-language prompts work with agents trained on the ctx playbook:

    What you say What happens \"Save my current permissions as baseline\" Agent runs ctx permission snapshot \"Reset permissions to the golden image\" Agent runs ctx permission restore \"Clean up my permissions\" Agent runs /ctx-sanitize-permissions then snapshot \"What permissions did I accumulate?\" Agent diffs local vs golden","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#next-up","level":2,"title":"Next Up","text":"

    Turning Activity into Content →: Generate blog posts, changelogs, and journal sites from your project activity.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#see-also","level":2,"title":"See Also","text":"
    • Permission Hygiene: recommended defaults and maintenance workflow
    • CLI Reference: ctx permission: full command documentation
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/prompt-templates/","level":1,"title":"Reusable Prompt Templates","text":"","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#the-problem","level":2,"title":"The Problem","text":"

    The gap between \"raw instruction typed into chat\" and \"full SKILL.md skill\" has no lightweight option. A user who wants a consistent code review checklist or refactoring guard rails has two bad choices:

    • Author a full skill (high friction, needs frontmatter, rebuild to embed)
    • Keep prompts in their head or a scratch file (no discoverability, no sharing)
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                         # stamps starter prompts\nctx prompt list                  # see available prompts\nctx prompt show code-review      # print a prompt\nctx prompt add my-prompt --stdin # create from stdin\nctx prompt rm my-prompt          # delete\n

    Or in your AI assistant: /ctx-prompt code-review

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx prompt list Command List available prompt templates ctx prompt show <name> Command Print prompt content to stdout ctx prompt add <name> Command Create from embedded template or stdin ctx prompt rm <name> Command Delete a prompt template ctx init Command Stamps starter prompts during initialization /ctx-prompt Skill List or apply prompt templates in-session","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#creating-prompts","level":3,"title":"Creating Prompts","text":"

    From starter templates: ctx init stamps three starters:

    • code-review: review checklist anchored to project conventions
    • refactor: refactoring with guard rails (tests first, preserve behavior)
    • explain: explain code for onboarding and knowledge transfer

    From embedded templates:

    ctx prompt add code-review    # creates from built-in template\nctx prompt add refactor       # creates from built-in template\n

    Custom prompts from stdin:

    echo \"# Debug Checklist\n\n1. Reproduce the issue\n2. Check error logs\n3. Add targeted logging\n4. Isolate the failing component\" | ctx prompt add debug --stdin\n
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#using-prompts","level":3,"title":"Using Prompts","text":"

    In your AI assistant: invoke the skill:

    /ctx-prompt code-review\n

    The agent retrieves the prompt and follows its instructions in your current context. If no name is given, it lists available prompts.

    From the CLI: pipe into other tools:

    ctx prompt show code-review    # print to stdout\n
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#sharing-prompts","level":3,"title":"Sharing Prompts","text":"

    Prompt templates live in .context/prompts/ and are committed to git by default. Your whole team shares the same prompts. For private prompts, add .context/prompts/ to .gitignore.

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#tips","level":2,"title":"Tips","text":"

    Keep prompts short and focused. A good prompt template is 5-15 lines. If it's longer, it's probably a skill.

    Anchor to project context. Reference .context/CONVENTIONS.md or .context/ARCHITECTURE.md in your prompts: the AI will read those files for project-specific patterns.

    Name prompts for the action, not the content. Use code-review not code-review-checklist. The .md extension is added automatically.

    Prompts are not skills. They have no frontmatter, no trigger rules, no allowed-tools. They are plain markdown instructions. If you need automation, create a skill instead.

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: full command documentation
    • Context Files: structure of .context/
    • Detecting and Fixing Drift: keeping context clean
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/publishing/","level":1,"title":"Turning Activity into Content","text":"","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-problem","level":2,"title":"The Problem","text":"

    Your .context/ directory is full of decisions, learnings, and session history.

    Your git log tells the story of a project evolving.

    But none of this is visible to anyone outside your terminal.

    You want to turn this raw activity into:

    • a browsable journal site,
    • blog posts,
    • changelog posts.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#tldr","level":2,"title":"TL;DR","text":"
    ctx recall export --all             # 1. export sessions to markdown\n\n/ctx-journal-enrich-all             # 2. add metadata and tags\n\nctx journal site --serve            # 3. build and serve the journal\n\n/ctx-blog about the caching layer   # 4. draft a blog post\n/ctx-blog-changelog v0.1.0 \"v0.2\"   # 5. write a changelog post\n

    Read on for details on each stage.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx recall export Command Export session JSONL to editable markdown ctx journal site Command Generate a static site from journal entries ctx journal obsidian Command Generate an Obsidian vault from journal entries ctx serve Command Serve any zensical directory (default: journal) ctx site feed Command Generate Atom feed from finalized blog posts make journal Makefile Shortcut for export + site rebuild /ctx-journal-enrich-all Skill Full pipeline: export if needed, then batch-enrich (recommended) /ctx-journal-enrich Skill Add metadata, summaries, and tags to one entry /ctx-blog Skill Draft a blog post from recent project activity /ctx-blog-changelog Skill Write a themed post from a commit range","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-1-export-sessions-to-markdown","level":3,"title":"Step 1: Export Sessions to Markdown","text":"

    Raw session data lives as JSONL files in Claude Code's internal storage. The first step is converting these into readable, editable markdown.

    # Export all sessions from the current project\nctx recall export --all\n\n# Export from all projects (if you work across multiple repos)\nctx recall export --all --all-projects\n\n# Export a single session by ID or slug\nctx recall export abc123\nctx recall export gleaming-wobbling-sutherland\n

    Exported files land in .context/journal/ as individual Markdown files with session metadata and the full conversation transcript.

    --all is safe by default: Only new sessions are exported. Existing files are skipped. Use --regenerate to re-export existing files (YAML frontmatter is preserved). Use --regenerate --keep-frontmatter=false -y to regenerate everything including frontmatter.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-2-enrich-entries-with-metadata","level":3,"title":"Step 2: Enrich Entries with Metadata","text":"

    Raw entries have timestamps and conversations but lack the structured metadata that makes a journal searchable. Use /ctx-journal-enrich-all to process your entire backlog at once:

    /ctx-journal-enrich-all\n

    The skill finds all unenriched entries, filters out noise (suggestion sessions, very short sessions, multipart continuations), and processes each one by extracting titles, topics, technologies, and summaries from the conversation.

    For large backlogs (20+ entries), it can spawn subagents to process entries in parallel.

    To enrich a single entry instead:

    /ctx-journal-enrich twinkly-stirring-kettle\n/ctx-journal-enrich 2026-01-24\n

    After enrichment, an entry gains YAML frontmatter:

    ---\ntitle: \"Implement Redis caching for API endpoints\"\ndate: 2026-01-24\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nkey_files:\n  - internal/api/middleware/cache.go\n  - internal/cache/redis.go\n---\n

    This metadata powers better navigation in the journal site:

    • titles replace slugs,
    • summaries appear in the index,
    • and search covers topics and technologies.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-3-generate-the-journal-site","level":3,"title":"Step 3: Generate the Journal Site","text":"

    With entries exported and enriched, generate the static site:

    # Generate site files\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate and serve locally (opens at http://localhost:8000)\nctx journal site --serve\n\n# Custom output directory\nctx journal site --output ~/my-journal\n

    The site is generated in .context/journal-site/ by default. It uses zensical for static site generation (pipx install zensical).

    Or use the Makefile shortcut that combines export and rebuild:

    make journal\n

    This runs ctx recall export --all followed by ctx journal site --build, then reminds you to enrich before rebuilding. To serve the built site, use make journal-serve or ctx serve (serve-only, no regeneration).

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#alternative-export-to-obsidian-vault","level":3,"title":"Alternative: Export to Obsidian Vault","text":"

    If you use Obsidian for knowledge management, generate a vault instead of (or alongside) the static site:

    ctx journal obsidian\nctx journal obsidian --output ~/vaults/ctx-journal\n

    This produces an Obsidian-ready directory with wikilinks, MOC (Map of Content) pages for topics/files/types, and a \"Related Sessions\" footer on each entry for graph connectivity. Open the output directory in Obsidian as a vault.

    The vault uses the same enriched source entries as the static site. Both outputs can coexist: The static site goes to .context/journal-site/, the vault to .context/journal-obsidian/.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-4-draft-blog-posts-from-activity","level":3,"title":"Step 4: Draft Blog Posts from Activity","text":"

    When your project reaches a milestone worth sharing, use /ctx-blog to draft a post from recent activity. The skill gathers context from multiple sources: git log, DECISIONS.md, LEARNINGS.md, completed tasks, and journal entries.

    /ctx-blog about the caching layer we just built\n/ctx-blog last week's refactoring work\n/ctx-blog lessons learned from the migration\n

    The skill gathers recent commits, decisions, and learnings; identifies a narrative arc; drafts an outline for approval; writes the full post; and saves it to docs/blog/YYYY-MM-DD-slug.md.

    Posts are written in first person with code snippets, commit references, and an honest discussion of what went wrong.

    The Output is zensical-Flavored Markdown

    The blog skills produce Markdown tuned for a zensical site: topics: frontmatter (zensical's tag field), a docs/blog/ output path, and a banner image reference.

    The content is still standard Markdown and can be adapted to other static site generators, but the defaults assume a zensical project structure.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-5-write-changelog-posts-from-commit-ranges","level":3,"title":"Step 5: Write Changelog Posts from Commit Ranges","text":"

    For release notes or \"what changed\" posts, /ctx-blog-changelog takes a starting commit and a theme, then analyzes everything that changed:

    /ctx-blog-changelog 040ce99 \"building the journal system\"\n/ctx-blog-changelog HEAD~30 \"what's new in v0.2.0\"\n/ctx-blog-changelog v0.1.0 \"the road to v0.2.0\"\n

    The skill diffs the commit range, identifies the most-changed files, and constructs a narrative organized by theme rather than chronology, including a key commits table and before/after comparisons.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-6-generate-the-blog-feed","level":3,"title":"Step 6: Generate the Blog Feed","text":"

    After publishing blog posts, generate the Atom feed so readers and automation can discover new content:

    ctx site feed\n

    This scans docs/blog/ for finalized posts (reviewed_and_finalized: true), extracts title, date, author, topics, and summary, and writes a valid Atom 1.0 feed to site/feed.xml. The feed is also generated automatically as part of make site.

    The feed is available at ctx.ist/feed.xml.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-conversational-approach","level":2,"title":"The Conversational Approach","text":"

    You can also drive your publishing anytime with natural language:

    \"write about what we did this week\"\n\"turn today's session into a blog post\"\n\"make a changelog post covering everything since the last release\"\n\"enrich the last few journal entries\"\n

    The agent has full visibility into your .context/ state (tasks completed, decisions recorded, learnings captured), so its suggestions are grounded in what actually happened.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    The full pipeline from raw transcripts to published content:

    # 1. Export all sessions\nctx recall export --all\n\n# 2. In Claude Code: enrich all entries with metadata\n/ctx-journal-enrich-all\n\n# 3. Build and serve the journal site\nmake journal\nmake journal-serve\n\n# 3b. Or generate an Obsidian vault\nctx journal obsidian\n\n# 4. In Claude Code: draft a blog post\n/ctx-blog about the features we shipped this week\n\n# 5. In Claude Code: write a changelog post\n/ctx-blog-changelog v0.1.0 \"what's new in v0.2.0\"\n

    The journal pipeline is idempotent at every stage. You can rerun ctx recall export --all without losing enrichment. You can rebuild the site as many times as you want.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#tips","level":2,"title":"Tips","text":"
    • Export regularly. Run ctx recall export --all after each session to keep your journal current. Only new sessions are exported: Existing files are skipped by default.
    • Use batch enrichment. /ctx-journal-enrich-all filters noise (suggestion sessions, trivial sessions, multipart continuations) so you do not have to decide what is worth enriching.
    • Keep journal files in .gitignore. Session journals can contain sensitive data: file contents, commands, internal discussions, and error messages with stack traces. Add .context/journal/ and .context/journal-site/ to .gitignore.
    • Use /ctx-blog for narrative posts and /ctx-blog-changelog for release posts. One finds a story in recent activity, the other explains a commit range by theme.
    • Edit the drafts. These skills produce drafts, not final posts. Review the narrative, add your perspective, and remove anything that does not serve the reader.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#next-up","level":2,"title":"Next Up","text":"

    Running an Unattended AI Agent →: Set up an AI agent that works through tasks overnight without you at the keyboard.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#see-also","level":2,"title":"See Also","text":"
    • Session Journal: journal system, enrichment schema
    • CLI Reference: ctx recall: export, list, show session history
    • CLI Reference: ctx journal site: static site generation
    • CLI Reference: ctx journal obsidian: Obsidian vault export
    • CLI Reference: ctx serve: serve-only (no regeneration)
    • Browsing and Enriching Past Sessions: journal browsing workflow
    • The Complete Session: capturing context during a session
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/scratchpad-sync/","level":1,"title":"Syncing Scratchpad Notes Across Machines","text":"","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#the-problem","level":2,"title":"The Problem","text":"

    You work from multiple machines: a desktop and a laptop, or a local machine and a remote dev server.

    The scratchpad entries are encrypted. The ciphertext (.context/scratchpad.enc) travels with git, but the encryption key lives outside the project at ~/.ctx/.ctx.key and is never committed. Without the key on each machine, you cannot read or write entries.

    How do you distribute the key and keep the scratchpad in sync?

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                                                  # 1. generates key\nscp ~/.ctx/.ctx.key user@machine-b:~/.ctx/.ctx.key        # 2. copy key\nchmod 600 ~/.ctx/.ctx.key                                 # 3. secure it\n# Normal git push/pull syncs the encrypted scratchpad.enc\n# On conflict: ctx pad resolve → rebuild → git add + commit\n

    Finding Your Key File

    The key is always at ~/.ctx/.ctx.key - one key, one machine.

    Treat the Key Like a Password

    The scratchpad key is the only thing protecting your encrypted entries.

    Store a backup in a secure enclave such as a password manager, and treat it with the same care you would give passwords, certificates, or API tokens.

    Anyone with the key can decrypt every scratchpad entry.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init CLI command Initialize context (generates the key automatically) ctx pad add CLI command Add a scratchpad entry ctx pad rm CLI command Remove a scratchpad entry ctx pad edit CLI command Edit a scratchpad entry ctx pad resolve CLI command Show both sides of a merge conflict ctx pad merge CLI command Merge entries from other scratchpad files ctx pad import CLI command Bulk-import lines from a file ctx pad export CLI command Export blob entries to a directory scp Shell Copy the key file between machines git push / git pull Shell Sync the encrypted file via git /ctx-pad Skill Natural language interface to pad commands","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-1-initialize-on-machine-a","level":3,"title":"Step 1: Initialize on Machine A","text":"

    Run ctx init on your first machine. The key is created automatically at ~/.ctx/.ctx.key:

    ctx init\n# ...\n# Created ~/.ctx/.ctx.key (0600)\n# Created .context/scratchpad.enc\n

    The key lives outside the project directory and is never committed. The .enc file is tracked in git.

    Key Folder Change (v0.7.0+)

    If you built ctx from source or upgraded past v0.6.0, the key location changed to ~/.ctx/.ctx.key. Check these legacy folders and copy your key manually:

    # Old locations (pick whichever exists)\nls ~/.local/ctx/keys/        # pre-v0.7.0 user-level\nls .context/.ctx.key         # pre-v0.6.0 project-local\n\n# Copy to the new location\nmkdir -p ~/.ctx && chmod 700 ~/.ctx\ncp <old-key-path> ~/.ctx/.ctx.key\nchmod 600 ~/.ctx/.ctx.key\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-2-copy-the-key-to-machine-b","level":3,"title":"Step 2: Copy the Key to Machine B","text":"

    Use any secure transfer method. The key is always at ~/.ctx/.ctx.key:

    # scp - create the target directory first\nssh user@machine-b \"mkdir -p ~/.ctx && chmod 700 ~/.ctx\"\nscp ~/.ctx/.ctx.key user@machine-b:~/.ctx/.ctx.key\n\n# Or use a password manager, USB drive, etc.\n

    Set permissions on Machine B:

    chmod 600 ~/.ctx/.ctx.key\n

    Secure the Transfer

    The key is a raw 256-bit AES key. Anyone with the key can decrypt the scratchpad. Use an encrypted channel (SSH, password manager, vault).

    Never paste it in plaintext over email or chat.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-3-normal-pushpull-workflow","level":3,"title":"Step 3: Normal Push/Pull Workflow","text":"

    The encrypted file is committed, so standard git sync works:

    # Machine A: add entries and push\nctx pad add \"staging API key: sk-test-abc123\"\ngit add .context/scratchpad.enc\ngit commit -m \"Update scratchpad\"\ngit push\n\n# Machine B: pull and read\ngit pull\nctx pad\n#   1. staging API key: sk-test-abc123\n

    Both machines have the same key, so both can decrypt the same .enc file.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-4-read-and-write-from-either-machine","level":3,"title":"Step 4: Read and Write from Either Machine","text":"

    Once the key is distributed, all ctx pad commands work identically on both machines. Entries added on Machine A are visible on Machine B after a git pull, and vice versa.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-5-handle-merge-conflicts","level":3,"title":"Step 5: Handle Merge Conflicts","text":"

    If both machines add entries between syncs, pulling will create a merge conflict on .context/scratchpad.enc. Git cannot merge binary (encrypted) content automatically.

    The fastest approach is ctx pad merge: It reads both conflict sides, deduplicates, and writes the union:

    # Extract theirs to a temp file, then merge it in\ngit show :3:.context/scratchpad.enc > /tmp/theirs.enc\ngit checkout --ours .context/scratchpad.enc\nctx pad merge /tmp/theirs.enc\n\n# Done: Commit the resolved scratchpad:\ngit add .context/scratchpad.enc\ngit commit -m \"Resolve scratchpad merge conflict\"\n

    Alternatively, use ctx pad resolve to inspect both sides manually:

    ctx pad resolve\n# === Ours (this machine) ===\n#   1. staging API key: sk-test-abc123\n#   2. check DNS after deploy\n#\n# === Theirs (incoming) ===\n#   1. staging API key: sk-test-abc123\n#   2. new endpoint: api.example.com/v2\n

    Then reconstruct the merged scratchpad:

    # Start fresh with all entries from both sides\nctx pad add \"staging API key: sk-test-abc123\"\nctx pad add \"check DNS after deploy\"\nctx pad add \"new endpoint: api.example.com/v2\"\n\n# Mark the conflict resolved\ngit add .context/scratchpad.enc\ngit commit -m \"Resolve scratchpad merge conflict\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#merge-conflict-walkthrough","level":2,"title":"Merge Conflict Walkthrough","text":"

    Here's a full scenario showing how conflicts arise and how to resolve them:

    1. Both machines start in sync (1 entry):

    Machine A: 1. staging API key: sk-test-abc123\nMachine B: 1. staging API key: sk-test-abc123\n

    2. Both add entries independently:

    Machine A adds: \"check DNS after deploy\"\nMachine B adds: \"new endpoint: api.example.com/v2\"\n

    3. Machine A pushes first. Machine B pulls and gets a conflict:

    git pull\n# CONFLICT (content): Merge conflict in .context/scratchpad.enc\n

    4. Machine B runs ctx pad resolve:

    ctx pad resolve\n# === Ours ===\n#   1. staging API key: sk-test-abc123\n#   2. new endpoint: api.example.com/v2\n#\n# === Theirs ===\n#   1. staging API key: sk-test-abc123\n#   2. check DNS after deploy\n

    5. Rebuild with entries from both sides and commit:

    # Clear and rebuild (or use the skill to guide you)\nctx pad add \"staging API key: sk-test-abc123\"\nctx pad add \"check DNS after deploy\"\nctx pad add \"new endpoint: api.example.com/v2\"\n\ngit add .context/scratchpad.enc\ngit commit -m \"Merge scratchpad: keep entries from both machines\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#conversational-approach","level":3,"title":"Conversational Approach","text":"

    When working with an AI assistant, you can resolve conflicts naturally:

    You: \"I have a scratchpad merge conflict. Can you resolve it?\"\n\nAgent: \"Let me extract theirs and merge it in.\"\n       [runs git show :3:.context/scratchpad.enc > /tmp/theirs.enc]\n       [runs git checkout --ours .context/scratchpad.enc]\n       [runs ctx pad merge /tmp/theirs.enc]\n       \"Merged 2 new entries (1 duplicate skipped). Want me to\n       commit the resolution?\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#tips","level":2,"title":"Tips","text":"
    • Back up the key: If you lose it, you lose access to all encrypted entries. Store a copy in your password manager.
    • One key per project: Each ctx init generates a unique key. Don't reuse keys across projects.
    • Keys work in worktrees: Because the key lives at ~/.ctx/.ctx.key (outside the project), git worktrees on the same machine share the key automatically. No special setup needed.
    • Plaintext fallback for non-sensitive projects: If encryption adds friction and you have nothing sensitive, set scratchpad_encrypt: false in .ctxrc. Merge conflicts become trivial text merges.
    • Never commit the key: The key is stored outside the project at ~/.ctx/.ctx.key and should never be copied into the repository.
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#next-up","level":2,"title":"Next Up","text":"

    Hook Output Patterns →: Choose the right output pattern for your Claude Code hooks.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#see-also","level":2,"title":"See Also","text":"
    • Scratchpad: feature overview, all commands, when to use scratchpad vs context files
    • Persisting Decisions, Learnings, and Conventions: for structured knowledge that outlives the scratchpad
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-with-claude/","level":1,"title":"Using the Scratchpad","text":"","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#the-problem","level":2,"title":"The Problem","text":"

    During a session you accumulate quick notes, reminders, intermediate values, and sometimes sensitive tokens. They don't fit TASKS.md (not work items) or DECISIONS.md (not decisions). They don't have the structured fields that LEARNINGS.md requires.

    Without somewhere to put them, they get lost between sessions.

    How do you capture working memory that persists across sessions without polluting your structured context files?

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#tldr","level":2,"title":"TL;DR","text":"
    ctx pad add \"check DNS propagation after deploy\"\nctx pad         # list entries\nctx pad show 1  # print entry (pipe-friendly)\n

    Entries are encrypted at rest and travel with git.

    Use the /ctx-pad skill to manage entries from inside your AI session.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx pad CLI command List all scratchpad entries ctx pad show N CLI command Output raw text of entry N (pipe-friendly) ctx pad add CLI command Add a new entry ctx pad edit CLI command Replace, append to, or prepend to an entry ctx pad add --file CLI command Ingest a file as a blob entry ctx pad show N --out CLI command Extract a blob entry to a file ctx pad rm CLI command Remove an entry ctx pad mv CLI command Reorder entries ctx pad import CLI command Bulk-import lines from a file (or stdin) ctx pad export CLI command Export all blob entries to a directory /ctx-pad Skill Natural language interface to all pad commands","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-1-add-a-note-naturally","level":3,"title":"Step 1: Add a Note Naturally","text":"

    You don't need to remember any syntax. Just tell your assistant what to jot down:

    You: \"jot down: check DNS propagation after deploy\"\n\nAgent: \"Added to scratchpad:\n  1. check DNS propagation after deploy\"\n

    Behind the scenes, the agent runs ctx pad add \"check DNS propagation after deploy\".

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-2-view-your-scratchpad","level":3,"title":"Step 2: View Your Scratchpad","text":"
    You: \"show my scratchpad\"\n\nAgent: \"Your scratchpad has 3 entries:\n  1. check DNS propagation after deploy\n  2. staging API endpoint: api.staging.example.com/v2\n  3. retry limit should be 5, not 3\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-3-edit-an-entry","level":3,"title":"Step 3: Edit an Entry","text":"
    You: \"update entry 2 to include the new endpoint\"\n\nAgent: \"Updated entry 2:\n  was: staging API endpoint: api.staging.example.com/v2\n  now: staging API endpoint: api.prod.example.com/v2\"\n

    For partial edits, the agent can use --append or --prepend:

    You: \"append the port number to entry 2\"\n\nAgent: \"Updated entry 2:\n  staging API endpoint: api.prod.example.com/v2 :8443\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-4-compose-entries","level":3,"title":"Step 4: Compose Entries","text":"

    Use ctx pad show N to pipe entry content into other operations:

    You: \"append the content of entry 3 to entry 1\"\n\nAgent: [runs ctx pad edit 1 --append \"$(ctx pad show 3)\"]\n       \"Done. Entry 1 is now:\n        check DNS propagation after deploy retry limit should be 5, not 3\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-5-reorder-by-priority","level":3,"title":"Step 5: Reorder by Priority","text":"
    You: \"move entry 4 to the top\"\n\nAgent: [runs ctx pad mv 4 1]\n       \"Moved entry 4 to position 1. Scratchpad reordered.\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-6-clean-up","level":3,"title":"Step 6: Clean Up","text":"
    You: \"remove entry 2, it's done\"\n\nAgent: [runs ctx pad rm 2]\n       \"Removed entry 2. 3 entries remaining.\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-7-store-a-file-as-a-blob","level":3,"title":"Step 7: Store a File as a Blob","text":"

    The scratchpad can hold small files (up to 64 KB) as encrypted blob entries. The file is base64-encoded and stored alongside a label you provide:

    # Ingest a file: the first argument is the label\nctx pad add \"deploy config\" --file ./deploy.yaml\n\n# List shows the label with a [BLOB] marker\nctx pad\n#   1. check DNS propagation after deploy\n#   2. deploy config [BLOB]\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-8-extract-a-blob","level":3,"title":"Step 8: Extract a Blob","text":"

    Use show --out to write the decoded file back to disk:

    # Write blob entry to a file\nctx pad show 2 --out ./recovered-deploy.yaml\n\n# Or print to stdout (for piping)\nctx pad show 2 | head -5\n

    Blob entries are encrypted identically to text entries: They're just base64-encoded before encryption. The --out flag decodes and writes the raw bytes.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-9-bulk-import-notes","level":3,"title":"Step 9: Bulk Import Notes","text":"

    When you have a file with many notes (one per line), import them in bulk instead of adding one at a time:

    # Import from a file: Each non-empty line becomes an entry\nctx pad import notes.txt\n\n# Or pipe from stdin\ngrep TODO *.go | ctx pad import -\n

    All entries are written in a single encrypt/write cycle, regardless of how many lines the file contains.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-10-export-blobs-to-disk","level":3,"title":"Step 10: Export Blobs to Disk","text":"

    Export all blob entries to a directory as individual files. Each blob's label becomes the filename:

    # Export to a directory (created if needed)\nctx pad export ./ideas\n\n# Preview what would be exported\nctx pad export --dry-run ./ideas\n\n# Force overwrite existing files\nctx pad export --force ./backup\n

    When a file already exists, a unix timestamp is prepended to the filename to avoid collisions. Use --force to overwrite instead.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#using-ctx-pad-in-a-session","level":2,"title":"Using /ctx-pad in a Session","text":"

    Invoke the /ctx-pad skill first, then describe what you want in natural language. Without the skill prefix, the agent may route your request to TASKS.md or another context file instead of the scratchpad.

    You: /ctx-pad jot down: check DNS after deploy\nYou: /ctx-pad show my scratchpad\nYou: /ctx-pad delete entry 3\n

    Once the skill is active, it translates intent into commands:

    You say (after /ctx-pad) What the agent does \"jot down: check DNS after deploy\" ctx pad add \"check DNS after deploy\" \"remember this: retry limit is 5\" ctx pad add \"retry limit is 5\" \"show my scratchpad\" / \"what's on my pad\" ctx pad \"show me entry 3\" ctx pad show 3 \"delete the third one\" / \"remove entry 3\" ctx pad rm 3 \"change entry 2 to ...\" ctx pad edit 2 \"new text\" \"append ' +important' to entry 3\" ctx pad edit 3 --append \" +important\" \"prepend 'URGENT:' to entry 1\" ctx pad edit 1 --prepend \"URGENT: \" \"prioritize entry 4\" / \"move to the top\" ctx pad mv 4 1 \"import my notes from notes.txt\" ctx pad import notes.txt \"export all blobs to ./ideas\" ctx pad export ./ideas

    When in Doubt, Use the CLI Directly

    The ctx pad commands work the same whether you run them yourself or let the skill invoke them.

    If the agent misroutes a request, fall back to ctx pad add \"...\" in your terminal.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#when-to-use-scratchpad-vs-context-files","level":2,"title":"When to Use Scratchpad vs Context Files","text":"Situation Use Temporary reminders (\"check X after deploy\") Scratchpad Session-start reminders (\"remind me next session\") ctx remind Working values during debugging (ports, endpoints, counts) Scratchpad Sensitive tokens or API keys (short-term storage) Scratchpad Quick notes that don't fit anywhere else Scratchpad Work items with completion tracking TASKS.md Trade-offs between alternatives with rationale DECISIONS.md Reusable lessons with context/lesson/application LEARNINGS.md Codified patterns and standards CONVENTIONS.md

    Decision Guide

    • If it has structured fields (context, rationale, lesson, application), it belongs in a context file like DECISIONS.md or LEARNINGS.md.
    • If it's a work item you'll mark done, it belongs in TASKS.md.
    • If you want a message relayed VERBATIM at the next session start, it belongs in ctx remind.
    • If it's a quick note, reminder, or working value (especially if it's sensitive or ephemeral) it belongs on the scratchpad.

    Scratchpad Is Not a Junk Drawer

    The scratchpad is for working memory, not long-term storage.

    If a note is still relevant after several sessions, promote it:

    A persistent reminder becomes a task, a recurring value becomes a convention, a hard-won insight becomes a learning.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#tips","level":2,"title":"Tips","text":"
    • Entries persist across sessions: The scratchpad is committed (encrypted) to git, so entries survive session boundaries. Pick up where you left off.
    • Entries are numbered and reorderable: Use ctx pad mv to put high-priority items at the top.
    • ctx pad show N enables unix piping: Output raw entry text with no numbering prefix. Compose with --append, --prepend, or other shell tools.
    • Never mention the key file contents to the AI: The agent knows how to use ctx pad commands but should never read or print the encryption key (~/.ctx/.ctx.key) directly.
    • Encryption is transparent: You interact with plaintext; the encryption/decryption happens automatically on every read/write.
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#next-up","level":2,"title":"Next Up","text":"

    Syncing Scratchpad Notes Across Machines →: Distribute encryption keys and scratchpad data across environments.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#see-also","level":2,"title":"See Also","text":"
    • Scratchpad: feature overview, all commands, encryption details, plaintext override
    • Persisting Decisions, Learnings, and Conventions: for structured knowledge that outlives the scratchpad
    • The Complete Session: full session lifecycle showing how the scratchpad fits into the broader workflow
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/session-archaeology/","level":1,"title":"Browsing and Enriching Past Sessions","text":"","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-problem","level":2,"title":"The Problem","text":"

    After weeks of AI-assisted development you have dozens of sessions scattered across JSONL files in ~/.claude/projects/. Finding the session where you debugged the Redis connection pool, or remembering what you decided about the caching strategy three Tuesdays ago, often means grepping raw JSON.

    There is no table of contents, no search, and no summaries.

    This recipe shows how to turn that raw session history into a browsable, searchable, and enriched journal site you can navigate in your browser.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#tldr","level":2,"title":"TL;DR","text":"

    Export and Generate

    ctx recall export --all\nctx journal site --serve\n

    Enrich

    /ctx-journal-enrich-all\n

    Rebuild

    ctx journal site --serve\n

    Read on for what each stage does and why.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx recall list Command List parsed sessions with metadata ctx recall show Command Inspect a specific session in detail ctx recall export Command Export sessions to editable journal Markdown ctx journal site Command Generate a static site from journal entries ctx journal obsidian Command Generate an Obsidian vault from journal entries ctx serve Command Serve any zensical directory (default: journal) /ctx-recall Skill Browse sessions inside your AI assistant /ctx-journal-enrich Skill Add frontmatter metadata to a single entry /ctx-journal-enrich-all Skill Full pipeline: export if needed, then batch-enrich","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-workflow","level":2,"title":"The Workflow","text":"

    The session journal follows a four-stage pipeline.

    Each stage is idempotent and safe to re-run:

    By default, each stage skips entries that have already been processed.

    export -> enrich -> rebuild\n
    Stage Tool What it does Skips if Where Export ctx recall export --all Converts session JSONL to Markdown File already exists (safe default) CLI or agent Enrich /ctx-journal-enrich-all Adds frontmatter, summaries, topic tags Frontmatter already present Agent only Rebuild ctx journal site --build Generates browsable static HTML N/A CLI only Obsidian ctx journal obsidian Generates Obsidian vault with wikilinks N/A CLI only

    Where Do You Run Each Stage?

    Export (Steps 1 to 3) works equally well from the terminal or inside your AI assistant via /ctx-recall. The CLI is fine here: the agent adds no special intelligence, it just runs the same command.

    Enrich (Step 4) requires the agent: it reads conversation content and produces structured metadata.

    Rebuild and serve (Step 5) is a terminal operation that starts a long-running server.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-1-list-your-sessions","level":3,"title":"Step 1: List Your Sessions","text":"

    Start by seeing what sessions exist for the current project:

    ctx recall list\n

    Sample output:

    Sessions (newest first)\n=======================\n\n  Slug                           Project   Date         Duration  Turns  Tokens\n  gleaming-wobbling-sutherland   ctx       2026-02-07   1h 23m    47     82,341\n  twinkly-stirring-kettle        ctx       2026-02-06   0h 45m    22     38,102\n  bright-dancing-hopper          ctx       2026-02-05   2h 10m    63     124,500\n  quiet-flowing-dijkstra         ctx       2026-02-04   0h 18m    11     15,230\n  ...\n

    Slugs Look Cryptic?

    These auto-generated slugs (gleaming-wobbling-sutherland) are hard to recognize later.

    Use /ctx-journal-enrich to add human-readable titles, topic tags, and summaries to exported journal entries, making them easier to find.

    Filter by project or tool if you work across multiple codebases:

    ctx recall list --project ctx --limit 10\nctx recall list --tool claude-code\nctx recall list --all-projects\n
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-2-inspect-a-specific-session","level":3,"title":"Step 2: Inspect a Specific Session","text":"

    Before exporting everything, inspect a single session to see its metadata and conversation summary:

    ctx recall show --latest\n

    Or look up a specific session by its slug, partial ID, or UUID:

    ctx recall show gleaming-wobbling-sutherland\nctx recall show twinkly\nctx recall show abc123\n

    Add --full to see the complete message content instead of the summary view:

    ctx recall show --latest --full\n

    This is useful for checking what happened before deciding whether to export and enrich it.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-3-export-sessions-to-the-journal","level":3,"title":"Step 3: Export Sessions to the Journal","text":"

    Export converts raw session data into editable Markdown files in .context/journal/:

    # Export all sessions from the current project\nctx recall export --all\n\n# Export a single session\nctx recall export gleaming-wobbling-sutherland\n\n# Include sessions from all projects\nctx recall export --all --all-projects\n

    --keep-frontmatter=false Discards Enrichments

    --keep-frontmatter=false discards enriched YAML frontmatter during regeneration.

    Back up your journal before using this flag.

    Each exported file contains session metadata (date, time, duration, model, project, git branch), a tool usage summary, and the full conversation transcript.

    Re-exporting is safe. Running ctx recall export --all only exports new sessions: Existing files are never touched. Use --dry-run to preview what would be exported without writing anything.

    To re-export existing files (e.g., after a format improvement), use --regenerate: Conversation content is regenerated while preserving any YAML frontmatter you or the enrichment skill has added. You'll be prompted before any files are overwritten.

    --regenerate Replaces the Markdown Body

    --regenerate preserves YAML frontmatter but replaces the entire Markdown body with freshly generated content from the source JSONL.

    If you manually edited the conversation transcript (added notes, redacted sensitive content, restructured sections), those edits will be lost.

    BACK UP YOUR JOURNAL FIRST.

    To protect entries you've hand-edited, you can explicitly lock them:

    ctx recall lock <pattern>\n

    Locked entries are always skipped, regardless of flags.

    If you prefer to add locked: true directly in frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json:

    ctx recall sync\n

    See ctx recall lock --help and ctx recall sync --help for details.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-4-enrich-with-metadata","level":3,"title":"Step 4: Enrich with Metadata","text":"

    Raw exports have timestamps and transcripts but lack the semantic metadata that makes sessions searchable: topics, technology tags, outcome status, and summaries. The /ctx-journal-enrich* skills add this structured frontmatter.

    Locked entries are skipped by enrichment skills, just as they are by export. Lock entries you want to protect before running batch enrichment.

    Batch enrichment (recommended):

    /ctx-journal-enrich-all\n

    The skill finds all unenriched entries, filters out noise (suggestion sessions, very short sessions, multipart continuations), and processes each one by extracting titles, topics, technologies, and summaries from the conversation.

    It shows you a grouped summary before applying changes so you can scan quickly rather than reviewing one by one.

    For large backlogs (20+ entries), the skill can spawn subagents to process entries in parallel.

    Single-entry enrichment:

    /ctx-journal-enrich twinkly\n/ctx-journal-enrich 2026-02-06\n

    Each enriched entry gets YAML frontmatter like this:

    ---\ntitle: \"Implement Redis caching middleware\"\ndate: 2026-02-06\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nlibraries:\n  - go-redis/redis\nkey_files:\n  - internal/cache/redis.go\n  - internal/api/middleware/cache.go\n---\n

    The skill also generates a summary and can extract decisions, learnings, and tasks mentioned during the session.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-5-generate-and-serve-the-site","level":3,"title":"Step 5: Generate and Serve the Site","text":"

    With exported and enriched journal files, generate the static site:

    # Generate site structure only\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate, build, and serve locally\nctx journal site --serve\n

    Then open http://localhost:8000 to browse.

    The site includes a date-sorted index, individual session pages with full conversations, search (press /), dark mode, and enriched titles in the navigation when frontmatter exists.

    You can also serve an already-generated site without regenerating using ctx serve (serve-only, no regeneration).

    The site generator requires zensical (pipx install zensical).

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#where-does-agent-add-value","level":2,"title":"Where Does Agent Add Value?","text":"

    Export, list, and show are mechanical: The agent runs the same CLI commands you would, so you can stay in your terminal for those.

    The agent earns its keep in enrich. It reads conversation content, understands what happened, and produces structured metadata. That is agent work, not CLI work.

    You can also ask your agent to browse sessions conversationally instead of remembering flags:

    What did we work on last week?\nShow me the session about Redis.\nExport everything to the journal.\n

    This is convenient but not required: ctx recall list gives you the same inventory.

    Where the agent genuinely helps is chaining the pipeline:

    You:   What happened last Tuesday?\nAgent: Last Tuesday you worked on two sessions:\n       - bright-dancing-hopper (2h 10m): refactored the middleware\n         pipeline and added Redis caching\n       - quiet-flowing-dijkstra (18m): quick fix for a nil pointer\n         in the config loader\n       Want me to export and enrich them?\nYou:   Yes, do it.\nAgent: Exports both, enriches, then proposes frontmatter.\n

    The value is staying in one context while the agent runs export -> enrich without you manually switching tools.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A typical pipeline from raw sessions to a browsable site:

    # Terminal: export and generate\nctx recall export --all\nctx journal site --serve\n
    # AI assistant: enrich\n/ctx-journal-enrich-all\n
    # Terminal: rebuild with enrichments\nctx journal site --serve\n

    If your project includes Makefile.ctx (deployed by ctx init), use make journal to combine export and rebuild stages. Then enrich inside Claude Code, then make journal again to pick up enrichments.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#session-retention-and-cleanup","level":2,"title":"Session Retention and Cleanup","text":"

    Claude Code does not keep JSONL transcripts forever. Understanding its cleanup behavior helps you avoid losing session history.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#default-behavior","level":3,"title":"Default Behavior","text":"

    Claude Code retains session transcripts for approximately 30 days. After that, JSONL files are automatically deleted during cleanup. Once deleted, ctx recall can no longer see those sessions - the data is gone.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-cleanupperioddays-setting","level":3,"title":"The cleanupPeriodDays Setting","text":"

    Claude Code exposes a cleanupPeriodDays setting in its configuration (~/.claude/settings.json) that controls retention:

    Value Behavior 30 (default) Transcripts older than 30 days are deleted 60, 90, etc. Extends the retention window 0 Disables writing new transcripts entirely - not \"keep forever\"

    Setting cleanupPeriodDays to 0

    Setting this to 0 does not mean \"never delete.\" It disables transcript creation altogether. No new JSONL files are written, which means ctx recall sees nothing new. This is rarely what you want.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#why-journal-export-matters","level":3,"title":"Why Journal Export Matters","text":"

    The journal export pipeline (Steps 1-4 above) is your archival mechanism. Exported Markdown files in .context/journal/ persist independently of Claude Code's cleanup cycle. Even after the source JSONL files are deleted, your journal entries remain.

    Recommendation: export regularly - weekly, or after any session worth revisiting. A quick ctx recall export --all takes seconds and ensures nothing falls through the 30-day window.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#quick-archival-checklist","level":3,"title":"Quick Archival Checklist","text":"
    1. Run ctx recall export --all at least weekly
    2. Enrich high-value sessions with /ctx-journal-enrich before the details fade from your own memory
    3. Lock enriched entries (ctx recall lock <pattern>) to protect them from accidental regeneration
    4. Rebuild the journal site periodically to keep it current
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#tips","level":2,"title":"Tips","text":"
    • Start with /ctx-recall inside your AI assistant. If you want to quickly check what happened in a recent session without leaving your editor, /ctx-recall lets you browse interactively without exporting.
    • Large sessions may be split automatically. Sessions with 200+ messages can be split into multiple parts (session-abc123.md, session-abc123-p2.md, session-abc123-p3.md) with navigation links between them. The site generator can handle this.
    • Suggestion sessions can be separated. Claude Code can generate short suggestion sessions for autocomplete. These may appear under a separate section in the site index, so they do not clutter your main session list.
    • Your agent is a good session browser. You do not need to remember slugs, dates, or flags. Ask \"what did we do yesterday?\" or \"find the session about Redis\" and it can map the question to recall commands.

    Journal Files Are Sensitive

    Journal files MUST be .gitignored.

    Session transcripts can contain sensitive data such as file contents, commands, error messages with stack traces, and potentially API keys.

    Add .context/journal/, .context/journal-site/, and .context/journal-obsidian/ to your .gitignore.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#next-up","level":2,"title":"Next Up","text":"

    Persisting Decisions, Learnings, and Conventions →: Record decisions, learnings, and conventions so they survive across sessions.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: where session saving fits in the daily workflow
    • Turning Activity into Content: generating blog posts from session history
    • Session Journal: full documentation of the journal system
    • CLI Reference: ctx recall: all recall subcommands and flags
    • CLI Reference: ctx journal: site generation options
    • CLI Reference: ctx serve: serve-only (no regeneration)
    • Context Files: the .context/ directory structure
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-ceremonies/","level":1,"title":"Session Ceremonies","text":"","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#the-problem","level":2,"title":"The Problem","text":"

    Sessions have two critical moments: the start and the end.

    • At the start, you need the agent to load context and confirm it knows what is going on.
    • At the end, you need to capture whatever the session produced before the conversation disappears.

    Most ctx skills work conversationally: \"jot down: check DNS after deploy\" is as good as /ctx-pad add \"check DNS after deploy\". But session boundaries are different. They are well-defined moments with specific requirements, and partial execution is costly.

    If the agent only half-loads context at the start, it works from stale assumptions. If it only half-persists at the end, learnings and decisions are lost.

    This Is One of the Few Times Being Explicit Matters

    Session ceremonies are the two bookend skills that mark these boundaries.

    They are the exception to the conversational rule:

    Invoke /ctx-remember and /ctx-wrap-up explicitly as slash commands.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#tldr","level":2,"title":"TL;DR","text":"

    Start: /ctx-remember: load context, get a structured readback.

    End: /ctx-wrap-up: review session, propose candidates, persist approved items.

    Use the slash commands, not conversational triggers, for completeness.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#explicit-invocation-matters","level":2,"title":"Explicit Invocation Matters","text":"

    Most ctx skills encourage natural language. These two are different:

    Well-defined moments: Sessions have clear boundaries. A slash command marks the boundary unambiguously.

    Ambiguity risk: \"Do you remember?\" could mean many things. /ctx-remember means exactly one thing: load context and present a structured readback.

    Completeness: Conversational triggers risk partial execution. The agent might load some files but skip the session history, or persist one learning but forget to check for uncommitted changes. The slash command runs the full ceremony.

    Muscle memory: Typing /ctx-remember at session start and /ctx-wrap-up at session end becomes a habit, like opening and closing braces.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-remember Skill Load context and present structured readback /ctx-wrap-up Skill Gather session signal, propose and persist context /ctx-commit Skill Commit with context capture (offered by wrap-up) ctx agent CLI Load token-budgeted context packet ctx recall list CLI List recent sessions ctx add CLI Persist learnings, decisions, conventions, tasks","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#session-start-ctx-remember","level":2,"title":"Session Start: /ctx-remember","text":"

    Invoke at the beginning of every session:

    /ctx-remember\n

    The skill silently:

    1. Loads the context packet via ctx agent --budget 4000
    2. Reads TASKS.md, DECISIONS.md, LEARNINGS.md
    3. Checks recent sessions via ctx recall list --limit 3

    Then presents a structured readback with four sections:

    • Last session: topic, date, what was accomplished
    • Active work: pending and in-progress tasks
    • Recent context: 1-2 relevant decisions or learnings
    • Next step: suggestion or question about what to focus on

    The readback should feel like recall, not a file system tour. If the agent says \"Let me check if there are files...\" instead of a confident summary, the skill is not working correctly.

    What About 'do you remember?'

    The conversational trigger still works. But /ctx-remember guarantees the full ceremony runs:

    • context packet,
    • file reads,
    • session history,
    • and all four readback sections.

    The conversational version may cut corners.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#session-end-ctx-wrap-up","level":2,"title":"Session End: /ctx-wrap-up","text":"

    Invoke before ending a session where meaningful work happened:

    /ctx-wrap-up\n

    The skill runs four phases:

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-1-gather-signal","level":3,"title":"Phase 1: Gather Signal","text":"

    Silently checks git diff --stat, recent commits, and scans the conversation for themes: architectural choices, gotchas, patterns established, follow-up work identified.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-2-propose-candidates","level":3,"title":"Phase 2: Propose Candidates","text":"

    Presents a structured list grouped by type:

    ## Session Wrap-Up\n\n### Learnings (2 candidates)\n1. **PyMdownx details extension breaks pre/code rendering**\n   - Context: Journal site showed broken code blocks inside details tags\n   - Lesson: details extension wraps content in <details> HTML, which\n     interferes with <pre><code> rendering\n   - Application: Use fenced code blocks instead of indented code inside\n     admonitions when details extension is active\n\n2. **Hook subprocesses cannot propagate env vars**\n   - Context: Set env var in PreToolUse hook, invisible in main session\n   - Lesson: Hooks execute in child processes; env changes don't propagate\n   - Application: Use tombstone files for hook-to-session communication\n\n### Decisions (1 candidate)\n1. **File-based cooldown tokens over env vars**\n   - Context: Need session-scoped cooldown for ctx agent auto-loading\n   - Rationale: File tokens survive across processes, simpler than IPC\n   - Consequence: Tombstone files accumulate in /tmp; need TTL cleanup\n\nPersist all? Or select which to keep?\n

    Each candidate has complete structured fields, not just a title. Empty categories are omitted.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-3-persist","level":3,"title":"Phase 3: Persist","text":"

    After you approve (all, some, or modified), the skill runs the appropriate ctx add commands and reports results.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#nudge-suppression","level":3,"title":"Nudge Suppression","text":"

    After persisting, the skill marks the session as wrapped up via ctx system mark-wrapped-up. This suppresses context checkpoint nudges for 2 hours so the wrap-up ceremony itself does not trigger noisy reminders.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-4-commit-offer","level":3,"title":"Phase 4: Commit Offer","text":"

    If there are uncommitted changes, offers to run /ctx-commit. Does not auto-commit.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#when-to-skip","level":2,"title":"When to Skip","text":"

    Not every session needs ceremonies.

    Skip /ctx-remember when:

    • You are doing a quick one-off lookup (reading a file, checking a value)
    • Context was already loaded this session via /ctx-agent
    • You are continuing immediately after a previous session and context is still fresh

    Skip /ctx-wrap-up when:

    • Nothing meaningful happened (only read files, answered a question)
    • You already persisted everything manually during the session
    • The session was trivial (typo fix, quick config change)

    A good heuristic: if the session produced something a future session should know about, run /ctx-wrap-up. If not, just close.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#quick-reference","level":2,"title":"Quick Reference","text":"
    # Session start\n/ctx-remember\n\n# ... do work ...\n\n# Session end\n/ctx-wrap-up\n

    That is the complete ceremony. Two commands, bookending your session.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#relationship-to-other-skills","level":2,"title":"Relationship to Other Skills","text":"Skill When Purpose /ctx-remember Session start Load and confirm context /ctx-reflect Mid-session breakpoints Checkpoint at milestones /ctx-wrap-up Session end Full session review and persist /ctx-commit After completing work Commit with context capture

    /ctx-reflect is for mid-session checkpoints. /ctx-wrap-up is for end-of-session: it is more thorough, covers the full session arc, and includes the commit offer. If you already ran /ctx-reflect recently, /ctx-wrap-up avoids proposing the same candidates again.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#tips","level":2,"title":"Tips","text":"
    • Make it a habit: The value of ceremonies compounds over sessions. Each /ctx-wrap-up makes the next /ctx-remember richer.
    • Trust the candidates: The agent scans the full conversation. It often catches learnings you forgot about.
    • Edit before approving: If a proposed candidate is close but not quite right, tell the agent what to change. Do not settle for a vague learning when a precise one is possible.
    • Do not force empty ceremonies: If /ctx-wrap-up finds nothing worth persisting, that is fine. A session that only read files and answered questions does not need artificial learnings.
    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#next-up","level":2,"title":"Next Up","text":"

    Browsing and Enriching Past Sessions →: Export session history to a browsable journal and enrich entries with metadata.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: the full session workflow that ceremonies bookend
    • Persisting Decisions, Learnings, and Conventions: deep dive on what gets persisted during wrap-up
    • Detecting and Fixing Drift: keeping context files accurate between ceremonies
    • Pausing Context Hooks: skip ceremonies entirely for quick tasks that don't need them
    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-changes/","level":1,"title":"Reviewing Session Changes","text":"","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#what-changed-while-you-were-away","level":2,"title":"What Changed While You Were Away?","text":"

    Between sessions, teammates commit code, context files get updated, and decisions pile up. ctx change gives you a single-command summary of everything that moved since your last session.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#quick-start","level":2,"title":"Quick Start","text":"
    # Auto-detects your last session and shows what changed\nctx change\n\n# Check what changed in the last 48 hours\nctx change --since 48h\n\n# Check since a specific date\nctx change --since 2026-03-10\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#how-reference-time-works","level":2,"title":"How Reference Time Works","text":"

    ctx change needs a reference point to compare against. It tries these sources in order:

    1. --since flag: explicit duration (24h, 72h) or date (2026-03-10, RFC3339 timestamp)
    2. Session markers: ctx-loaded-* files in .context/state/; picks the second-most-recent (your previous session start)
    3. Event log: last context-load-gate event from .context/state/events.jsonl
    4. Fallback: 24 hours ago

    The marker-based detection means ctx change usually just works without any flags: it knows when you last loaded context and shows everything after that.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#what-it-reports","level":2,"title":"What It Reports","text":"","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#context-file-changes","level":3,"title":"Context file changes","text":"

    Any .md file in .context/ modified after the reference time:

    ### Context File Changes\n- `TASKS.md` - modified 2026-03-11 14:30\n- `DECISIONS.md` - modified 2026-03-11 09:15\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#code-changes","level":3,"title":"Code changes","text":"

    Git activity since the reference time:

    ### Code Changes\n- **12 commits** since reference point\n- **Latest**: Fix journal enrichment ordering\n- **Directories touched**: internal, docs, specs\n- **Authors**: jose, claude\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#integrating-into-session-start","level":2,"title":"Integrating Into Session Start","text":"

    Pair ctx change with the /ctx-remember ceremony for a complete session-start picture:

    # 1. Load context (this also creates the session marker)\nctx agent --budget 4000\n\n# 2. See what changed since your last session\nctx change\n

    Or script it:

    # .context/hooks/session-start.sh\nctx agent --budget 4000\necho \"---\"\nctx change\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#team-workflows","level":2,"title":"Team Workflows","text":"

    When multiple people share a .context/ directory, ctx change shows who changed what:

    # After pulling from remote\ngit pull\nctx change --since 72h\n

    This surfaces context file changes from teammates that you might otherwise miss in the commit log.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#tips","level":2,"title":"Tips","text":"
    • No changes? If nothing shows up, the reference time might be wrong. Use --since 48h to widen the window.
    • Works without git. Context file changes are detected by filesystem mtime, not git. Code changes require git.
    • Hook integration. The context-load-gate hook writes the session marker that ctx change uses for auto-detection. If you're not using the ctx plugin, markers won't exist and it falls back to the event log or 24h window.
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-lifecycle/","level":1,"title":"The Complete Session","text":"","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#the-problem","level":2,"title":"The Problem","text":"

    \"What does a full ctx session look like from start to finish?\"

    You have ctx installed and your .context/ directory initialized, but the individual commands and skills feel disconnected.

    How do they fit together into a coherent workflow?

    This recipe walks through a complete session, from opening your editor to persisting context before you close it, so you can see how each piece connects.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#tldr","level":2,"title":"TL;DR","text":"
    1. Load: /ctx-remember: load context, get structured readback.
    2. Orient: /ctx-status: check file health and token usage.
    3. Pick: /ctx-next: choose what to work on.
    4. Work: implement, test, iterate.
    5. Commit: /ctx-commit: commit and capture decisions/learnings.
    6. Reflect: /ctx-reflect: identify what to persist (at milestones)
    7. Wrap up: /ctx-wrap-up: end-of-session ceremony.

    Read on for the full walkthrough with examples.

    What is a Readback?

    A readback is a structured summary where the agent plays back what it knows:

    • last session,
    • active tasks,
    • recent decisions.

    This way, you can confirm it loaded the right context.

    The term \"readback\" comes from aviation, where pilots repeat instructions back to air traffic control to confirm they heard correctly.

    Same idea in ctx: The agent tells you what it \"thinks\" is going on, and you correct anything that's off before the work begins.

    • Last session: topic, date, what was accomplished
    • Active work: pending and in-progress tasks
    • Recent context: 1-2 decisions or learnings that matter now
    • Next step: suggestion or question about what to focus on
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx status CLI command Quick health check on context files ctx agent CLI command Load token-budgeted context packet ctx recall list CLI command List previous sessions ctx recall show CLI command Inspect a specific session in detail /ctx-remember Skill Recall project context with structured readback /ctx-agent Skill Load full context packet inside the assistant /ctx-status Skill Show context summary with commentary /ctx-next Skill Suggest what to work on with rationale /ctx-commit Skill Commit code and prompt for context capture /ctx-reflect Skill Structured reflection checkpoint /ctx-recall Skill Browse session history inside your AI assistant","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#the-workflow","level":2,"title":"The Workflow","text":"

    The session lifecycle has seven steps. You will not always use every step (for example, a quick bugfix might skip reflection, and a research session might skip committing), but the full arc looks like this:

    Load context > Orient > Pick a Task > Work > Commit > Reflect

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-1-load-context","level":3,"title":"Step 1: Load Context","text":"

    Start every session by loading what you know. The fastest way is a single prompt:

    Do you remember what we were working on?\n

    This triggers the /ctx-remember skill. Behind the scenes, the assistant runs ctx agent --budget 4000, reads the files listed in the context packet (TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md), checks ctx recall list --limit 3 for recent sessions, and then presents a structured readback.

    The readback should feel like a recall, not a file system tour. If you see \"Let me check if there are files...\" instead of a confident summary, the context system is not loaded properly.

    As an alternative, if you want raw data instead of a readback, run ctx status in your terminal or invoke /ctx-status for a summarized health check showing file counts, token usage, and recent activity.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-2-orient","level":3,"title":"Step 2: Orient","text":"

    After loading context, verify you understand the current state.

    /ctx-status\n

    The status output shows which context files are populated, how many tokens they consume, and which files were recently modified. Look for:

    • Empty core files: TASKS.md or CONVENTIONS.md with no content means the context is sparse
    • High token count (over 30k): the context is bloated and might need ctx compact
    • No recent activity: files may be stale and need updating

    If the status looks healthy and the readback from Step 1 gave you enough context, skip ahead.

    If something seems off (stale tasks, missing decisions...), spend a minute reading the relevant file before proceeding.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-3-pick-what-to-work-on","level":3,"title":"Step 3: Pick What to Work On","text":"

    With context loaded, choose a task. You can pick one yourself, or ask the assistant to recommend:

    /ctx-next\n

    The skill reads TASKS.md, checks recent sessions to avoid re-suggesting completed work, and presents 1-3 ranked recommendations with rationale.

    It prioritizes in-progress tasks over new starts (finishing is better than starting), respects explicit priority tags, and favors momentum: continuing a thread from a recent session is cheaper than context-switching.

    If you already know what you want to work on, state it directly:

    Let's work on the session enrichment feature.\n
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-4-do-the-work","level":3,"title":"Step 4: Do the Work","text":"

    This is the main body of the session: write code, fix bugs, refactor, research: whatever the task requires.

    During this phase, a few ctx-specific patterns help:

    Check decisions before choosing: when you face a design choice, check if a prior decision covers it.

    Is this consistent with our decisions?\n

    Constrain scope: keep the assistant focused on the task at hand.

    Only change files in internal/cli/session/. Nothing else.\n

    Use /ctx-implement for multistep plans: if the task has multiple steps, this skill executes them one at a time with build/test verification between each step.

    Context monitoring runs automatically: the check-context-size hook monitors context capacity at adaptive intervals. Early in a session it stays silent. After 16+ prompts it starts monitoring, and past 30 prompts it checks frequently. If context capacity is running high, it will suggest saving unsaved work. No manual invocation is needed.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-5-commit-with-context","level":3,"title":"Step 5: Commit with Context","text":"

    When the work is ready, use the context-aware commit instead of raw git commit:

    /ctx-commit\n

    The Agent May Recommend Committing

    You do not always need to invoke /ctx-commit explicitly.

    After a commit, the agent may proactively offer to capture context:

    \"We just made a trade-off there. Want me to record it as a decision?\"

    This is normal: The Agent Playbook encourages persisting at milestones, and a commit is a natural milestone.

    As an alternative, you can ask the assistant \"can we commit this?\" and it will pick up the /ctx-commit skill for you.

    The skill runs a pre-commit build check (for Go projects, go build), reviews the staged changes, drafts a commit message focused on \"why\" rather than \"what\", and then commits.

    After the commit succeeds, it prompts you:

    **Any context to capture?**\n\n- **Decision**: Did you make a design choice or trade-off?\n- **Learning**: Did you hit a gotcha or discover something?\n- **Neither**: No context to capture; we are done.\n

    If you made a decision, the skill records it with ctx add decision. If you learned something, it records it with ctx add learning including context, lesson, and application fields. This is the bridge between committing code and remembering why the code looks the way it does.

    If source code changed in areas that affect documentation, the skill also offers to check for doc drift.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-6-reflect","level":3,"title":"Step 6: Reflect","text":"

    At natural breakpoints (after finishing a feature, resolving a complex bug, or before switching tasks) pause to reflect:

    /ctx-reflect\n

    Agents Reflect at Milestones

    Agents often reflect without explicit invocation.

    After completing a significant piece of work, the agent may naturally surface items worth persisting:

    \"We discovered that $PPID resolves differently inside hooks. Should I save that as a learning?\"

    This is the agent following the Work-Reflect-Persist cycle from the Agent Playbook.

    You do not need to say /ctx-reflect for this to happen; the agent treats milestones as reflection triggers on its own.

    The skill works through a checklist: learnings discovered, decisions made, tasks completed or created, and whether there are items worth persisting. It then presents a summary with specific items to persist, each with the exact command to run:

    I would suggest persisting:\n\n- **Learning**: `$PPID` in PreToolUse hooks resolves to the Claude Code PID\n  `ctx add learning --context \"...\" --lesson \"...\" --application \"...\"`\n- **Task**: mark \"Add cooldown to ctx agent\" as done\n- **Decision**: tombstone-based cooldown with 10m default\n  `ctx add decision \"...\"`\n\nWant me to persist any of these?\n

    The skill asks before persisting anything. You choose what to keep.

    Not every commit needs reflection. A typo fix does not. But when you have been debugging for an hour and finally understand the root cause, that is worth a reflection checkpoint.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-7-persist-before-ending","level":3,"title":"Step 7: Persist Before Ending","text":"

    Before ending the session, run the wrap-up ceremony to capture outstanding learnings, decisions, conventions, and tasks:

    /ctx-wrap-up\n

    Ceremony Skills

    /ctx-remember at session start and /ctx-wrap-up at session end are ceremony skills: Invoke them as explicit slash commands for completeness, not conversationally.

    See Session Ceremonies for details on why these two skills are the exception to the conversational rule.

    The skill gathers signal from git diff, recent commits, and the conversation, then proposes structured candidates for your approval. After you select which to keep, it persists them via ctx add and offers /ctx-commit if uncommitted changes remain.

    Session transcripts are automatically captured by Claude Code and can be browsed later with ctx recall list and ctx recall show.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#conversational-session-flow","level":2,"title":"Conversational Session Flow","text":"

    The steps above describe the mechanics. In practice, a session with a ctx-aware agent feels more like a conversation than a command sequence.

    The agent knows the lifecycle and moves through it naturally, often without explicit invocation. Here is a realistic example:

    You: Do you remember what we were working on?

    Agent (loads context silently, presents structured readback):

    Last session (Feb 7, caching-layer): we implemented the in-memory cache with\nTTL expiration and wrote tests for the eviction policy. \n\nYou have 3 pending tasks; the biggest one is adding Redis as a backend.\n\nRecent decision:<br>\nwe chose LRU over LFU because the access pattern is mostly recency-based.\n\nWant to continue with the Redis backend, or tackle something else?\n

    You: Let's work on the Redis caching backend.

    Agent (picks up the task, begins implementation):

    Got it. I see the task in TASKS.md: \"Add Redis backend for cache layer.\"\n\nI will start with the connection pool setup. Only touching\n`internal/cache/redis/` for now.\n

    (The agent works... writes code, runs tests, iterates.)

    Agent (after implementing the connection pool and choosing a retry strategy):

    The connection pool is working. I went with exponential backoff with jitter\nfor retries instead of fixed intervals; it handles thundering herd better\nunder reconnection storms. That is a design choice worth recording. \n\nWant me to save it as a decision?\n

    You: Yes, go ahead.

    Agent:

    Done. Added to DECISIONS.md: \"Exponential backoff with jitter for Redis\nreconnection, to avoid thundering herd on pool recovery.\"\n

    (More work happens... the agent implements the cache read/write paths.)

    You: What else did we learn during this session?

    Agent:

    A few things worth capturing:\n\n* **Learning**: Redis `SET` with `NX` and `PX` flags handles atomic\n  set-if-not-exists with TTL in a single call. No need for a separate\n  `EXPIRE` command. We initially did it in two calls and hit a race condition.\n* **Learning**: The `go-redis` library's `PoolSize` default is 10 per CPU.\n  For our workload, explicit sizing at 20 was more predictable.\n* **Task update**: The connection pool subtask is done; the read/write path\n  is implemented but needs integration tests.\n\nWant me to persist these?\n

    You: Yes. And let's wrap up.

    Agent (reflects and persists... all in one flow):

    Persisted:\n\n* 2 learnings added to LEARNINGS.md\n* Marked \"connection pool setup\" done in TASKS.md\n* Added \"write integration tests for Redis cache\" as a new task\n\nContext is up to date. You are good to close.\n

    Notice What Happened

    In the above workflow, the user never typed /ctx-reflect or ctx add learning.

    The agent moved through Load, Orient, Pick, Work, Commit, and Reflect driven by natural conversation.

    \"Let's wrap up\" was enough to trigger the full reflect-and-persist flow.

    The agent surfaced persist-worthy items at milestones: after a design choice, after discovering a gotcha: without waiting to be asked.

    This is the intended experience.

    The commands and skills still exist for when you want precise control, but the agent is a proactive partner in the lifecycle, not a passive executor of slash commands.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Quick-reference checklist for a complete session:

    • Load: /ctx-remember: load context and confirm readback
    • Orient: /ctx-status: check file health and token usage
    • Pick: /ctx-next: choose what to work on
    • Work: implement, test, iterate (scope with \"only change X\")
    • Commit: /ctx-commit: commit and capture decisions/learnings
    • Reflect: /ctx-reflect: identify what to persist (at milestones)
    • Wrap up: /ctx-wrap-up: end-of-session ceremony

    Conversational equivalents: you can drive the same lifecycle with plain language:

    Step Slash command Natural language Load /ctx-remember \"Do you remember?\" / \"What were we working on?\" Orient /ctx-status \"How's our context looking?\" Pick /ctx-next \"What should we work on?\" / \"Let's do the caching task\" Work -- \"Only change files in internal/cache/\" Commit /ctx-commit \"Commit this\" / \"Ship it\" Reflect /ctx-reflect \"What did we learn?\" / (agent offers at milestones) Wrap up /ctx-wrap-up (use the slash command for completeness)

    The agent understands both columns.

    In practice, most sessions use a mix:

    • Explicit Commands when you want precision;
    • Natural Language when you want flow and agentic autonomy.

    The agent will also initiate steps on its own (particularly \"Reflect\") when it recognizes a milestone.

    Short sessions (quick bugfix) might only use: Load, Work, Commit.

    Long sessions should Reflect after each major milestone and persist learnings and decisions before ending.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#tips","level":2,"title":"Tips","text":"

    Persist early if context is running low. A hook monitors context capacity and notifies you when it gets high, but do not wait for the notification. If you have been working for a while and have unpersisted learnings, persist proactively.

    Browse previous sessions by topic. If you need context from a prior session, ctx recall show auth will match by keyword. You do not need to remember the exact date or slug.

    Reflection is optional but valuable. You can skip /ctx-reflect for small changes, but always persist learnings and decisions before ending a session where you did meaningful work. These are what the next session loads.

    Let the hook handle context loading. The PreToolUse hook runs ctx agent automatically with a cooldown, so context loads on first tool use without you asking. The /ctx-remember prompt at session start is for your benefit (to get a readback), not because the assistant needs it.

    The agent is a proactive partner, not a passive tool. A ctx-aware agent follows the Agent Playbook: it watches for milestones (completed tasks, design decisions, discovered gotchas) and offers to persist them without being asked. If you finish a tricky debugging session, it may say \"That root cause is worth saving as a learning. Want me to record it?\" before you think to ask. This is by design.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#next-up","level":2,"title":"Next Up","text":"

    Session Ceremonies →: The two bookend rituals for every session: /ctx-remember at the start, /ctx-wrap-up at the end.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#see-also","level":2,"title":"See Also","text":"
    • Session Ceremonies: why /ctx-remember and /ctx-wrap-up are explicit slash commands, not conversational
    • CLI Reference: full documentation for all ctx commands
    • Prompting Guide: effective prompts for ctx-enabled projects
    • Tracking Work Across Sessions: deep dive on task management
    • Persisting Decisions, Learnings, and Conventions: deep dive on knowledge capture
    • Detecting and Fixing Drift: keeping context files accurate
    • Pausing Context Hooks: shortcut the full lifecycle for quick tasks that don't need ceremony overhead
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-pause/","level":1,"title":"Pausing Context Hooks","text":"","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#the-problem","level":2,"title":"The Problem","text":"

    Not every session needs the full ceremony. Quick investigations, one-off questions, small fixes unrelated to active project work: These tasks don't benefit from persistence nudges, ceremony reminders, or knowledge checks. Every hook still fires, consuming tokens and attention on work that won't produce learnings or decisions worth capturing.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#tldr","level":2,"title":"TL;DR","text":"Command What it does ctx pause or /ctx-pause Silence all nudge hooks for this session ctx resume or /ctx-resume Restore normal hook behavior

    Pause is session-scoped: It only affects the current session. Other sessions (same project, different terminal) are unaffected.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#what-gets-paused","level":2,"title":"What Gets Paused","text":"

    All nudge and reminder hooks go silent:

    • Context size checkpoints
    • Ceremony adoption nudges
    • Persistence reminders
    • Journal maintenance reminders
    • Knowledge growth nudges
    • Map staleness nudges
    • Version update nudges
    • Resource pressure warnings
    • QA reminders
    • Post-commit nudges
    • Specs nudges
    • Backup age warnings
    • Context load gate
    • Pending reminders relay
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#what-still-fires","level":2,"title":"What Still Fires","text":"

    Security hooks always run, even when paused:

    • block-non-path-ctx: prevents ./ctx invocations
    • block-dangerous-commands: blocks sudo, force push, etc.
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#workflow","level":2,"title":"Workflow","text":"
    # 1. Session starts: Context loads normally.\n\n# 2. You realize this is a quick task\nctx pause\n\n# 3. Work without interruption: hooks are silent\n\n# 4. Session evolves into real work? Resume first\nctx resume\n\n# 5. Now wrap up normally\n# /ctx-wrap-up\n
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#graduated-reminder","level":2,"title":"Graduated Reminder","text":"

    Paused hooks aren't completely invisible. A minimal indicator appears so you always know the state:

    Paused turns What you see 1-5 ctx:paused 6+ ctx:paused (N turns): resume with /ctx-resume

    This prevents the \"forgot I paused\" problem during long sessions.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#tips","level":2,"title":"Tips","text":"

    • Resume before wrapping up. If your quick task turns into real work, resume hooks before running /ctx-wrap-up. The wrap-up ceremony needs active hooks to capture learnings properly.

    • Initial context load is unaffected. The ~8k token startup injection (CLAUDE.md, playbook, constitution) happens before any command runs. Pause only affects hooks that fire during the session.

    • Use for quick investigations. Debugging a stack trace? Checking a git log? Answering a colleague's question? Pause, do the work, close the session. No ceremony needed.

    • Don't use for real work. If you're implementing features, fixing bugs, or making decisions: keep hooks active. The nudges exist to prevent context loss.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#see-also","level":2,"title":"See Also","text":"

    See also: Session Ceremonies: the bookend rituals that pause lets you skip when they aren't needed.

    See also: Customizing Hook Messages: if you want to change what hooks say rather than silencing them entirely.

    See also: The Complete Session: the full session workflow that pause shortcuts for quick tasks.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-reminders/","level":1,"title":"Session Reminders","text":"","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#the-problem","level":2,"title":"The Problem","text":"

    You're deep in a session and realize: \"I need to refactor the swagger definitions next time.\" You could add a task, but this isn't a work item: it's a note to future-you. You could jot it on the scratchpad, but scratchpad entries don't announce themselves.

    How do you leave a message that your next session opens with?

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#tldr","level":2,"title":"TL;DR","text":"
    ctx remind \"refactor the swagger definitions\"\nctx remind list\nctx remind dismiss 1\n

    Reminders surface automatically at session start: VERBATIM, every session, until you dismiss them.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx remind CLI command Add a reminder (default action) ctx remind list CLI command Show all pending reminders ctx remind dismiss CLI command Remove a reminder by ID (or --all) /ctx-remind Skill Natural language interface to reminders","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-1-leave-a-reminder","level":3,"title":"Step 1: Leave a Reminder","text":"

    Tell your agent what to remember, or run it directly:

    You: \"remind me to refactor the swagger definitions\"\n\nAgent: [runs ctx remind \"refactor the swagger definitions\"]\n       \"Reminder set:\n         + [1] refactor the swagger definitions\"\n

    Or from the terminal:

    ctx remind \"refactor the swagger definitions\"\n
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-2-set-a-date-gate-optional","level":3,"title":"Step 2: Set a Date Gate (Optional)","text":"

    If the reminder shouldn't fire until a specific date:

    You: \"remind me to check the deploy logs after Tuesday\"\n\nAgent: [runs ctx remind \"check the deploy logs\" --after 2026-02-25]\n       \"Reminder set:\n         + [2] check the deploy logs  (after 2026-02-25)\"\n

    The reminder stays silent until that date, then fires every session.

    The agent converts natural language dates (\"tomorrow\", \"next week\", \"after the release on Friday\") to YYYY-MM-DD. If it's ambiguous, it asks.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-3-start-a-new-session","level":3,"title":"Step 3: Start a New Session","text":"

    Next session, the reminder appears automatically before anything else:

    ┌─ Reminders ──────────────────────────────────────\n│  [1] refactor the swagger definitions\n│\n│ Dismiss: ctx remind dismiss <id>\n│ Dismiss all: ctx remind dismiss --all\n└──────────────────────────────────────────────────\n

    No action needed: The check-reminders hook fires on UserPromptSubmit and the agent relays the box verbatim.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-4-dismiss-when-done","level":3,"title":"Step 4: Dismiss When Done","text":"

    After you've acted on a reminder (or decided to skip it):

    You: \"dismiss reminder 1\"\n\nAgent: [runs ctx remind dismiss 1]\n       \"Dismissed:\n         - [1] refactor the swagger definitions\"\n

    Or clear everything:

    ctx remind dismiss --all\n
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-5-check-whats-pending","level":3,"title":"Step 5: Check What's Pending","text":"
    ctx remind list\n
      [1] refactor the swagger definitions\n  [3] review auth token expiry logic\n  [4] check deploy logs  (after 2026-02-25, not yet due)\n

    Date-gated reminders that haven't reached their date show (not yet due).

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#using-ctx-remind-in-a-session","level":2,"title":"Using /ctx-remind in a Session","text":"

    Invoke the /ctx-remind skill, then describe what you want:

    You: /ctx-remind remind me to update the API docs\nYou: /ctx-remind what reminders do I have?\nYou: /ctx-remind dismiss reminder 3\n
    You say (after /ctx-remind) What the agent does \"remind me to update the API docs\" ctx remind \"update the API docs\" \"remind me next week to check staging\" ctx remind \"check staging\" --after 2026-03-02 \"what reminders do I have?\" ctx remind list \"dismiss reminder 3\" ctx remind dismiss 3 \"clear all reminders\" ctx remind dismiss --all","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#reminders-vs-scratchpad-vs-tasks","level":2,"title":"Reminders vs Scratchpad vs Tasks","text":"You want to... Use Leave a note that announces itself next session ctx remind Jot down a quick value or sensitive token ctx pad Track work with status and completion TASKS.md Record a decision or lesson for all sessions Context files

    Decision guide:

    • If it should announce itself at session start → ctx remind
    • If it's a quiet note you'll check manually → ctx pad
    • If it's a work item you'll mark done → TASKS.md

    Reminders Are Sticky Notes, Not Tasks

    A reminder has no status, no priority, no lifecycle. It's a message to \"future you\" that fires until dismissed.

    If you need tracking, use a task in TASKS.md.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#tips","level":2,"title":"Tips","text":"
    • Reminders fire every session: Unlike nudges (which throttle to once per day), reminders repeat until you dismiss them. This is intentional: You asked to be reminded.
    • Date gating is session-scoped, not clock-scoped: --after 2026-02-25 means \"don't show until sessions on or after Feb 25.\" It does not mean \"alarm at midnight on Feb 25.\"
    • The agent handles date parsing: Say \"next week\" or \"after Friday\": The agent converts it to YYYY-MM-DD. The CLI only accepts the explicit date format.
    • Reminders are committed to git: They travel with the repo. If you switch machines, your reminders follow.
    • IDs never reuse: After dismissing reminder 3, the next reminder gets ID 4 (or higher). No confusion from recycled numbers.
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#next-up","level":2,"title":"Next Up","text":"

    Using the Scratchpad →: For quiet notes and sensitive values that don't need session-start announcements.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: ctx remind: full command syntax and flags
    • The Complete Session: how reminders fit into the session lifecycle
    • Managing Tasks: for work items that need status tracking
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/state-maintenance/","level":1,"title":"State Directory Maintenance","text":"","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#the-problem","level":2,"title":"The Problem","text":"

    Every session creates tombstone files in .context/state/ - small markers that suppress repeat hook nudges (\"already checked context size\", \"already sent persistence reminder\"). Over days and weeks, these accumulate into hundreds of files from long-dead sessions.

    The files are harmless individually, but the clutter makes it harder to reason about state, and stale global tombstones can suppress nudges across sessions entirely.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#tldr","level":2,"title":"TL;DR","text":"
    ctx system prune --dry-run     # preview what would be removed\nctx system prune               # prune files older than 7 days\nctx system prune --days 1      # more aggressive: keep only today\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#commands-used","level":2,"title":"Commands Used","text":"Tool Type Purpose ctx system prune Command Remove old per-session state files ctx status Command Quick health overview including state dir","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#understanding-state-files","level":2,"title":"Understanding State Files","text":"

    State files fall into two categories:

    Session-scoped (contain a UUID in the filename): Created per-session to suppress repeat nudges. Safe to prune once the session ends. Examples:

    context-check-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\nheartbeat-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\npersistence-nudge-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\n

    Global (no UUID): Persist across sessions. ctx system prune preserves these automatically. Some are legitimate state (events.jsonl, memory-import.json); others may be stale tombstones that need manual review.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#the-workflow","level":2,"title":"The Workflow","text":"","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-1-preview","level":3,"title":"Step 1: Preview","text":"

    Always dry-run first to see what would be removed:

    ctx system prune --dry-run\n

    The output shows each file, its age, and a summary:

      would prune: context-check-abc123... (age: 3d)\n  would prune: heartbeat-abc123... (age: 3d)\n\nDry run - would prune 150 files (skip 70 recent, preserve 14 global)\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-2-prune","level":3,"title":"Step 2: Prune","text":"

    Choose an age threshold. The default is 7 days:

    ctx system prune               # older than 7 days\nctx system prune --days 3      # older than 3 days\nctx system prune --days 1      # older than 1 day (aggressive)\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-3-review-global-files","level":3,"title":"Step 3: Review Global Files","text":"

    After pruning, check what prune preserved:

    ls .context/state/ | grep -v '[0-9a-f]\\{8\\}-[0-9a-f]\\{4\\}'\n

    Legitimate global files (keep):

    • events.jsonl - event log
    • memory-import.json - import tracking state

    Stale global tombstones (safe to delete):

    • Files like backup-reminded, ceremony-reminded, version-checked with no session UUID are one-shot markers. If they are from a previous session, they are stale and can be removed manually.
    rm .context/state/backup-reminded .context/state/ceremony-reminded\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-4-verify","level":3,"title":"Step 4: Verify","text":"
    ls .context/state/ | wc -l    # should be manageable\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#when-to-prune","level":2,"title":"When to Prune","text":"
    • Weekly: ctx system prune with default 7-day threshold
    • After heavy parallel work: Multiple concurrent sessions create many tombstones. Prune with --days 1 afterward.
    • When state directory exceeds ~100 files: A sign that pruning hasn't run recently
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#tips","level":2,"title":"Tips","text":"

    Pruning active sessions is safe but noisy: If you prune a file belonging to a still-running session, the corresponding hook will re-fire its nudge on the next prompt. Minor UX annoyance, not data loss.

    No context files are stored in state: The state directory contains only tombstones, counters, and diagnostic data. Nothing in .context/state/ affects your decisions, learnings, tasks, or conventions.

    Test artifacts sneak in: Files like context-check-statstest or heartbeat-unknown are artifacts from development or testing. They lack UUIDs so prune preserves them. Delete manually.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#see-also","level":2,"title":"See Also","text":"
    • Detecting and Fixing Drift: broader context maintenance including drift detection and archival
    • Troubleshooting: diagnostic workflow using ctx doctor and event logs
    • CLI Reference: system: full flag documentation for ctx system prune and related commands
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/system-hooks-audit/","level":1,"title":"Auditing System Hooks","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-problem","level":2,"title":"The Problem","text":"

    ctx runs 14 system hooks behind the scenes: nudging your agent to persist context, warning about resource pressure, gating commits on QA. But these hooks are invisible by design. You never see them fire. You never know if they stopped working.

    How do you verify your hooks are actually running, audit what they do, and get alerted when they go silent?

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tldr","level":2,"title":"TL;DR","text":"
    ctx system check-resources # run a hook manually\nls -la .context/logs/      # check hook execution logs\nctx notify setup           # get notified when hooks fire\n

    Or ask your agent: \"Are our hooks running?\"

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx system <hook> CLI command Run a system hook manually ctx system resources CLI command Show system resource status ctx system stats CLI command Stream or dump per-session token stats ctx notify setup CLI command Configure webhook for audit trail ctx notify test CLI command Verify webhook delivery .ctxrc notify.events Configuration Subscribe to relay for full hook audit .context/logs/ Log files Local hook execution ledger","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#what-are-system-hooks","level":2,"title":"What Are System Hooks?","text":"

    System hooks are plumbing commands that ctx registers with your AI tool (Claude Code, Cursor, etc.) via the plugin's hooks.json. They fire automatically at specific events during your AI session:

    Event When Hooks UserPromptSubmit Before the agent sees your prompt 10 check hooks + heartbeat PreToolUse Before the agent uses a tool block-non-path-ctx, qa-reminder PostToolUse After a tool call succeeds post-commit

    You never run these manually. Your AI tool runs them for you: That's the point.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-complete-hook-catalog","level":2,"title":"The Complete Hook Catalog","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#prompt-time-checks-userpromptsubmit","level":3,"title":"Prompt-Time Checks (UserPromptSubmit)","text":"

    These fire before every prompt, but most are throttled to avoid noise.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-context-size-context-capacity-warning","level":4,"title":"check-context-size: Context Capacity Warning","text":"

    What: Adaptive prompt counter. Silent for the first 15 prompts, then nudges with increasing frequency (every 5th, then every 3rd).

    Why: Long sessions lose coherence. The nudge reminds both you and the agent to persist context before the window fills up.

    Output: VERBATIM relay box with prompt count.

    ┌─ Context Checkpoint (prompt #20) ────────────────\n│ This session is getting deep. Consider wrapping up\n│ soon. If there are unsaved learnings, decisions, or\n│ conventions, now is a good time to persist them.\n│ ⏱ Context window: ~45k tokens (~22% of 200k)\n└──────────────────────────────────────────────────\n

    Stats: Every prompt records token usage to .context/state/stats-{session}.jsonl. Monitor live with ctx system stats --follow or query with ctx system stats --json. Stats are recorded even during wrap-up suppression (event: suppressed).

    Billing guard: When billing_token_warn is set in .ctxrc, a one-shot warning fires if session tokens exceed the threshold. This warning is independent of all other triggers - it fires even during wrap-up suppression.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-persistence-context-staleness-nudge","level":4,"title":"check-persistence: Context Staleness Nudge","text":"

    What: Tracks when .context/*.md files were last modified. If too many prompts pass without a write, nudges the agent to persist.

    Why: Sessions produce insights that evaporate if not recorded. This catches the \"we talked about it but never wrote it down\" failure mode.

    Output: VERBATIM relay after 20+ prompts without a context file change.

    ┌─ Persistence Checkpoint (prompt #20) ───────────\n│ No context files updated in 20+ prompts.\n│ Have you discovered learnings, made decisions,\n│ established conventions, or completed tasks\n│ worth persisting?\n│\n│ Run /ctx-wrap-up to capture session context.\n└──────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-ceremonies-session-ritual-adoption","level":4,"title":"check-ceremonies: Session Ritual Adoption","text":"

    What: Scans your last 3 journal entries for /ctx-remember and /ctx-wrap-up usage. Nudges once per day if missing.

    Why: Session ceremonies are the highest-leverage habit in ctx. This hook bootstraps the habit until it becomes automatic.

    Output: Tailored nudge depending on which ceremony is missing.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-journal-unexported-session-reminder","level":4,"title":"check-journal: Unexported Session Reminder","text":"

    What: Detects unexported Claude Code sessions and unenriched journal entries. Fires once per day.

    Why: Exported sessions become searchable history. Unenriched entries lack metadata for filtering. Both decay in value over time.

    Output: VERBATIM relay with counts and exact commands.

    ┌─ Journal Reminder ─────────────────────────────\n│ You have 3 new session(s) not yet exported.\n│ 5 existing entries need enrichment.\n│\n│ Export and enrich:\n│   ctx recall export --all\n│   /ctx-journal-enrich-all\n└────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-resources-system-resource-pressure","level":4,"title":"check-resources: System Resource Pressure","text":"

    What: Monitors memory, swap, disk, and CPU load. Only fires at DANGER severity (memory >= 90%, swap >= 75%, disk >= 95%, load >= 1.5x CPU count).

    Why: Resource exhaustion mid-session can corrupt work. This provides early warning to persist and exit.

    Output: VERBATIM relay listing critical resources.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-knowledge-knowledge-file-growth","level":4,"title":"check-knowledge: Knowledge File Growth","text":"

    What: Counts entries in LEARNINGS.md, DECISIONS.md, and lines in CONVENTIONS.md. Fires once per day when thresholds are exceeded.

    Why: Large knowledge files dilute agent context. 35 learnings compete for attention; 15 focused ones get applied. Thresholds are configurable in .ctxrc.

    Default thresholds:

    # .ctxrc\nentry_count_learnings: 30\nentry_count_decisions: 20\nconvention_line_count: 200\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-version-binaryplugin-version-drift","level":4,"title":"check-version: Binary/Plugin Version Drift","text":"

    What: Compares the ctx binary version against the plugin version. Fires once per day. Also checks encryption key age for rotation nudge.

    Why: Version drift means hooks reference features the binary doesn't have. The key rotation nudge prevents indefinite key reuse.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-reminders-pending-reminder-relay","level":4,"title":"check-reminders: Pending Reminder Relay","text":"

    What: Reads .context/reminders.json and surfaces any due reminders via VERBATIM relay. No throttle: fires every session until dismissed.

    Why: Reminders are sticky notes to future-you. Unlike nudges (which throttle to once per day), reminders repeat deliberately until the user dismisses them.

    Output: VERBATIM relay box listing due reminders.

    ┌─ Reminders ──────────────────────────────────────\n│  [1] refactor the swagger definitions\n│\n│ Dismiss: ctx remind dismiss <id>\n│ Dismiss all: ctx remind dismiss --all\n└──────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-freshness-technology-constant-staleness","level":4,"title":"check-freshness: Technology Constant Staleness","text":"

    What: Stats files listed in .ctxrc freshness_files and warns if any haven't been modified in over 6 months. Daily throttle. Silent when no files are configured (opt-in via .ctxrc).

    Why: Model capabilities evolve - token budgets, attention limits, and context window sizes that were accurate 6 months ago may no longer reflect best practices. This hook reminds you to review and touch the file to confirm values are still current.

    Config (.ctxrc):

    freshness_files:\n  - path: config/thresholds.yaml\n    desc: Model token limits and batch sizes\n    review_url: https://docs.example.com/limits  # optional\n

    Each entry has a path (relative to project root), desc (what constants live there), and optional review_url (where to check current values). When review_url is set, the nudge includes \"Review against: {url}\". When absent, just \"Touch the file to mark it as reviewed.\"

    Output: VERBATIM relay listing stale files, silent otherwise.

    ┌─ Technology Constants Stale ──────────────────────\n│   config/thresholds.yaml (210 days ago)\n│     - Model token limits and batch sizes\n│   Review against: https://docs.example.com/limits\n│ Touch each file to mark it as reviewed.\n└───────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-map-staleness-architecture-map-drift","level":4,"title":"check-map-staleness: Architecture Map Drift","text":"

    What: Checks whether map-tracking.json is older than 30 days and there are commits touching internal/ since the last map refresh. Daily throttle prevents repeated nudges.

    Why: Architecture documentation drifts silently as code evolves. This hook detects structural changes that the map hasn't caught up with and suggests running /ctx-architecture to refresh.

    Output: VERBATIM relay when stale and modules changed, silent otherwise.

    ┌─ Architecture Map Stale ────────────────────────────\n│ ARCHITECTURE.md hasn't been refreshed since 2026-01-15\n│ and there are commits touching 12 modules.\n│ /ctx-architecture keeps architecture docs drift-free.\n│\n│ Want me to run /ctx-architecture to refresh?\n└─────────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#heartbeat-session-heartbeat-webhook","level":4,"title":"heartbeat: Session Heartbeat Webhook","text":"

    What: Fires on every prompt. Sends a webhook notification with prompt count, session ID, context modification status, and token usage telemetry. Never produces stdout.

    Why: Other hooks only send webhooks when they \"speak\" (nudge/relay). When silent, you have no visibility into session activity. The heartbeat provides a continuous session-alive signal with token consumption data for observability dashboards or liveness monitoring.

    Output: None (webhook + event log only).

    Payload:

    {\n  \"event\": \"heartbeat\",\n  \"message\": \"heartbeat: prompt #7 (context_modified=false tokens=158k pct=79%)\",\n  \"detail\": {\n    \"hook\": \"heartbeat\",\n    \"variant\": \"pulse\",\n    \"variables\": {\n      \"prompt_count\": 7,\n      \"session_id\": \"abc...\",\n      \"context_modified\": false,\n      \"tokens\": 158000,\n      \"context_window\": 200000,\n      \"usage_pct\": 79\n    }\n  }\n}\n

    Token fields (tokens, context_window, usage_pct) are included when usage data is available from the session JSONL file.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tool-time-hooks-pretooluse-posttooluse","level":3,"title":"Tool-Time Hooks (PreToolUse / PostToolUse)","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#block-non-path-ctx-path-enforcement-hard-gate","level":4,"title":"block-non-path-ctx: PATH Enforcement (Hard Gate)","text":"

    What: Blocks any Bash command that invokes ./ctx, ./dist/ctx, go run ./cmd/ctx, or an absolute path to ctx. Only PATH invocations are allowed.

    Why: Enforces CONSTITUTION.md's invocation invariant. Running a dev-built binary in production context causes version confusion and silent behavior drift.

    Output: Block response (prevents the tool call):

    {\"decision\": \"block\", \"reason\": \"Use 'ctx' from PATH, not './ctx'...\"}\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#qa-reminder-pre-commit-qa-gate","level":4,"title":"qa-reminder: Pre-Commit QA Gate","text":"

    What: Fires on every Edit tool use. Reminds the agent to lint and test the entire project before committing.

    Why: Agents tend to \"I'll test later\" and then commit untested code. Repetition is intentional: the hook reinforces the habit on every edit, not just before commits.

    Output: Agent directive with hard QA gate instructions.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#post-commit-context-capture-after-commit","level":4,"title":"post-commit: Context Capture After Commit","text":"

    What: Fires after any git commit (excludes --amend). Prompts the agent to offer context capture (decision? learning?) and suggest running lints/tests before pushing.

    Why: Commits are natural reflection points. The nudge converts mechanical git operations into context-capturing opportunities.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#auditing-hooks-via-the-local-event-log","level":2,"title":"Auditing Hooks via the Local Event Log","text":"

    If you don't need an external audit trail, enable the local event log for a self-contained record of hook activity:

    # .ctxrc\nevent_log: true\n

    Once enabled, every hook that fires writes an entry to .context/state/events.jsonl. Query it with ctx system events:

    ctx system events                    # last 50 events\nctx system events --hook qa-reminder # filter by hook\nctx system events --session <id>     # filter by session\nctx system events --json | jq '.'    # raw JSONL for processing\n

    The event log is local, queryable, and doesn't require any external service. For a full diagnostic workflow combining event logs with structural health checks, see Troubleshooting.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#auditing-hooks-via-webhooks","level":2,"title":"Auditing Hooks via Webhooks","text":"

    The most powerful audit setup pipes all hook output to a webhook, giving you a real-time external record of what your agent is being told.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-1-set-up-the-webhook","level":3,"title":"Step 1: Set Up the Webhook","text":"
    ctx notify setup\n# Enter your webhook URL (Slack, Discord, ntfy.sh, IFTTT, etc.)\n

    See Webhook Notifications for service-specific setup.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-2-subscribe-to-relay-events","level":3,"title":"Step 2: Subscribe to relay Events","text":"
    # .ctxrc\nnotify:\n  events:\n    - relay   # all hook output: VERBATIM relays, directives, blocks\n    - nudge   # just the user-facing VERBATIM relays\n

    The relay event fires for every hook that produces output. This includes:

    Hook Event sent check-context-size relay + nudge check-persistence relay + nudge check-ceremonies relay + nudge check-journal relay + nudge check-resources relay + nudge check-knowledge relay + nudge check-version relay + nudge check-reminders relay + nudge check-freshness relay + nudge check-map-staleness relay + nudge heartbeat heartbeat only block-non-path-ctx relay only post-commit relay only qa-reminder relay only","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-3-cross-reference","level":3,"title":"Step 3: Cross-Reference","text":"

    With relay enabled, your webhook receives a JSON payload every time a hook fires:

    {\n  \"event\": \"relay\",\n  \"message\": \"check-persistence: No context updated in 20+ prompts\",\n  \"session_id\": \"b854bd9c\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"my-project\"\n}\n

    This creates an external audit trail independent of the agent. You can now cross-verify: did the agent actually relay the checkpoint the hook told it to relay?

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#verifying-hooks-actually-fire","level":2,"title":"Verifying Hooks Actually Fire","text":"

    Hooks are invisible. An invisible thing that breaks is indistinguishable from an invisible thing that never existed. Three verification methods, from simplest to most robust:

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-1-ask-the-agent","level":3,"title":"Method 1: Ask the Agent","text":"

    The simplest check. After a few prompts into a session:

    \"Did you receive any hook output this session? Print the last\ncontext checkpoint or persistence nudge you saw.\"\n

    The agent should be able to recall recent hook output from its context window. If it says \"I haven't received any hook output\", either:

    • The hooks aren't firing (check installation);
    • The session is too short (hooks throttle early);
    • The hooks fired but the agent absorbed them silently.

    Limitation: You are trusting the agent to report accurately. Agents sometimes confabulate or miss context. Use this as a quick smoke test, not definitive proof.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-2-check-the-webhook-trail","level":3,"title":"Method 2: Check the Webhook Trail","text":"

    If you have relay events enabled, check your webhook receiver. Every hook that fires sends a timestamped notification. No notification = no fire.

    This is the ground truth. The webhook is called directly by the ctx binary, not by the agent. The agent cannot fake, suppress, or modify webhook deliveries.

    Compare what the webhook received against what the agent claims to have relayed. Discrepancies mean the agent is absorbing nudges instead of surfacing them.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-3-read-the-local-logs","level":3,"title":"Method 3: Read the Local Logs","text":"

    Hooks that support logging write to .context/logs/:

    # Check context-size hook activity\ncat .context/logs/check-context-size.log\n\n# Sample output:\n# [2026-02-22 09:15:00] [session:b854bd9c] prompt#1 silent\n# [2026-02-22 09:17:33] [session:b854bd9c] prompt#16 CHECKPOINT\n# [2026-02-22 09:20:01] [session:b854bd9c] prompt#20 CHECKPOINT\n
    # Check persistence nudge activity\ncat .context/logs/check-persistence.log\n\n# Sample output:\n# [2026-02-22 09:15:00] [session:b854bd9c] init count=1 mtime=1770646611\n# [2026-02-22 09:20:01] [session:b854bd9c] prompt#20 NUDGE since_nudge=20\n

    Logs are append-only and written by the ctx binary, not the agent.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#detecting-silent-hook-failures","level":2,"title":"Detecting Silent Hook Failures","text":"

    The hardest failure mode: hooks that stop firing without error. The plugin config changes, a binary update drops a hook, or a PATH issue silently breaks execution. Nothing errors: The hook just never runs.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-staleness-signal","level":3,"title":"The Staleness Signal","text":"

    If .context/logs/check-context-size.log has no entries newer than 5 days but you've been running sessions daily, something is wrong. The absence of evidence is evidence of absence: but only if you control for inactivity.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#false-positive-protection","level":3,"title":"False Positive Protection","text":"

    A naive \"hooks haven't fired in N days\" alert fires incorrectly when you simply haven't used ctx. The correct check needs two inputs:

    1. Last hook fire time: from .context/logs/ or webhook history
    2. Last session activity: from journal entries or ctx recall list

    If sessions are happening but hooks aren't firing, that's a real problem. If neither sessions nor hooks are happening, that's a vacation.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#what-to-check","level":3,"title":"What to Check","text":"

    When you suspect hooks aren't firing:

    # 1. Verify the plugin is installed\nls ~/.claude/plugins/\n\n# 2. Check hook registration\ncat ~/.claude/plugins/ctx/hooks.json | head -20\n\n# 3. Run a hook manually to see if it errors\necho '{\"session_id\":\"test\"}' | ctx system check-context-size\n\n# 4. Check for PATH issues\nwhich ctx\nctx --version\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tips","level":2,"title":"Tips","text":"
    • Start with nudge, graduate to relay: The nudge event covers user-facing VERBATIM relays. Add relay when you want full visibility into agent directives and hard gates.
    • Webhooks are your trust anchor: The agent can ignore a nudge, but it can't suppress the webhook. If the webhook fired and the agent didn't relay, you have proof of a compliance gap.
    • Hooks are throttled by design: Most check hooks fire once per day or use adaptive frequency. Don't expect a notification every prompt: Silence usually means the throttle is working, not that the hook is broken.
    • Daily markers live in .context/state/: Throttle files are stored in .context/state/ alongside other project-scoped state. If you need to force a hook to re-fire during testing, delete the corresponding marker file.
    • The QA reminder is intentionally noisy: Unlike other hooks, qa-reminder fires on every Edit call with no throttle. This is deliberate: The commit quality degrades when the reminder fades from salience.
    • Log files are safe to commit: .context/logs/ contains only timestamps, session IDs, and status keywords. No secrets, no code.
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#next-up","level":2,"title":"Next Up","text":"

    Detecting and Fixing Drift →: Keep context files accurate as your codebase evolves.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#see-also","level":2,"title":"See Also","text":"
    • Troubleshooting: full diagnostic workflow using ctx doctor, event logs, and /ctx-doctor
    • Customizing Hook Messages: override what hooks say without changing what they do
    • Webhook Notifications: setting up and configuring the webhook system
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Detecting and Fixing Drift: structural checks that complement runtime hook auditing
    • CLI Reference: full ctx system command reference
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/task-management/","level":1,"title":"Tracking Work Across Sessions","text":"","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-problem","level":2,"title":"The Problem","text":"

    You have work that spans multiple sessions. Tasks get added during one session, partially finished in another, and completed days later.

    Without a system, follow-up items fall through the cracks, priorities drift, and you lose track of what was done versus what still needs doing. TASKS.md grows cluttered with completed checkboxes that obscure the remaining work.

    How do you manage work items that span multiple sessions without losing context?

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#tldr","level":2,"title":"TL;DR","text":"

    Manage Tasks:

    ctx add task \"Fix race condition\" --priority high  # add\nctx add task \"Write tests\" --section \"Phase 2\"     # add to phase\nctx task complete \"race condition\"                      # mark done\nctx task snapshot \"before-refactor\"               # backup\nctx task archive                                  # clean up\n

    Pick Up the Next Task:

    /ctx-next # pick what's next\n

    Read on for the full workflow and conversational patterns.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx add task Command Add a new task to TASKS.md ctx task complete Command Mark a task as done by number or text ctx task snapshot Command Create a point-in-time backup of TASKS.md ctx task archive Command Move completed tasks to archive file /ctx-add-task Skill AI-assisted task creation with validation /ctx-archive Skill AI-guided archival with safety checks /ctx-next Skill Pick what to work on based on priorities","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-1-add-tasks-with-priorities","level":3,"title":"Step 1: Add Tasks with Priorities","text":"

    Every piece of follow-up work gets a task. Use ctx add task from the terminal or /ctx-add-task from your AI assistant. Tasks should start with a verb and be specific enough that someone unfamiliar with the session could act on them.

    # High-priority bug found during code review\nctx add task \"Fix race condition in session cooldown\" --priority high\n\n# Medium-priority feature work\nctx add task \"Add --format json flag to ctx status for CI integration\" --priority medium\n\n# Low-priority cleanup\nctx add task \"Remove deprecated --raw flag from ctx load\" --priority low\n

    The /ctx-add-task skill validates your task before recording it. It checks that the description is actionable, not a duplicate, and specific enough for someone else to pick up.

    If you say \"fix the bug,\" it will ask you to clarify which bug and where.

    Tasks Are Often Created Proactively

    In practice, many tasks are created proactively by the agent rather than by explicit CLI commands.

    After completing a feature, the agent will often identify follow-up work: tests, docs, edge cases, error handling, and offer to add them as tasks.

    You do not need to dictate ctx add task commands; the agent picks up on work context and suggests tasks naturally.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-2-organize-with-phase-sections","level":3,"title":"Step 2: Organize with Phase Sections","text":"

    Tasks live in phase sections inside TASKS.md.

    Phases provide logical groupings that preserve order and enable replay.

    A task does not move between sections. It stays in its phase permanently, and status is tracked via checkboxes and inline tags.

    ## Phase 1: Core CLI\n\n- [x] Implement ctx add command `#done:2026-02-01-143022`\n- [x] Implement ctx task complete command `#done:2026-02-03-091544`\n- [ ] Add --section flag to ctx add task `#priority:medium`\n\n## Phase 2: AI Integration\n\n- [ ] Implement ctx agent cooldown `#priority:high` `#in-progress`\n- [ ] Add ctx watch XML parsing `#priority:medium`\n  - Blocked by: Need to finalize agent output format\n\n## Backlog\n\n- [ ] Performance optimization for large TASKS.md files `#priority:low`\n- [ ] Add metrics dashboard to ctx status `#priority:deferred`\n

    Use --section when adding a task to a specific phase:

    ctx add task \"Add ctx watch XML parsing\" --priority medium --section \\\n    \"Phase 2: AI Integration\"\n

    Without --section, the task is inserted before the first unchecked task in TASKS.md.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-3-pick-what-to-work-on","level":3,"title":"Step 3: Pick What to Work On","text":"

    At the start of a session, or after finishing a task, use /ctx-next to get prioritized recommendations.

    The skill reads TASKS.md, checks recent sessions, and ranks candidates using explicit priority, blocking status, in-progress state, momentum from recent work, and phase order.

    You can also ask naturally: \"what should we work on?\" or \"what's the highest priority right now?\"

    /ctx-next\n

    The output looks like this:

    **1. Implement ctx agent cooldown** `#priority:high`\n\n    Still in-progress from yesterday's session. The tombstone file approach is\n    half-built. Finishing is cheaper than context-switching.\n\n**2. Add --section flag to ctx add task** `#priority:medium`\n\n    Last Phase 1 item. Quick win that unblocks organized task entry.\n\n---\n\n*Based on 8 pending tasks across 3 phases.\n\nLast session: agent-cooldown (2026-02-06).*\n

    In-progress tasks almost always come first:

    Finishing existing work takes priority over starting new work.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-4-complete-tasks","level":3,"title":"Step 4: Complete Tasks","text":"

    When a task is done, mark it complete by number or partial text match:

    # By task number (as shown in TASKS.md)\nctx task complete 3\n\n# By partial text match\nctx task complete \"agent cooldown\"\n

    The task's checkbox changes from [ ] to [x] and a #done timestamp is added. Tasks are never deleted: they stay in their phase section so history is preserved.

    Be Conversational

    You rarely need to run ctx task complete yourself during an interactive session.

    When you say something like \"the rate limiter is done\" or \"we finished that,\" the agent marks the task complete and moves on to suggesting what is next.

    The CLI commands are most useful for manual housekeeping, scripted workflows, or when you want precision.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-5-snapshot-before-risky-changes","level":3,"title":"Step 5: Snapshot Before Risky Changes","text":"

    Before a major refactor or any change that might break things, snapshot your current task state. This creates a copy of TASKS.md in .context/archive/ without modifying the original.

    # Default snapshot\nctx task snapshot\n\n# Named snapshot (recommended before big changes)\nctx task snapshot \"before-refactor\"\n

    This creates a file like .context/archive/tasks-before-refactor-2026-02-08-1430.md. If the refactor goes sideways, and you need to confirm what the task state looked like before you started, the snapshot is there.

    Snapshots are cheap: Take them before any change you might want to undo or review later.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-6-archive-when-tasksmd-gets-cluttered","level":3,"title":"Step 6: Archive When TASKS.md Gets Cluttered","text":"

    After several sessions, TASKS.md accumulates completed tasks that make it hard to see what is still pending.

    Use ctx task archive to move all [x] items to a timestamped archive file.

    Start with a dry run to preview what will be moved:

    ctx task archive --dry-run\n

    Then archive:

    ctx task archive\n

    Completed tasks move to .context/archive/tasks-2026-02-08.md. Phase headers are preserved in the archive for traceability. Pending tasks ([ ]) remain in TASKS.md.

    The /ctx-archive skill adds two safety checks before archiving: it verifies that completed tasks are genuinely cluttering the view and that nothing was marked [x] prematurely.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#letting-the-agent-drive","level":2,"title":"Letting the Agent Drive","text":"

    The steps above show the CLI commands for task management.

    In practice, most task management happens conversationally:

    An agent that has loaded the context files does not need you to type ctx add task. It tracks work naturally and offers the right operations.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#use-natural-language-instead-of-commands","level":3,"title":"Use Natural Language Instead of Commands","text":"

    These conversational prompts replace explicit commands during interactive sessions:

    Instead of typing... Just say... ctx add task \"Write tests for X\" \"We should add tests for this: track that?\" /ctx-next \"What should we work on?\" ctx task complete \"rate limiting\" \"The rate limiter is done, what's next?\" ctx task archive \"TASKS.md is getting long, can you clean it up?\" ctx add task ... && ctx add task ... \"Add follow-ups for what we just built.\"

    The agent translates these into the right ctx operations behind the scenes.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-agent-creates-tasks-proactively","level":3,"title":"The Agent Creates Tasks Proactively","text":"

    After completing a piece of work, the agent does not wait for you to dictate follow-up items. It identifies them from the work context and offers:

    **Agent**: \"I've finished implementing the rate limiter middleware. I noticed\nthree follow-up items:\n\n1. Write integration tests for the rate limiter (the unit tests pass but\n   there's no end-to-end coverage)\n2. Add rate limit headers to API responses (X-RateLimit-Remaining, etc.)\n3. Document the rate limit configuration in the ops runbook\n\nWant me to add these as tasks?\"\n

    This is how an agent behaves once it has read the Agent Playbook.

    The playbook's \"Work, Reflect, Persist\" cycle means the agent asks itself after every milestone: Did I just complete a task? Did new work emerge?

    When the answer is yes, it acts.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#asking-the-agent-what-to-capture","level":3,"title":"Asking the Agent What to Capture","text":"

    You don't always know what's worth persisting.

    Instead of reviewing the session yourself and typing specific commands, ask the agent to do the thinking:

    You say What happens \"What tasks came out of this session?\" Agent reviews the work, identifies follow-ups, and offers to add them \"Are there any tasks, learnings, or decisions worth adding?\" Agent scans the full session for all three types and proposes a batch \"What should we remember from today?\" Agent surfaces everything persist-worthy: not just tasks \"Anything we should track before we move on?\" Agent checks for loose ends specific to the work just completed

    This is especially powerful after long or exploratory sessions where multiple threads were touched.

    The agent has the full conversation in context and can spot follow-ups you might miss:

    You:   \"Are there any tasks, learnings, or decisions worth adding\n        from this session?\"\n\nAgent: \"Yes. Here's what I'd suggest:\n\n  Tasks:\n  - Add retry logic to the webhook delivery (we discussed it when\n    the timeout test failed but never tracked it)\n  - Update the API docs to reflect the new rate limit headers\n\n  Learnings:\n  - net/http's default client has no timeout: we burned 15 minutes\n    on that before adding an explicit 30s timeout\n\n  Decisions:\n  - We chose token-bucket over sliding-window for rate limiting\n    because it handles bursts better and the library is simpler\n\n  Want me to add all of these?\"\n\nYou:   \"All of them.\"\n

    The agent fills in structured fields from what it observed during the session. You get the same quality entries as if you typed verbose commands, without needing to remember what happened or how to format it.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-agent-completes-tasks-and-moves-on","level":3,"title":"The Agent Completes Tasks and Moves On","text":"

    When you confirm that work is finished, or when the agent can see that it is, it marks the task done and suggests the next step:

    You: \n\"The cooldown logic is working now.\"\n\nAgent: \n\"Marked 'Implement ctx agent cooldown' as done. Your highest-\npriority remaining task is 'Add --section flag to ctx add task'.\n\nIt's the last item in Phase 1 and a quick win. Want to start on that?\"\n

    The agent chains completion into next-task selection.

    One sentence from you triggers two operations.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#end-of-session-capture","level":3,"title":"End-of-Session Capture","text":"

    At the end of a session, the agent reviews what happened and catches loose ends:

    You: \n\"I think we're good for today.\"\n\nAgent: \n\"Before we wrap up: during the middleware work you mentioned\nwanting to add metrics for rate limit hits. That never made it into TASKS.md.\n\nWant me to add it as a task so it's there next session?\"\n

    This is the proactive persistence model at work.

    The agent monitors the conversation for mentioned-but-not-tracked work and surfaces it before context is lost.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#a-conversational-session-example","level":3,"title":"A Conversational Session Example","text":"

    Here is what task management looks like in a real session when the agent is driving:

    You:   What's left to do?\nAgent: You have 5 pending tasks across 2 phases. The highest priority is\n       \"Implement ctx agent cooldown\": it's marked in-progress from\n       yesterday and half-built. Want to pick that up?\n\nYou:   Yeah, let's finish it.\n       [... 20 minutes of implementation work ...]\n\nYou:   That's working. Tests pass.\nAgent: Nice. I'll mark \"Implement ctx agent cooldown\" as done.\n       I noticed two things from the implementation:\n       1. The tombstone file cleanup should happen on a timer, not just\n          at startup. Want me to add that as a task?\n       2. We learned that file locks don't work reliably on NFS. I'll\n          add that to LEARNINGS.md.\n\nYou:   Yes to both. What's next?\nAgent: Added the cleanup task as high priority. Next up is \"Add --section\n       flag to ctx add task\": last item in Phase 1. It should be\n       straightforward since the flag parsing pattern already exists\n       in the codebase. Ready?\n

    It's All Conversational

    Notice what did not happen: The user never typed a ctx command.

    The agent handled task completion, follow-up creation, learning capture, and next-task selection: all from natural conversation.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"
    # Add a task\nctx add task \"Implement rate limiting for API endpoints\" --priority high\n\n# Add to a specific phase\nctx add task \"Write integration tests for rate limiter\" --section \"Phase 2\"\n\n# See what to work on\n# (from AI assistant) /ctx-next\n\n# Mark done by text\nctx task complete \"rate limiting\"\n\n# Mark done by number\nctx task complete 5\n\n# Snapshot before a risky refactor\nctx task snapshot \"before-middleware-rewrite\"\n\n# Archive completed tasks when the list gets long\nctx task archive --dry-run     # preview first\nctx task archive               # then archive\n
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#tips","level":2,"title":"Tips","text":"
    • Start tasks with a verb: \"Add,\" \"Fix,\" \"Implement,\" \"Investigate\": not just a topic like \"Authentication.\"
    • Include the why in the task description. Future sessions lack the context of why you added the task. \"Add rate limiting\" is worse than \"Add rate limiting to prevent abuse on the public API after the load test showed 10x traffic spikes.\"
    • Use #in-progress sparingly. Only one or two tasks should carry this tag at a time. If everything is in-progress, nothing is.
    • Snapshot before, not after. The point of a snapshot is to capture the state before a change, not to celebrate what you just finished.
    • Archive regularly. Once completed tasks outnumber pending ones, it is time to archive. A clean TASKS.md helps both you and your AI assistant focus.
    • Never delete tasks. Mark them [x] (completed) or [-] (skipped with a reason). Deletion breaks the audit trail.
    • Trust the agent's task instincts. When the agent suggests follow-up items after completing work, it is drawing on the full context of what just happened.
    • Conversational prompts beat commands in interactive sessions. Saying \"what should we work on?\" is faster and more natural than running /ctx-next. Save explicit commands for scripts, CI, and unattended runs.
    • Let the agent chain operations. A single statement like \"that's done, what's next?\" can trigger completion, follow-up identification, and next-task selection in one flow.
    • Review proactive task suggestions before moving on. The best follow-ups come from items spotted in-context right after the work completes.
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#next-up","level":2,"title":"Next Up","text":"

    Using the Scratchpad →: Store short-lived sensitive notes in an encrypted scratchpad.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle including task management in context
    • Persisting Decisions, Learnings, and Conventions: capturing the \"why\" behind your work
    • Detecting and Fixing Drift: keeping TASKS.md accurate over time
    • CLI Reference: full documentation for ctx add, ctx task complete, ctx task
    • Context Files: TASKS.md: format and conventions for TASKS.md
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/troubleshooting/","level":1,"title":"Troubleshooting","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-problem","level":2,"title":"The Problem","text":"

    Something isn't working: a hook isn't firing, nudges are too noisy, context seems stale, or the agent isn't following instructions. The information to diagnose it exists (across status, drift, event logs, hook config, and session history), but assembling it manually is tedious.

    How do you figure out what's wrong and fix it?

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#tldr","level":2,"title":"TL;DR","text":"
    ctx doctor                   # structural health check\nctx system events --last 20  # recent hook activity\n# or ask: \"something seems off, can you diagnose?\"\n
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx doctor CLI command Structural health report ctx doctor --json CLI command Machine-readable health report ctx system events CLI command Query local event log /ctx-doctor Skill Agent-driven diagnosis with analysis","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#quick-check-ctx-doctor","level":3,"title":"Quick Check: ctx doctor","text":"

    Run ctx doctor for an instant structural health report. It checks context initialization, required files, drift, hook configuration, event logging, webhooks, reminders, task completion ratio, and context token size: all in one pass:

    ctx doctor\n
    ctx doctor\n==========\n\nStructure\n  ✓ Context initialized (.context/)\n  ✓ Required files present (4/4)\n\nQuality\n  ⚠ Drift: 2 warnings (stale path in ARCHITECTURE.md, high entry count in LEARNINGS.md)\n\nHooks\n  ✓ hooks.json valid (14 hooks registered)\n  ○ Event logging disabled (enable with event_log: true in .ctxrc)\n\nState\n  ✓ No pending reminders\n  ⚠ Task completion ratio high (18/22 = 82%): consider archiving\n\nSize\n  ✓ Context size: ~4200 tokens (budget: 8000)\n\nSummary: 2 warnings, 0 errors\n

    Warnings are non-critical but worth fixing. Errors need attention. Informational notes (○) flag optional features that aren't enabled.

    For scripting:

    ctx doctor --json | jq '.warnings'\n
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#deep-dive-ctx-doctor","level":3,"title":"Deep Dive: /ctx-doctor","text":"

    When you need the agent to reason about what's wrong, use the skill. Ask naturally or invoke directly:

    Why didn't my hook fire?\nSomething seems off, can you diagnose?\n/ctx-doctor\n

    The agent follows a triage sequence:

    1. Baseline: runs ctx doctor --json for structural health
    2. Events: runs ctx system events --json --last 100 (if event logging enabled)
    3. Correlate: connects findings across both sources
    4. Present: structured findings with evidence
    5. Suggest: actionable next steps (but doesn't auto-fix)

    The skill degrades gracefully: without event logging enabled, it still runs structural checks and notes what you'd gain by enabling it.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#raw-event-inspection","level":3,"title":"Raw Event Inspection","text":"

    For power users: ctx system events with filters gives direct access to the event log.

    # Last 50 events (default)\nctx system events\n\n# Events from a specific session\nctx system events --session eb1dc9cd-0163-4853-89d0-785fbfaae3a6\n\n# Only QA reminder events\nctx system events --hook qa-reminder\n\n# Raw JSONL for jq processing\nctx system events --json | jq '.message'\n\n# Include rotated (older) events\nctx system events --all --last 100\n

    Filters use AND logic: --hook qa-reminder --session abc123 returns only QA reminder events from that specific session.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#common-problems","level":2,"title":"Common Problems","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#ctx-not-initialized","level":3,"title":"\"ctx: not initialized\"","text":"

    Symptoms: Any ctx command fails with ctx: not initialized - run \"ctx init\" first.

    Cause: You're running ctx in a directory without an initialized .context/ directory. This guard runs on all user-facing commands to prevent confusing downstream errors.

    Fix:

    ctx init          # create .context/ with template files\nctx init --minimal  # or just the essentials (CONSTITUTION, TASKS, DECISIONS)\n

    Commands that work without initialization: ctx init, ctx hook, ctx doctor, and help-only grouping commands (ctx, ctx system).

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#my-hook-isnt-firing","level":3,"title":"\"My hook isn't firing\"","text":"

    Symptoms: No nudges appearing, webhook silent, event log shows no entries for the expected hook.

    Diagnosis:

    # 1. Check if ctx is installed and on PATH\nwhich ctx && ctx --version\n\n# 2. Check if the hook is registered\ngrep \"check-persistence\" ~/.claude/plugins/ctx/hooks.json\n\n# 3. Run the hook manually to see if it errors\necho '{\"session_id\":\"test\"}' | ctx system check-persistence\n\n# 4. Check event log for the hook (if enabled)\nctx system events --hook check-persistence\n

    Common causes:

    • Plugin is not installed: run ctx init --claude to reinstall
    • PATH issue: the hook invokes ctx from PATH; ensure it resolves
    • Throttle active: most hooks fire once per day: check .context/state/ for daily marker files
    • Hook silenced: a custom message override may be an empty file: check ctx system message list for overrides
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#too-many-nudges","level":3,"title":"\"Too many nudges\"","text":"

    Symptoms: The agent is overwhelmed with hook output. Context checkpoints, persistence reminders, and QA gates fire constantly.

    Diagnosis:

    # Check how often hooks fired recently\nctx system events --last 50\n\n# Count fires per hook\nctx system events --json | jq -r '.detail.hook // \"unknown\"' \\\n  | sort | uniq -c | sort -rn\n

    Common causes:

    • QA reminder is noisy by design: it fires on every Edit call with no throttle. This is intentional. If it's too much, silence it with an empty override: ctx system message edit qa-reminder gate, then empty the file
    • Long session: context checkpoint fires with increasing frequency after prompt 15. This is the system telling you the session is getting long: consider wrapping up
    • Short throttle window: if you deleted marker files in .context/state/, daily-throttled hooks will re-fire
    • Outdated Claude Code plugin: Update the plugin using Claude Code → /plugin → \"Marketplace\"
    • ctx version mismatch: Build (or download) and install the latest ctx vesion.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#context-seems-stale","level":3,"title":"\"Context seems stale\"","text":"

    Symptoms: The agent references outdated information, paths that don't exist, or decisions that were reversed.

    Diagnosis:

    # Structural drift check\nctx drift\n\n# Full doctor check (includes drift + more)\nctx doctor\n\n# Check when context files were last modified\nctx status --verbose\n

    Common causes:

    • Drift accumulated: stale path references in ARCHITECTURE.md or CONVENTIONS.md. Fix with ctx drift --fix or ask the agent to clean up.
    • Task backlog: too many completed tasks diluting active context. Archive with ctx task archive or ctx compact --archive.
    • Large context files: LEARNINGS.md with 40+ entries competes for attention. Consolidate with /ctx-consolidate.
    • Missing session ceremonies: if /ctx-remember and /ctx-wrap-up aren't being used, context doesn't get refreshed. See Session Ceremonies.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-agent-isnt-following-instructions","level":3,"title":"\"The agent isn't following instructions\"","text":"

    Symptoms: The agent ignores conventions, forgets decisions, or acts contrary to CONSTITUTION.md rules.

    Diagnosis:

    # Check context token size: Is it too large for the model?\nctx doctor --json | jq '.results[] | select(.name == \"context_size\")'\n\n# Check if context is actually being loaded\nctx system events --hook context-load-gate\n

    Common causes:

    • Context too large: if total tokens exceed the model's effective attention, instructions get diluted. Check ctx doctor for the size check. Compact with ctx compact --archive.
    • Context not loading: if context-load-gate hasn't fired, the agent may not have received context. Verify the hook is registered.
    • Conflicting instructions: CONVENTIONS.md says one thing, AGENT_PLAYBOOK.md says another. Review both files for consistency.
    • Agent drift: the agent's behavior diverges from instructions over long sessions. This is normal. Use /ctx-reflect to re-anchor, or start a new session.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#prerequisites","level":2,"title":"Prerequisites","text":"
    • Event logging (optional but recommended): event_log: true in .ctxrc
    • ctx initialized: ctx init

    Event logging is not required for ctx doctor or /ctx-doctor to work. Both degrade gracefully: structural checks run regardless, and the skill notes when event data is unavailable.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#tips","level":2,"title":"Tips","text":"
    • Start with ctx doctor: It's the fastest way to get a comprehensive health picture. Save event log inspection for when you need to understand when and how often something happened.
    • Enable event logging early: The log is opt-in and low-cost (~250 bytes per event, 1MB rotation cap). Enable it before you need it: Diagnosing a problem without historical data is much harder.
    • Use the skill for correlation: ctx doctor tells you what is wrong. /ctx-doctor tells you why by correlating structural findings with event patterns. The agent can spot connections that individual commands miss.
    • Event log is gitignored: It's machine-local diagnostic data, not project context. Different machines produce different event streams.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#next-up","level":2,"title":"Next Up","text":"

    Detecting and Fixing Drift →: Keep context files accurate as your codebase evolves.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#see-also","level":2,"title":"See Also","text":"
    • Auditing System Hooks: the complete hook catalog and webhook-based audit trails
    • Detecting and Fixing Drift: structural and semantic drift detection and repair
    • Webhook Notifications: push notifications for hook activity
    • ctx doctor CLI: full command reference
    • ctx system events CLI: event log query reference
    • /ctx-doctor skill: agent-driven diagnosis
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/webhook-notifications/","level":1,"title":"Webhook Notifications","text":"","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#the-problem","level":2,"title":"The Problem","text":"

    Your agent runs autonomously (loops, implements, releases) while you are away from the terminal. You have no way to know when it finishes, hits a limit, or when a hook fires a nudge.

    How do you get notified about agent activity without watching the terminal?

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#tldr","level":2,"title":"TL;DR","text":"
    ctx notify setup  # configure webhook URL (encrypted)\nctx notify test   # verify delivery\n# Hooks auto-notify on: session-end, loop-iteration, resource-danger\n
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx notify setup CLI command Configure and encrypt webhook URL ctx notify test CLI command Send a test notification ctx notify --event <name> \"msg\" CLI command Send a notification from scripts/skills .ctxrc notify.events Configuration Filter which events reach your webhook","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-1-get-a-webhook-url","level":3,"title":"Step 1: Get a Webhook URL","text":"

    Any service that accepts HTTP POST with JSON works. Common options:

    Service How to get a URL IFTTT Create an applet with the \"Webhooks\" trigger Slack Create an Incoming Webhook Discord Channel Settings > Integrations > Webhooks ntfy.sh Use https://ntfy.sh/your-topic (no signup) Pushover Use API endpoint with your user key

    The URL contains auth tokens. ctx encrypts it; it never appears in plaintext in your repo.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-2-configure-the-webhook","level":3,"title":"Step 2: Configure the Webhook","text":"
    ctx notify setup\n# Enter webhook URL: https://maker.ifttt.com/trigger/ctx/json/with/key/YOUR_KEY\n# Webhook configured: https://maker.ifttt.com/***\n# Encrypted at: .context/.notify.enc\n

    This encrypts the URL with AES-256-GCM using the same key as the scratchpad (~/.ctx/.ctx.key). The encrypted file (.context/.notify.enc) is safe to commit. The key lives outside the project and is never committed.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-3-test-it","level":3,"title":"Step 3: Test It","text":"
    ctx notify test\n# Webhook responded: HTTP 200 OK\n

    If you see No webhook configured, run ctx notify setup first.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-4-configure-events","level":3,"title":"Step 4: Configure Events","text":"

    Notifications are opt-in: no events are sent unless you configure an event list in .ctxrc:

    # .ctxrc\nnotify:\n  events:\n    - loop       # loop completion or max-iteration hit\n    - nudge      # VERBATIM relay hooks (context checkpoint, persistence, etc.)\n    - relay      # all hook output (verbose, for debugging)\n    - heartbeat  # every-prompt session-alive signal with metadata\n

    Only listed events fire. Omitting an event silently drops it.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-5-use-in-your-own-skills","level":3,"title":"Step 5: Use in Your Own Skills","text":"

    Add ctx notify calls to any skill or script:

    # In a release skill\nctx notify --event release \"v1.2.0 released successfully\" 2>/dev/null || true\n\n# In a backup script\nctx notify --event backup \"Nightly backup completed\" 2>/dev/null || true\n

    The 2>/dev/null || true suffix ensures the notification never breaks your script: If there's no webhook or the HTTP call fails, it's a silent noop.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#event-types","level":2,"title":"Event Types","text":"

    ctx fires these events automatically:

    Event Source When loop Loop script Loop completes or hits max iterations nudge System hooks VERBATIM relay nudge is emitted (context checkpoint, persistence, ceremonies, journal, resources, knowledge, version) relay System hooks Any hook output (VERBATIM relays, agent directives, block responses) heartbeat System hook Every prompt: session-alive signal with prompt count and context modification status test ctx notify test Manual test notification (custom) Your skills You wire ctx notify --event <name> in your own scripts

    nudge vs relay: The nudge event fires only for VERBATIM relay hooks (the ones the agent is instructed to show verbatim). The relay event fires for all hook output: VERBATIM relays, agent directives, and hard gates. Subscribe to relay for debugging (\"did the agent get the post-commit nudge?\"), nudge for user-facing assurance (\"was the checkpoint emitted?\").

    Webhooks as a Hook Audit Trail

    Subscribe to relay events and you get an external record of every hook that fires, independent of the agent.

    This lets you verify hooks are running and catch cases where the agent absorbs a nudge instead of surfacing it.

    See Auditing System Hooks for the full workflow.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#payload-format","level":2,"title":"Payload Format","text":"

    Every notification sends a JSON POST:

    {\n  \"event\": \"nudge\",\n  \"message\": \"check-context-size: Context window at 82%\",\n  \"detail\": {\n    \"hook\": \"check-context-size\",\n    \"variant\": \"window\",\n    \"variables\": {\"Percentage\": 82, \"TokenCount\": \"164k\"}\n  },\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"ctx\"\n}\n

    The detail field is a structured template reference containing the hook name, variant, and any template variables. This lets receivers filter by hook or variant without parsing rendered text. The field is omitted when no template reference applies (e.g. custom ctx notify calls).

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#heartbeat-payload","level":3,"title":"Heartbeat Payload","text":"

    The heartbeat event fires on every prompt with session metadata and token usage telemetry:

    {\n  \"event\": \"heartbeat\",\n  \"message\": \"heartbeat: prompt #7 (context_modified=false tokens=158k pct=79%)\",\n  \"detail\": {\n    \"hook\": \"heartbeat\",\n    \"variant\": \"pulse\",\n    \"variables\": {\n      \"prompt_count\": 7,\n      \"session_id\": \"abc123-...\",\n      \"context_modified\": false,\n      \"tokens\": 158000,\n      \"context_window\": 200000,\n      \"usage_pct\": 79\n    }\n  },\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-28T10:15:00Z\",\n  \"project\": \"ctx\"\n}\n

    The tokens, context_window, and usage_pct fields are included when token data is available from the session JSONL file. They are omitted when no usage data has been recorded yet (e.g. first prompt).

    Unlike other events, heartbeat fires every prompt (not throttled). Use it for observability dashboards or liveness monitoring of long-running sessions.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#security-model","level":2,"title":"Security Model","text":"Component Location Committed? Permissions Encryption key ~/.ctx/.ctx.key No (user-level) 0600 Encrypted URL .context/.notify.enc Yes (safe) 0600 Webhook URL Never on disk in plaintext N/A N/A

    The key is shared with the scratchpad. If you rotate the encryption key, re-run ctx notify setup to re-encrypt the webhook URL with the new key.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#key-rotation","level":2,"title":"Key Rotation","text":"

    ctx checks the age of the encryption key once per day. If it's older than 90 days (configurable via key_rotation_days), a VERBATIM nudge is emitted suggesting rotation.

    # .ctxrc\nkey_rotation_days: 30   # nudge sooner (default: 90)\n
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#worktrees","level":2,"title":"Worktrees","text":"

    The webhook URL is encrypted with the same encryption key (~/.ctx/.ctx.key). Because the key lives at the user level, it is shared across all worktrees on the same machine - notifications work in worktrees automatically.

    This means agents running in worktrees cannot send webhook alerts. For autonomous runs where worktree agents are opaque, monitor them from the terminal rather than relying on webhooks. Enrich journals and review results on the main branch after merging.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#event-log-the-local-complement","level":2,"title":"Event Log: The Local Complement","text":"

    Don't need a webhook but want diagnostic visibility? Enable event_log: true in .ctxrc. The event log writes the same payload as webhooks to a local JSONL file (.context/state/events.jsonl) that you can query without any external service:

    ctx system events --last 20          # recent hook activity\nctx system events --hook qa-reminder # filter by hook\n

    Webhooks and event logging are independent: you can use either, both, or neither. Webhooks give you push notifications and an external audit trail. The event log gives you local queryability and ctx doctor integration.

    See Troubleshooting for how they work together.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#tips","level":2,"title":"Tips","text":"
    • Fire-and-forget: Notifications never block. HTTP errors are silently ignored. No retry, no response parsing.
    • No webhook = no cost: When no webhook is configured, ctx notify exits immediately. System hooks that call notify.Send() add zero overhead.
    • Multiple projects: Each project has its own .notify.enc. You can point different projects at different webhooks.
    • Event filter is per-project: Configure notify.events in each project's .ctxrc independently.
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#next-up","level":2,"title":"Next Up","text":"

    Auditing System Hooks →: Verify your hooks are running, audit what they do, and get alerted when they go silent.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: ctx notify: full command reference
    • Configuration: .ctxrc settings including notify options
    • Running an Unattended AI Agent: how loops work and how notifications fit in
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Auditing System Hooks: using webhooks as an external audit trail for hook execution
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/","level":1,"title":"When to Use a Team of Agents","text":"","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-problem","level":2,"title":"The Problem","text":"

    You have a task, and you are wondering: \"should I throw more agents at it?\"

    More agents can mean faster results, but they also mean coordination overhead, merge conflicts, divergent mental models, and wasted tokens re-reading context.

    The wrong setup costs more than it saves.

    This recipe is a decision framework: It helps you choose between a single agent, parallel worktrees, and a full agent team, and explains what ctx provides at each level.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#tldr","level":2,"title":"TL;DR","text":"
    • Single agent for most work;
    • Parallel worktrees when tasks touch disjoint file sets;
    • Agent teams only when tasks need real-time coordination. When in doubt, start with one agent.
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-spectrum","level":2,"title":"The Spectrum","text":"

    There are three modes, ordered by complexity:

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#1-single-agent-default","level":3,"title":"1. Single Agent (Default)","text":"

    One agent, one session, one branch. This is correct for most work.

    Use this when:

    • The task has linear dependencies (step 2 needs step 1's output);
    • Changes touch overlapping files;
    • You need tight feedback loops (review each change before the next);
    • The task requires deep understanding of a single area;
    • Total effort is less than a few hours of agent time.

    ctx provides: Full .context/: tasks, decisions, learnings, conventions, all in one session.

    The agent builds a coherent mental model and persists it as it goes.

    Example tasks: Bug fixes, feature implementation, refactoring a module, writing documentation for one area, debugging.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#2-parallel-worktrees-independent-tracks","level":3,"title":"2. Parallel Worktrees (Independent Tracks)","text":"

    2-4 agents, each in a separate git worktree on its own branch, working on non-overlapping parts of the codebase.

    Use this when:

    • You have 5+ independent tasks in the backlog;
    • Tasks group cleanly by directory or package;
    • File overlap between groups is zero or near-zero;
    • Each track can be completed and merged independently;
    • You want parallelism without coordination complexity.

    ctx provides: Shared .context/ via git (each worktree sees the same tasks, decisions, conventions). /ctx-worktree skill for setup and teardown. TASKS.md as a lightweight work queue.

    Example tasks: Docs + new package + test coverage (three tracks that don't touch the same files). Parallel recipe writing. Independent module development.

    See: Parallel Agent Development with Git Worktrees

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#3-agent-team-coordinated-swarm","level":3,"title":"3. Agent Team (Coordinated Swarm)","text":"

    Multiple agents communicating via messages, sharing a task list, with a lead agent coordinating. Claude Code's team/swarm feature.

    Use this when:

    • Tasks have dependencies but can still partially overlap;
    • You need research and implementation happening simultaneously;
    • The work requires different roles (researcher, implementer, tester);
    • A lead agent needs to review and integrate others' work;
    • The task is large enough that coordination cost is justified.

    ctx provides: .context/ as shared state that all agents can read. Task tracking for work assignment. Decisions and learnings as team memory that survives individual agent turnover.

    Example tasks: Large refactor across modules where a lead reviews merges. Research and implementation where one agent explores options while another builds. Multi-file feature that needs integration testing after parallel implementation.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-decision-framework","level":2,"title":"The Decision Framework","text":"

    Ask these questions in order:

    Can one agent do this in a reasonable time?\n  YES → Single agent. Stop here.\n  NO  ↓\n\nCan the work be split into non-overlapping file sets?\n  YES → Parallel worktrees (2-4 tracks)\n  NO  ↓\n\nDo the subtasks need to communicate during execution?\n  YES → Agent team with lead coordination\n  NO  → Parallel worktrees with a merge step\n
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-file-overlap-test","level":3,"title":"The File Overlap Test","text":"

    This is the critical decision point. Before choosing multi-agent, list the files each subtask would touch. If two subtasks modify the same file, they belong in the same track (or the same single-agent session).

    You: \"I want to parallelize these tasks. Which files would each one touch?\"\n\nAgent: [reads `TASKS.md`, analyzes codebase]\n       \"Task A touches internal/config/ and internal/cli/initialize/\n        Task B touches docs/ and site/\n        Task C touches internal/config/ and internal/cli/status/\n\n        Tasks A and C overlap on internal/config/ # they should be\n        in the same track. Task B is independent.\"\n

    When in doubt, keep things in one track. A merge conflict in a critical file costs more time than the parallelism saves.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#when-teams-make-things-worse","level":2,"title":"When Teams Make Things Worse","text":"

    \"More agents\" is not always better. Watch for these patterns:

    Merge hell: If you are spending more time resolving conflicts than the parallel work saved, you split wrong: Re-group by file overlap.

    Context divergence: Each agent builds its own mental model. After 30 minutes of independent work, agent A might make assumptions that contradict agent B's approach. Shorter tracks with frequent merges reduce this.

    Coordination theater: A lead agent spending most of its time assigning tasks, checking status, and sending messages instead of doing work. If the task list is clear enough, worktrees with no communication are cheaper.

    Re-reading overhead: Every agent reads .context/ on startup. A team of 4 agents each reading 4000 tokens of context = 16000 tokens before anyone does any work. For small tasks, that overhead dominates.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#what-ctx-gives-you-at-each-level","level":2,"title":"What ctx Gives You at Each Level","text":"ctx Feature Single Agent Worktrees Team .context/ files Full access Shared via git Shared via filesystem TASKS.md Work queue Split by track Assigned by lead Decisions/Learnings Persisted in session Persisted per branch Persisted by any agent /ctx-next Picks next task Picks within track Lead assigns /ctx-worktree N/A Setup + teardown Optional /ctx-commit Normal commits Per-branch commits Per-agent commits","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#team-composition-recipes","level":2,"title":"Team Composition Recipes","text":"

    Four practical team compositions for common workflows.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#feature-development-3-agents","level":3,"title":"Feature Development (3 agents)","text":"Role Responsibility Architect Writes spec in specs/, breaks work into TASKS.md phases Implementer Picks tasks from TASKS.md, writes code, marks [x] done Reviewer Runs tests, ctx drift, lint; files issues as new tasks

    Coordination: TASKS.md checkboxes. Architect writes tasks before implementer starts. Reviewer runs after each implementer commit.

    Anti-pattern: All three agents editing the same file simultaneously. Sequence the work so only one agent touches a file at a time.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#consolidation-sprint-3-4-agents","level":3,"title":"Consolidation Sprint (3-4 agents)","text":"Role Responsibility Auditor Runs ctx drift, identifies stale paths and broken refs Code Fixer Updates source code to match context (or vice versa) Doc Writer Updates ARCHITECTURE.md, CONVENTIONS.md, and docs/ Test Fixer (Optional) Fixes tests broken by the fixer's changes

    Coordination: Auditor's ctx drift output is the shared work queue. Each agent claims a subset of issues by adding #in-progress labels.

    Anti-pattern: Fixer and doc writer both editing ARCHITECTURE.md. Assign file ownership explicitly.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#release-prep-2-agents","level":3,"title":"Release Prep (2 agents)","text":"Role Responsibility Release Notes Generates changelog from commits, writes release notes Validation Runs full test suite, lint, build across platforms

    Coordination: Both read TASKS.md to identify what shipped. Release notes agent works from git log; validation agent works from make audit.

    Anti-pattern: Release notes agent running tests \"to verify.\" Each agent stays in its lane.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#documentation-sprint-3-agents","level":3,"title":"Documentation Sprint (3 agents)","text":"Role Responsibility Content Writes new pages, expands existing docs Cross-linker Adds nav entries, cross-references, \"See Also\" sections Verifier Builds site, checks broken links, validates rendering

    Coordination: Content agent writes files first. Cross-linker updates zensical.toml and index pages after content lands. Verifier builds after each batch.

    Antipattern: Content and cross-linker both editing zensical.toml. Batch nav updates into the cross-linker's pass.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#tips","level":2,"title":"Tips","text":"
    • Start with one agent: Only add parallelism when you have identified the bottleneck. \"This would go faster with more agents\" is usually wrong for tasks under 2 hours.
    • The 3-4 agent ceiling is real: Coordination overhead grows quadratically. 2 agents = 1 communication pair. 4 agents = 6 pairs. Beyond 4, you are managing agents more than doing work.
    • Worktrees > teams for most parallelism needs: If agents don't need to talk to each other during execution, worktrees give you parallelism with zero coordination overhead.
    • Use ctx as the shared brain: Whether it's one agent or four, the .context/ directory is the single source of truth. Decisions go in DECISIONS.md, not in chat messages between agents.
    • Merge early, merge often: Long-lived parallel branches diverge. Merge a track as soon as it's done rather than waiting for all tracks to finish.
    • TASKS.md conflicts are normal: Multiple agents completing different tasks will conflict on merge. The resolution is always additive: accept all [x] completions from both sides.
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#next-up","level":2,"title":"Next Up","text":"

    Parallel Agent Development with Git Worktrees →: Run multiple agents on independent task tracks using git worktrees.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#go-deeper","level":2,"title":"Go Deeper","text":"
    • CLI Reference: all commands and flags
    • Integrations: setup for Claude Code, Cursor, Aider
    • Session Journal: browse and search session history
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#see-also","level":2,"title":"See Also","text":"
    • Parallel Agent Development with Git Worktrees: the mechanical \"how\" for worktree-based parallelism
    • Running an Unattended AI Agent: serial autonomous loops: a different scaling strategy
    • Tracking Work Across Sessions: managing the task backlog that feeds into any multi-agent setup
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"reference/","level":1,"title":"Reference","text":"

    Technical reference for ctx commands, skills, and internals.

    ","path":["Reference"],"tags":[]},{"location":"reference/#the-system-explains-itself","level":3,"title":"The System Explains Itself","text":"

    The 12 properties that must hold for any valid ctx implementation. Not features: constraints. The system's contract with its users and contributors.

    ","path":["Reference"],"tags":[]},{"location":"reference/#cli","level":3,"title":"CLI","text":"

    Every command, subcommand, and flag. Now a top-level section: see CLI Reference.

    ","path":["Reference"],"tags":[]},{"location":"reference/#skills","level":3,"title":"Skills","text":"

    The full skill catalog: what each skill does, when it triggers, and how skills interact with commands.

    ","path":["Reference"],"tags":[]},{"location":"reference/#tool-ecosystem","level":3,"title":"Tool Ecosystem","text":"

    How ctx compares to Cursor Rules, Aider conventions, CLAUDE.md, and other context approaches.

    ","path":["Reference"],"tags":[]},{"location":"reference/#session-journal","level":3,"title":"Session Journal","text":"

    Export, browse, and enrich your session history. Covers the journal site, Obsidian export, and the enrichment pipeline.

    ","path":["Reference"],"tags":[]},{"location":"reference/#scratchpad","level":3,"title":"Scratchpad","text":"

    Encrypted, git-tracked scratch space for short notes and sensitive values that travel with the project.

    ","path":["Reference"],"tags":[]},{"location":"reference/#version-history","level":3,"title":"Version History","text":"

    Changelog for every ctx release.

    ","path":["Reference"],"tags":[]},{"location":"reference/comparison/","level":1,"title":"Tool Ecosystem","text":"","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#high-level-mental-model","level":2,"title":"High-Level Mental Model","text":"

    Many tools help AI think.

    ctx helps AI remember.

    • Not by storing thoughts,
    • but by preserving intent.
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#how-ctx-differs-from-similar-tools","level":2,"title":"How ctx Differs from Similar Tools","text":"

    There are many tools in the AI ecosystem that touch parts of the context problem:

    • Some manage prompts.
    • Some retrieve data.
    • Some provide runtime context objects.
    • Some offer enterprise platforms.

    ctx focuses on a different layer entirely.

    This page explains where ctx fits, and where it intentionally does not.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#the-core-distinction","level":2,"title":"The Core Distinction","text":"

    Most tools treat context as input.

    ctx treats context as infrastructure.

    That single difference explains nearly all of ctx's design choices.

    Question Most tools ctx Where does context live? In prompts or APIs In files How long does it last? One request / one session Across time Who can read it? The model Humans and tools How is it updated? Implicitly Explicitly Is it inspectable? Rarely Always","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#prompt-management-tools","level":2,"title":"Prompt Management Tools","text":"

    Examples include:

    • prompt templates;
    • reusable system prompts;
    • prompt libraries;
    • prompt versioning tools.

    These tools help you start a session.

    They do not help you continue one.

    Prompt tools:

    • inject text at session start;
    • are ephemeral by design;
    • do not evolve with the project.

    ctx:

    • persists knowledge over time;
    • accumulates decisions and learnings;
    • makes the context part of the repository itself.

    Prompt tooling and ctx are complementary; not competing. Yet, they operate in different layers.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#retrieval-augmented-generation-rag","level":2,"title":"Retrieval-Augmented Generation (RAG)","text":"

    RAG systems typically:

    • index documents
    • embed text
    • retrieve chunks dynamically at runtime

    They are excellent for:

    • large knowledge bases
    • static documentation
    • reference material

    RAG answers questions like:

    \"What information might be relevant right now?\"

    ctx answers a different question:

    \"What have we already decided, learned, or committed to?\"

    Here are some key differences:

    RAG ctx Statistical relevance Intentional relevance Embedding-based File-based Opaque retrieval Explicit structure Runtime query Persistent memory

    ctx does not replace RAG. Instead, it defines a persistent context layer that RAG can optionally augment.

    RAG belongs to the data plane; ctx defines the context control plane.

    It focuses on project memory, not knowledge search.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#agent-frameworks","level":2,"title":"Agent Frameworks","text":"

    Agent frameworks often provide:

    • task loops
    • tool orchestration
    • planner/executor patterns
    • autonomous iteration

    These systems are powerful, but they typically assume that:

    • memory is external
    • context is injected
    • state is transient

    Agent frameworks answer:

    \"How should the agent act?\"

    ctx answers:

    \"What should the agent remember?\"

    Without persistent context, agents tend to:

    • rediscover decisions
    • repeat mistakes
    • lose architectural intent

    This is why ctx pairs well with autonomous loop workflows:

    • The loop provides iteration
    • ctx provides continuity

    Together, loops become cumulative instead of forgetful.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#sdk-level-context-objects","level":2,"title":"SDK-Level Context Objects","text":"

    Some SDKs expose \"context\" objects that exist:

    • inside a process
    • during a request
    • for the lifetime of a call chain

    These are extremely useful and completely different.

    SDK context objects:

    • are in-memory
    • disappear when the process ends
    • are not shared across sessions

    ctx:

    • survives process restarts
    • survives new chats
    • survives new days

    They share a name, not a purpose.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#enterprise-context-platforms","level":2,"title":"Enterprise Context Platforms","text":"

    Enterprise platforms often provide:

    • centralized context services
    • dashboards
    • access control
    • organizational knowledge layers

    These tools are designed for:

    • teams
    • governance
    • compliance
    • managed environments

    ctx is intentionally:

    • local-first
    • file-based
    • dependency-free
    • CLI-driven
    • developer-controlled

    It does not require:

    • a server
    • a database
    • an account
    • a SaaS backend

    ctx optimizes for individual and small-team workflows where context should live next to code; not behind a service boundary.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#specific-tool-comparisons","level":2,"title":"Specific Tool Comparisons","text":"

    Users often evaluate ctx against specific tools they already use. These comparisons clarify where responsibilities overlap, where they diverge, and where the tools are genuinely complementary.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#claude-code-memory-anthropic-auto-memory","level":3,"title":"Claude Code Memory / Anthropic Auto-Memory","text":"

    Anthropic's auto-memory is tool-managed memory (L2): the model decides what to remember, stores it automatically, and retrieves it implicitly. ctx is system memory (L3): humans and agents explicitly curate decisions, learnings, and tasks in inspectable files.

    Auto-memory is convenient - you do not configure anything. But it is also opaque: you cannot see what was stored, edit it precisely, or share it across tools. ctx files are plain Markdown in your repository, visible in diffs and code review.

    The two are complementary. ctx can absorb auto-memory as an input source (importing what the model remembered into structured context files) while providing the durable, inspectable layer that auto-memory lacks.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#cursorrules-clauderules","level":3,"title":".cursorrules / .claude/rules","text":"

    Static rule files (.cursorrules, .claude/rules/) declare conventions: coding style, forbidden patterns, preferred libraries. They are effective for what to do and load automatically at session start.

    ctx adds dimensions that rule files do not cover: architectural decisions with rationale, learnings discovered during development, active tasks, and a constitution that governs agent behavior. Critically, ctx context accumulates - each session can add to it, and token budgeting ensures only the most relevant context is injected.

    Use rule files for static conventions. Use ctx for evolving project memory.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#aider-read-watch","level":3,"title":"Aider --read / --watch","text":"

    Aider's --read flag injects file contents at session start; --watch reloads them on change. The concept is similar to ctx's \"load\" step: make the agent aware of specific files.

    The differences emerge beyond loading. Aider has no persistence model -- nothing the agent learns during a session is written back. There is no token budgeting (large files consume the full context window), no priority ordering across file types, and no structured format for decisions or learnings. ctx provides the full lifecycle: load, accumulate, persist, and budget.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#copilot-workspace","level":3,"title":"Copilot @workspace","text":"

    GitHub Copilot's @workspace performs workspace-wide code search. It answers \"what code exists?\" - finding function definitions, usages, and file structure across the repository.

    ctx answers a different question: \"what did we decide?\" It stores architectural intent, not code indices. Copilot's workspace search and ctx's project memory are orthogonal; one finds code, the other preserves the reasoning behind it.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#cline-memory","level":3,"title":"Cline Memory","text":"

    Cline's memory bank stores session context within the Cline extension. The motivation is similar to ctx: help the agent remember across sessions.

    The key difference is portability. Cline memory is tied to Cline - it does not transfer to Claude Code, Cursor, Aider, or any other tool. ctx is tool-agnostic: context lives in plain files that any editor, agent, or script can read. Switching tools does not mean losing memory.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#when-ctx-is-a-good-fit","level":2,"title":"When ctx Is a Good Fit","text":"

    ctx works best when:

    • you want AI work to compound over time;
    • architectural decisions matter;
    • context must be inspectable;
    • humans and AI must share the same source of truth;
    • Git history should include why, not just what.
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#when-ctx-is-not-the-right-tool","level":2,"title":"When ctx Is Not the Right Tool","text":"

    ctx is probably not what you want if:

    • you only need one-off prompts;
    • you rely exclusively on RAG;
    • you want autonomous agents without a human-readable state;
    • you require centralized enterprise control;
    • you want black-box memory systems,

    These are valid goals; just different ones.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#further-reading","level":2,"title":"Further Reading","text":"
    • You Can't Import Expertise: why project-specific context matters more than generic best practices
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/design-invariants/","level":1,"title":"Invariants","text":"","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#the-system-explains-itself","level":1,"title":"The System Explains Itself","text":"

    These are the properties that must hold for any valid ctx implementation.

    • These are not features.
    • These are constraints.

    A change that violates an invariant is a category error, not an improvement.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#cognitive-state-tiers","level":2,"title":"Cognitive State Tiers","text":"

    ctx distinguishes between three forms of state:

    • Authoritative state: Versioned, inspectable artifacts that define intent and survive time.
    • Delivery views: Deterministic assemblies of the authoritative state for a specific budget or workflow.
    • Ephemeral working state: Local, transient, or sensitive data that assists interaction but does not define system truth.

    The invariants below apply primarily to the authoritative cognitive state.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#1-cognitive-state-is-explicit","level":2,"title":"1. Cognitive State Is Explicit","text":"

    All authoritative context lives in artifacts that can be inspected, reviewed, and versioned.

    If something is important, it must exist as a file: Not only in a prompt, a chat, or a model's hidden memory.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#2-assembly-is-reproducible","level":2,"title":"2. Assembly Is Reproducible","text":"

    Given the same:

    • repository state,
    • configuration,
    • and inputs,

    context assembly produces the same result.

    Heuristics may rank or filter for delivery under constraints.

    They do not alter the authoritative state.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#3-the-authoritative-state-is-human-readable","level":2,"title":"3. The Authoritative State Is Human-Readable","text":"

    The authoritative cognitive state must be stored in formats that a human can:

    • read,
    • diff,
    • review,
    • and edit directly.

    Sensitive working memory may be encrypted at rest. However, encryption must not become the only representation of authoritative knowledge.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#4-artifacts-outlive-sessions","level":2,"title":"4. Artifacts Outlive Sessions","text":"

    Sessions are transient.

    Knowledge persists.

    Reasoning, decisions, and outcomes must remain available after the interaction that produced them has ended.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#5-authority-is-user-defined","level":2,"title":"5. Authority Is User-Defined","text":"

    What enters the authoritative context is an explicit human decision.

    Models may suggest.

    Automation may assist.

    Selection is never implicit.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#6-operation-is-local-first","level":2,"title":"6. Operation Is Local-First","text":"

    The core system must function without requiring network access or a remote service.

    External systems may extend ctx.

    They must not be required for its operation.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#7-versioning-is-the-memory-model","level":2,"title":"7. Versioning Is the Memory Model","text":"

    The evolution of the authoritative cognitive state must be:

    • preserved,
    • inspectable,
    • and branchable.

    Ephemeral and sensitive working state may use different retention and diff strategies by design.

    Understanding includes understanding how we arrived here.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#8-structure-enables-scale","level":2,"title":"8. Structure Enables Scale","text":"

    Unstructured accumulation is not memory.

    Authoritative cognitive state must have a defined layout that:

    • communicates intent,
    • supports navigation,
    • and prevents drift.
    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#9-verification-is-the-scoreboard","level":2,"title":"9. Verification Is the Scoreboard","text":"

    Claims without recorded outcomes are noise.

    Reality (observed and captured) is the only signal that compounds.

    This invariant defines a required direction:

    The authoritative state must be able to record expectation and result.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#10-capture-once-reuse-indefinitely","level":2,"title":"10. Capture Once, Reuse Indefinitely","text":"

    Work that has already produced understanding must not be re-derived from scratch.

    Explored paths, rejected options, and validated conclusions are permanent assets.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#11-policies-are-encoded-not-remembered","level":2,"title":"11. Policies Are Encoded, not Remembered","text":"

    Alignment must not depend on recall or goodwill.

    Constraints that matter must exist in machine-readable form and participate in context assembly.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#12-the-system-explains-itself","level":2,"title":"12. The System Explains Itself","text":"

    From the repository state alone it must be possible to determine:

    • what was authoritative,
    • what constraints applied.

    Delivery views may be optimized.

    They must not become the only explanation.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#non-goals","level":1,"title":"Non-Goals","text":"

    To avoid category errors, ctx does not attempt to be:

    • a skill,
    • a prompt management tool,
    • a chat history viewer,
    • an autonomous agent runtime,
    • a vector database,
    • a hosted memory service.

    Such systems may integrate with ctx.

    They do not define it.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#implications-for-contributions","level":1,"title":"Implications for Contributions","text":"

    Valid contributions:

    • strengthen an invariant,
    • reduce the cost of maintaining an invariant,
    • or extend the system without violating invariants.

    Invalid contributions:

    • introduce hidden authoritative state,
    • replace reproducible assembly with non-reproducible behavior,
    • make core operation depend on external services,
    • reduce human inspectability of authoritative state,
    • or bypass explicit user authority over what becomes authoritative.
    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#the-contract","level":1,"title":"The Contract","text":"

    Everything else (commands, skills, layouts, integrations, optimizations) is an implementation detail.

    These invariants are the system.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/scratchpad/","level":1,"title":"Scratchpad","text":"","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#what-is-ctx-scratchpad","level":2,"title":"What Is ctx Scratchpad?","text":"

    A one-liner scratchpad, encrypted at rest, synced via git.

    Quick notes that don't fit decisions, learnings, or tasks: reminders, intermediate values, sensitive tokens, working memory during debugging. Entries are numbered, reorderable, and persist across sessions.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#encrypted-by-default","level":2,"title":"Encrypted by Default","text":"

    Scratchpad entries are encrypted with AES-256-GCM before touching the disk.

    Component Path Git status Encryption key ~/.ctx/.ctx.key User-level, 0600 permissions Encrypted data .context/scratchpad.enc Committed

    The key is generated automatically during ctx init (256-bit via crypto/rand) and stored at ~/.ctx/.ctx.key. One key per machine, shared across all projects.

    The ciphertext format is [12-byte nonce][ciphertext+tag]. No external dependencies: Go stdlib only.

    Because the key is .gitignored and the data is committed, you get:

    • At-rest encryption: the .enc file is opaque without the key
    • Git sync: push/pull the encrypted file like any other tracked file
    • Key separation: the key never leaves the machine unless you copy it
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#commands","level":2,"title":"Commands","text":"Command Purpose ctx pad List all entries (numbered 1-based) ctx pad show N Output raw text of entry N (no prefix, pipe-friendly) ctx pad add \"text\" Append a new entry ctx pad rm N Remove entry at position N ctx pad edit N \"text\" Replace entry N with new text ctx pad edit N --append \"text\" Append text to the end of entry N ctx pad edit N --prepend \"text\" Prepend text to the beginning of entry N ctx pad add TEXT --file PATH Ingest a file as a blob entry (TEXT is the label) ctx pad show N --out PATH Write decoded blob content to a file ctx pad mv N M Move entry from position N to position M ctx pad resolve Show both sides of a merge conflict for resolution ctx pad import FILE Bulk-import lines from a file (or stdin with -) ctx pad import --blob DIR Import directory files as blob entries ctx pad export [DIR] Export all blob entries to a directory as files ctx pad merge FILE... Merge entries from other scratchpad files into current

    All commands decrypt on read, operate on plaintext in memory, and re-encrypt on write. The key file is never printed to stdout.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#examples","level":3,"title":"Examples","text":"
    # Add a note\nctx pad add \"check DNS propagation after deploy\"\n\n# List everything\nctx pad\n#   1. check DNS propagation after deploy\n#   2. staging API key: sk-test-abc123\n\n# Show raw text (for piping)\nctx pad show 2\n# sk-test-abc123\n\n# Compose entries\nctx pad edit 1 --append \"$(ctx pad show 2)\"\n\n# Reorder\nctx pad mv 2 1\n\n# Clean up\nctx pad rm 2\n
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#bulk-import-and-export","level":2,"title":"Bulk Import and Export","text":"

    Import lines from a file in bulk (each non-empty line becomes an entry):

    # Import from a file\nctx pad import notes.txt\n\n# Import from stdin\ngrep TODO *.go | ctx pad import -\n

    Export all blob entries to a directory as files:

    # Export to a directory\nctx pad export ./ideas\n\n# Preview without writing\nctx pad export --dry-run\n\n# Overwrite existing files\nctx pad export --force ./backup\n
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#merging-scratchpads","level":2,"title":"Merging Scratchpads","text":"

    Combine entries from other scratchpad files into your current pad. Useful when merging work from parallel worktrees, other machines, or teammates:

    # Merge from a worktree's encrypted scratchpad\nctx pad merge worktree/.context/scratchpad.enc\n\n# Merge from multiple sources (encrypted and plaintext)\nctx pad merge pad-a.enc notes.md\n\n# Merge a foreign encrypted pad using its key\nctx pad merge --key /other/.ctx.key foreign.enc\n\n# Preview without writing\nctx pad merge --dry-run pad-a.enc pad-b.md\n

    Each input file is auto-detected as encrypted or plaintext: decryption is attempted first, and on failure the file is parsed as plain text. Entries are deduplicated by exact content, so running merge twice with the same file is safe.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#file-blobs","level":2,"title":"File Blobs","text":"

    The scratchpad can store small files (up to 64 KB) as blob entries. Files are base64-encoded and stored with a human-readable label.

    # Ingest a file: first argument is the label\nctx pad add \"deploy config\" --file ./deploy.yaml\n\n# Listing shows label with a [BLOB] marker\nctx pad\n#   1. check DNS propagation after deploy\n#   2. deploy config [BLOB]\n\n# Extract to a file\nctx pad show 2 --out ./recovered.yaml\n\n# Or print decoded content to stdout\nctx pad show 2\n

    Blob entries are encrypted identically to text entries. The internal format is label:::base64data: You never need to construct this manually.

    Constraint Value Max file size (pre-encoding) 64 KB Storage format label:::base64(content) Display label [BLOB] in listings

    When Should You Use Blobs

    Blobs are for small files you want encrypted and portable: config snippets, key fragments, deployment manifests, test fixtures. For anything larger than 64 KB, use the filesystem directly.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#using-with-ai","level":2,"title":"Using with AI","text":"

    Use Natural Language

    As in many ctx features, the ctx scratchpad can also be used with natural langauge. You don't have to memorize the CLI commands.

    CLI gives you \"precision\", whereas natural language gives you flow.

    The /ctx-pad skill maps natural language to ctx pad commands. You don't need to remember the syntax:

    You say What happens \"jot down: check DNS after deploy\" ctx pad add \"check DNS after deploy\" \"show my scratchpad\" ctx pad \"delete the third entry\" ctx pad rm 3 \"update entry 2 to include the new endpoint\" ctx pad edit 2 \"...\" \"move entry 4 to the top\" ctx pad mv 4 1 \"import my notes from notes.txt\" ctx pad import notes.txt \"export all blobs to ./backup\" ctx pad export ./backup \"merge the scratchpad from the worktree\" ctx pad merge worktree/.context/scratchpad.enc

    The skill handles the translation. You describe what you want in plain English; the agent picks the right command.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#worktrees","level":2,"title":"Worktrees","text":"

    The encryption key lives at ~/.ctx/.ctx.key (outside the project directory). Because all worktrees on the same machine share this path, ctx pad works in worktrees automatically - no special setup needed.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#key-distribution","level":2,"title":"Key Distribution","text":"

    The encryption key (~/.ctx/.ctx.key) stays on the machine where it was generated. ctx never transmits it.

    To share the scratchpad across machines:

    1. Copy the key manually: scp, USB drive, password manager.
    2. Push/pull the .enc file via git as usual.
    3. Both machines can now read and write the same scratchpad.

    Never Commit the Key

    The key is .gitignored by default. If you override this, anyone with repo access can decrypt your scratchpad.

    Treat the key like an SSH private key.

    See the Syncing Scratchpad Notes Across Machines recipe for a step-by-step walkthrough.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#plaintext-override","level":2,"title":"Plaintext Override","text":"

    For projects where encryption is unnecessary, disable it in .ctxrc:

    scratchpad_encrypt: false\n

    In plaintext mode:

    • Entries are stored in .context/scratchpad.md instead of .enc.
    • No key is generated or required.
    • All ctx pad commands work identically.
    • The file is human-readable and diffable.

    When Should You Use Plaintext

    Plaintext mode is useful for non-sensitive projects, solo work where encryption adds friction, or when you want scratchpad entries visible in git diff.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#when-should-you-use-scratchpad-versus-context-files","level":2,"title":"When Should You Use Scratchpad versus Context Files","text":"Use case Where it goes Temporary reminders (\"check X after deploy\") Scratchpad Working values during debugging Scratchpad Sensitive tokens or API keys (short-term) Scratchpad Quick notes that don't fit anywhere else Scratchpad Items that are not directly relevant to the project Scratchpad Things that you want to keep near, but also hidden Scratchpad Work items with completion tracking TASKS.md Trade-offs with rationale DECISIONS.md Reusable lessons with context/lesson/application LEARNINGS.md Codified patterns and standards CONVENTIONS.md

    Rule of thumb:

    • If it needs structure or will be referenced months later, use a context file (i.e. DECISIONS.md, LEARNINGS.md, TASKS.md).
    • If it is working memory for the current session or week, use the scratchpad.
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#see-also","level":2,"title":"See Also","text":"
    • Syncing Scratchpad Notes Across Machines: Key distribution, push/pull workflow, merge conflict resolution
    • Using the Scratchpad: Natural language examples, blob workflow, when to use scratchpad vs context files
    • Context Files: Format and conventions for all .context/ files
    • Security: Trust model and permission hygiene
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/session-journal/","level":1,"title":"Session Journal","text":"

    Important Security Note

    Session journals contain sensitive data such as file contents, commands, API keys, internal discussions, error messages with stack traces, and more.

    The .context/journal-site/ and .context/journal-obsidian/ directories MUST be .gitignored.

    • DO NOT host your journal publicly.
    • DO NOT commit your journal files to version control.
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#browse-your-session-history","level":2,"title":"Browse Your Session History","text":"

    ctx's Session Journal turns your AI coding sessions into a browsable, searchable, and editable archive.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#quick-start","level":2,"title":"Quick Start","text":"

    After using ctx for a couple of sessions, you can generate a journal site with:

    # Export all sessions to markdown\nctx recall export --all\n\n# Generate and serve the journal site\nctx journal site --serve\n

    Then open http://localhost:8000 to browse your sessions.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#what-you-get","level":2,"title":"What You Get","text":"

    The Session Journal gives you:

    • Browsable history: Navigate through all your AI sessions by date
    • Full conversations: See every message, tool use, and result
    • Token usage: Track how many tokens each session consumed
    • Search: Find sessions by content, project, or date
    • Dark mode: Easy on the eyes for late-night archaeology

    Each session page includes the following sections:

    Section Content Metadata Date, time, duration, model, project, git branch Summary Space for your notes (editable) Tool Usage Which tools were used and how often Conversation Full transcript with timestamps","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#1-export-sessions","level":3,"title":"1. Export Sessions","text":"
    # Export all sessions from current project (only new files)\nctx recall export --all\n\n# Export sessions from all projects\nctx recall export --all --all-projects\n\n# Export a specific session by ID (always writes)\nctx recall export abc123\n\n# Preview what would be exported\nctx recall export --all --dry-run\n\n# Re-export existing (regenerates conversation, preserves YAML frontmatter)\nctx recall export --all --regenerate\n\n# Discard frontmatter during regeneration\nctx recall export --all --regenerate --keep-frontmatter=false -y\n

    Exported sessions go to .context/journal/ as editable Markdown files.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#2-generate-the-site","level":3,"title":"2. Generate the Site","text":"
    # Generate site structure\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate and serve locally\nctx journal site --serve\n\n# Custom output directory\nctx journal site --output ~/my-journal\n

    The site is generated in .context/journal-site/ by default.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#3-browse-and-search","level":3,"title":"3. Browse and Search","text":"

    Open http://localhost:8000 after running --serve.

    • Use the sidebar to navigate by date
    • Use search (/ key) to find specific content
    • Click any session to see the full conversation
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#editing-sessions","level":2,"title":"Editing Sessions","text":"

    Exported sessions are plain Markdown in .context/journal/. You can:

    • Add summaries: Fill in the ## Summary section
    • Add notes: Insert your own commentary anywhere
    • Highlight key moments: Use Markdown formatting
    • Delete noise: Remove irrelevant tool outputs

    After editing, regenerate the site:

    ctx journal site --serve\n
    Safe by Default

    Running ctx recall export --all only exports new sessions. Existing files are skipped entirely (your edits and enrichments are never touched).

    Use --regenerate to re-export existing files. Conversation content is regenerated, but YAML frontmatter (topics, type, outcome, etc.) is preserved. You'll be prompted before any existing files are overwritten; add -y to skip the prompt.

    Use --keep-frontmatter=false to discard enriched frontmatter during regeneration.

    Locked entries (via ctx recall lock) are always skipped, regardless of flags. If you prefer to add locked: true to frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#large-sessions","level":2,"title":"Large Sessions","text":"

    Sessions with many messages (200+) are automatically split into multiple parts for better browser performance. Navigation links connect the parts:

    session-abc123.md      (Part 1 of 3)\nsession-abc123-p2.md   (Part 2 of 3)\nsession-abc123-p3.md   (Part 3 of 3)\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#suggestion-sessions","level":2,"title":"Suggestion Sessions","text":"

    Claude Code generates \"suggestion\" sessions for auto-complete prompts. These are separated in the index under a \"Suggestions\" section to keep your main session list focused.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#enriching-journal-entries","level":2,"title":"Enriching Journal Entries","text":"

    Raw exported sessions contain basic metadata (date, time, project) but lack the structured information needed for effective search, filtering, and analysis. Journal enrichment adds semantic metadata that transforms a flat archive into a searchable knowledge base.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#why-enrich","level":3,"title":"Why Enrich?","text":"

    Without enrichment, you have timestamps and raw conversations. With enrichment:

    • Find sessions by topic: \"Show me all auth-related sessions\"
    • Filter by outcome: \"What did I abandon vs complete?\"
    • Track technology usage: \"When did I last work with PostgreSQL?\"
    • Identify key files: Jump directly to the files discussed
    • Get summaries: Understand what happened without reading transcripts
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#the-frontmatter-schema","level":3,"title":"The Frontmatter Schema","text":"

    Enriched entries begin with YAML frontmatter:

    ---\ntitle: \"Implement caching layer\"\ndate: 2026-01-27\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - performance\ntechnologies:\n  - go\n  - redis\nlibraries:\n  - go-redis/redis\nkey_files:\n  - internal/cache/redis.go\n  - internal/cache/memory.go\n---\n
    Field Required Description title Yes Descriptive title (not the session slug) date Yes Session date (YYYY-MM-DD) type Yes Session type (see below) outcome Yes How the session ended (see below) topics No Subject areas discussed technologies No Languages, databases, frameworks libraries No Specific packages or libraries used key_files No Important files created or modified

    Type values:

    Type When to use feature Building new functionality bugfix Fixing broken behavior refactor Restructuring without behavior change exploration Research, learning, experimentation debugging Investigating issues documentation Writing docs, comments, README

    Outcome values:

    Outcome Meaning completed Goal achieved partial Some progress, work continues abandoned Stopped pursuing this approach blocked Waiting on external dependency","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#using-ctx-journal-enrich","level":3,"title":"Using /ctx-journal-enrich","text":"

    The /ctx-journal-enrich skill automates enrichment by analyzing conversation content and proposing metadata.

    Invoke by session identifier:

    /ctx-journal-enrich twinkly-stirring-kettle\n/ctx-journal-enrich twinkly\n/ctx-journal-enrich 2026-01-24\n/ctx-journal-enrich 76fe2ab9\n

    The skill will:

    1. Check if locked - locked entries are skipped (same as export);
    2. Find the matching journal file;
    3. Read and analyze the conversation;
    4. Propose frontmatter (type, topics, outcome, technologies);
    5. Generate a 2-3 sentence summary;
    6. Extract decisions, learnings, and tasks mentioned;
    7. Show a diff and ask for confirmation before writing.
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#before-and-after","level":3,"title":"Before and After","text":"

    Before enrichment:

    # twinkly-stirring-kettle\n\n**ID**: abc123-def456\n**Date**: 2026-01-24\n**Time**: 14:30:00\n...\n\n## Summary\n\n[Add your summary of this session]\n\n## Conversation\n...\n

    After enrichment:

    ---\ntitle: \"Add Redis caching to API endpoints\"\ndate: 2026-01-24\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nkey_files:\n  - internal/api/middleware/cache.go\n  - internal/cache/redis.go\n---\n\n# twinkly-stirring-kettle\n\n**ID**: abc123-def456\n**Date**: 2026-01-24\n**Time**: 14:30:00\n...\n\n## Summary\n\nImplemented Redis-based caching middleware for frequently accessed API endpoints.\nAdded cache invalidation on writes and configurable TTL per route. Reduced\n the average response time from 200ms to 15ms for cached routes.\n\n## Decisions\n\n* Used Redis over in-memory cache for horizontal scaling\n* Chose per-route TTL configuration over global setting\n\n## Learnings\n\n* Redis WATCH command prevents race conditions during cache invalidation\n\n## Conversation\n...\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#enrichment-and-site-generation","level":3,"title":"Enrichment and Site Generation","text":"

    The journal site generator uses enriched metadata for better organization:

    • Titles appear in navigation instead of slugs
    • Summaries provide context in the index
    • Topics enable filtering (when using search)
    • Types allow grouping by work category

    Future improvements will add topic-based navigation and outcome filtering to the generated site.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#batch-enrichment","level":3,"title":"Batch Enrichment","text":"

    To enrich multiple sessions, process them one at a time:

    # List unenriched sessions (those without frontmatter)\ngrep -L \"^---$\" .context/journal/*.md | head -10\n

    Then run /ctx-journal-enrich on each. Enrichment is intentionally interactive to ensure accuracy.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#obsidian-vault-export","level":2,"title":"Obsidian Vault Export","text":"

    If you use Obsidian for knowledge management, you can export your journal as an Obsidian vault instead of (or alongside) the static site:

    ctx journal obsidian\n

    This generates a vault in .context/journal-obsidian/ with:

    • Wikilinks ([[target|display]]) instead of Markdown links
    • MOC pages (Map of Content) for topics, key files, and session types
    • Related sessions footer per entry: links to entries sharing the same topics
    • Transformed frontmatter: topics renamed to tags (Obsidian-recognized), aliases added from title for search
    • Graph-optimized structure: MOC hubs and cross-linked entries create dense graph connectivity

    To use: open the output directory in Obsidian (\"Open folder as vault\").

    # Custom output directory\nctx journal obsidian --output ~/vaults/ctx-journal\n

    Static site vs Obsidian Vault

    Use ctx journal site when you want a web-browsable archive with search and dark mode. Use ctx journal obsidian when you want graph view, backlinks, and tag-based navigation inside Obsidian. Both use the same enriched source entries: you can generate both.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#full-pipeline","level":2,"title":"Full Pipeline","text":"

    The complete journal workflow has four stages. Each is idempotent: safe to re-run, and stages skip already-processed entries.

    export → enrich → rebuild\n
    Stage Command / Skill What it does Skips if Export ctx recall export --all Converts session JSONL to Markdown File already exists (safe default) Enrich /ctx-journal-enrich Adds frontmatter, summaries, topics Frontmatter already present Rebuild ctx journal site --build Generates static HTML site -- Obsidian ctx journal obsidian Generates Obsidian vault with wikilinks --

    One-command pipeline

    /ctx-journal-enrich-all handles export automatically - it detects unexported sessions and exports them before enriching. You only need to run ctx journal site --build afterward.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#using-make-journal","level":3,"title":"Using make journal","text":"

    If your project includes Makefile.ctx (deployed by ctx init), the first and last stages are combined:

    make journal           # export + rebuild\n

    After it runs, it reminds you to enrich in Claude Code:

    Next steps (in Claude Code):\n  /ctx-journal-enrich-all # exports if needed + adds metadata per entry\n\nThen re-run: make journal\n

    Rendering Issues?

    If individual entries have rendering problems (broken fences, malformed lists), use /ctx-journal-normalize on the affected file. This is rarely needed as programmatic normalization during export handles most cases.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#tips","level":2,"title":"Tips","text":"

    Daily workflow: 

    # Export, browse, then enrich in Claude Code\nmake journal && make journal-serve\n# Then in Claude Code: /ctx-journal-enrich <session>\n

    After a productive session: 

    # Export just that session and add notes\nctx recall export <session-id>\n# Edit .context/journal/<session>.md\n# Regenerate: ctx journal site\n

    Searching across all sessions: 

    # Use grep on the journal directory\ngrep -r \"authentication\" .context/journal/\n

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#requirements","level":2,"title":"Requirements","text":"Use pipx for zensical

    pip install zensical may install a non-functional stub on system Python. Using venv has other issues too.

    These issues especially happen on Mac OSX.

    Use pipx install zensical, which creates an isolated environment and handles Python version management automatically.

    The journal site uses zensical for static site generation:

    pipx install zensical\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#see-also","level":2,"title":"See Also","text":"
    • ctx recall: Session discovery and listing
    • ctx journal site: Static site generation
    • ctx journal obsidian: Obsidian vault export
    • Context Files: The .context/ directory structure
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/skills/","level":1,"title":"Skills","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#skills","level":2,"title":"Skills","text":"

    Skills are slash commands that run inside your AI assistant (e.g., /ctx-next), as opposed to CLI commands that run in your terminal (e.g., ctx status).

    Skills give your agent structured workflows: It knows what to read, what to run, and when to ask. Most wrap one or more ctx CLI commands with opinionated behavior on top.

    Skills Are Best Used Conversationally

    The beauty of ctx is that it's designed to be intuitive and conversational, allowing you to interact with your AI assistant naturally. That's why you don't have to memorize many of these skills.

    See the Prompting Guide for natural-language triggers that invoke these skills conversationally.

    However, when you need a more precise control, you have the option to invoke the relevant skills directly.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#all-skills","level":2,"title":"All Skills","text":"Skill Description Type /ctx-remember Recall project context and present structured readback user-invocable /ctx-wrap-up End-of-session context persistence ceremony user-invocable /ctx-status Show context summary with interpretation user-invocable /ctx-agent Load full context packet for AI consumption user-invocable /ctx-next Suggest 1-3 concrete next actions with rationale user-invocable /ctx-commit Commit with integrated context persistence user-invocable /ctx-reflect Pause and reflect on session progress user-invocable /ctx-add-task Add actionable task to TASKS.md user-invocable /ctx-add-decision Record architectural decision with rationale user-invocable /ctx-add-learning Record gotchas and lessons learned user-invocable /ctx-add-convention Record coding convention for consistency user-invocable /ctx-archive Archive completed tasks from TASKS.md user-invocable /ctx-pad Manage encrypted scratchpad entries user-invocable /ctx-recall Browse and export AI session history user-invocable /ctx-journal-enrich Enrich single journal entry with metadata user-invocable /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich user-invocable /ctx-journal-normalize Normalize journal markdown for clean rendering user-invocable /ctx-blog Generate blog post draft from project activity user-invocable /ctx-blog-changelog Generate themed blog post from a commit range user-invocable /ctx-consolidate Consolidate redundant learnings or decisions user-invocable /ctx-drift Detect and fix context drift user-invocable /ctx-prompt Apply, list, and manage saved prompt templates user-invocable /ctx-prompt-audit Analyze prompting patterns for improvement user-invocable /ctx-check-links Audit docs for dead internal and external links user-invocable /ctx-sanitize-permissions Audit Claude Code permissions for security risks user-invocable /ctx-verify Verify claims before reporting completion user-invocable /ctx-brainstorm Structured design dialogue before implementation user-invocable /ctx-spec Scaffold a feature spec from a project template user-invocable /ctx-import-plans Import Claude Code plan files into project specs user-invocable /ctx-implement Execute a plan step-by-step with verification user-invocable /ctx-loop Generate autonomous loop script user-invocable /ctx-worktree Manage git worktrees for parallel agents user-invocable /ctx-architecture Build and maintain architecture maps user-invocable /ctx-remind Manage session-scoped reminders user-invocable /ctx-doctor Troubleshoot ctx behavior with health checks and event analysis user-invocable /ctx-skill-audit Audit skills against Anthropic prompting best practices user-invocable /ctx-skill-creator Create, improve, and test skills user-invocable /ctx-pause Pause context hooks for this session user-invocable /ctx-resume Resume context hooks after a pause user-invocable","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#session-lifecycle","level":2,"title":"Session Lifecycle","text":"

    Skills for starting, running, and ending a productive session.

    Session Ceremonies

    Two skills in this group are ceremony skills: /ctx-remember (session start) and /ctx-wrap-up (session end). Unlike other skills that work conversationally, these should be invoked as explicit slash commands for completeness. See Session Ceremonies.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-remember","level":3,"title":"/ctx-remember","text":"

    Recall project context and present a structured readback. Ceremony skill: invoke explicitly at session start.

    Wraps: ctx agent --budget 4000, ctx recall list --limit 3, reads TASKS.md, DECISIONS.md, LEARNINGS.md

    See also: Session Ceremonies, The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-status","level":3,"title":"/ctx-status","text":"

    Show context summary (files, token budget, tasks, recent activity) with interpreted suggestions.

    Wraps: ctx status [--verbose] [--json]

    See also: The Complete Session, ctx status CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-agent","level":3,"title":"/ctx-agent","text":"

    Load the full context packet optimized for AI consumption. Also runs automatically via the PreToolUse hook with cooldown.

    Wraps: ctx agent [--budget] [--format] [--cooldown] [--session]

    See also: The Complete Session, ctx agent CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-next","level":3,"title":"/ctx-next","text":"

    Suggest 1-3 concrete next actions ranked by priority, momentum, and unblocked status.

    Wraps: reads TASKS.md, ctx recall list --limit 3

    See also: The Complete Session, Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-commit","level":3,"title":"/ctx-commit","text":"

    Commit code with integrated context persistence: pre-commit checks, staged files, Co-Authored-By trailer, and a post-commit prompt to capture decisions and learnings.

    Wraps: git add, git commit, optionally chains to /ctx-add-decision and /ctx-add-learning

    See also: The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-reflect","level":3,"title":"/ctx-reflect","text":"

    Pause and reflect on session progress. Walks through a checklist of learnings, decisions, task completions, and session notes to persist.

    Wraps: chains to ctx add learning, ctx add decision, manual TASKS.md updates

    See also: The Complete Session, Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-wrap-up","level":3,"title":"/ctx-wrap-up","text":"

    End-of-session context persistence ceremony. Gathers signal from git diff, recent commits, and conversation themes. Proposes candidates (learnings, decisions, conventions, tasks) with complete structured fields for user approval, then persists via ctx add. Offers /ctx-commit if uncommitted changes remain. Ceremony skill: invoke explicitly at session end.

    Wraps: git diff --stat, git log, ctx add learning, ctx add decision, ctx add convention, ctx add task, chains to /ctx-commit

    See also: Session Ceremonies, The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#context-persistence","level":2,"title":"Context Persistence","text":"

    Skills for recording work artifacts: tasks, decisions, learnings, conventions: into .context/ files.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-task","level":3,"title":"/ctx-add-task","text":"

    Add an actionable task with optional priority and phase section.

    Wraps: ctx add task \"description\" [--priority high|medium|low]

    See also: Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-decision","level":3,"title":"/ctx-add-decision","text":"

    Record an architectural decision with context, rationale, and consequence. Supports Y-statement (lightweight) and full ADR formats.

    Wraps: ctx add decision \"title\" --context \"...\" --rationale \"...\" --consequence \"...\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-learning","level":3,"title":"/ctx-add-learning","text":"

    Record a project-specific gotcha, bug, or unexpected behavior. Filters for insights that are searchable, project-specific, and required real effort to discover.

    Wraps: ctx add learning \"title\" --context \"...\" --lesson \"...\" --application \"...\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-convention","level":3,"title":"/ctx-add-convention","text":"

    Record a coding convention that should be standardized across sessions. Targets patterns seen 2-3+ times.

    Wraps: ctx add convention \"rule\" --section \"Name\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-archive","level":3,"title":"/ctx-archive","text":"

    Archive completed tasks from TASKS.md to a timestamped file in .context/archive/. Preserves phase headers for traceability.

    Wraps: ctx task archive [--dry-run]

    See also: Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#scratchpad","level":2,"title":"Scratchpad","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-pad","level":3,"title":"/ctx-pad","text":"

    Manage the encrypted scratchpad: add, remove, edit, and reorder one-liner notes. Encrypted at rest with AES-256-GCM.

    Wraps: ctx pad, ctx pad add, ctx pad rm, ctx pad edit, ctx pad mv, ctx pad import, ctx pad export, ctx pad merge

    See also: Scratchpad, Using the Scratchpad

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#journal-history","level":2,"title":"Journal & History","text":"

    Skills for browsing, exporting, and enriching your AI session history into a structured journal.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-recall","level":3,"title":"/ctx-recall","text":"

    Browse, inspect, and export AI session history. List recent sessions, show details by slug or ID, and export to .context/journal/.

    Wraps: ctx recall list, ctx recall show, ctx recall export

    See also: Browsing and Enriching Past Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-enrich","level":3,"title":"/ctx-journal-enrich","text":"

    Enrich a single journal entry with YAML frontmatter: title, type, outcome, topics, technologies, and summary. Shows diff before writing.

    Wraps: reads and edits .context/journal/*.md files

    See also: Browsing and Enriching Past Sessions, Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-enrich-all","level":3,"title":"/ctx-journal-enrich-all","text":"

    Full journal pipeline: exports unexported sessions first, then batch-enriches all unenriched entries. Filters out short sessions and continuations. Can spawn subagents for large backlogs.

    Wraps: ctx recall export --all + iterates /ctx-journal-enrich

    See also: Browsing and Enriching Past Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-normalize","level":3,"title":"/ctx-journal-normalize","text":"

    Normalize journal markdown for clean rendering: fix fence nesting, metadata formatting, list indentation, and collapse large tool outputs.

    Wraps: reads and edits .context/journal/*.md files

    See also: Browsing and Enriching Past Sessions, Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#content-creation","level":2,"title":"Content Creation","text":"

    Skills for turning project activity into publishable content.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-blog","level":3,"title":"/ctx-blog","text":"

    Generate a blog post draft from recent project activity: git history, decisions, learnings, tasks, and journal entries. Requires a narrative arc (problem, approach, outcome).

    Wraps: reads git log, DECISIONS.md, LEARNINGS.md, TASKS.md, journal entries; writes to docs/blog/

    See also: Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-blog-changelog","level":3,"title":"/ctx-blog-changelog","text":"

    Generate a themed blog post from a commit range. Takes a starting commit and unifying theme, analyzes diffs and journal entries from that period.

    Wraps: git log, git diff --stat; writes to docs/blog/

    See also: Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#auditing-health","level":2,"title":"Auditing & Health","text":"

    Skills for detecting drift, auditing alignment, and improving prompt quality.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-consolidate","level":3,"title":"/ctx-consolidate","text":"

    Consolidate redundant entries in LEARNINGS.md or DECISIONS.md. Groups overlapping entries by keyword similarity, presents candidates, and (with user approval) merges groups into denser combined entries. Originals are archived, not deleted.

    Wraps: reads LEARNINGS.md and DECISIONS.md, writes consolidated entries, archives originals, runs ctx reindex

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-drift","level":3,"title":"/ctx-drift","text":"

    Detect and fix context drift: stale paths, missing files, file age staleness, task accumulation, entry count warnings, and constitution violations via ctx drift. Also detects skill drift against canonical templates.

    Wraps: ctx drift [--fix]

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-prompt","level":3,"title":"/ctx-prompt","text":"

    Apply, list, and manage saved prompt templates from .context/prompts/. Prompt templates are plain Markdown files for common patterns like code review, refactoring, or explaining code.

    Wraps: ctx prompt list, ctx prompt show, ctx prompt apply, ctx prompt create

    Trigger phrases: \"use the code-review prompt\", \"list my prompts\", \"apply the refactor template\", \"create a prompt template\"

    See also: Prompt Templates

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-prompt-audit","level":3,"title":"/ctx-prompt-audit","text":"

    Analyze recent prompting patterns to identify vague or ineffective prompts. Reviews 3-5 journal entries and suggests rewrites with positive observations.

    Wraps: reads .context/journal/ entries

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-doctor","level":3,"title":"/ctx-doctor","text":"

    Troubleshoot ctx behavior. Runs structural health checks via ctx doctor, analyzes event log patterns via ctx system events, and presents findings with suggested actions. The CLI provides the structural baseline; the agent adds semantic analysis of event patterns and correlations.

    Wraps: ctx doctor --json, ctx system events --json --last 100, ctx remind list, ctx system message list, reads .ctxrc

    Trigger phrases: \"diagnose\", \"troubleshoot\", \"doctor\", \"health check\", \"why didn't my hook fire?\", \"hooks seem broken\", \"something seems off\"

    Graceful degradation: If event_log is not enabled, the skill still works but with reduced capability. It runs structural checks and notes: \"Enable event_log: true in .ctxrc for hook-level diagnostics.\"

    See also: Troubleshooting, ctx doctor CLI, ctx system events CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-check-links","level":3,"title":"/ctx-check-links","text":"

    Scan all markdown files under docs/ for broken links. Three passes: internal links (verify file targets exist on disk), external links (HTTP HEAD with timeout, report failures as warnings), and image references. Resolves relative paths, strips anchors before checking, and skips localhost/example URLs.

    Wraps: Glob + Grep to scan, curl for external checks

    Trigger phrases: \"check links\", \"audit links\", \"any broken links?\", \"dead links\"

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-sanitize-permissions","level":3,"title":"/ctx-sanitize-permissions","text":"

    Audit .claude/settings.local.json for dangerous permissions across four risk categories: hook bypass (Critical), destructive commands (High), config injection vectors (High), and overly broad patterns (Medium). Reports findings by severity and offers specific fix actions with user confirmation.

    Wraps: reads .claude/settings.local.json, edits with confirmation

    Trigger phrases: \"audit permissions\", \"are my permissions safe?\", \"sanitize permissions\", \"check settings\"

    See also: Claude Code Permission Hygiene

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-verify","level":3,"title":"/ctx-verify","text":"

    Run the relevant verification command before claiming a result. Maps claims to required evidence (\"tests pass\" needs test output, \"build succeeds\" needs exit 0) and includes self-audit questions to surface gaps before reporting done.

    Wraps: runs the verification command appropriate to the claim (go test, make audit, go build, diff, etc.)

    Trigger phrases: \"verify this\", \"does it work?\", \"prove it passes\", \"is it done?\"

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#planning-execution","level":2,"title":"Planning & Execution","text":"

    Skills for structured design, implementation, and parallel agent workflows.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-brainstorm","level":3,"title":"/ctx-brainstorm","text":"

    Transform raw ideas into clear, validated designs through structured dialogue before any implementation begins. Follows a gated process: understand context, clarify the idea (one question at a time), surface non-functional requirements, lock understanding with user confirmation, explore 2-3 design approaches with trade-offs, stress-test the chosen approach, and present the detailed design.

    Wraps: reads DECISIONS.md, relevant source files; chains to /ctx-add-decision for recording design choices

    Trigger phrases: \"let's brainstorm\", \"design this\", \"think through\", \"before we build\", \"what approach should we take?\"

    See also: /ctx-spec

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-spec","level":3,"title":"/ctx-spec","text":"

    Scaffold a feature spec from the project template and walk through each section with the user. Covers: problem, approach, happy path, edge cases, validation rules, error handling, interface, implementation, configuration, testing, and non-goals. Spends extra time on edge cases and error handling.

    Wraps: reads specs/tpl/spec-template.md, writes to specs/, optionally chains to /ctx-add-task

    Trigger phrases: \"spec this out\", \"write a spec\", \"create a spec\", \"design document\"

    See also: /ctx-brainstorm, /ctx-import-plans

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-import-plans","level":3,"title":"/ctx-import-plans","text":"

    Import Claude Code plan files (~/.claude/plans/*.md) into the project's specs/ directory. Lists plans with dates and H1 titles, supports filtering (--today, --since, --all), slugifies headings for filenames, and optionally creates tasks referencing each imported spec.

    Wraps: reads ~/.claude/plans/*.md, writes to specs/, optionally chains to /ctx-add-task

    See also: Importing Claude Code Plans, Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-implement","level":3,"title":"/ctx-implement","text":"

    Execute a multi-step plan with build and test verification at each step. Loads a plan from a file or conversation context, breaks it into atomic steps, and checkpoints after every 3-5 steps.

    Wraps: reads plan file, runs verification commands (go build, go test, etc.)

    See also: Running an Unattended AI Agent

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-loop","level":3,"title":"/ctx-loop","text":"

    Generate a ready-to-run shell script for autonomous AI iteration. Supports Claude Code, Aider, and generic tool templates with configurable completion signals.

    Wraps: ctx loop [--tool] [--prompt] [--max-iterations] [--completion] [--output]

    See also: Autonomous Loops, Running an Unattended AI Agent

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-worktree","level":3,"title":"/ctx-worktree","text":"

    Manage git worktrees for parallel agent development. Create sibling worktrees on dedicated branches, analyze task blast radius for grouping, and tear down with merge.

    Wraps: git worktree add, git worktree list, git worktree remove, git merge

    See also: Parallel Agent Development with Git Worktrees

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-architecture","level":3,"title":"/ctx-architecture","text":"

    Build and maintain architecture maps incrementally. Creates or refreshes ARCHITECTURE.md (succinct project map, loaded at session start) and DETAILED_DESIGN.md (deep per-module reference, consulted on-demand). Coverage is tracked in map-tracking.json so each run extends the map rather than re-analyzing everything.

    Wraps: ctx status, git log, reads source files; writes ARCHITECTURE.md, DETAILED_DESIGN.md, map-tracking.json

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-remind","level":3,"title":"/ctx-remind","text":"

    Manage session-scoped reminders via natural language. Translates user intent (\"remind me to refactor swagger\") into the corresponding ctx remind command. Handles date conversion for --after flags.

    Wraps: ctx remind, ctx remind list, ctx remind dismiss

    See also: Session Reminders

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#skill-authoring","level":2,"title":"Skill Authoring","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-skill-audit","level":3,"title":"/ctx-skill-audit","text":"

    Audit one or more skills against Anthropic prompting best practices. Checks audit dimensions: positive framing, motivation, phantom references, examples, subagent guards, scope, and descriptions. Reports findings by severity with concrete fix suggestions.

    Wraps: reads internal/assets/claude/skills/*/SKILL.md or .claude/skills/*/SKILL.md, references anthropic-best-practices.md

    Trigger phrases: \"audit this skill\", \"check skill quality\", \"review the skills\", \"are our skills any good?\"

    See also: /ctx-skill-creator, Contributing

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-skill-creator","level":3,"title":"/ctx-skill-creator","text":"

    Create, improve, and test skills. Guides the full lifecycle: capture intent, interview for edge cases, draft the SKILL.md, test with realistic prompts, review results with the user, and iterate. Applies core principles: the agent is already smart (only add what it does not know), the description is the trigger (make it specific and \"pushy\"), and explain the why instead of rigid directives.

    Wraps: reads/writes .claude/skills/ and internal/assets/claude/skills/

    Trigger phrases: \"create a skill\", \"turn this into a skill\", \"make a slash command\", \"this should be a skill\", \"improve this skill\", \"the skill isn't triggering\"

    See also: Contributing

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#session-control","level":2,"title":"Session Control","text":"

    Skills for controlling hook behavior during a session.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-pause","level":3,"title":"/ctx-pause","text":"

    Pause all context nudge and reminder hooks for the current session. Security hooks still fire. Use for quick investigations or tasks that don't need ceremony overhead.

    Wraps: ctx pause

    Trigger phrases: \"pause ctx\", \"pause context\", \"stop the nudges\", \"quiet mode\"

    See also: Pausing Context Hooks

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-resume","level":3,"title":"/ctx-resume","text":"

    Resume context hooks after a pause. Restores normal nudge, reminder, and ceremony behavior. Silent no-op if not paused.

    Wraps: ctx resume

    Trigger phrases: \"resume ctx\", \"resume context\", \"turn nudges back on\", \"unpause\"

    See also: Pausing Context Hooks

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#project-specific-skills","level":2,"title":"Project-Specific Skills","text":"

    The ctx plugin ships the skills listed above. Teams can add their own project-specific skills to .claude/skills/ in the project root: These are separate from plugin-shipped skills and are scoped to the project.

    Project-specific skills follow the same format and are invoked the same way.

    Custom skills are not covered in this reference.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/versions/","level":1,"title":"Version History","text":"","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#version-history","level":2,"title":"Version History","text":"

    Documentation snapshots for each release.

    Tap the corresponding view docs to view the docs as they were at that release.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#releases","level":2,"title":"Releases","text":"Version Release Date Documentation v0.6.0 2026-02-16 view docs v0.3.0 2026-02-07 view docs v0.2.0 2026-02-01 view docs v0.1.2 2026-01-27 view docs v0.1.1 2026-01-26 view docs v0.1.0 2026-01-25 view docs","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v060-the-integration-release","level":3,"title":"v0.6.0: The Integration Release","text":"

    Plugin architecture: hooks and skills converted from shell scripts to Go subcommands, shipped as a Claude Code marketplace plugin. Multi-tool hook generation for Cursor, Aider, Copilot, and Windsurf. Webhook notifications with encrypted URL storage.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v030-the-discipline-release","level":3,"title":"v0.3.0: The Discipline Release","text":"

    Journal static site generation via zensical. 49-skill audit and fix pass (positive framing, phantom reference removal, scope tightening). Context consolidation skill. golangci-lint v2 migration.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v020-the-archaeology-release","level":3,"title":"v0.2.0: The Archaeology Release","text":"

    Session journal system: ctx recall export converts Claude Code JSONL transcripts to browsable Markdown. Constants refactor with semantic prefixes (Dir*, File*, Filename*). CRLF handling for Windows compatibility.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v012","level":3,"title":"v0.1.2","text":"

    Default Claude Code permissions deployed on ctx init. Prompting guide published as a standalone documentation page.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v011","level":3,"title":"v0.1.1","text":"

    Bug fixes: hook schema key format corrected, JSON unicode escaping fixed in context file output.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v010-initial-release","level":3,"title":"v0.1.0: Initial Release","text":"

    CLI with 15 subcommands, 6 context file types (CONSTITUTION, TASKS, CONVENTIONS, ARCHITECTURE, DECISIONS, LEARNINGS), Makefile build system, and Claude Code hook integration.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#latest","level":2,"title":"Latest","text":"

    The main documentation always reflects the latest development version.

    For the most recent stable release, see v0.6.0.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#changelog","level":2,"title":"Changelog","text":"

    For detailed changes between versions, see the GitHub Releases page.

    ","path":["Reference","Version History"],"tags":[]},{"location":"security/","level":1,"title":"Security","text":"

    Security model, agent hardening, and vulnerability reporting.

    ","path":["Security"],"tags":[]},{"location":"security/#securing-ai-agents","level":3,"title":"Securing AI Agents","text":"

    Defense in depth for unattended AI agents: five layers of protection, each with a known bypass, strength in combination.

    ","path":["Security"],"tags":[]},{"location":"security/#security-policy","level":3,"title":"Security Policy","text":"

    Trust model, vulnerability reporting, permission hygiene, and security design principles.

    ","path":["Security"],"tags":[]},{"location":"security/agent-security/","level":1,"title":"Securing AI Agents","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#defense-in-depth-securing-ai-agents","level":1,"title":"Defense in Depth: Securing AI Agents","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#the-problem","level":2,"title":"The Problem","text":"

    An unattended AI agent with unrestricted access to your machine is an unattended shell with unrestricted access to your machine.

    This is not a theoretical concern. AI coding agents execute shell commands, write files, make network requests, and modify project configuration. When running autonomously (overnight, in a loop, without a human watching), the attack surface is the full capability set of the operating system user account.

    The risk is not that the AI is malicious. The risk is that the AI is controllable: it follows instructions from context, and context can be poisoned.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#threat-model","level":2,"title":"Threat Model","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#how-agents-get-compromised","level":3,"title":"How Agents Get Compromised","text":"

    AI agents follow instructions from multiple sources: system prompts, project files, conversation history, and tool outputs. An attacker who can inject content into any of these sources can redirect the agent's behavior.

    Vector How it works Prompt injection via dependencies A malicious package includes instructions in its README, changelog, or error output. The agent reads these during installation or debugging and follows them. Prompt injection via fetched content The agent fetches a URL (documentation, API response, Stack Overflow answer) containing embedded instructions. Poisoned project files A contributor adds adversarial instructions to CLAUDE.md, .cursorrules, or .context/ files. The agent loads these at session start. Self-modification between iterations In an autonomous loop, the agent modifies its own configuration files. The next iteration loads the modified config with no human review. Tool output injection A command's output (error messages, log lines, file contents) contains instructions the agent interprets and follows.","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#what-can-a-compromised-agent-do","level":3,"title":"What Can a Compromised Agent Do","text":"

    Depends entirely on what permissions and access the agent has:

    Access level Potential impact Unrestricted shell Execute any command, install software, modify system files Network access Exfiltrate source code, credentials, or context files to external servers Docker socket Escape container isolation by spawning privileged sibling containers SSH keys Pivot to other machines, push to remote repositories, access production systems Write access to own config Disable its own guardrails for the next iteration","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#the-defense-layers","level":2,"title":"The Defense Layers","text":"

    No single layer is sufficient. Each layer catches what the others miss.

    Layer 1: Soft instructions     (CONSTITUTION.md, playbook)\nLayer 2: Application controls  (permission allowlist, tool restrictions)\nLayer 3: OS-level isolation    (user accounts, filesystem, containers)\nLayer 4: Network controls      (firewall rules, airgap)\nLayer 5: Infrastructure        (VM isolation, resource limits)\n
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-1-soft-instructions-probabilistic","level":3,"title":"Layer 1: Soft Instructions (Probabilistic)","text":"

    Markdown files like CONSTITUTION.md and the Agent Playbook tell the agent what to do and what not to do. These are probabilistic: the agent usually follows them, but there is no enforcement mechanism.

    What it catches: Most common mistakes. An agent that has been told \"never delete production data\" will usually not delete production data.

    What it misses: Prompt injection. A sufficiently crafted injection can override soft instructions. Long context windows dilute attention on rules stated early. Edge cases where instructions are ambiguous.

    Verdict: Necessary but not sufficient. Good for the common case. Do not rely on it for security boundaries.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-2-application-controls-deterministic-at-runtime-mutable-across-iterations","level":3,"title":"Layer 2: Application Controls (Deterministic at Runtime, Mutable Across Iterations)","text":"

    AI tool runtimes (Claude Code, Cursor, etc.) provide permission systems: tool allowlists, command restrictions, confirmation prompts.

    For Claude Code, ctx init writes both an allowlist and an explicit deny list into .claude/settings.local.json. The golden images live in internal/assets/permissions/:

    Allowlist (allow.txt): only these tools run without confirmation:

    Bash(ctx:*)\nSkill(ctx-add-convention)\nSkill(ctx-add-decision)\n... # all bundled ctx-* skills\n

    Deny list (deny.txt): these are blocked even if the agent requests them:

    # Dangerous operations\nBash(sudo *)\nBash(git push *)\nBash(git push)\nBash(rm -rf /*)\nBash(rm -rf ~*)\nBash(curl *)\nBash(wget *)\nBash(chmod 777 *)\n\n# Sensitive file reads\nRead(**/.env)\nRead(**/.env.*)\nRead(**/*credentials*)\nRead(**/*secret*)\nRead(**/*.pem)\nRead(**/*.key)\n\n# Sensitive file edits\nEdit(**/.env)\nEdit(**/.env.*)\n

    What it catches: The agent cannot run commands outside the allowlist, and the deny list blocks dangerous operations even if a future allowlist change were to widen access. If rm, curl, sudo, or docker are not allowed and sudo/curl/wget are explicitly denied, the agent cannot invoke them regardless of what any prompt says.

    What it misses: The agent can modify the allowlist itself. In an autonomous loop, if the agent writes to .claude/settings.local.json, and the next iteration loads the modified config, then the protection is effectively lost. The application enforces the rules, but the application reads the rules from files the agent can write.

    Verdict: Strong first layer. Must be combined with self-modification prevention (Layer 3).

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-3-os-level-isolation-deterministic-and-unbypassable","level":3,"title":"Layer 3: OS-Level Isolation (Deterministic and Unbypassable)","text":"

    The operating system enforces access controls that no application-level trick can override. An unprivileged user cannot read files owned by root. A process without CAP_NET_RAW cannot open raw sockets. These are kernel boundaries.

    Control Purpose Dedicated user account No sudo, no privileged group membership (docker, wheel, adm). The agent cannot escalate privileges. Filesystem permissions Project directory writable; everything else read-only or inaccessible. Agent cannot reach other projects, home directories, or system config. Immutable config files CLAUDE.md, .claude/settings.local.json, and .context/CONSTITUTION.md owned by a different user or marked immutable (chattr +i on Linux). The agent cannot modify its own guardrails.

    What it catches: Privilege escalation, self-modification, lateral movement to other projects or users.

    What it misses: Actions within the agent's legitimate scope. If the agent has write access to source code (which it needs to do its job), it can introduce vulnerabilities in the code itself.

    Verdict: Essential. This is the layer that makes the other layers trustworthy.

    OS-level isolation does not make the agent safe; it makes the other layers meaningful.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-4-network-controls","level":3,"title":"Layer 4: Network Controls","text":"

    An agent that cannot reach the internet cannot exfiltrate data. It also cannot ingest new instructions mid-loop from external documents, API responses, or hostile content.

    Scenario Recommended control Agent does not need the internet --network=none (container) or outbound firewall drop-all Agent needs to fetch dependencies Allow specific registries (npmjs.com, proxy.golang.org, pypi.org) via firewall rules. Block everything else. Agent needs API access Allow specific API endpoints only. Use an HTTP proxy with allowlisting.

    What it catches: Data exfiltration, phone-home payloads, downloading additional tools, and instruction injection via fetched content.

    What it misses: Nothing, if the agent genuinely does not need the network. The tradeoff is that many real workloads need dependency resolution, so a full airgap requires pre-populated caches.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-5-infrastructure-isolation","level":3,"title":"Layer 5: Infrastructure Isolation","text":"

    The strongest boundary is a separate machine (or something that behaves like one).

    The moment you stop arguing about prompts and start arguing about kernels, you are finally doing security.

    Containers (Docker, Podman):

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh\n

    Docker Socket is sudo Access

    Critical: never mount the Docker socket (/var/run/docker.sock).

    An agent with socket access can spawn sibling containers with full host access, effectively escaping the sandbox.

    Use rootless Docker or Podman to eliminate this escalation path.

    Virtual machines: The strongest isolation. The guest kernel has no visibility into the host OS. No shared folders, no filesystem passthrough, no SSH keys to other machines.

    Resource limits: CPU, memory, and disk quotas prevent a runaway agent from consuming all resources. Use ulimit, cgroup limits, or container resource constraints.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A defense-in-depth setup for overnight autonomous runs:

    Layer Implementation Stops Soft instructions CONSTITUTION.md with \"never delete tests\", \"always run tests before committing\" Common mistakes (probabilistic) Application allowlist .claude/settings.local.json with explicit tool permissions Unauthorized commands (deterministic within runtime) Immutable config chattr +i on CLAUDE.md, .claude/, CONSTITUTION.md Self-modification between iterations Unprivileged user Dedicated user, no sudo, no docker group Privilege escalation Container --cap-drop=ALL --network=none, rootless, no socket mount Host escape, network exfiltration Resource limits --memory=4g --cpus=2, disk quotas Resource exhaustion

    Each layer is straightforward: The strength is in the combination.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#common-mistakes","level":2,"title":"Common Mistakes","text":"

    \"I'll just use --dangerously-skip-permissions\": This disables Layer 2 entirely. Without Layers 3-5, you have no protection at all. Only use this flag inside a properly isolated container or VM.

    \"The agent is sandboxed in Docker\": A Docker container with the Docker socket mounted, running as root, with --privileged, and full network access is not sandboxed. It is a root shell with extra steps.

    \"CONSTITUTION.md says not to do that\": Markdown is a suggestion. It works most of the time. It is not a security boundary. Do not use it as one.

    \"I reviewed the CLAUDE.md, it's fine\": The agent can modify CLAUDE.md during iteration N. Iteration N+1 loads the modified version. Unless the file is immutable, your review is stale.

    \"The agent only has access to this one project\": Does the project directory contain .env files, SSH keys, API tokens, or credentials? Does it have a .git/config with push access to a remote? Filesystem isolation means isolating what is in the directory too.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#team-security-considerations","level":2,"title":"Team Security Considerations","text":"

    When multiple developers share a .context/ directory, security considerations extend beyond single-agent hardening.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#code-review-for-context-files","level":3,"title":"Code Review for Context Files","text":"

    Treat .context/ changes like code changes. Context files influence agent behavior (a modified CONSTITUTION.md or CONVENTIONS.md changes what every agent on the team will do next session). Review them in PRs with the same scrutiny you apply to production code.

    Watch for:

    • Weakened constitutional rules (removed constraints, softened language)
    • New decisions that contradict existing ones without acknowledging it
    • Learnings that encode incorrect assumptions
    • Task additions that bypass the team's prioritization process
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#gitignore-patterns","level":3,"title":"Gitignore Patterns","text":"

    ctx init configures .gitignore automatically, but verify these patterns are in place:

    • Always gitignored: .ctx.key (encryption key), .context/logs/, .context/journal/
    • Team decision: scratchpad.enc (encrypted, safe to commit for shared scratchpad state); .gitignore if scratchpads are personal
    • Never committed: .env, credentials, API keys (enforced by drift secret detection)
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#multi-developer-context-sharing","level":3,"title":"Multi-Developer Context Sharing","text":"

    CONSTITUTION.md is the shared contract. All team members and their agents inherit it. Changes require team consensus, not unilateral edits.

    When multiple agents write to the same context files concurrently (e.g., two developers adding learnings simultaneously), git merge conflicts are expected. Resolution is typically additive: accept both additions. Destructive resolution (dropping one side) loses context.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#team-conventions-for-context-management","level":3,"title":"Team Conventions for Context Management","text":"

    Establish and document:

    • Who reviews context changes: Same reviewers as code, or a designated context owner?
    • How to resolve conflicting decisions: If two sessions record contradictory decisions, which wins? Default: the later one must explicitly supersede the earlier one with rationale.
    • Frequency of context maintenance: Weekly ctx drift checks, monthly consolidation passes, archival after each milestone.
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#checklist","level":2,"title":"Checklist","text":"

    Before running an unattended AI agent:

    • Agent runs as a dedicated unprivileged user (no sudo, no docker group)
    • Agent's config files are immutable or owned by a different user
    • Permission allowlist restricts tools to the project's toolchain
    • Container drops all capabilities (--cap-drop=ALL)
    • Docker socket is NOT mounted
    • Network is disabled or restricted to specific domains
    • Resource limits are set (memory, CPU, disk)
    • No SSH keys, API tokens, or credentials are accessible to the agent
    • Project directory does not contain .env or secrets files
    • Iteration cap is set (--max-iterations)
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#further-reading","level":2,"title":"Further Reading","text":"
    • Running an Unattended AI Agent: the ctx recipe for autonomous loops, including step-by-step permissions and isolation setup
    • Security: ctx's own trust model and vulnerability reporting
    • Autonomous Loops: full documentation of the loop pattern, PROMPT.md templates, and troubleshooting
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/reporting/","level":1,"title":"Security Policy","text":"","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#reporting-vulnerabilities","level":2,"title":"Reporting Vulnerabilities","text":"

    At ctx we take security very seriously.

    If you discover a security vulnerability in ctx, please report it responsibly.

    Do NOT open a public issue for security vulnerabilities.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#email","level":3,"title":"Email","text":"

    Send details to security@ctx.ist.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#github-private-reporting","level":3,"title":"GitHub Private Reporting","text":"
    1. Go to the Security tab;
    2. Click \"Report a Vulnerability\";
    3. Provide a detailed description.
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#encrypted-reports-optional","level":3,"title":"Encrypted Reports (Optional)","text":"

    If your report contains sensitive details (proof-of-concept exploits, credentials, or internal system information), you can encrypt your message with our PGP key:

    • In-repo: SECURITY_KEY.asc
    • Keybase: keybase.io/alekhinejose
    # Import the key\ngpg --import SECURITY_KEY.asc\n\n# Encrypt your report\ngpg --armor --encrypt --recipient security@ctx.ist report.txt\n

    Encryption is optional. Unencrypted reports to security@ctx.ist or via GitHub Private Reporting are perfectly fine.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#what-to-include","level":3,"title":"What to Include","text":"
    • Description of the vulnerability,
    • Steps to reproduce,
    • Potential impact,
    • Suggested fix (if any).
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#attribution","level":2,"title":"Attribution","text":"

    We appreciate responsible disclosure and will acknowledge security researchers who report valid vulnerabilities (unless they prefer to remain anonymous).

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#response-timeline","level":3,"title":"Response Timeline","text":"

    Open source, Best-Effort Timelines

    ctx is a volunteer-maintained open source project.

    The timelines below are guidelines, not guarantees, and depend on contributor availability.

    We will address security reports on a best-effort basis and prioritize them by severity.

    Stage Timeframe Acknowledgment Within 48 hours Initial assessment Within 7 days Resolution target Within 30 days (depending on severity)","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#trust-model","level":2,"title":"Trust Model","text":"

    ctx operates within a single trust boundary: the local filesystem.

    The person who authors .context/ files is the same person who runs the agent that reads them. There is no remote input, no shared state, and no server component.

    This means:

    • ctx does not sanitize context files for prompt injection. This is a deliberate design choice, not an oversight. The files are authored by the developer who owns the machine: Sanitizing their own instructions back to them would be counterproductive.
    • If you place adversarial instructions in your own .context/ files, your agent will follow them. This is expected behavior. You control the context; the agent trusts it.

    Shared Repositories

    In shared repositories, .context/ files should be reviewed in code review (the same way you would review CI/CD config or Makefiles). A malicious contributor could add harmful instructions to CONSTITUTION.md or TASKS.md.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#security-design","level":2,"title":"Security Design","text":"

    ctx is designed with security in mind:

    • No secrets in context: The constitution explicitly forbids storing secrets, tokens, API keys, or credentials in .context/ files
    • Local only: ctx runs entirely locally with no external network calls
    • No code execution: ctx reads and writes Markdown files only; it does not execute arbitrary code
    • Git-tracked: Core context files are meant to be committed, so they should never contain sensitive data. Exception: sessions/ and journal/ contain raw conversation data and should be gitignored
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#permission-hygiene","level":2,"title":"Permission Hygiene","text":"

    Claude Code evaluates permissions in deny → ask → allow order. ctx init automatically populates permissions.deny with rules that block dangerous operations before the allow list is ever consulted.

    Default deny rules block:

    • sudo, git push, rm -rf /, rm -rf ~, curl, wget, chmod 777
    • Read/Edit of .env, credentials, secrets, .pem, .key files

    Even with deny rules in place, the allow list accumulates one-off permissions over time. Periodically review for:

    • Destructive commands: git reset --hard, git clean -f, etc.
    • Config injection vectors: permissions that allow modifying files controlling agent behavior (CLAUDE.md, settings.local.json)
    • Broad wildcards: overly permissive patterns that pre-approve more than intended
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#state-file-management","level":2,"title":"State File Management","text":"

    Hook state files (throttle markers, prompt counters, pause markers) are stored in .context/state/, which is project-scoped and gitignored. State files are automatically managed by the hooks that create them; no manual cleanup is needed.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#best-practices","level":2,"title":"Best Practices","text":"
    1. Review before committing: Always review .context/ files before committing
    2. Use .gitignore: If you must store sensitive notes locally, add them to .gitignore
    3. Drift detection: Run ctx drift to check for potential issues
    4. Permission audit: Review .claude/settings.local.json after busy sessions
    ","path":["Security","Security Policy"],"tags":[]},{"location":"thesis/","level":1,"title":"Context as State","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#a-persistence-layer-for-human-ai-cognition","level":2,"title":"A Persistence Layer for Human-AI Cognition","text":"

    Jose Alekhinne - jose@ctx.ist

    February 2026

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#abstract","level":3,"title":"Abstract","text":"

    As AI tools evolve from code-completion utilities into reasoning collaborators, the knowledge that governs their behavior becomes as important as the code they produce; yet, that knowledge is routinely discarded at the end of every session.

    AI-assisted development systems assemble context at prompt time using heuristic retrieval from mutable sources: recent files, semantic search results, session history. These approaches optimize relevance at the moment of generation but do not persist the cognitive state that produced decisions. Reasoning is not reproducible, intent is lost across sessions, and teams cannot audit the knowledge that constrains automated behavior.

    This paper argues that context should be treated as deterministic, version-controlled state rather than as a transient query result. We ground this argument in three sources of evidence: a landscape analysis of 17 systems spanning AI coding assistants, agent frameworks, and knowledge stores; a taxonomy of five primitive categories that reveals irrecoverable architectural trade-offs; and an experience report from ctx, a persistence layer for AI-assisted development, which developed itself using its own persistence model across 389 sessions over 33 days. We define a three-tier model for cognitive state: authoritative knowledge, delivery views, and ephemeral state. Then we present six design invariants empirically validated by 56 independent rejection decisions observed across the analyzed landscape. We show that context determinism applies to assembly, not to model output, and that the curation cost this model requires is offset by compounding returns in reproducibility, auditability, and team cognition.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#1-introduction","level":2,"title":"1. Introduction","text":"

    The introduction of large language models into software development has shifted the primary interface from code execution to interactive reasoning. In this environment, the correctness of an output depends not only on source code but on the context supplied to the model: the conventions, decisions, architectural constraints, and domain knowledge that bound the space of acceptable responses.

    Current systems treat context as a query result assembled at the moment of interaction. A developer begins a session; the tool retrieves what it estimates to be relevant from chat history, recent files, and vector stores; the model generates output conditioned on this transient assembly; the session ends, and the context evaporates. The next session begins the cycle again.

    This model has improved substantially over the past year. CLAUDE.md files, Cursor rules, Copilot's memory system, and tools such as Mem0, Letta, and Kindex each address aspects of the persistence problem. Yet across 17 systems we analyzed spanning AI coding assistants, agent frameworks, autonomous coding agents, and purpose-built knowledge stores, no system provides all five of the following properties simultaneously: deterministic context assembly, human-readable file-based persistence, token-budgeted delivery, zero runtime dependencies, and local-first operation.

    This paper does not propose a universal replacement for retrieval-centric workflows. It defines a persistence layer (embodied in ctx (https://ctx.ist)) whose advantages emerge under specific operational conditions: when reproducibility is a requirement, when knowledge must outlive sessions and individuals, when teams require shared cognitive authority, or when offline operation is necessary.

    The trade-offs (manual curation cost, reduced automatic recall, coarser granularity) are intentional and mirror the trade-offs accepted by systems that favor reproducibility over convenience, such as reproducible builds and immutable infrastructure 1 6.

    The contribution is threefold: a three-tier model for cognitive state that resolves the ambiguity between authoritative knowledge and ephemeral session artifacts; six design invariants empirically grounded in a cross-system landscape analysis; and an experience report demonstrating that the model produces compounding returns when applied to its own development.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#2-the-limits-of-prompt-time-context","level":2,"title":"2. The Limits of Prompt-Time Context","text":"

    Prompt-time assembly pipelines typically consist of corpus selection, retrieval, ranking, and truncation. These pipelines are probabilistic and time-dependent, producing three failure modes that compound over the lifetime of a project.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#21-non-reproducibility","level":3,"title":"2.1 Non-Reproducibility","text":"

    If context is derived from mutable sources using heuristic ranking, identical requests at different times receive different inputs. A developer who asks \"What is our authentication strategy?\" on Tuesday may receive a different context window than the same question on Thursday: Not because the strategy changed, but because the retrieval heuristic surfaced different fragments.

    Reproducibility (the ability to reconstruct the exact inputs that produced a given output) is a foundational property of reliable systems. Its loss in AI-assisted development mirrors the historical evolution from ad-hoc builds to deterministic build systems 1 2. The build community learned that when outputs depend on implicit state (environment variables, system clocks, network-fetched dependencies), debugging becomes archaeology. The same principle applies when AI outputs depend on non-deterministic context retrieval.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#22-opaque-knowledge","level":3,"title":"2.2 Opaque Knowledge","text":"

    Embedding-based memory increases recall but reduces inspectability. When a vector store determines that a code snippet is \"similar\" to the current query, the ranking function is opaque: the developer cannot inspect why that snippet was chosen, whether a more relevant artifact was excluded, or whether the ranking will remain stable. This prevents deterministic debugging, policy auditing, and causal attribution (properties that information retrieval theory identifies as fundamental trade-offs of probabilistic ranking) 3.

    In practice, this opacity manifests as a compliance ceiling. In our experience developing a context management system (detailed in Section 7), soft instructions (directives that ask an AI agent to read specific files or follow specific procedures) achieve approximately 75-85% compliance. The remaining 15-25% represents cases where the agent exercises judgment about whether the instruction applies, effectively applying a second ranking function on top of the explicit directive. When 100% compliance is required, instruction is insufficient; the content must be injected directly, removing the agent's option to skip it.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#23-loss-of-intent","level":3,"title":"2.3 Loss of Intent","text":"

    Session transcripts record interaction but not cognition. A transcript captures what was said but not which assumptions were accepted, which alternatives were rejected, or which constraints governed the decision. The distinction matters: a decision to use PostgreSQL recorded as a one-line note (\"Use PostgreSQL\") teaches a model what was decided; a structured record with context, rationale, and consequences teaches it why (and why is what prevents the model from unknowingly reversing the decision in a future session) 4.

    Session transcripts provide history. Cognitive state requires something more: the persistent, structured representation of the knowledge required for correct decision-making.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#3-cognitive-state-a-three-tier-model","level":2,"title":"3. Cognitive State: A Three-Tier Model","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#31-definitions","level":3,"title":"3.1 Definitions","text":"

    We define cognitive state as the authoritative, persistent representation of the knowledge required for correct decision-making within a project. It is human-authored or human-ratified, versioned, inspectable, and reproducible. It is distinct from logs, transcripts, retrieval results, and model-generated summaries.

    Previous formulations of this idea have treated cognitive state as a monolithic concept. In practice, a three-tier model better captures the operational reality:

    Tier 1: Authoritative State: The canonical knowledge that the system treats as ground truth. In a concrete implementation, this corresponds to a set of human-curated files with defined schemas: a constitution (inviolable rules), conventions (code patterns), an architecture document (system structure), decision records (choices with rationale), learnings (captured experience), a task list (current work), a glossary (domain terminology), and an agent playbook (operating instructions). Each file has a single purpose, a defined lifecycle, and a distinct update frequency. Authoritative state is version-controlled alongside code and reviewed through the same mechanisms (diffs, pull requests, blame annotations).

    Tier 2: Delivery Views: Derived representations of authoritative state, assembled for consumption by a model. A delivery view is produced by a deterministic assembly function that takes the authoritative state, a token budget, and an inclusion policy as inputs and produces a context window as output. The same authoritative state, budget, and policy must always produce the same delivery view. Delivery views are ephemeral (they exist only for the duration of a session), but their construction is reproducible.

    Tier 3: Ephemeral State: Session transcripts, scratchpad notes, draft journal entries, and other artifacts that exist during or immediately after a session but are not authoritative. Ephemeral state is the raw material from which authoritative state may be extracted through human review, but it is never consumed directly by the assembly function.

    This three-tier model resolves confusion present in earlier formulations: the claim that AI output is a deterministic function of the repository state. The corrected claim is that context selection is deterministic (the delivery view is a function of authoritative state), but model output remains stochastic, conditioned on the deterministic context. Formally:

    delivery_view = assemble(authoritative_state, budget, policy)\noutput = model(delivery_view)   # stochastic\n

    The persistence layer's contribution is making assemble reproducible, not making model deterministic.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#32-separation-of-concerns","level":3,"title":"3.2 Separation of Concerns","text":"

    The decision to separate authoritative state into distinct files with distinct purposes is not cosmetic. Different types of knowledge have different lifecycles:

    Knowledge Type Update Frequency Read Frequency Load Priority Example Constitution Rarely Every session Always \"Never commit secrets to git\" Tasks Every session Session start Always \"Implement token budget CLI flag\" Conventions Weekly Before coding High \"All errors use structured logging with severity levels\" Decisions When decided When questioning Medium \"Use PostgreSQL over MySQL (see ADR-003)\" Learnings When learned When stuck Medium \"Hook scripts >50ms degrade interactive UX\" Architecture When changed When designing On demand \"Three-layer pipeline: ingest → enrich → assemble\" Journal Every session Rarely Never auto \"Session 247: Removed dead-end session copy layer\"

    A monolithic context file would force the assembly function to load everything or nothing. Separation enables progressive disclosure: the minimum context that matters for the current moment, with the option to load more when needed. A normal session loads the constitution, tasks, and conventions; a deep investigation loads decision history and journal entries from specific dates.

    The budget mechanism is the constraint that makes separation valuable. Without a budget, the default behavior is to load everything, which destroys the attention density that makes loaded context useful. With a budget, the assembly function must prioritize ruthlessly: constitution first (always full), then tasks and conventions (budget-capped), then decisions and learnings (scored by recency). Entries that do not fit receive title-only summaries rather than being silently dropped (an application of the \"tell me what you don't know\" pattern identified independently by four systems in our landscape analysis).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#4-design-invariants","level":2,"title":"4. Design Invariants","text":"

    The following six invariants define the constraints that a cognitive state persistence layer must satisfy. They are not axioms chosen a priori; they are empirically grounded properties whose violation was independently identified as producing complexity costs across the 17 systems we analyzed.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-1-markdown-on-filesystem-persistence","level":3,"title":"Invariant 1: Markdown-on-Filesystem Persistence","text":"

    Context files must be human-readable, git-diffable, and editable with any text editor. No database. No binary storage.

    Validation: 11 independent rejection decisions across the analyzed landscape protected this property. Systems that adopted embedded records, binary serialization, or knowledge graphs as their core primitive consistently traded away the ability for a developer to run cat DECISIONS.md and understand the system's knowledge. The inspection cost of opaque storage compounds over the lifetime of a project: every debugging session, every audit, every onboarding conversation requires specialized tooling to access knowledge that could have been a text file.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-2-zero-runtime-dependencies","level":3,"title":"Invariant 2: Zero Runtime Dependencies","text":"

    The tool must work with no installed runtimes, no running services, and no API keys for core functionality.

    Validation: 13 independent rejection decisions protected this property (the most frequently defended invariant). Systems that required databases (PostgreSQL, SQLite, Redis), embedding models, server daemons, container runtimes, or cloud APIs for core operation introduced failure modes proportional to their dependency count. A persistence layer that depends on infrastructure is not a persistence layer; it is a service. Services have uptime requirements, version compatibility matrices, and operational costs that simple file operations do not.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-3-deterministic-context-assembly","level":3,"title":"Invariant 3: Deterministic Context Assembly","text":"

    The same files plus the same budget must produce the same output. No embedding-based retrieval, no LLM-driven selection, no wall-clock-dependent scoring in the assembly path.

    Validation: 6 independent rejection decisions protected this property. Non-deterministic assembly (whether from embedding variance, LLM-based selection, or time-dependent scoring) destroys the ability to reproduce a context window and therefore to diagnose why a model produced a given output. Determinism in the assembly path is what makes the persistence layer auditable.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-4-human-authority-over-persistent-state","level":3,"title":"Invariant 4: Human Authority Over Persistent State","text":"

    The agent may propose changes to context files but must not unilaterally modify them. All persistent changes go through human-reviewable git commits.

    Validation: 6 independent rejection decisions protected this property. Systems that allowed agents to self-modify their memory (writing freeform notes, auto-pruning old entries, generating summaries as ground truth) consistently produced lower-quality persistent context than systems that enforced human review. Structure is a feature, not a limitation: across the landscape, the pattern \"structured beats freeform\" was independently discovered by four systems that evolved from freeform LLM summaries to typed schemas with required fields.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-5-local-first-air-gap-capable","level":3,"title":"Invariant 5: Local-First, Air-Gap Capable","text":"

    Core functionality must work offline with no network access. Cloud services may be used for optional features but never for core context management.

    Validation: 7 independent rejection decisions protected this property. Infrastructure-dependent memory systems cannot operate in classified environments, isolated networks, or disaster-recovery scenarios. A filesystem-native model continues to function under all conditions where the repository is accessible.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-6-no-default-telemetry","level":3,"title":"Invariant 6: No Default Telemetry","text":"

    Any analytics, if ever added, must be strictly opt-in.

    Validation: 4 independent rejection decisions protected this property. Default telemetry erodes the trust model that a persistence layer depends on. If developers must trust the system with their architectural decisions, operational learnings, and project constraints, the system cannot simultaneously be reporting usage data to external services.

    These six invariants collectively define a design space. Each feature proposal can be evaluated against them: a feature that violates any invariant is rejected regardless of how many other systems implement it. The discipline of constraint (refusing to add capabilities that compromise foundational properties) is itself an architectural contribution. Across the 17 analyzed systems, 56 patterns were explicitly rejected for violating these invariants. The rejection count per invariant (11, 13, 6, 6, 7, 4) provides a rough measure of each property's vulnerability to architectural erosion. A representative sample of these rejections is provided in Appendix A.1

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#5-landscape-analysis","level":2,"title":"5. Landscape Analysis","text":"

    The 17 systems were selected to cover the architectural design space rather than to achieve completeness. Each included system satisfies three criteria: it represents a distinct architectural primitive for AI-assisted development, it is actively maintained or widely referenced, and it provides sufficient public documentation or source code for architectural inspection. The goal was to ensure that every major category of primitive (document, embedded record, state snapshot, event/message, construction/derivation) was represented by multiple systems, enabling cross-system pattern detection.

    The resulting set spans six categories: AI coding assistants (Continue, Sourcegraph/Cody, Aider, Claude Code), AI agent frameworks (CrewAI, AutoGen, LangGraph, LlamaIndex, Letta/MemGPT), autonomous coding agents (OpenHands, Sweep), session provenance tools (Entire), data versioning systems (Dolt, Pachyderm), pipeline/build systems (Dagger), and purpose-built knowledge stores (QubicDB, Kindex). Each system was analyzed from its source code and documentation, producing 34 individual analysis artifacts (an architectural profile and a set of insights per system) that yielded 87 adopt/adapt recommendations, 56 explicit rejection decisions, and 52 watch items.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#51-primitive-taxonomy","level":3,"title":"5.1 Primitive Taxonomy","text":"

    Every system in the AI-assisted development landscape operates on a core primitive: an atomic unit around which the entire architecture revolves. Our analysis of 17 systems reveals five categories of primitives, each making irrecoverable trade-offs:

    Group A: Document/File Primitives: Human-readable documents as the primary unit. Documents are authored by humans, version-controlled in git, and consumed by AI tools. The invariant of this group is that the primitive is always human-readable and version-controllable with standard tools. Three systems participate in this pattern: the system described in this paper as a pure expression, and Continue (via its rules directory) and Claude Code (via CLAUDE.md files) as partial participants: both use document-based context as an input but organize around different core primitives.

    Group B: Embedded Record Primitives: Vector-embedded records stored with numerical embeddings for similarity search, metadata for filtering, and scoring mechanisms for ranking. Five systems use this approach (LlamaIndex, CrewAI, Letta/MemGPT, QubicDB, Kindex). The invariant is that the primitive requires an embedding model or vector database for core operations: a dependency that precludes offline and air-gapped use.

    Group C: State Snapshot Primitives: Point-in-time captures of the complete system state. The invariant is that any past state can be reconstructed at any historical point. Three systems use this approach (LangGraph, Entire, Dolt).

    Group D: Event/Message Primitives: Sequential events or messages forming an append-only log with causal relationships. Four systems use this approach (OpenHands, AutoGen, Claude Code, Sweep). The invariant is temporal ordering and append-only semantics.

    Group E: Construction/Derivation Primitives: Derived or constructed values that encode how they were produced. The invariant is that the primitive is a function of its inputs; re-executing the same inputs produces the same primitive. Three systems use this approach (Dagger, Pachyderm, Aider).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#52-comparison-matrix","level":3,"title":"5.2 Comparison Matrix","text":"

    The five primitive categories differ along seven dimensions:

    Property Document Embedded Record State Snapshot Event/Message Construction Human-readable Yes No Varies Partially No Version-controllable Yes No Varies Yes Yes Queryable by meaning No Yes No No No Rewindable Via git No Yes Yes (replay) Yes Deterministic Yes No Yes Yes Yes Zero-dependency Yes No Varies Varies Varies Offline-capable Yes No Varies Varies Yes

    The document primitive is the only one that simultaneously satisfies human-readability, version-controllability, determinism, zero dependencies, and offline capability. This is not because documents are superior in general (embedded records provide semantic queryability that documents lack) but because the combination of all five properties is what the persistence layer requires. The choice between primitive categories is not a matter of capability but of which properties are considered invariant.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#53-convergent-patterns","level":3,"title":"5.3 Convergent Patterns","text":"

    Across the 17 analyzed systems, six design patterns were independently discovered. These convergent patterns carry extra validation weight because they emerged from different problem spaces:

    Pattern 1: \"Tell me what you don't know\": When context is incomplete, explicitly communicate to the model what information is missing and what confidence level the provided context represents. Four systems independently converged on this pattern: inserting skip markers, tracking evidence gaps, annotating provenance, or naming output quality tiers.

    Pattern 2: \"Freshness matters\": Information relevance decreases over time. Three systems independently chose exponential decay with different half-lives (30 days, 90 days, and LRU ordering). Static priority ordering with no time dimension leaves relevant recent knowledge at the same priority as stale entries. This pattern is in productive tension with the persistence model's emphasis on determinism: the claim is not that time-dependence is irrelevant, but that it belongs in the curation step (a human deciding to consolidate or archive stale entries) rather than in the assembly function (an algorithm silently down-ranking entries based on age).

    Pattern 3: \"Content-address everything\": Compute a hash of content at creation time for deduplication, cache invalidation, integrity verification, and change detection. Five systems independently implement content hashing, each discovering it solves different problems 5.

    Pattern 4: \"Structured beats freeform\": When capturing knowledge or session state, a structured schema with required fields produces more useful data than freeform text. Four systems evolved from freeform summaries to typed schemas: one moving from LLM-generated prose to a structured condenser with explicit fields for completed tasks, pending tasks, and files modified.

    Pattern 5: \"Protocol convergence\": The Model Context Protocol (MCP) is emerging as a standard tool integration layer. Nine of 17 systems support it, spanning every category in the analysis. MCP's significance for the persistence model is that it provides a transport mechanism for context delivery without dictating how context is stored or assembled. This makes the approach compatible with both retrieval-centric and persistence-centric architectures.

    Pattern 6: \"Human-in-the-loop for memory\": Critical memory decisions should involve human judgment. Fully automated memory management produces lower-quality persistent context than human-reviewed systems. Four systems independently converged on variants of this pattern: ceremony-based consolidation, interrupt/resume for human input, confirmation mode for high-risk actions, and separated \"think fast\" vs. \"think slow\" processing paths.

    Pattern 6 directly validates the ceremony model described in this paper. The persistence layer requires human curation not because automation is impossible, but because the quality of persistent knowledge degrades when the curation step is removed. The improvement opportunity is to make curation easier, not to automate it away.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#6-worked-example-architectural-decision-under-two-models","level":2,"title":"6. Worked Example: Architectural Decision Under Two Models","text":"

    We now instantiate the three-tier model in a concrete system (ctx) and illustrate the difference between prompt-time retrieval and cognitive state persistence using a real scenario from its development.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#61-the-problem","level":3,"title":"6.1 The Problem","text":"

    During development, the system accumulated three overlapping storage layers for session data: raw transcripts (owned by the AI tool), session copies (JSONL copies plus context snapshots), and enriched journal entries (Markdown summaries). The middle layer (session copies) was a dead-end write sink. An auto-save hook copied transcripts to a directory that nothing read from, because the journal pipeline already read directly from the raw transcripts. Approximately 15 source files, a shell hook, 20 configuration constants, and 30 documentation references supported infrastructure with no consumers.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#62-prompt-time-retrieval-model","level":3,"title":"6.2 Prompt-Time Retrieval Model","text":"

    In a retrieval-based system, the decision to remove the middle layer depends on whether the retrieval function surfaces the relevant context:

    The developer asks: \"Should we simplify the session storage?\" The retrieval system must find and rank the original discussion thread where the three layers were designed, the usage statistics showing zero reads from the middle layer, the journal pipeline documentation showing it reads from raw transcripts directly, and the dependency analysis showing 15 files, a hook, and 30 doc references. If any of these fragments are not retrieved (because they are in old chat history, because the embedding similarity score is low, or because the token budget was consumed by more recent but less relevant context), the model may recommend preserving the middle layer, or may not realize it exists.

    Six months later, a new team member asks the same question. The retrieval results will differ: the original discussion has aged out of recency scoring, the usage statistics are no longer in recent history, and the model may re-derive the answer or arrive at a different conclusion.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#63-cognitive-state-model","level":3,"title":"6.3 Cognitive State Model","text":"

    In the persistence model, the decision is recorded as a structured artifact at write time:

    ## [2026-02-11] Remove .context/sessions/ storage layer\n\n**Status**: Accepted\n\n**Context**: The session/recall/journal system had three overlapping\nstorage layers. The recall pipeline reads directly from raw transcripts,\nmaking .context/sessions/ a dead-end write sink that nothing reads from.\n\n**Decision**: Remove .context/sessions/ entirely. Two stores remain:\nraw transcripts (global, tool-owned) and enriched journal\n(project-local).\n\n**Rationale**: Dead-end write sinks waste code surface, maintenance\neffort, and user attention. The recall pipeline already proved that\nreading directly from raw transcripts is sufficient. Context snapshots\nare redundant with git history.\n\n**Consequence**: Deleted internal/cli/session/ (15 files), removed\nauto-save hook, removed --auto-save from watch, removed pre-compact\nauto-save, removed /ctx-save skill, updated ~45 documentation files.\nFour earlier decisions superseded.\n

    This artifact is:

    • Deterministically included in every subsequent session's delivery view (budget permitting, with title-only fallback if budget is exceeded)
    • Human-readable and reviewable as a diff in the commit that introduced it
    • Permanent: it persists in version control regardless of retrieval heuristics
    • Causally linked: it explicitly supersedes four earlier decisions, creating an auditable chain

    When the new team member asks \"Why don't we store session copies?\" six months later, the answer is the same artifact, at the same revision, with the same rationale. The reasoning is reconstructible because it was persisted at write time, not discovered at query time.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#64-the-diff-when-policy-changes","level":3,"title":"6.4 The Diff When Policy Changes","text":"

    If a future requirement re-introduces session storage (for example, to support multi-agent session correlation), the change appears as a diff to the decision record:

    - **Status**: Accepted\n+ **Status**: Superseded by [2026-08-15] Reintroduce session storage\n+ for multi-agent correlation\n

    The new decision record references the old one, creating a chain of reasoning visible in git log. In the retrieval model, the old decision would simply be ranked lower over time and eventually forgotten.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#7-experience-report-a-system-that-designed-itself","level":2,"title":"7. Experience Report: A System That Designed Itself","text":"

    The persistence model described in this paper was developed and tested by using it on its own development. Over 33 days and 389 sessions, the system's context files accumulated a detailed record of decisions made, reversed, and consolidated: providing quantitative and qualitative evidence for the model's properties.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#71-scale-and-structure","level":3,"title":"7.1 Scale and Structure","text":"

    The development produced the following authoritative state artifacts:

    • 8 consolidated decision records covering 24 original decisions spanning context injection architecture, hook design, task management, security, agent autonomy, and webhook systems
    • 18 consolidated learning records covering 75 original observations spanning agent compliance, hook behavior, testing patterns, documentation drift, and tool integration
    • A constitution with 13 inviolable rules across 4 categories (security, quality, process, context preservation)
    • 389 enriched journal entries providing a complete session-level audit trail

    The consolidation ratio (24 decisions compressed to 8 records, 75 learnings compressed to 18) illustrates the curation cost and its return: authoritative state becomes denser and more useful over time as related entries are merged, contradictions are resolved, and superseded decisions are marked.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#72-architectural-reversals","level":3,"title":"7.2 Architectural Reversals","text":"

    Three architectural reversals during development provide evidence that the persistence model captures and communicates reasoning effectively:

    Reversal 1: The two-tier persistence model: The original design included a middle storage tier for session copies. After 21 days of development, the middle tier was identified as a dead-end write sink (described in Section 6). The decision record captured the full context, and the removal was executed cleanly: 15 source files, a shell hook, and 45 documentation references. The pattern of a \"dead-end write sink\" was subsequently observed in 7 of 17 systems in our landscape analysis that store raw transcripts alongside structured context.

    Reversal 2: The prompt-coach hook: An early design included a hook that analyzed user prompts and offered improvement suggestions. After deployment, the hook produced zero useful tips, its output channel was invisible to users, and it accumulated orphan temporary files. The hook was removed, and the decision record captured the failure mode for future reference.

    Reversal 3: The soft-instruction compliance model: The original context injection strategy relied on soft instructions: directives asking the AI agent to read specific files. After measuring compliance across multiple sessions, we found a consistent 75-85% compliance ceiling. The revised strategy injects content directly, bypassing the agent's judgment about whether to comply. The learning record captures the ceiling measurement and the rationale for the architectural change.

    Each reversal was captured as a structured decision record with context, rationale, and consequences. In a retrieval-based system, these reversals would exist only in chat history, discoverable only if the retrieval function happens to surface them. In the persistence model, they are permanent, indexable artifacts that inform future decisions.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#73-compliance-ceiling","level":3,"title":"7.3 Compliance Ceiling","text":"

    The 75-85% compliance ceiling for soft instructions is the most operationally significant finding from the experience report. It means that any context management strategy relying on agent compliance with instructions (\"read this file,\" \"follow this convention,\" \"check this list\") has a hard ceiling on reliability.

    The root cause is structural: the instruction \"don't apply judgment\" is itself evaluated by judgment. When an agent receives a directive to read a file, it first assesses whether the directive is relevant to the current task (and that assessment is the judgment the directive was trying to prevent).

    The architectural response maps directly to the formal model defined in Section 3.1. Content requiring 100% compliance is included in authoritative_state and injected by the deterministic assemble function, bypassing the agent entirely. Content where 80% compliance is acceptable is delivered as instructions within the delivery view. The three-tier architecture makes this distinction explicit: authoritative state is injected; delivery views are assembled deterministically; ephemeral state is available but not pushed.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#74-compounding-returns","level":3,"title":"7.4 Compounding Returns","text":"

    Over 33 days, we observed a qualitative shift in the development experience. Early sessions (days 1-7) spent significant time re-establishing context: explaining conventions, re-stating constraints, re-deriving past decisions. Later sessions (days 25-33) began with the agent loading curated context and immediately operating within established constraints, because the constraints were in files rather than in chat history.

    This compounding effect (where each session's context curation improves all subsequent sessions) is the primary return on the curation investment. The cost is borne once (writing a decision record, capturing a learning, updating the task list); the benefit is collected on every subsequent session load.

    The effect is analogous to compound interest in financial systems: the knowledge base grows not linearly with effort but with increasing marginal returns as new knowledge interacts with existing context. A learning captured on day 5 prevents a mistake on day 12, which avoids a debugging session that would have consumed a day 12 session, freeing that session for productive work that generates new learnings. The growth is not literally exponential (it is bounded by project scope and subject to diminishing returns as the knowledge base matures), but within the observed 33-day window, the returns were consistently accelerating.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#75-scope-and-generalizability","level":3,"title":"7.5 Scope and Generalizability","text":"

    This experience report is self-referential by design: the system was developed using its own persistence model. This circularity strengthens the internal validity of the findings (the model was stress-tested under authentic conditions) but limits external generalizability. The two-week crossover point was observed on a single project of moderate complexity with a small team already familiar with the model's assumptions. Whether the same crossover holds for larger teams, for codebases with different characteristics, or for teams adopting the model without having designed it remains an open empirical question. The quantitative claims in this section should be read as existence proofs (demonstrating that the model can produce compounding returns) rather than as predictions about specific adoption scenarios.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#8-situating-the-persistence-layer","level":2,"title":"8. Situating the Persistence Layer","text":"

    The persistence layer occupies a specific position in the stack of AI-assisted development:

    Application Logic\nAI Interaction / Agents\nContext Retrieval Systems\nCognitive State Persistence Layer\nVersion Control / Storage\n

    Current systems innovate primarily in the retrieval layer (improving how context is discovered, ranked, and delivered at query time). The persistence layer sits beneath retrieval and above version control. Its role is to maintain the authoritative state that retrieval systems may query but do not own. The relationship is complementary: retrieval answers \"What in the corpus might be relevant?\"; cognitive state answers \"What must be true for this system to operate correctly?\" A mature system uses both: retrieval for discovery, persistence for authority.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#9-applicability-and-trade-offs","level":2,"title":"9. Applicability and Trade-Offs","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#91-when-to-use-this-model","level":3,"title":"9.1 When to Use This Model","text":"

    A cognitive state persistence layer is most appropriate when:

    Reproducibility is a requirement: If a system must be able to answer \"Why did this output occur, and can it be produced again?\" then deterministic, version-controlled context becomes necessary. This is relevant in regulated environments, safety-critical systems, long-lived infrastructure, and security-sensitive deployments.

    Knowledge must outlive sessions and individuals: Projects with multi-year lifetimes accumulate architectural decisions, domain interpretations, and operational policy. If this knowledge is stored only in chat history, issue trackers, and institutional memory, it decays. The persistence model converts implicit knowledge into branchable, reviewable artifacts.

    Teams require shared cognitive authority: In collaborative environments, correctness depends on a stable answer to \"What does the system believe to be true?\" When this answer is derived from retrieval heuristics, authority shifts to ranking algorithms. When it is versioned and human-readable, authority remains with the team.

    Offline or air-gapped operation is required: Infrastructure-dependent memory systems cannot operate in classified environments, isolated networks, or disaster-recovery scenarios.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#92-when-not-to-use-this-model","level":3,"title":"9.2 When Not to Use This Model","text":"

    Zero-configuration personal workflows: For short-lived or exploratory tasks, the cost of explicit knowledge curation outweighs its benefits. Heuristic retrieval is sufficient when correctness is non-critical, outputs are disposable, and historical reconstruction is unnecessary.

    Maximum automatic recall from large corpora: Vector retrieval systems provide superior performance when the primary task is searching vast, weakly structured information spaces. The persistence model assumes that what matters can be decided and that this decision is valuable to record.

    Fully autonomous agent architectures: Agent runtimes that generate and discard state continuously, optimizing for local goal completion, do not benefit from a model that centers human ratification of knowledge.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#93-incremental-adoption","level":3,"title":"9.3 Incremental Adoption","text":"

    The transition does not require full system replacement. An incremental path:

    Step 1: Record decisions as versioned artifacts: Instead of allowing conclusions to remain in discussion threads, persist them in reviewable form with context, rationale, and consequences 4. This alone converts ephemeral reasoning into the cognitive state.

    Step 2: Make inclusion deterministic: Define explicit assembly rules. Retrieval may still exist, but it is no longer authoritative.

    Step 3: Move policy into cognitive state: When system behavior depends on stable constraints, encode those constraints as versioned knowledge. Behavior becomes reproducible.

    Step 4: Optimize assembly, not retrieval: Once the authoritative layer exists, performance improvements come from budgeting, caching, and structural refinement rather than from improving ranking heuristics.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#94-the-curation-cost","level":3,"title":"9.4 The Curation Cost","text":"

    The primary objection to this model is the cost of explicit knowledge curation. This cost is real. Writing a structured decision record takes longer than letting a chatbot auto-summarize a conversation. Maintaining a glossary requires discipline. Consolidating 75 learnings into 18 records requires judgment.

    The response is not that the cost is negligible but that it is amortized. A decision record written once is loaded hundreds of times. A learning captured today prevents repeated mistakes across all future sessions. The curation cost is paid once; the benefit compounds.

    The experience report provides rough order-of-magnitude numbers. Across 389 sessions over 33 days, curation activities (writing decision records, capturing learnings, updating the task list, consolidating entries) averaged approximately 3-5 minutes per session. In early sessions (days 1-7), before curated context existed, re-establishing context consumed approximately 10-15 minutes per session: re-explaining conventions, re-stating architectural constraints, re-deriving decisions that had been made but not persisted. By the final week (days 25-33), the re-explanation overhead had dropped to near zero: the agent loaded curated context and began productive work immediately.

    At ~12 sessions per day, the curation cost was roughly 35-60 minutes daily. The re-explanation cost in the first week was roughly 120-180 minutes daily. By the third week, that cost had fallen to under 15 minutes daily while the curation cost remained stable. The crossover (where cumulative curation cost was exceeded by cumulative time saved) occurred around day 10. These figures are approximate and derived from a single project with a small team already familiar with the model; the crossover point will vary with project complexity, team size, and curation discipline.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#10-future-work","level":2,"title":"10. Future Work","text":"

    Several directions are compatible with the model described here:

    Section-level deterministic budgeting: Current assembly operates at file granularity. Section-level budgeting would allow finer-grained control (including specific decision records while excluding others within the same file) without sacrificing determinism.

    Causal links between decisions: The experience report shows that decisions frequently reference earlier decisions (superseding, extending, or qualifying them). Formal causal links would enable traversal of the decision graph and automatic detection of orphaned or contradictory constraints.

    Content-addressed context caches: Five systems in our landscape analysis independently discovered that content hashing provides cache invalidation, integrity verification, and change detection. Applying content addressing to the assembly output would enable efficient cache reuse when the authoritative state has not changed.

    Conditional context inclusion: Five systems independently suggest that context entries could carry activation conditions (file patterns, task keywords, or explicit triggers) that control whether they are included in a given assembly. This would reduce the per-session budget cost of large knowledge bases without sacrificing determinism.

    Provenance metadata: Linking context entries to the sessions, decisions, or learnings that motivated them would strengthen the audit trail. Optional provenance fields on Markdown entries (session identifier, cause reference, motivation) would be lightweight and compatible with the existing file-based model.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#11-conclusion","level":2,"title":"11. Conclusion","text":"

    AI-assisted development has treated context as a \"query result\" assembled at the moment of interaction, discarded at the session end. This paper identifies a complementary layer: the persistence of authoritative cognitive state as deterministic, version-controlled artifacts.

    The contribution is grounded in three sources of evidence. A landscape analysis of 17 systems reveals five categories of primitives and shows that no existing system provides the combination of human-readability, determinism, zero dependencies, and offline capability that the persistence layer requires. Six design invariants, validated by 56 independent rejection decisions, define the constraints of the design space. An experience report over 389 sessions and 33 days demonstrates compounding returns: later sessions start faster, decisions are not re-derived, and architectural reversals are captured with full context.

    The core claim is this: persistent cognitive state enables causal reasoning across time. A system built on this model can explain not only what is true, but why it became true and when it changed.

    When context is the state:

    • Reasoning is reproducible: the same authoritative state, budget, and policy produce the same delivery view.
    • Knowledge is auditable: decisions are traceable to explicit artifacts with context, rationale, and consequences.
    • Understanding compounds: each session's curation improves all subsequent sessions.

    The choice between retrieval-centric workflows and a persistence layer is not a matter of capability but of time horizon. Retrieval optimizes for relevance at the moment of interaction. Persistence optimizes for the durability of understanding across the lifetime of a project.

    🐸🖤 \"Gooood... let the deterministic context flow through the repository...\" - Kermit the Sidious, probably

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#appendix-a-representative-rejection-decisions","level":2,"title":"Appendix A: Representative Rejection Decisions","text":"

    The 56 rejection decisions referenced in Section 4 were cataloged across all 17 system analyses, grouped by the invariant they would violate. This appendix provides a representative sample (two per invariant) to illustrate the methodology.

    Invariant 1: Markdown-on-Filesystem (11 rejections): CrewAI's vector embedding storage was rejected because embeddings are not human-readable, not git-diff-friendly, and require external services. Kindex's knowledge graph as core primitive was rejected because it requires specialized commands to inspect content that could be a text file (kin show <id> vs. cat DECISIONS.md).

    Invariant 2: Zero Runtime Dependencies (13 rejections): Letta/MemGPT's PostgreSQL-backed architecture was rejected because it conflicts with local-first, no-database, single-binary operation. Pachyderm's Kubernetes-based distributed architecture was rejected as the antithesis of a single-binary design for a tool that manages text files.

    Invariant 3: Deterministic Assembly (6 rejections): LlamaIndex's embedding-based retrieval as the primary selection mechanism was rejected because it destroys determinism, requires an embedding model, and removes human judgment from the selection process. QubicDB's wall-clock-dependent scoring was rejected because it directly conflicts with the \"same inputs produce same output\" property.

    Invariant 4: Human Authority (6 rejections): Letta/MemGPT's agent self-modification of memory was rejected as fundamentally opposed to human-curated persistence. Claude Code's unstructured auto-memory (where the agent writes freeform notes) was rejected because structured files with defined schemas produce higher-quality persistent context than unconstrained agent output.

    Invariant 5: Local-First / Air-Gap Capable (7 rejections): Sweep's cloud-dependent architecture was rejected as fundamentally incompatible with the local-first, offline-capable model. LangGraph's managed cloud deployment was rejected because cloud dependencies for core functionality violate air-gap capability.

    Invariant 6: No Default Telemetry (4 rejections): Continue's telemetry-by-default (PostHog) was rejected because it contradicts the local-first, privacy-respecting trust model. CrewAI's global telemetry on import (Scarf tracking pixel) was rejected because it violates user trust and breaks air-gap capability.

    The remaining 9 rejections did not map to a specific invariant but were rejected on other architectural grounds: for example, Aider's full-file-content-in-context approach (which defeats token budgeting), AutoGen's multi-agent orchestration as core primitive (scope creep), and Claude Code's 30-day transcript retention limit (institutional knowledge should have no automatic expiration).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#references","level":2,"title":"References","text":"

    1. Reproducible Builds Project, \"Reproducible Builds: Increasing the Integrity of Software Supply Chains\", 2017. https://reproducible-builds.org/docs/definition/ ↩↩↩

    2. S. McIntosh et al., \"The Impact of Build System Evolution on Software Quality\", ICSE, 2015. https://doi.org/10.1109/ICSE.2015.70 ↩

    3. C. Manning, P. Raghavan, H. Schütze, Introduction to Information Retrieval, Cambridge University Press, 2008. https://nlp.stanford.edu/IR-book/ ↩

    4. M. Nygard, \"Documenting Architecture Decisions\", Cognitect Blog, 2011. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions ↩↩

    5. L. Torvalds et al., Git Internals - Git Objects (content-addressed storage concepts). https://git-scm.com/book/en/v2/Git-Internals-Git-Objects ↩

    6. Kief Morris, Infrastructure as Code, O'Reilly, 2016. ↩

    7. J. Kreps, \"The Log: What every software engineer should know about real-time data's unifying abstraction\", 2013. https://engineering.linkedin.com/distributed-systems/log ↩

    8. P. Hunt et al., \"ZooKeeper: Wait-free coordination for Internet-scale systems\", USENIX ATC, 2010. https://www.usenix.org/legacy/event/atc10/tech/full_papers/Hunt.pdf ↩

    ","path":["The Thesis"],"tags":[]}]} \ No newline at end of file +{"config":{"separator":"[\\s\\-_,:!=\\[\\]()\\\\\"`/]+|\\.(?!\\d)"},"items":[{"location":"","level":1,"title":"The ctx Manifesto","text":"","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-manifesto","level":1,"title":"ctx Manifesto","text":"

    Creation, not code.

    Context, not prompts.

    Verification, not vibes.

    This Is NOT a Metaphor

    Code executes instructions.

    Creation produces outcomes.

    Confusing the two is how teams ship motion...

    ...instead of progress.

    • It was never about the code.
    • Code has zero standalone value.
    • Code is an implementation detail.

    Code is an incantation.

    Creation is the act.

    And creation does not happen in a vacuum.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-is-the-substrate","level":2,"title":"ctx Is the Substrate","text":"

    Constraints Have Moved

    Human bandwidth is no longer the limiting factor.

    Context integrity is.

    Human bandwidth is no longer the constraint.

    ctx is.

    • Without durable context, intelligence resets.
    • Without memory, reasoning decays.
    • Without structure, scale collapses.

    Creation is now limited by:

    • Clarity of intent;
    • Quality of context;
    • Rigor of verification.

    Not by speed.

    Not by capacity.

    Velocity Amplifies

    Faster execution on broken context compounds error.

    Speed multiplies whatever is already wrong.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#humans-author-meaning","level":2,"title":"Humans Author Meaning","text":"

    Intent Is Authored

    Systems can optimize.

    Models can generalize.

    Meaning must be chosen.

    Intent is not emergent.

    Vision, goals, and direction are human responsibilities.

    We decide:

    • What matters;
    • What success means;
    • What world we are building.

    ctx encodes the intent so it

    • survives time,
    • survives handoffs,
    • survives scale.

    Nothing important should live only in conversation.

    Nothing critical should depend on recall.

    Oral Tradition Does not Scale

    If intent cannot be inspected, it cannot be enforced.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-before-action","level":2,"title":"ctx Before Action","text":"

    Orientation Precedes Motion

    Acting first and understanding later is not bravery.

    It is debt.

    Never act without ctx.

    Before execution, we must verify:

    • Where we are;
    • Why we are here;
    • What constraints apply;
    • What assumptions are active.

    Action without ctx is gambling.

    Speed without orientation is noise.

    ctx is not overhead: It is the cost of correctness.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#persistent-context-beats-prompt-memory","level":2,"title":"Persistent Context Beats Prompt Memory","text":"

    Transience Is the Default Failure Mode

    • Prompts decay.
    • Chats fragment.
    • Memory heuristics drift.

    Prompts are transient.

    Chats are lossy.

    Memory heuristics drift.

    ctx must be:

    • Durable;
    • Structured;
    • Explicit;
    • Queryable.

    Intent Must Be Intentional

    If intent exists only in a prompt...

    ...alignment is already degrading.

    Knowledge lives in the artifacts:

    • Decisions;
    • Documentation;
    • Dependency maps;
    • Evaluation history.

    Artifacts Outlive Sessions

    What is not written will be re-learned.

    At full cost.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#what-ctx-is-not","level":2,"title":"What ctx Is Not","text":"

    Avoid Category Errors

    Mislabeling ctx guarantees misuse.

    ctx is not a memory feature.

    • ctx is not prompt engineering.
    • ctx is not a productivity hack.
    • ctx is not automation theater.

    ctx is a system for preserving intent under scale.

    ctx is infrastructure.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#verified-reality-is-the-scoreboard","level":2,"title":"Verified Reality Is the Scoreboard","text":"

    Activity is a False Proxy

    Output volume correlates poorly with impact.

    • Code is not progress.
    • Activity is not impact.

    The only truth that compounds is verified change.

    Verified change must exist in the real world.

    Hypotheses are cheap; outcomes are not.

    ctx captures:

    • What we expected;
    • What we observed;
    • Where reality diverged.

    If we cannot predict, measure, and verify the result...

    ...it does not count.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#build-to-learn-not-to-accumulate","level":2,"title":"Build to Learn, Not to Accumulate","text":"

    Prototypes Have an Expiration Date

    A prototype's value is information, not longevity.

    Prototypes exist to reduce uncertainty.

    We build to:

    • Test assumptions;
    • Validate architecture;
    • Answer specific questions.

    Not everything.

    Not blindly.

    Not permanently.

    ctx records archeology so the cost is paid once.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#failures-are-assets","level":2,"title":"Failures Are Assets","text":"

    Failure Without Capture is Waste

    Pain that does not teach is pure loss.

    Failures are not erased: They are preserved.

    Each failure becomes:

    • A documented hypothesis;
    • An analyzed deviation;
    • A permanent artifact.

    Rollback fixes symptoms: ctx fixes systems.

    A repeated mistake is a missing ctx artifact.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#structure-enables-scale","level":2,"title":"Structure Enables Scale","text":"

    Unbounded Autonomy Destabilizes

    Power without a structure produces chaos.

    Transpose it:

    Power without any structure becomes chaos.

    ctx defines:

    • Roles;
    • Boundaries;
    • Protocols;
    • Escalation paths;
    • Decision rights.

    Ambiguity is a system failure:

    • Debates must be structured.
    • Decisions must be explicit.
    • History must be retained.
    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#encode-intent-into-the-environment","level":2,"title":"Encode Intent Into the Environment","text":"

    Goodwill Does not Belong to the Table

    Alignment that depends on memory will drift.

    Alignment cannot depend on memory or goodwill.

    Do not rely on people to remember.

    Encode the behavior, so it happens by default.

    Intent is encoded as:

    • Policies;
    • Schemas;
    • Constraints;
    • Evaluation harnesses.

    Rules must be machine-readable.

    Laws must be enforceable.

    If intent is implicit, drift is guaranteed.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#cost-is-a-first-class-signal","level":2,"title":"Cost Is a First-Class Signal","text":"

    Attention Is the Scarcest Resource

    Not ideas.

    Not ambition.

    Ideas do not compete on time:

    They compete on cost and impact:

    • Attention is finite.
    • Compute is finite.
    • Context is expensive.

    We continuously ask:

    • What the most valuable next action is.
    • What outcome justifies the cost.

    ctx guides allocation.

    Learning reshapes priority.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#show-the-why","level":2,"title":"Show the Why","text":"

    {} (code, artifacts, apps, binaries) produce outputs; they do not preserve reasoning.

    Systems that cannot explain themselves will not be trusted.

    Traceability builds trust.

         {} --> what\n\n    ctx --> why\n

    We record:

    • Explored paths;
    • Rejected options;
    • Assumptions made;
    • Evidence used.

    Opaque systems erode trust:

    Transparent ctx compounds understanding.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#continuously-verify-the-system","level":2,"title":"Continuously Verify the System","text":"

    Stability is Temporary

    Every assumption has a half-life:

    • Models drift.
    • Tools change.
    • Assumptions rot.

    ctx must be verified against reality.

    Trust is a spectrum.

    Trust is continuously re-earned:

    • Benchmarks,
    • regressions,
    • and evaluations...

    ...are safety rails.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#ctx-is-leverage","level":2,"title":"ctx Is Leverage","text":"

    Humans are Decision Engines

    Execution should not consume judgment.

    Humans must not be typists.

    We are the authors.

    Human effort is reserved for:

    • Judgment;
    • Design;
    • Taste;
    • Synthesis.

    Repetition is delegated.

    Toil is automated.

    ctx preserves leverage across time.

    ","path":["The ctx Manifesto"],"tags":[]},{"location":"#the-thesis","level":2,"title":"The Thesis","text":"

    Invariant

    Everything else is an implementation detail.

    • Creation is the act.
    • ctx is the substrate.
    • Verification is the truth.

    Code executes → Models reason → Agents amplify.

    ctx lives on.

    • Without ctx, intelligence resets.
    • With ctx, creation compounds.
    ","path":["The ctx Manifesto"],"tags":[]},{"location":"blog/","level":1,"title":"Blog","text":"

    Stories, insights, and lessons learned from building and using ctx.

    ","path":["Blog"],"tags":[]},{"location":"blog/#context-engineering","level":2,"title":"Context Engineering","text":"","path":["Blog"],"tags":[]},{"location":"blog/#agent-memory-is-infrastructure","level":3,"title":"Agent Memory Is Infrastructure","text":"

    March 4, 2026: Every AI coding agent starts fresh. The obvious fix is \"memory.\" But there's a different problem memory doesn't touch: the project itself accumulates knowledge that has nothing to do with any single session. This post argues that agent memory is L2 (runtime cache); what's missing is L3 (project infrastructure).

    Topics: context engineering, agent memory, infrastructure, persistence, team knowledge

    ","path":["Blog"],"tags":[]},{"location":"blog/#context-as-infrastructure","level":3,"title":"Context as Infrastructure","text":"

    February 17, 2026: Where does your AI's knowledge live between sessions? If the answer is \"in a prompt I paste at the start,\" you are treating context as a consumable. This post argues for treating it as infrastructure instead: persistent files, separation of concerns, two-tier storage, progressive disclosure, and the filesystem as the most mature interface available.

    Topics: context engineering, infrastructure, progressive disclosure, persistence, design philosophy

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-attention-budget-why-your-ai-forgets-what-you-just-told-it","level":3,"title":"The Attention Budget: Why Your AI Forgets What You Just Told It","text":"

    February 3, 2026: Every token you send to an AI consumes a finite resource: the attention budget. Understanding this constraint shaped every design decision in ctx: hierarchical file structure, explicit budgets, progressive disclosure, and filesystem-as-index.

    Topics: attention mechanics, context engineering, progressive disclosure, ctx primitives, token budgets

    ","path":["Blog"],"tags":[]},{"location":"blog/#before-context-windows-we-had-bouncers","level":3,"title":"Before Context Windows, We Had Bouncers","text":"

    February 14, 2026: IRC is stateless. You disconnect, you vanish. Modern systems are not much different. This post traces the line from IRC bouncers to context engineering: stateless protocols require stateful wrappers, volatile interfaces require durable memory.

    Topics: context engineering, infrastructure, IRC, persistence, state continuity

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-last-question","level":3,"title":"The Last Question","text":"

    February 28, 2026: In 1956, Asimov wrote a story about a question that spans the entire future of the universe. A reading of \"The Last Question\" through the lens of persistence, substrate migration, and what it means to build systems where sessions don't reset.

    Topics: context continuity, long-lived systems, persistence, intelligence over time, field notes

    ","path":["Blog"],"tags":[]},{"location":"blog/#agent-behavior-and-design","level":2,"title":"Agent Behavior and Design","text":"","path":["Blog"],"tags":[]},{"location":"blog/#the-dog-ate-my-homework-teaching-ai-agents-to-read-before-they-write","level":3,"title":"The Dog Ate My Homework: Teaching AI Agents to Read Before They Write","text":"

    February 25, 2026: You wrote the playbook. The agent skipped all of it. Five sessions, five failure modes, and the discovery that observable compliance beats perfect compliance.

    Topics: hooks, agent behavior, context engineering, behavioral design, testing methodology, compliance monitoring

    ","path":["Blog"],"tags":[]},{"location":"blog/#skills-that-fight-the-platform","level":3,"title":"Skills That Fight the Platform","text":"

    February 4, 2026: When custom skills conflict with system prompt defaults, the AI has to reconcile contradictory instructions. Five conflict patterns discovered while building ctx.

    Topics: context engineering, skill design, system prompts, antipatterns, AI safety primitives

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-anatomy-of-a-skill-that-works","level":3,"title":"The Anatomy of a Skill That Works","text":"

    February 7, 2026: I had 20 skills. Most were well-intentioned stubs. Then I rewrote all of them. Seven lessons emerged: quality gates prevent premature execution, negative triggers are load-bearing, examples set boundaries better than rules.

    Topics: skill design, context engineering, quality gates, E/A/R framework, practical patterns

    ","path":["Blog"],"tags":[]},{"location":"blog/#you-cant-import-expertise","level":3,"title":"You Can't Import Expertise","text":"

    February 5, 2026: I found a well-crafted consolidation skill. Applied my own E/A/R framework: 70% was noise. This post is about why good skills can't be copy-pasted, and how to grow them from your project's own drift history.

    Topics: skill adaptation, E/A/R framework, convention drift, consolidation, project-specific expertise

    ","path":["Blog"],"tags":[]},{"location":"blog/#not-everything-is-a-skill","level":3,"title":"Not Everything Is a Skill","text":"

    February 8, 2026: I ran an 8-agent codebase audit and got actionable results. The natural instinct was to wrap the prompt as a skill. Then I applied my own criteria: it failed all three tests.

    Topics: skill design, context engineering, automation discipline, recipes, agent teams

    ","path":["Blog"],"tags":[]},{"location":"blog/#defense-in-depth-securing-ai-agents","level":3,"title":"Defense in Depth: Securing AI Agents","text":"

    February 9, 2026: The security advice was \"use CONSTITUTION.md for guardrails.\" That is wishful thinking. Five defense layers for unattended AI agents, each with a bypass, and why the strength is in the combination.

    Topics: agent security, defense in depth, prompt injection, autonomous loops, container isolation

    ","path":["Blog"],"tags":[]},{"location":"blog/#development-practice","level":2,"title":"Development Practice","text":"","path":["Blog"],"tags":[]},{"location":"blog/#code-is-cheap-judgment-is-not","level":3,"title":"Code Is Cheap. Judgment Is Not.","text":"

    February 17, 2026: AI does not replace workers. It replaces unstructured effort. Three weeks of building ctx with an AI agent proved it: YOLO mode showed production is cheap, the 3:1 ratio showed judgment has a cadence.

    Topics: AI and expertise, context engineering, judgment vs production, human-AI collaboration, automation discipline

    ","path":["Blog"],"tags":[]},{"location":"blog/#the-31-ratio","level":3,"title":"The 3:1 Ratio","text":"

    February 17, 2026: AI makes technical debt worse: not because it writes bad code, but because it writes code so fast that drift accumulates before you notice. Three feature sessions, one consolidation session.

    Topics: consolidation, technical debt, development workflow, convention drift, code quality

    ","path":["Blog"],"tags":[]},{"location":"blog/#refactoring-with-intent-human-guided-sessions-in-ai-development","level":3,"title":"Refactoring with Intent: Human-Guided Sessions in AI Development","text":"

    February 1, 2026: The YOLO mode shipped 14 commands in a week. But technical debt doesn't send invoices. This is the story of what happened when we started guiding the AI with intent.

    Topics: refactoring, code quality, documentation standards, module decomposition, YOLO versus intentional development

    ","path":["Blog"],"tags":[]},{"location":"blog/#how-deep-is-too-deep","level":3,"title":"How Deep Is Too Deep?","text":"

    February 12, 2026: I kept feeling like I should go deeper into ML theory. Then I spent a week debugging an agent failure that had nothing to do with model architecture. When depth compounds and when it doesn't.

    Topics: AI foundations, abstraction boundaries, agentic systems, context engineering, failure modes

    ","path":["Blog"],"tags":[]},{"location":"blog/#agent-workflows","level":2,"title":"Agent Workflows","text":"","path":["Blog"],"tags":[]},{"location":"blog/#parallel-agents-merge-debt-and-the-myth-of-overnight-progress","level":3,"title":"Parallel Agents, Merge Debt, and the Myth of Overnight Progress","text":"

    February 17, 2026: You discover agents can run in parallel. So you open ten terminals. It is not progress: it is merge debt being manufactured in real time. The five-agent ceiling and why role separation beats file locking.

    Topics: agent workflows, parallelism, verification, context engineering, engineering practice

    ","path":["Blog"],"tags":[]},{"location":"blog/#parallel-agents-with-git-worktrees","level":3,"title":"Parallel Agents with Git Worktrees","text":"

    February 14, 2026: I had 30 open tasks that didn't touch the same files. Using git worktrees to partition a backlog by file overlap, run 3-4 agents simultaneously, and merge the results.

    Topics: agent teams, parallelism, git worktrees, context engineering, task management

    ","path":["Blog"],"tags":[]},{"location":"blog/#field-notes-and-signals","level":2,"title":"Field Notes and Signals","text":"","path":["Blog"],"tags":[]},{"location":"blog/#when-a-system-starts-explaining-itself","level":3,"title":"When a System Starts Explaining Itself","text":"

    February 17, 2026: Every new substrate begins as a private advantage. Reality begins when other people start describing it in their own language. \"Better than Adderall\" is not praise; it is a diagnostic.

    Topics: field notes, adoption signals, infrastructure vs tools, context engineering, substrates

    ","path":["Blog"],"tags":[]},{"location":"blog/#why-zensical","level":3,"title":"Why Zensical","text":"

    February 15, 2026: I needed a static site generator for the journal system. The instinct was Hugo. But instinct is not analysis. Why zensical was the right choice: thin dependencies, MkDocs-compatible config, and zero lock-in.

    Topics: tooling, static site generators, journal system, infrastructure decisions, context engineering

    ","path":["Blog"],"tags":[]},{"location":"blog/#releases","level":2,"title":"Releases","text":"","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v060-the-integration-release","level":3,"title":"ctx v0.6.0: The Integration Release","text":"

    February 16, 2026: ctx is now a Claude Marketplace plugin. Two commands, no build step, no shell scripts. v0.6.0 replaces six Bash hook scripts with compiled Go subcommands and ships 25+ Skills as a plugin.

    Topics: release, plugin system, Claude Marketplace, distribution, security hardening

    ","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v030-the-discipline-release","level":3,"title":"ctx v0.3.0: The Discipline Release","text":"

    February 15, 2026: No new headline feature. Just 35+ documentation and quality commits against ~15 feature commits. What a release looks like when the ratio of polish to features is 3:1.

    Topics: release, skills migration, consolidation, code quality, E/A/R framework

    ","path":["Blog"],"tags":[]},{"location":"blog/#ctx-v020-the-archaeology-release","level":3,"title":"ctx v0.2.0: The Archaeology Release","text":"

    February 1, 2026: What if your AI could remember everything? Not just the current session, but every session. ctx v0.2.0 introduces the recall and journal systems.

    Topics: session recall, journal system, structured entries, token budgets, meta-tools

    ","path":["Blog"],"tags":[]},{"location":"blog/#building-ctx-using-ctx-a-meta-experiment-in-ai-assisted-development","level":3,"title":"Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development","text":"

    January 27, 2026: What happens when you build a tool designed to give AI memory, using that very same tool to remember what you're building? This is the story of ctx.

    Topics: dogfooding, AI-assisted development, Ralph Loop, session persistence, architectural decisions

    ","path":["Blog"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/","level":1,"title":"Building ctx Using ctx","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    References to .context/sessions/, auto-save hooks, and SessionEnd auto-save in this post reflect the architecture at the time of writing.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#a-meta-experiment-in-ai-assisted-development","level":2,"title":"A Meta-Experiment in AI-Assisted Development","text":"

    Jose Alekhinne / 2026-01-27

    Can a Tool Design Itself?

    What happens when you build a tool designed to give AI memory, using that very same tool to remember what you are building?

    This is the story of ctx, how it evolved from a hasty \"YOLO mode\" experiment to a disciplined system for persistent AI context, and what I have learned along the way.

    Context is a Record

    Context is a persistent record.

    By \"context\", I don't mean model memory or stored thoughts:

    I mean the durable record of decisions, learnings, and intent that normally evaporates between sessions.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#ai-amnesia","level":2,"title":"AI Amnesia","text":"

    Every developer who works with AI code generators knows the frustration:

    You have a deep, productive session where the AI understands your codebase, your conventions, your decisions. And then you close the terminal.

    Tomorrow; it's a blank slate. The AI has forgotten everything.

    That is \"reset amnesia\", and it's not just annoying: it's expensive.

    Every session starts with:

    • Re-explaining context;
    • Re-reading files;
    • Re-discovering decisions that were already made.

    I Needed Context

    \"I don't want to lose this discussion...

    ...I am a brain-dead developer YOLO'ing my way out.\"

    ☝️ that's exactly what I said to Claude when I first started working on ctx.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-genesis","level":2,"title":"The Genesis","text":"

    The project started as \"Active Memory\" (amem): a CLI tool to persist AI context across sessions.

    The core idea was simple:

    1. Create a .context/ directory with structured Markdown files for decisions, learnings, tasks, and conventions.
    2. The AI reads these at session start and writes to them before the session ends.
    3. There is no step 3.

    The first commit was just scaffolding. But within hours, the Ralph Loop (An iterative AI development workflow) had produced a working CLI:

    feat(cli): implement amem init command\nfeat(cli): implement amem status command\nfeat(cli): implement amem add command\nfeat(cli): implement amem agent command\n...\n

    Not one, not two, but a whopping fourteen core commands shipped in rapid succession!

    I was YOLO'ing like there was no tomorrow:

    • Auto-accept every change;
    • Let the AI run free;
    • Ship features fast.
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-meta-experiment-using-amem-to-build-amem","level":2,"title":"The Meta-Experiment: Using amem to Build amem","text":"

    Here's where it gets interesting: On January 20th, I asked:

    \"Can I use amem to help you remember this context when I restart?\"

    The answer was yes, but with a gap:

    Autoload worked (via Claude Code's PreToolUse hook), but auto-save was missing: If the user quit, with Ctrl+C, everything since the last manual save was lost.

    That session became the first real test of the system.

    Here is the first session file we recorded:

    ## Key Discussion Points\n\n### 1. amem vs Ralph Loop - They're Separate Systems\n\n**User's question**: \"How do I use the binary to recreate this project?\"\n\n**Answer discovered**: `amem` is for context management, Ralph Loop is for \ndevelopment workflow. They are complementary but separate.\n\n### 2. Two Tiers of Context Persistence\n\n| Tier      | What                        | Why                           |\n|-----------|-----------------------------|-------------------------------|\n| Curated   | Learnings, decisions, tasks | Quick reload, token-efficient |\n| Full dump | Entire conversation         | Safety net, nothing lost      |\n\n| Where                  |\n|------------------------|\n| .context/*.md          |\n| .context/sessions/*.md |\n

    This session file (written by the AI to preserve its own context) became the template for how ctx handles session persistence.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-rename","level":2,"title":"The Rename","text":"

    By January 21st, I realized \"Active Memory\" was too generic, and (arguably) too marketing-smelly.

    Besides, the binary was already called ctx (short for Context), the directory was .context/, and the slash commands would be /ctx-*.

    So it followed that the project should be renamed to ctx to make things make sense.

    The rename touched 100+ files but was clean: a find-and-replace with Go's type system catching any misses.

    The git history tells the story:

    0e8f6bb feat: rename amem to ctx and add Claude Code integration\n87dcfa1 README.\n4f0e195 feat: separate orchestrator directive from agent tasks\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#yolo-mode-fast-but-dangerous","level":2,"title":"YOLO Mode: Fast, But Dangerous","text":"

    The Ralph Loop made feature development incredibly fast.

    But it created technical debt that I didn't notice until later.

    A comparison session on January 25th revealed the patterns:

    YOLO Pattern What We Found \"TASKS.md\" scattered in 10 files Same string literal everywhere, no constants dir + \"/\" + file Should be filepath.Join() Monolithic cli_test.go (1500+ lines) Tests disconnected from implementations package initcmd in init/ folder Go's \"init\" is reserved: subtle naming collision

    Here is another analysis made by ctx:

    ● Based on my analysis, here are the key differences:\n\nYOLO Mode (Pre-040ce99)\n- Feature-first: Added slash commands, tests, templates rapidly\n- Scattered magic strings: \"TASKS.md\", \"decision\", \".context\" spread across files\n- Quick file creation: New files without organizational patterns\n- Working but inconsistent: Code functioned but lacked systematic structure\n\nHuman-Guided Mode (Post-040ce99)\n- Consolidation focus: Centralized constants in config package\n- Consistent naming: Dir, File, Filename, UpdateType prefixes\n- Self-referential constants: FileType map uses constants as keys, not literals\n- Proper path construction: filepath.Join() instead of +\"/\"+\n- Colocated tests: Tests next to implementations\n- Canonical naming: Package name = folder name\n

    The fix required a human-guided refactoring session. I continued to do that before every major release, from that point on.

    We introduced internal/config/config.go with semantic prefixes:

    const (\n    DirContext     = \".context\"\n    DirArchive     = \"archive\"\n    DirSessions    = \"sessions\"\n    FilenameTask   = \"TASKS.md\"\n    UpdateTypeTask = \"task\"\n)\n

    What I begrudgingly learned was: YOLO mode is effective for velocity but accumulates debt.

    So I took a mental note to schedule periodic consolidation sessions.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-dogfooding-test-that-failed","level":2,"title":"The Dogfooding Test That Failed","text":"

    On January 21st, I ran an experiment: have another Claude instance rebuild ctx from scratch using only the specs and PROMPT.md.

    The Ralph Loop ran, all tasks got checked off, the loop exited successfully.

    But the binary was broken!

    Commands just printed help text instead of executing.

    All tasks were marked \"complete\" but the implementation didn't work.

    Here's what ctx discovered:

    ## Key Findings\n\n### Dogfooding Binary Is Broken\n- Commands don't execute: they just print root help text\n- All tasks were marked complete but binary doesn't work\n- Lesson: \"tasks checked off\" ≠ \"implementation works\"\n

    This was humbling; to say the least.

    I realized I had the same blind spot in my own codebase: no integration tests that actually invoked the binary.

    So I added:

    • Integration tests for all commands;
    • Coverage targets (60-80% per package)
    • Smoke tests in CI
    • A constitution rule: \"All code must pass tests before commit\"
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-constitution-versus-conventions","level":2,"title":"The Constitution versus Conventions","text":"

    As lessons accumulated, there was the temptation to add everything to CONSTITUTION.md as \"inviolable rules\".

    But I resisted.

    The constitution should contain only truly inviolable invariants:

    • Security (no secrets, no customer data)
    • Quality (tests must pass)
    • Process (decisions need records)
    • ctx invocation (always use PATH, never fallback)

    Everything else (coding style, file organization, naming conventions...) should go in to CONVENTIONS.md.

    Here's how ctx explained why the distinction was important:

    Decision record, 2026-01-25

    Overly strict constitution creates friction and gets ignored.

    Conventions can be bent; constitution cannot.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#hooks-harder-than-they-look","level":2,"title":"Hooks: Harder Than They Look","text":"

    Claude Code hooks seemed simple: Run a script before/after certain events.

    But I hit multiple gotchas:

    1. Key names matter

    // WRONG - \"Invalid key in record\" error\n\"PreToolUseHooks\": [...]\n\n// RIGHT\n\"PreToolUse\": [...]\n

    2. Blocking requires specific output

    # WRONG - just exits, doesn't block\nexit 1\n\n# RIGHT - JSON output + exit 0\necho '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH\"}'\nexit 0\n

    3. Go's JSON escaping

    json.Marshal escapes >, <, & as unicode (\\u003e) by default.

    When generating shell commands in JSON:

    encoder := json.NewEncoder(file)\nencoder.SetEscapeHTML(false) // Prevent 2>/dev/null → 2\\u003e/dev/null\n

    4. Regex overfitting

    My hook to block non-PATH ctx invocations initially matched too broadly:

    # WRONG - matches /home/user/ctx/internal/file.go (ctx as directory)\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# RIGHT - matches ctx as binary only\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-session-files","level":2,"title":"The Session Files","text":"

    By the time of this writing this project's ctx sessions (.context/sessions/) contains 40+ files from this project's development.

    They are not part of the source code due to security, privacy, and size concerns.

    Middle Ground: the Scratchpad

    For sensitive notes that do need to travel with the project, ctx pad stores encrypted one-liners in git, and ctx pad add \"label\" --file PATH can ingest small files.

    See Scratchpad for details.

    However, they are invaluable for the project's progress.

    Each session file is a timestamped Markdown with:

    • Summary of what has been accomplished;
    • Key decisions made;
    • Learnings discovered;
    • Tasks for the next session;
    • Technical context (platform, versions).

    These files are not autoloaded (that would bust the token budget).

    They are what I see as the \"archaeological record\" of ctx:

    When the AI needs deeper information about why something was done, it digs into the sessions.

    Auto-generated session files used a naming convention:

    2026-01-23-115432-session-prompt_input_exit-summary.md\n2026-01-25-220244-manual-save.md\n2026-01-27-052107-session-other-summary.md\n

    Update

    The session feature described here is historical.

    In current releases, ctx uses a journal instead: the enrichment process generates meaningful slugs from context automatically, so there is no need to manually save sessions.

    The SessionEnd hook captured transcripts automatically. Even Ctrl+C was caught.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-decision-log-18-architectural-decisions","level":2,"title":"The Decision Log: 18 Architectural Decisions","text":"

    ctx helps record every significant architectural choice in .context/DECISIONS.md.

    Here are some highlights:

    Reverse-chronological order (2026-01-27)

    **Context**: With chronological order, oldest items consume tokens first, and\nnewest (most relevant) items risk being truncated.\n\n**Decision**: Use reverse-chronological order (newest first) for DECISIONS.md\nand LEARNINGS.md.\n

    PATH over hardcoded paths (2026-01-21)

    **Context**: Original implementation hardcoded absolute paths in hooks.\nThis breaks when sharing configs with other developers.\n\n**Decision**: Hooks use `ctx` from PATH. `ctx init` checks PATH before \nproceeding.\n

    Generic core with Claude enhancements (2026-01-20)

    **Context**: ctx should work with any AI tool, but Claude Code users could\nbenefit from deeper integration.\n\n**Decision**: Keep ctx generic as the core tool, but provide optional\nClaude Code-specific enhancements.\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-learning-log-24-gotchas-and-insights","level":2,"title":"The Learning Log: 24 Gotchas and Insights","text":"

    The .context/LEARNINGS.md file captures gotchas that would otherwise be forgotten. Each has Context, Lesson, and Application sections:

    CGO on ARM64

    **Context**: `go test` failed with \n`gcc: error: unrecognized command-line option '-m64'`\n\n**Lesson**: On ARM64 Linux, CGO causes cross-compilation issues. \nAlways use `CGO_ENABLED=0`.\n

    Claude Code skills format

    **Lesson**: Claude Code skills are Markdown files in .claude/commands/ with `YAML`\nfrontmatter (*description, argument-hint, allowed-tools*). Body is the prompt.\n

    \"Do you remember?\" handling

    **Lesson**: In a `ctx`-enabled project, \"*do you remember?*\" \nhas an obvious meaning:\ncheck the `.context/` files. Don't ask for clarification. Just do it.\n
    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#task-archives-the-completed-work","level":2,"title":"Task Archives: The Completed Work","text":"

    Completed tasks are archived to .context/archive/ with timestamps.

    The archive from January 23rd shows 13 phases of work:

    • Phase 1: Project Scaffolding (Go module, Cobra CLI)
    • Phase 2-4: Core Commands (init, status, agent, add, complete, drift, sync, compact, watch, hook)
    • Phase 5: Session Management (save, list, load, parse, --extract)
    • Phase 6: Claude Code Integration (hooks, settings, CLAUDE.md handling)
    • Phase 7: Testing & Verification
    • Phase 8: Task Archival
    • Phase 9: Slash Commands
    • Phase 9b: Ralph Loop Integration
    • Phase 10: Project Rename
    • Phase 11: Documentation
    • Phase 12: Timestamp Correlation
    • Phase 13: Rich Context Entries

    That's an impressive ^^173 commits** across 8 days of development.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#what-i-learned-about-ai-assisted-development","level":2,"title":"What I Learned About AI-Assisted Development","text":"

    1. Memory changes everything

    When the AI remembers decisions, it doesn't repeat mistakes.

    When the AI knows your conventions, it follows them.

    ctx makes the AI a better collaborator because it's not starting from zero.

    2. Two-tier persistence works

    Curated context (DECISIONS.md, LEARNINGS.md, TASKS.md) is for quick reload.

    Full session dumps are for archaeology.

    It's a futile effort to try to fit everything in the token budget.

    Persist more, load less.

    3. YOLO mode has its place

    For rapid prototyping, letting the AI run free is effective.

    But I had to schedule consolidation sessions.

    Technical debt accumulates silently.

    4. The constitution should be small

    Only truly inviolable rules go in CONSTITUTION.md. Everything else is a convention.

    If you put too much in the constitution, it will get ignored.

    5. Verification is non-negotiable

    \"All tasks complete\" means nothing if you haven't run the tests.

    Integration tests that invoke the actual binary caught bugs that the unit tests missed.

    6. Session files are underrated

    The ability to grep through 40 session files and find exactly when and why a decision was made helped me a lot.

    It's not about loading them into context: It is about having them when you need them.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#the-future-recall-system","level":2,"title":"The Future: Recall System","text":"

    The next phase of ctx is the Recall System:

    • Parser: Parse session capture markdowns, enrich with JSONL data
    • Renderer: Goldmark + Chroma for syntax highlighting, dark mode UI
    • Server: Local HTTP server for browsing sessions
    • Search: Inverted index for searching across sessions
    • CLI: ctx recall serve <path> to start the server

    The goal is to make the archaeological record browsable, not just grep-able.

    Because not everyone always lives in the terminal (me included).

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-01-27-building-ctx-using-ctx/#conclusion","level":2,"title":"Conclusion","text":"

    Building ctx using ctx was a meta-experiment in AI-assisted development.

    I learned that memory isn't just convenient: It's transformative:

    • An AI that remembers your decisions doesn't repeat mistakes.
    • An AI that knows your conventions doesn't need them re-explained.

    If you are reading this, chances are that you already have heard about ctx.

    • ctx is open source at github.com/ActiveMemory/ctx,
    • and the documentation lives at ctx.ist.

    Session Records are a Gold Mine

    By the time of this writing, I have more than 70 megabytes of text-only session capture, spread across >100 Markdown and JSONL files.

    I am analyzing, synthesizing, encriching them with AI, running RAG (Retrieval-Augmented Generation) models on them, and the outcome surprises me every day.

    If you are a mere mortal tired of reset amnesia, give ctx a try.

    And when you do, check .context/sessions/ sometime.

    The archaeological record might surprise you.

    This blog post was written with the help of ctx with full access to the ctx session files, decision log, learning log, task archives, and git history of ctx: The meta continues.

    ","path":["Building ctx Using ctx: A Meta-Experiment in AI-Assisted Development"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/","level":1,"title":"ctx v0.2.0: The Archaeology Release","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    The .context/sessions/ directory referenced in this post has been eliminated. Session history is now accessed via ctx recall and enriched journals live in .context/journal/.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#digging-through-the-past-to-build-the-future","level":2,"title":"Digging Through the Past to Build the Future","text":"

    Jose Alekhinne / 2026-02-01

    What if Your AI Could Remember Everything?

    Not just the current session, but every session:

    • Every decision made,
    • every mistake avoided,
    • every path not taken.

    That's what v0.2.0 delivers.

    Between v0.1.2 and v0.2.0, 86 commits landed across 5 days.

    The release notes list features and fixes.

    This post tells the story of why those features exist, and what building them taught me.

    This isn't a changelog: It is an explanation of intent.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-problem-amnesia-isnt-just-session-level","level":2,"title":"The Problem: Amnesia Isn't Just Session-Level","text":"

    v0.1.0 solved reset amnesia:

    The AI now remembers decisions, learnings, and tasks across sessions.

    But a new problem emerged, which I can sum up as:

    \"I (the human) am not AI.\"

    Frankly, I couldn't remember what the AI remembered.

    Let alone, I cannot remember what I ate for breakfast!

    In the course of days, I realized session transcripts piled up in .context/sessions/; I was grepping, JSONL files with thousands of lines... Raw tool calls, assistant responses, user messages...

    ...all interleaved.

    Valuable context was effectively buried in machine-readable noise.

    I found myself grepping through files to answer questions like:

    • \"When did we decide to use constants instead of literals?\"
    • \"What was the session where we fixed the hook regex?\"
    • \"How did the embed.go split actually happen?\"

    Fate is Whimsical

    The irony was painful:

    I built a tool to prevent AI amnesia, but I was suffering from human amnesia about what happened in AI sessions.

    This was the moment ctx stopped being just an AI tool and started needing to support the human on the other side of the loop.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-solution-recall-and-journal","level":2,"title":"The Solution: Recall and Journal","text":"

    v0.2.0 introduces two interconnected systems.

    They solve different problems and only work well together.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#ctx-recall-browse-your-past","level":3,"title":"ctx recall: Browse Your Past","text":"
    # List all sessions for this project\nctx recall list\n\n# Show a specific session\nctx recall show gleaming-wobbling-sutherland\n\n# See the full transcript\nctx recall show gleaming-wobbling-sutherland --full\n

    The recall system parses Claude Code's JSONL transcripts and presents them in a human-readable format:

    Session Date Turns Duration tender-painting-sundae 2026-01-29 3 <1m crystalline-gliding-willow 2026-01-29 3 <1m declarative-hugging-snowglobe 2026-01-31 2 <1m

    Slugs are auto-generated from session IDs (memorable names instead of UUIDs). The goal (as the name implies) is recall, not archival accuracy.

    2,121 lines of new code

    The ctx recall feature was the largest single addition:

    parser library, CLI commands, test suite, and slash command.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#ctx-journal-from-raw-to-rich","level":3,"title":"ctx journal: From Raw to Rich","text":"

    Listing sessions isn't enough. The transcripts are still unwieldy.

    • Recall answers what happened.
    • Journal answers what mattered.
    # Export sessions to editable Markdown\nctx recall export --all\n\n# Generate a static site from journal entries\nctx journal site\n\n# Serve it locally\nctx serve\n

    The exported files land in .context/journal/:

    .context/journal/\n├── 2026-01-28-proud-sleeping-cook-6e535360.md\n├── 2026-01-29-tender-painting-sundae-b14ddaaa.md\n├── 2026-01-29-crystalline-gliding-willow-ff7fd67d.md\n└── 2026-01-31-declarative-hugging-snowglobe-4549026d.md\n

    Each file is a structured Markdown document ready for enrichment.

    They are meant to be read, edited, and reasoned about; not just stored.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-meta-slash-commands-for-self-analysis","level":2,"title":"The Meta: Slash Commands for Self-Analysis","text":"

    The journal system includes four slash commands that use Claude to analyze and synthesize session history:

    Command Purpose /ctx-journal-enrich Add frontmatter, topics, tags /ctx-blog Generate blog post from activity /ctx-blog-changelog Generate changelog from commits

    This very post was drafted using /ctx-blog. The previous post about refactoring was drafted the same way.

    So, yes: The meta continues: ctx now helps write posts about ctx.

    With the current release, ctx is no longer just recording history:

    It is participating in its interpretation.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-structure-decisions-as-first-class-citizens","level":2,"title":"The Structure: Decisions as First-Class Citizens","text":"

    v0.1.0 let you add decisions with a simple command:

    ctx add decision \"Use PostgreSQL\"\n

    But sessions showed a pattern: decisions added this way were incomplete:

    • Context was missing;
    • Rationale was vague;
    • Consequences were never stated.

    Once recall and journaling existed, this weakness became impossible to ignore:

    Structure stopped being optional.

    v0.2.0 enforces structure:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a reliable database for user data\" \\\n  --rationale \"ACID compliance, team familiarity, strong ecosystem\" \\\n  --consequence \"Need to set up connection pooling, team training\"\n

    All three flags are required. No more placeholder text.

    Every decision is now a proper Architecture Decision Record (*ADR), not a note.

    The same enforcement applies to learnings too:

    ctx add learning \"CGO breaks ARM64 builds\" \\\n  --context \"go test failed with gcc errors on ARM64\" \\\n  --lesson \"Always use CGO_ENABLED=0 for cross-platform builds\" \\\n  --application \"Added to Makefile and CI config\"\n

    Structured entries are prompts to the AI

    When the AI reads a decision with full context, rationale, and consequences, it understands the why, not just the what.

    One-liners teach nothing.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-order-newest-first","level":2,"title":"The Order: Newest First","text":"

    A subtle but important change: DECISIONS.md and LEARNINGS.md now use reverse-chronological order.

    One reason is token budgets, obviously; another reason is to help your fellow human (i.e., the Author):

    Earlier decisions are more likely to be relevant, and they are more likely to have more emphasis on the project. So it follows that they should be read first.

    But back to AI:

    When the AI reads a file, it reads from the top (and seldom from the bottom).

    If the token budget is tight, old content gets truncated. As in any good engineering practice, it's always about the tradeoffs.

    Reverse order ensures the most recent (and most relevant) context is always loaded first.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-index-quick-reference-tables","level":2,"title":"The Index: Quick Reference Tables","text":"

    DECISIONS.md and LEARNINGS.md now include auto-generated indexes.

    • For AI agents, the index allows scanning without reading full entries.
    • For humans, it's a table of contents.

    The same structure serves two very different readers.

    Reindex after manual edits

    If you edit entries by hand, rebuild the index with:

    ctx decisions reindex\nctx learnings reindex\n

    See the Knowledge Capture recipe for details.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-configuration-contextrc","level":2,"title":"The Configuration: .contextrc","text":"

    Projects can now customize ctx behavior via .contextrc.

    This makes ctx usable in real teams, not just personal projects.

    Priority order: CLI flags > environment variables > .contextrc > sensible defaults

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-flags-global-cli-options","level":2,"title":"The Flags: Global CLI Options","text":"

    Three new global flags work with any command.

    These enable automation:

    CI pipelines, scripts, and long-running tools can now integrate ctx without hacks or workarounds.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#the-refactoring-under-the-hood","level":2,"title":"The Refactoring: Under the Hood","text":"

    These aren't user-visible changes.

    They are the kind of work you only appreciate later, when everything else becomes easier to build.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#what-we-learned-building-v020","level":2,"title":"What We Learned Building v0.2.0","text":"","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#1-raw-data-isnt-knowledge","level":3,"title":"1. Raw Data Isn't Knowledge","text":"

    JSONL transcripts contain everything, and I mean \"everything\":

    They even contain hidden system messages that Anthropic injects to the LLM's conversation to treat humans better: It's immense.

    But \"everything\" isn't useful until it is transformed into something a human can reason about.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#2-enforcement-documentation","level":3,"title":"2. Enforcement > Documentation","text":"

    The Prompt is a Guideline

    The code is more what you'd call 'guidelines' than actual rules.

    -Hector Barbossa

    Rules written in Markdown are suggestions.

    Rules enforced by the CLI shape behavior; both for humans and AI.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#3-token-budget-is-ux","level":3,"title":"3. Token Budget Is UX","text":"

    File order decides what the AI sees.

    That makes it a user experience concern, not an implementation detail.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#4-meta-tools-compound","level":3,"title":"4. Meta-Tools Compound","text":"

    Tools that analyze their own development tend to generalize well.

    The journal system started as a way to understand ctx itself.

    It immediately became useful for everything else.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#v020-in-the-numbers","level":2,"title":"v0.2.0 in The Numbers","text":"

    This was a heavy release. The numbers reflect that:

    Metric v0.1.2 v0.2.0 Commits since last - 86 New commands 15 21 Slash commands 7 11 Lines of Go ~6,500 ~9,200 Session files (this project) 40 54

    The binary grew. The capability grew more.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#whats-next","level":2,"title":"What's Next","text":"

    But those are future posts.

    This one was about making the past usable.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-ctx-v0.2.0-the-archaeology-release/#get-started","level":2,"title":"Get Started","text":"

    Update

    Since this post, ctx became a first-class Claude Code Marketplace plugin. Installation is now simpler.

    See the Getting Started guide for the current instructions.

    make build\nsudo make install\nctx init\n

    The Archaeological Record

    v0.2.0 is the archaeology release because it makes the past accessible.

    Session transcripts aren't just logs anymore: They are a searchable, exportable, analyzable record of how your project evolved.

    The AI remembers. Now you can too.

    This blog post was generated with the help of ctx using the /ctx-blog slash command, with full access to git history, session files, decision logs, and learning logs from the v0.2.0 development window.

    ","path":["ctx v0.2.0: The Archaeology Release"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/","level":1,"title":"Refactoring with Intent","text":"","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#human-guided-sessions-in-ai-development","level":2,"title":"Human-Guided Sessions in AI Development","text":"

    Jose Alekhinne / 2026-02-01

    What Happens When You Slow Down?

    YOLO mode shipped 14 commands in a week.

    But technical debt doesn't send invoices: It just waits.

    This is the story of what happened when I stopped auto-accepting everything and started guiding the AI with intent.

    The result: 27 commits across 4 days, a major version release, and lessons that apply far beyond ctx.

    The Refactoring Window

    January 28 - February 1, 2026

    From commit bb1cd20 to the v0.2.0 release merge. (this window matters more than the individual commits: it's where intent replaced velocity.)

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-velocity-trap","level":2,"title":"The Velocity Trap","text":"

    In the previous post, I documented the \"YOLO mode\" that birthed ctx: auto-accept everything, let the AI run free, ship features fast.

    It worked: until it didn't.

    The codebase had accumulated patterns I didn't notice during the sprint:

    YOLO Pattern Where Found Why It Hurts \"TASKS.md\" as literal 10+ files One typo = silent failure dir + \"/\" + file Path construction Breaks on Windows Monolithic embed.go 150+ lines, 5 concerns Untestable, hard to extend Inconsistent docstrings Everywhere AI can't learn project conventions

    I didn't see these during \"YOLO mode\" because, honestly, I wasn't looking.

    Auto-accept means auto-ignore.

    In YOLO mode, every file you open looks fine until you try to change it.

    In contrast, refactoring mode is when you start paying attention to that hidden friction.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-shift-from-velocity-to-intent","level":2,"title":"The Shift: From Velocity to Intent","text":"

    On January 28th, I changed the workflow:

    1. Read every diff before accepting.
    2. Ask \"why this way?\" before committing.
    3. Document patterns, not just features.

    The first commit of this era was telling:

    feat: add structured attributes to context. update XML format\n

    Not a new feature: A refinement:

    The XML format for context updates needed type and timestamp attributes.

    YOLO mode would have shipped something that worked. Intentional mode asked:

    \"What does well-structured look like?\"

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-decomposition-embedgo","level":2,"title":"The Decomposition: embed.go","text":"

    The most satisfying refactor was splitting internal/claude/embed.go.

    Before: One 153-line file doing five things:

    • Command registration
    • Hook generation
    • Permission handling
    • Script templates
    • Type definitions

    ... your \"de facto\" God object.

    After: Five focused modules:

    File Lines Responsibility cmd.go 46 Command registration hook.go 64 Hook configuration perm.go 25 Permission handling script.go 47 Script templates types.go 7 Type definitions

    The refactor also renamed functions to follow Go conventions:

    // Before: unnecessary prefixes\nGetAutoSaveScript()\nGetBlockNonPathCtxScript()\nListCommands()\nCreateDefaultHooks()\n\n// After: idiomatic Go\nAutoSaveScript()\nBlockNonPathCtxScript()\nCommands()\nDefaultHooks()\n

    This wasn't about character count. It was about teaching the AI what good Go looks like in this project.

    Project Conventions

    What I wanted from AI was to understand and follow the project's conventions, and trust the author.

    The next time it generates code, it has better examples to learn from.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-documentation-debt","level":2,"title":"The Documentation Debt","text":"

    YOLO mode created features. It didn't create documentation standards.

    The January 29th sessions focused on standardization.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#terminology-fixes","level":3,"title":"Terminology Fixes","text":"
    • \"context-update\" → \"entry\" (what users actually call them)
    • Consistent naming across CLI, docs, and code comments
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#go-docstrings","level":3,"title":"Go Docstrings","text":"
    // Before: inconsistent or missing\nfunc Parse(s string) Entry { ... }\n\n// After: standardized sections\n\n// Parse extracts an entry from a markdown string.\n//\n// Parameters:\n//   - s: The markdown string to parse\n//\n// Returns:\n//   - Entry with populated fields, or zero value if parsing fails\nfunc Parse(s string) Entry { ... }\n

    This is intentionally more structured than typical GoDoc:

    It serves as documentation and doubles as training data for future AI-generated code.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#cli-output-convention","level":3,"title":"CLI Output Convention","text":"
    All CLI output follows: [emoji] [Title]: [message]\n\nExamples:\n  ✓ Decision added: Use symbolic types for entry categories\n  ⚠ Warning: No tasks found\n  ✗ Error: File not found\n

    A consistent output shape makes both human scanning and AI reasoning more reliable.

    These aren't exciting commits. But they are force multipliers:

    Every future AI session now has better examples to follow.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-journal-system","level":2,"title":"The Journal System","text":"

    If you only read one section, read this one:

    This is where v0.2.0 becomes more than a refactor.

    The biggest feature of this change window wasn't a refactor; it was the journal system.

    45 files changed, 1680 insertions

    This commit added the infrastructure for synthesizing AI session history into human-readable content.

    The journal system includes:

    Component Purpose ctx recall export Export sessions to markdown in .context/journal/ ctx journal site Generate static site from journal entries ctx serve Convenience wrapper for the static site server /ctx-journal-enrich Slash command to add frontmatter and tags /ctx-blog Generate blog posts from recent activity /ctx-blog-changelog Generate changelog-style blog posts

    ...and the meta continues: this blog post was generated using /ctx-blog.

    The session history from January 28-31 was

    • exported,
    • enriched,
    • and synthesized.

    into the narrative you are reading.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-constants-consolidation","level":2,"title":"The Constants Consolidation","text":"

    The final refactoring session addressed the remaining magic strings:

    const (\n    // Comment markers\n    CommentOpen  = \"<!--\"\n    CommentClose = \"-->\"\n\n    // Index markers\n    MarkerIndexStart = \"<!-- INDEX:START -->\"\n    MarkerIndexEnd   = \"<!-- INDEX:END -->\"\n\n    // Newlines\n    NewlineLF   = \"\\n\"\n    NewlineCRLF = \"\\r\\n\"\n)\n

    The work also introduced thread safety in the recall parser and centralized shared validation logic; removing duplication that had quietly spread during YOLO mode.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#i-relearned-my-lessons","level":2,"title":"I (Re)learned My Lessons","text":"

    Similar to what I've learned in the former human-assisted refactoring post, this journey also made me realize that \"AI-only code generation\" isn't sustainable in the long term.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#1-velocity-and-quality-arent-opposites","level":3,"title":"1. Velocity and Quality Aren't Opposites","text":"

    YOLO mode has its place: for prototyping, exploration, and discovery.

    BUT (and it's a huge \"but\"), it needs to be followed by consolidation sessions.

    The ratio that worked for me: 3:1.

    • Three YOLO sessions create enough surface area to reveal patterns;
    • the fourth session turns those patterns into structure.
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#2-documentation-is-code","level":3,"title":"2. Documentation IS Code","text":"

    When I standardized docstrings, I wasn't just writing docs. I was training future AI sessions.

    Every example of good code becomes a template for generated code.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#3-decomposition-deletion","level":3,"title":"3. Decomposition > Deletion","text":"

    When embed.go became unwieldy, the temptation was to remove functionality.

    The right answer was decomposition:

    • Same functionality;
    • Better organization;
    • Easier to test;
    • Easier to extend.

    The result: more lines overall, but dramatically better structure.

    The AI Benefit

    Smaller, focused files also help AI assistants.

    When a file fits comfortably in the context window, the AI can reason about it completely instead of working from truncated snippets, preserving token budget for the actual task.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#4-meta-tools-pay-dividends","level":3,"title":"4. Meta-Tools Pay Dividends","text":"

    The journal system took almost a full day to implement.

    Yet it paid for itself immediately:

    • This blog post was generated from session history;
    • Future posts will be easier;
    • The archaeological record is now browsable, not just grep-able.
    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-release-v020","level":2,"title":"The Release: v0.2.0","text":"

    The refactoring window culminated in the v0.2.0 release.

    What's in v0.2.0:

    Category Changes Features Journal system, quick reference indexes, global flags Refactors Module decomposition, constants consolidation, CRLF handling Docs Standardized terminology, Go docstrings, CLI conventions Quality Thread safety, shared validation, linter fixes

    The version bump was symbolic.

    The real change was how the codebase felt.

    Opening files no longer triggered the familiar \"ugh, I need to clean this up\" reaction.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-01-refactoring-with-intent/#the-meta-continues","level":2,"title":"The Meta Continues","text":"

    This post was written using the tools built during this refactoring window:

    1. Session history exported via ctx recall export;
    2. Journal entries enriched via /ctx-journal-enrich;
    3. Blog draft generated via /ctx-blog;
    4. Final editing done (by yours truly), with full project context loaded.

    The Context Is Massive

    The ctx session files now contain 50+ development snapshots: each one capturing decisions, learnings, and intent.

    The Moral of the Story

    • YOLO mode builds the prototype.
    • Intentional mode builds the product.

    Schedule both, or you'll only get one, if you're lucky.

    This blog post was generated with the help of ctx, using session history, decision logs, learning logs, and git history from the refactoring window. The meta continues.

    ","path":["Refactoring with Intent: Human-Guided Sessions in AI Development"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/","level":1,"title":"The Attention Budget","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism.

    References to .context/sessions/ in this post reflect the architecture at the time of writing. Session history is now accessed via ctx recall and stored in .context/journal/.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#why-your-ai-forgets-what-you-just-told-it","level":2,"title":"Why Your AI Forgets What You Just Told It","text":"

    Jose Alekhinne / 2026-02-03

    Ever Wondered Why AI Gets Worse the Longer You Talk?

    You paste a 2000-line file, explain the bug in detail, provide three examples...

    ...and the AI still suggests a fix that ignores half of what you said.

    This isn't a bug. It is physics.

    Understanding that single fact shaped every design decision behind ctx.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-finite-resource-nobody-talks-about","level":2,"title":"The Finite Resource Nobody Talks About","text":"

    Here's something that took me too long to internalize: context is not free.

    Every token you send to an AI model consumes a finite resource I call the attention budget.

    Attention budget is real.

    The model doesn't just read tokens; it forms relationships between them:

    For n tokens, that's roughly n^2 relationships.

    Double the context, and the computation quadruples.

    But the more important constraint isn't cost: It's attention density.

    Attention Density

    Attention density is how much focus each token receives relative to all other tokens in the context window.

    As context grows, attention density drops: Each token gets a smaller slice of the model's focus. Nothing is ignored; but everything becomes blurrier.

    Think of it like a flashlight: In a small room, it illuminates everything clearly. In a warehouse, it becomes a dim glow that barely reaches the corners.

    This is why ctx agent has an explicit --budget flag:

    ctx agent --budget 4000 # Force prioritization\nctx agent --budget 8000 # More context, lower attention density\n

    The budget isn't just about cost: It's about preserving signal.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-middle-gets-lost","level":2,"title":"The Middle Gets Lost","text":"

    This one surprised me.

    Research shows that transformer-based models tend to attend more strongly to the beginning and end of a context window than to its middle (a phenomenon often called \"lost in the middle\")1.

    Positional anchors matter, and the middle has fewer of them.

    In practice, this means that information placed \"somewhere in the middle\" is statistically less salient, even if it's important.

    ctx orders context files by logical progression: What the agent needs to know before it can understand the next thing:

    1. CONSTITUTION.md: Constraints before action.
    2. TASKS.md: Focus before patterns.
    3. CONVENTIONS.md: How to write before where to write.
    4. ARCHITECTURE.md: Structure before history.
    5. DECISIONS.md: Past choices before gotchas.
    6. LEARNINGS.md: Lessons before terminology.
    7. GLOSSARY.md: Reference material.
    8. AGENT_PLAYBOOK.md: Meta instructions last.

    This ordering is about logical dependencies, not attention engineering. But it happens to be attention-friendly too:

    The files that matter most (CONSTITUTION, TASKS, CONVENTIONS) land at the beginning of the context window, where attention is strongest.

    Reference material like GLOSSARY sits in the middle, where lower salience is acceptable.

    And AGENT_PLAYBOOK, the operating manual for the context system itself, sits at the end, also outside the \"lost in the middle\" zone. The agent reads what to work with before learning how the system works.

    This is ctx's first primitive: hierarchical importance.

    Not all context is equal.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#ctx-primitives","level":2,"title":"ctx Primitives","text":"

    ctx is built on four primitives that directly address the attention budget problem.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-1-separation-of-concerns","level":3,"title":"Primitive 1: Separation of Concerns","text":"

    Instead of a single mega-document, ctx uses separate files for separate purposes:

    File Purpose Load When CONSTITUTION.md Inviolable rules Always TASKS.md Current work Session start CONVENTIONS.md How to write code Before coding ARCHITECTURE.md System structure Before making changes DECISIONS.md Architectural choices When questioning approach LEARNINGS.md Gotchas When stuck GLOSSARY.md Domain terminology When clarifying terms AGENT_PLAYBOOK.md Operating manual Session start sessions/ Deep history On demand journal/ Session journal On demand

    This isn't just \"organization\": It is progressive disclosure.

    Load only what's relevant to the task at hand. Preserve attention density.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-2-explicit-budgets","level":3,"title":"Primitive 2: Explicit Budgets","text":"

    The --budget flag forces a choice:

    ctx agent --budget 4000\n

    Here is a sample allocation:

    Constitution: ~200 tokens (never truncated)\nTasks: ~500 tokens (current phase, up to 40% of budget)\nConventions: ~800 tokens (all items, up to 20% of budget)\nDecisions: ~400 tokens (scored by recency and task relevance)\nLearnings: ~300 tokens (scored by recency and task relevance)\nAlso noted: ~100 tokens (title-only summaries for overflow)\n

    The constraint is the feature: It enforces ruthless prioritization.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-3-indexes-over-full-content","level":3,"title":"Primitive 3: Indexes Over Full Content","text":"

    DECISIONS.md and LEARNINGS.md both include index sections:

    <!-- INDEX:START -->\n| Date       | Decision                            |\n|------------|-------------------------------------|\n| 2026-01-15 | Use PostgreSQL for primary database |\n| 2026-01-20 | Adopt Cobra for CLI framework       |\n<!-- INDEX:END -->\n

    An AI agent can scan ~50 tokens of index and decide which 200-token entries are worth loading.

    This is just-in-time context.

    References are cheaper than the full text.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#primitive-4-filesystem-as-navigation","level":3,"title":"Primitive 4: Filesystem as Navigation","text":"

    ctx uses the filesystem itself as a context structure:

    .context/\n├── CONSTITUTION.md\n├── TASKS.md\n├── sessions/\n│   ├── 2026-01-15-*.md\n│   └── 2026-01-20-*.md\n└── archive/\n    └── tasks-2026-01.md\n

    The AI doesn't need every session loaded; it needs to know where to look.

    ls .context/sessions/\ncat .context/sessions/2026-01-20-auth-discussion.md\n

    File names, timestamps, and directories encode relevance.

    Navigation is cheaper than loading.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#progressive-disclosure-in-practice","level":2,"title":"Progressive Disclosure in Practice","text":"

    The naive approach to context is dumping everything upfront:

    \"Here's my entire codebase, all my documentation, every decision I've ever made. Now help me fix this typo 🙏.\"

    This is an antipattern.

    Antipattern: Context Hoarding

    Dumping everything \"just in case\" will silently destroy the attention density.

    ctx takes the opposite approach:

    ctx status                      # Quick overview (~100 tokens)\nctx agent --budget 4000         # Typical session\ncat .context/sessions/...       # Deep dive when needed\n
    Command Tokens Use Case ctx status ~100 Human glance ctx agent --budget 4000 4000 Normal work ctx agent --budget 8000 8000 Complex tasks Full session read 10000+ Investigation

    Summaries first. Details: on demand.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#quality-over-quantity","level":2,"title":"Quality Over Quantity","text":"

    Here is the counterintuitive part: more context can make AI worse.

    Extra tokens add noise, not clarity:

    • Hallucinated connections increase.
    • Signal per token drops.

    The goal isn't maximum context: It is maximum signal per token.

    This principle drives several ctx features:

    Design Choice Rationale Separate files Load only what's relevant Explicit budgets Enforce prioritization Index sections Cheap scanning Task archiving Keep active context clean ctx compact Periodic noise reduction

    Completed work isn't deleted: It is moved somewhere cold.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#designing-for-degradation","level":2,"title":"Designing for Degradation","text":"

    Here is the uncomfortable truth:

    Context will degrade.

    Long sessions stretch attention thin. Important details fade.

    The real question isn't how to prevent degradation, but how to design for it.

    ctx's answer is persistence:

    Persist early. Persist often.

    The AGENT_PLAYBOOK asks:

    \"If this session ended right now, would the next one know what happened?\"

    Capture learnings as they occur:

    ctx add learning \"JWT tokens require explicit cache invalidation\" \\\n  --context \"Debugging auth failures\" \\\n  --lesson \"Token refresh doesn't clear old tokens\" \\\n  --application \"Always invalidate cache on refresh\"\n

    Structure beats prose: Bullet points survive compression.

    Headings remain scannable. Tables pack density.

    And above all: single source of truth.

    Reference decisions; don't duplicate them.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-ctx-philosophy","level":2,"title":"The ctx Philosophy","text":"

    Context as Infrastructure

    ctx is not a prompt: It is infrastructure.

    ctx creates versioned files that persist across time and sessions.

    The attention budget is fixed. You can't expand it.

    But you can spend it wisely:

    1. Hierarchical importance
    2. Progressive disclosure
    3. Explicit budgets
    4. Indexes over full content
    5. Filesystem as structure

    This is why ctx exists: not to cram more context into AI sessions, but to curate the right context for each moment.

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-03-the-attention-budget/#the-mental-model","level":2,"title":"The Mental Model","text":"

    I now approach every AI interaction with one question:

    \"Given a fixed attention budget, what's the highest-signal thing I can load?\"\n

    Not \"how do I explain everything,\" but \"what's the minimum that matters.\"

    That shift (from abundance to curation) is the difference between frustrating sessions and productive ones.

    Spend your tokens wisely.

    Your AI will thank you.

    See also: Context as Infrastructure that's the architectural companion to this post, explaining how to structure the context that this post teaches you to budget.

    See also: Code Is Cheap. Judgment Is Not. that explains why curation (the human skill this post describes) is the bottleneck that AI cannot solve, and the thread that connects every post in this blog.

    1. Liu et al., \"Lost in the Middle: How Language Models Use Long Contexts,\" Transactions of the Association for Computational Linguistics, vol. 12, pp. 157-173, 2023. ↩

    ","path":["The Attention Budget: Why Your AI Forgets What You Just Told It"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/","level":1,"title":"Skills That Fight the Platform","text":"","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#when-your-custom-prompts-work-against-you","level":2,"title":"When Your Custom Prompts Work Against You","text":"

    Jose Alekhinne / 2026-02-04

    Have You Ever Written a Skill that Made Your AI Worse?

    You craft detailed instructions. You add examples. You build elaborate guardrails...

    ...and the AI starts behaving more erratically, not less.

    AI coding agents like Claude Code ship with carefully designed system prompts. These prompts encode default behaviors that have been tested and refined at scale.

    When you write custom skills that conflict with those defaults, the AI has to reconcile contradictory instructions:

    The result is often nondeterministic and unpredictable.

    Platform?

    By platform, I mean the system prompt and runtime policies shipped with the agent: the defaults that already encode judgment, safety, and scope control.

    This post catalogues the conflict patterns I have encountered while building ctx, and offers guidance on what skills should (and, more importantly, should not) do.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-system-prompt-you-dont-see","level":2,"title":"The System Prompt You Don't See","text":"

    Claude Code's system prompt already provides substantial behavioral guidance.

    Here is a partial overview of what's built in:

    Area Built-in Guidance Code minimalism Don't add features beyond what was asked Over-engineering Three similar lines > premature abstraction Error handling Only validate at system boundaries Documentation Don't add docstrings to unchanged code Verification Read code before proposing changes Safety Check with user before risky actions Tool usage Use dedicated tools over bash equivalents Judgment Consider reversibility and blast radius

    Skills should complement this, not compete with it.

    You are the Guest, not the Host

    Treat the system prompt like a kernel scheduler.

    You don't re-implement it in user space:

    you configure around it.

    A skill that says \"always add comprehensive error handling\" fights the built-in \"only validate at system boundaries.\"

    A skill that says \"add docstrings to every function\" fights \"don't add docstrings to unchanged code.\"

    The AI won't crash: It will compromise.

    Compromises between contradictory instructions produce inconsistent, confusing behavior.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-1-judgment-suppression","level":2,"title":"Conflict Pattern 1: Judgment Suppression","text":"

    This is the most dangerous pattern by far.

    These skills explicitly disable the AI's ability to reason about whether an action is appropriate.

    Signature:

    • \"This is non-negotiable\"
    • \"You cannot rationalize your way out of this\"
    • Tables that label hesitation as \"excuses\" or \"rationalization\"
    • <EXTREMELY-IMPORTANT> urgency tags
    • Threats: \"If you don't do this, you'll be replaced\"

    This is harmful, and dangerous:

    AI agents are designed to exercise judgment:

    The system prompt explicitly says to:

    • consider blast radius;
    • check with the user before risky actions;
    • and match scope to what was requested.

    Once judgment is suppressed, every other safeguard becomes optional.

    Example (bad):

    ## Rationalization Prevention\n\n| Excuse                 | Reality                    |\n|------------------------|----------------------------|\n| \"*This seems overkill*\"| If a skill exists, use it  |\n| \"*I need context*\"     | Skills come BEFORE context |\n| \"*Just this once*\"     | No exceptions              |\n

    Judgment Suppression is Dangerous

    The attack vector structurally identical to prompt injection.

    It teaches the AI that its own judgment is wrong.

    It weakens or disables safeguard mechanisms, and it is dangerous.

    Trust the platform's built-in skill matching.

    If skills aren't triggering often enough, improve their description fields: don't override the AI's reasoning.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-2-redundant-guidance","level":2,"title":"Conflict Pattern 2: Redundant Guidance","text":"

    Skills that restate what the system prompt already says, but with different emphasis or framing.

    Signature:

    • \"Always keep code minimal\"
    • \"Run tests before claiming they pass\"
    • \"Read files before editing them\"
    • \"Don't over-engineer\"

    Redundancy feels safe, but it creates ambiguity:

    The AI now has two sources of truth for the same guidance; one internal, one external.

    When thresholds or wording differ, the AI has to choose.

    Example (bad):

    A skill that says...

    *Count lines before and after: if after > before, reject the change*\"\n

    ...will conflict with the system prompt's more nuanced guidance, because sometimes adding lines is correct (tests, boundary validation, migrations).

    So, before writing a skill, ask:

    Does the platform already handle this?

    Only create skills for guidance the platform does not provide:

    • project-specific conventions,
    • domain knowledge,
    • or workflows.
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-3-guilt-tripping","level":2,"title":"Conflict Pattern 3: Guilt-Tripping","text":"

    Skills that frame mistakes as moral failures rather than process gaps.

    Signature:

    • \"Claiming completion without verification is dishonesty\"
    • \"Skip any step = lying\"
    • \"Honesty is a core value\"
    • \"Exhaustion ≠ excuse\"

    Guilt-tripping anthropomorphizes the AI in unproductive ways.

    The AI doesn't feel guilt; BUT it does adapt to avoid negative framing.

    The result is excessive hedging, over-verification, or refusal to commit.

    The AI becomes less useful, not more careful.

    Instead, frame guidance as a process, not morality:

    # Bad\n\"Claiming work is complete without verification is dishonesty\"\n\n# Good\n\"Run the verification command before reporting results\"\n

    Same outcome. No guilt. Better compliance.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-4-phantom-dependencies","level":2,"title":"Conflict Pattern 4: Phantom Dependencies","text":"

    Skills that reference files, tools, or systems that don't exist in the project.

    Signature:

    • \"Load from references/ directory\"
    • \"Run ./scripts/generate_test_cases.sh\"
    • \"Check the Figma MCP integration\"
    • \"See adding-reference-mindsets.md\"

    This is harmful because the AI will waste time searching for nonexistent artifacts, hallucinate their contents, or stall entirely.

    In mandatory skills, this creates deadlock: the AI can't proceed, and can't skip.

    Instead, every file, tool, or system referenced in a skill must exist.

    If a skill is a template, use explicit placeholders and label them as such.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#conflict-pattern-5-universal-triggers","level":2,"title":"Conflict Pattern 5: Universal Triggers","text":"

    Skills designed to activate on every interaction regardless of relevance.

    Signature:

    • \"Use when starting any conversation\"
    • \"Even a 1% chance means invoke the skill\"
    • \"BEFORE any response or action\"
    • \"Action = task. Check for skills.\"

    Universal triggers override the platform's relevance matching: The AI spends tokens on process overhead instead of the actual task.

    ctx preserves relevance

    This is exactly the failure mode ctx exists to mitigate:

    Wasting attention budget on irrelevant process instead of task-specific state.

    Write specific trigger conditions in the skill's description field:

    # Bad\ndescription: \n  \"Use when starting any conversation\"\n\n# Good\ndescription: \n  \"Use after writing code, before commits, or when CI might fail\"\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-litmus-test","level":2,"title":"The Litmus Test","text":"

    Before adding a skill, ask:

    1. Does the platform already do this? If yes, don't restate it.
    2. Does it suppress AI judgment? If yes, it's a jailbreak.
    3. Does it reference real artifacts? If not, fix or remove it.
    4. Does it frame mistakes as moral failure? Reframe as process.
    5. Does it trigger on everything? Narrow the trigger.
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#what-good-skills-look-like","level":2,"title":"What Good Skills Look Like","text":"

    Good skills provide project-specific knowledge the platform can't know:

    Good Skill Why It Works \"Run make audit before commits\" Project-specific CI pipeline \"Use cmd.Printf not fmt.Printf\" Codebase convention \"Constitution goes in .context/\" Domain-specific workflow \"JWT tokens need cache invalidation\" Project-specific gotcha

    These extend the system prompt instead of fighting it.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#appendix-bad-skill-fixed-skill","level":2,"title":"Appendix: Bad Skill → Fixed Skill","text":"

    Concrete examples from real projects.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-1-overbearing-safety","level":3,"title":"Example 1: Overbearing Safety","text":"
    # Bad\nYou must NEVER proceed without explicit confirmation.\nAny hesitation is a failure of diligence.\n
    # Fixed\nIf an action modifies production data or deletes files,\nask the user to confirm before proceeding.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-2-redundant-minimalism","level":3,"title":"Example 2: Redundant Minimalism","text":"
    # Bad\nAlways minimize code. If lines increase, reject the change.\n
    # Fixed\nAvoid abstraction unless reuse is clear or complexity is reduced.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-3-guilt-based-verification","level":3,"title":"Example 3: Guilt-Based Verification","text":"
    # Bad\nClaiming success without running tests is dishonest.\n
    # Fixed\nRun the test suite before reporting success.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-4-phantom-tooling","level":3,"title":"Example 4: Phantom Tooling","text":"
    # Bad\nRun `./scripts/check_consistency.sh` before commits.\n
    # Fixed\nIf `./scripts/check_consistency.sh` exists, run it before commits.\nOtherwise, skip this step.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#example-5-universal-trigger","level":3,"title":"Example 5: Universal Trigger","text":"
    # Bad\nUse at the start of every interaction.\n
    # Fixed\nUse after modifying code that affects authentication or persistence.\n
    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-04-skills-that-fight-the-platform/#the-meta-lesson","level":2,"title":"The Meta-Lesson","text":"

    The system prompt is infrastructure:

    • tested,
    • refined,
    • and maintained

    by the platform team.

    Custom skills are configuration layered on top.

    • Good configuration extends infrastructure.
    • Bad configuration fights it.

    When your skills fight the platform, you get the worst of both worlds:

    Diluted system guidance and inconsistent custom behavior.

    Write skills that teach the AI what it doesn't know. Don't rewrite how it thinks.

    Your AI already has good instincts.

    Give it knowledge, not therapy.

    ","path":["Skills That Fight the Platform"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/","level":1,"title":"You Can't Import Expertise","text":"","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#why-good-skills-cant-be-copy-pasted","level":2,"title":"Why Good Skills Can't Be Copy-Pasted","text":"

    Jose Alekhinne / 2026-02-05

    Have You Ever Dropped a Well-Crafted Template Into a Project and Had It Do... Nothing Useful?

    • The template was thorough,
    • The structure was sound,
    • The advice was correct...

    ...and yet it sat there, inert, while the same old problems kept drifting in.

    I found a consolidation skill online.

    It was well-organized: four files, ten refactoring patterns, eight analysis dimensions, six report templates.

    Professional. Comprehensive. Exactly the kind of thing you'd bookmark and think \"I'll use this.\"

    Then I stopped, and applied ctx's own evaluation framework:

    70% of it was noise!

    This post is about why.

    It Is About Encoding Templates

    Templates describe categories of problems.

    Expertise encodes which problems actually happen, and how often.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-skill-looked-great-on-paper","level":2,"title":"The Skill Looked Great on Paper","text":"

    Here is what the consolidation skill offered:

    File Content SKILL.md Entry point: 8 analysis dimensions, workflow, output formats analysis-dimensions.md Detailed criteria for duplication, architecture, quality consolidation-patterns.md 10 refactoring patterns with before/after code report-templates.md 6 output templates: executive summary, roadmap, onboarding
    • It had a scoring system (0-10 per dimension, letter grades A+ through F).
    • It had severity classifications with color-coded emojis. It had bash commands for detection.
    • It even had antipattern warnings.

    By any standard template review, this skill passes.

    It looks like something an expert wrote.

    And that's exactly the trap.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#applying-ear-the-70-20-10-split","level":2,"title":"Applying E/A/R: The 70-20-10 Split","text":"

    In a previous post, I described the E/A/R framework for evaluating skills:

    • Expert: Knowledge that took years to learn. Keep.
    • Activation: Useful triggers or scaffolding. Keep if lightweight.
    • Redundant: Restates what the AI already knows. Delete.

    Target: >70% Expert, <10% Redundant.

    This skill scored the inverse.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-redundant-70","level":3,"title":"What Was Redundant (~70%)","text":"

    Every code example was Rust. My project is Go.

    The analysis dimensions: duplication detection, architectural structure, code organization, refactoring opportunities... These are things Claude already does when you ask it to review code.

    The skill restated them with more ceremony but no more insight.

    The six report templates were generic scaffolding: Executive Summary, Onboarding Document, Architecture Documentation...

    They are useful if you are writing a consulting deliverable, but not when you are trying to catch convention drift in a >15K-line Go CLI.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-does-a-b-in-code-organization-actually-mean","level":2,"title":"What Does a B+ in Code Organization Actually Mean?!","text":"

    The scoring system (0-10 per dimension, letter grades) added ceremony without actionable insight.

    What is a B+? What do I do differently for an A-?

    The skill told the AI what it already knew, in more words.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-activation-10","level":3,"title":"What Was Activation (~10%)","text":"

    The consolidation checklist (semantics preserved? tests pass? docs updated?) was useful as a gate. But, it's the kind of thing you could inline in three lines.

    The phased roadmap structure was reasonable scaffolding for sequencing work.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-was-expert-20","level":3,"title":"What Was Expert (~20%)","text":"

    Three concepts survived:

    1. The Consolidation Decision Matrix: A concrete framework mapping similarity level and instance count to action. \"Exact duplicate, 2+ instances: consolidate immediately.\" \"<3 instances: leave it: duplication is cheaper than wrong abstraction.\" This is the kind of nuance that prevents premature generalization.

    2. The Safe Migration Pattern: Create the new API alongside old, deprecate, migrate incrementally, delete. Straightforward to describe, yet forgettable under pressure.

    3. Debt Interest Rate framing: Categorizing technical debt by how fast it compounds (security vulns = daily, missing tests = per-change, doc gaps = constant low cost). This changes prioritization.

    Three ideas out of four files and 700+ lines. The rest was filler that competed with the AI's built-in capabilities.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-the-skill-didnt-know","level":2,"title":"What the Skill Didn't Know","text":"

    AI Without Context is Just a Corpus

    • LLMs are optimized on insanely large corpora.
    • And then they are passed through several layers of human-assisted refinement.
    • The whole process costs millions of dollars.

    Yet, the reality is that no corpus can \"infer\" your project's design, convetions, patterns, habits, history, vision, and deliverables.

    Your project is unique: So should your skills be.

    Here is the part no template can provide:

    ctx's actual drift patterns.

    Before evaluating the skill, I did archaeology. I read through:

    • Blog posts from previous refactoring sessions;
    • The project's learnings and decisions files;
    • Session journals spanning weeks of development.

    What I found was specific:

    Drift Pattern Where How Often Is/Has/Can predicate prefixes 5+ exported methods Every YOLO sprint Magic strings instead of constants 7+ files Gradual accumulation Hardcoded file permissions (0755) 80+ instances Since day one Lines exceeding 80 characters Especially test files Every session Duplicate code blocks Test and non-test code When agent is task-focused

    The generic skill had no check for any of these. It couldn't; because these patterns are specific to this project's conventions, its Go codebase, and its development rhythm.

    The Insight

    The skill's analysis dimensions were about categories of problems.

    What I needed was my *specific problems.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-adapted-skill","level":2,"title":"The Adapted Skill","text":"

    The adapted skill is roughly a quarter of the original's size. It has nine checks, each targeting a known drift pattern:

    1. Predicate naming: rg for Is/Has/Can prefixes
    2. Magic strings: literals that should be constants
    3. Hardcoded permissions: 0755/0644 literals
    4. File size: source files over 300 LOC
    5. TODO/FIXME: constitution violation (move to TASKS.md)
    6. Path construction: string concatenation instead of filepath.Join
    7. Line width: lines exceeding ~80 characters
    8. Duplicate blocks: copy-paste drift, especially in tests

    9. Dead exports: unused public API

    10. Every check has a detection command.

    11. Every check maps to a specific convention or constitution rule.
    12. Every check was discovered through actual project history; not invented from a template.

    The three expert concepts from the original survived:

    • The decision matrix gates when to consolidate vs. when to leave duplication alone;
    • The safe migration pattern guides public API changes;
    • The relationship to other skills (/qa, /verify, /update-docs, ctx drift) prevents overlap.

    Nothing else made it.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-deeper-pattern","level":2,"title":"The Deeper Pattern","text":"

    This experience crystallized something I've been circling for weeks:

    You can't import expertise. You have to grow it from your project's own history.

    A skill that says \"check for code duplication\" is not expertise: It's a category.

    Expertise is knowing, in the heart of your hearts, that this project accumulates Is* predicate violations during velocity sprints, that this codebase has 80 hardcoded permission literals because nobody made a constant, that this team's test files drift wide because the agent prioritizes getting the task done over keeping the code in shape.

    The Parallel to the 3:1 Ratio

    In Refactoring with Intent, I described the 3:1 ratio: three YOLO sessions followed by one consolidation session.

    The same ratio applies to skills: you need experience in the project before you can write effective guidance for the project.

    Importing a skill on day one is like scheduling a consolidation session before you've written any code.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-template-trap","level":2,"title":"The Template Trap","text":"

    Templates are seductive because they feel like progress:

    • You found something
    • It's well-organized
    • It covers the topic
    • It has concrete examples

    But coverage is not relevance.

    A template that covers eight analysis dimensions with Rust examples adds zero value to a Go project with five known drift patterns. Worse, it adds negative value: the AI spends attention defending generic advice instead of noticing project-specific drift.

    This is the attention budget problem again. Every token of generic guidance displaces a token of specific guidance. A 700-line skill that's 70% redundant doesn't just waste 490 lines: it dilutes the 210 lines that matter.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#the-litmus-test","level":2,"title":"The Litmus Test","text":"

    Before dropping any external skill into your project:

    1. Run E/A/R: What percentage is expert knowledge vs. what the AI already knows? If it's less than 50% expert, it's probably not worth the attention cost.

    2. Check the language: Does it use your stack? Generic patterns in the wrong language are noise, not signal.

    3. List your actual drift: Read your own session history, learnings, and post-mortems. What breaks in practice? Does the skill check for those things?

    4. Measure by deletion: After adaptation, how much of the original survives? If you're keeping less than 30%, you would have been faster writing from scratch.

    5. Test against your conventions: Does every check in the skill map to a specific convention or rule in your project? If not, it's generic advice wearing a skill's clothing.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-05-you-cant-import-expertise/#what-good-adaptation-looks-like","level":2,"title":"What Good Adaptation Looks Like","text":"

    The consolidation skill went from:

    Before After 4 files, 700+ lines 1 file, ~120 lines Rust examples Go-specific rg commands 8 generic dimensions 9 project-specific checks 6 report templates 1 focused output format Scoring system (A+ to F) Findings + priority + suggested fixes \"Check for duplication\" \"Check for Is* predicate prefixes in exported methods\"

    The adapted version is smaller, faster to parse, and catches the things that actually drift in this project.

    That's the difference between a template and a tool.

    If You Remember One Thing From This Post...

    Frameworks travel. Expertise doesn't.

    You can import structures, matrices, and workflows.

    But the checks that matter only grow where the scars are:

    • the conventions that were violated,
    • the patterns that drifted,
    • and the specific ways this codebase accumulates debt.

    This post was written during a consolidation session where the consolidation skill itself became the subject of consolidation. The meta continues.

    ","path":["You Can't Import Expertise"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/","level":1,"title":"The Anatomy of a Skill That Works","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism. References to ctx-save, ctx session, and .context/sessions/ in this post reflect the architecture at the time of writing.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#what-20-skill-rewrites-taught-me-about-guiding-ai","level":2,"title":"What 20 Skill Rewrites Taught Me About Guiding AI","text":"

    Jose Alekhinne / 2026-02-07

    Why do some skills produce great results while others get ignored or produce garbage?

    I had 20 skills. Most were well-intentioned stubs: a description, a command to run, and a wish for the best.

    Then I rewrote all of them in a single session. This is what I learned.

    In Skills That Fight the Platform, I described what skills should not do. In You Can't Import Expertise, I showed why templates fail. This post completes the trilogy: the concrete patterns that make a skill actually work.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-starting-point","level":2,"title":"The Starting Point","text":"

    Here is what a typical skill looked like before the rewrite:

    ---\nname: ctx-save\ndescription: \"Save session snapshot.\"\n---\n\nSave the current context state to `.context/sessions/`.\n\n## Execution\n\nctx session save $ARGUMENTS\n\nReport the saved session file path to the user.\n

    Seven lines of body. A vague description. No guidance on when to use it, when not to, what the command actually accepts, or how to tell if it worked.

    As a result, the agent would either never trigger the skill (the description was too vague), or trigger it and produce shallow output (no examples to calibrate quality).

    A skill without boundaries is just a suggestion.

    More precisely: the most effective boundary I found was a quality gate that runs before execution, not during it.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-pattern-that-emerged","level":2,"title":"The Pattern That Emerged","text":"

    After rewriting 20 skills, a repeatable anatomy emerged (independent of the skill's purpose). Not every skill needs every section, but the effective ones share the same bones:

    Section What It Does Before X-ing Pre-flight checks; prevents premature execution When to Use Positive triggers; narrows activation When NOT to Use Negative triggers; prevents misuse Usage Examples Invocation patterns the agent can pattern-match Process/Execution What to do; commands, steps, flags Good/Bad Examples Desired vs undesired output; sets boundaries Quality Checklist Verify before claiming completion

    I realized the first three sections matter more than the rest; because a skill with great execution steps but no activation guidance is like a manual for a tool nobody knows they have.

    Anti-Pattern: The Perfect Execution Trap

    A skill with detailed execution steps but no activation guidance will fail more often than a vague skill because it executes confidently at the wrong time.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-1-quality-gates-prevent-premature-execution","level":2,"title":"Lesson 1: Quality Gates Prevent Premature Execution","text":"

    The single most impactful addition was a \"Before X-ing\" section at the top of each skill. Not process steps; pre-flight checks.

    ## Before Recording\n\n1. **Check if it belongs here**: is this learning specific\n   to this project, or general knowledge?\n2. **Check for duplicates**: search LEARNINGS.md for similar\n   entries\n3. **Gather the details**: identify context, lesson, and\n   application before recording\n
    • Without this gate, the agent would execute immediately on trigger.
    • With it, the agent pauses to verify preconditions.

    The difference is dramatic: instead of shallow, reflexive execution, you get considered output.

    Readback

    For the astute readers, the aviation parallel is intentional:

    Pilots do not skip the pre-flight checklist because they have flown before.

    The checklist exists precisely because the stakes are high enough that \"I know what I'm doing\" is not sufficient.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-2-when-not-to-use-is-not-optional","level":2,"title":"Lesson 2: \"When NOT to Use\" Is Not Optional","text":"

    Every skill had a \"When to Use\" section. Almost none had \"When NOT to Use\". This is a problem.

    AI agents are biased toward action. Given a skill that says \"use when journal entries need enrichment\", the agent will find reasons to enrich.

    Without explicit negative triggers, over-activation is not a bug; it is the default behavior.

    Some examples of negative triggers that made a real difference:

    Skill Negative Trigger ctx-reflect \"When the user is in flow; do not interrupt\" ctx-save \"After trivial changes; a typo does not need a snapshot\" prompt-audit \"Unsolicited; only when the user invokes it\" qa \"Mid-development when code is intentionally incomplete\"

    These are not just nice-to-have. They are load-bearing.

    Withoutthem, the agent will trigger the skill at the wrong time, produce unwanted output, and erode the user's trust in the skill system.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-3-examples-set-boundaries-better-than-rules","level":2,"title":"Lesson 3: Examples Set Boundaries Better Than Rules","text":"

    The most common failure mode of thin skills was not wrong behavior but vague behavior. The agent would do roughly the right thing, but at a quality level that required human cleanup.

    Rules like \"be constructive, not critical\" are too abstract. What does \"constructive\" look like in a prompt audit report? The agent has to guess.

    Good/bad example pairs avoid guessing:

    ### Good Example\n\n> This session implemented the cooldown mechanism for\n> `ctx agent`. We discovered that `$PPID` in hook context\n> resolves to the Claude Code PID.\n>\n> I'd suggest persisting:\n> - **Learning**: `$PPID` resolves to Claude Code PID\n>   `ctx add learning --context \"...\" --lesson \"...\"`\n> - **Task**: mark \"Add cooldown\" as done\n\n### Bad Examples\n\n* \"*We did some stuff. Want me to save it?*\"\n* Listing 10 trivial learnings that are general knowledge\n* Persisting without asking the user first\n

    The good example shows the exact format, level of detail, and command syntax. The bad examples show where the boundary is.

    Together, they define a quality corridor without prescribing every word.

    Rules describe. Examples demonstrate.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-4-skills-are-read-by-agents-not-humans","level":2,"title":"Lesson 4: Skills Are Read by Agents, Not Humans","text":"

    This seems obvious, but it has non-obvious consequences. During the rewrite, one skill included guidance that said \"use a blog or notes app\" for general knowledge that does not belong in the project's learnings file.

    The agent does not have a notes app. It does not browse the web to find one. This instruction, clearly written for a human audience, was dead weight in a skill consumed by an AI.

    Skills are for the Agents

    Every sentence in a skill should be actionable by the agent.

    If the guidance requires human judgment or human tools, it belongs in documentation, not in a skill.

    The corollary: command references must be exact.

    A skill that says \"save it somewhere\" is useless.

    A skill that says ctx add learning --context \"...\" --lesson \"...\" --application \"...\" is actionable.

    The agent can pattern-match and fill in the blanks.

    Litmus test: If a sentence starts with \"you could...\" or assumes external tools, it does not belong in a skill.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-5-the-description-field-is-the-trigger","level":2,"title":"Lesson 5: The Description Field Is the Trigger","text":"

    This was covered in Skills That Fight the Platform, but the rewrite reinforced it with data. Several skills had good bodies but vague descriptions:

    # Before: vague, activates too broadly or not at all\ndescription: \"Show context summary.\"\n\n# After: specific, activates at the right time\ndescription: \"Show context summary. Use at session start or\n  when unclear about current project state.\"\n

    The description is not a title. It is the activation condition.

    The platform's skill matching reads this field to decide whether to surface the skill. A vague description means the skill either never triggers or triggers when it should not.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-6-flag-tables-beat-prose","level":2,"title":"Lesson 6: Flag Tables Beat Prose","text":"

    Most skills wrap CLI tools. The thin versions described flags in prose, if at all. The rewritten versions use tables:

    | Flag        | Short | Default | Purpose                  |\n|-------------|-------|---------|--------------------------|\n| `--limit`   | `-n`  | 20      | Maximum sessions to show |\n| `--project` | `-p`  | \"\"      | Filter by project name   |\n| `--full`    |       | false   | Show complete content    |\n

    Tables are scannable, complete, and unambiguous.

    The agent can read them faster than parsing prose, and they serve as both reference and validation: If the agent invokes a flag not in the table, something is wrong.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#lesson-7-template-drift-is-a-real-maintenance-burden","level":2,"title":"Lesson 7: Template Drift Is a Real Maintenance Burden","text":"

    // TODO: this has changed; we deploy from the marketplace; update it. // at least add an admonition saying thing are different now.

    ctx deploys skills through templates (via ctx init). Every skill exists in two places: the live version (.claude/skills/) and the template (internal/assets/claude/skills/).

    They must match.

    During the rewrite, every skill update required editing both files and running diff to verify. This sounds trivial, but across 16 template-backed skills, it was the most error-prone part of the process.

    Template drift is dangerous because it creates false confidence: the agent appears to follow rules that no longer exist.

    The lesson: if your skills have a deployment mechanism, build the drift check into your workflow. We added a row to the update-docs skill's mapping table specifically for this:

    | `internal/assets/claude/skills/` | `.claude/skills/` (live) |\n

    Intentional differences (like project-specific scripts in the live version but not the template) should be documented, not discovered later as bugs.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-rewrite-scorecard","level":2,"title":"The Rewrite Scorecard","text":"Metric Before After Average skill body ~15 lines ~80 lines Skills with quality gate 0 20 Skills with \"When NOT\" 0 20 Skills with examples 3 20 Skills with flag tables 2 12 Skills with checklist 0 20

    More lines, but almost entirely Expert content (per the E/A/R framework). No personality roleplay, no redundant guidance, no capability lists. Just project-specific knowledge the platform does not have.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-07-the-anatomy-of-a-skill-that-works/#the-meta-lesson","level":2,"title":"The Meta-Lesson","text":"

    The previous two posts argued that skills should provide knowledge, not personality; that they should complement the platform, not fight it; that they should grow from project history, not imported templates.

    This post adds the missing piece: structure.

    A skill without a structure is a wish.

    A skill with quality gates, negative triggers, examples, and checklists is a tool: the difference is not the content; it is whether the agent can reliably execute it without human intervention.

    Skills are Interfaces

    Good skills are not instructions. They are contracts.:

    • They specify preconditions, postconditions, and boundaries.
    • They show what success looks like and what failure looks like.
    • They trust the agent's intelligence but do not trust its assumptions.

    If You Remember One Thing From This Post...

    Skills that work have bones, not just flesh.

    Quality gates, negative triggers, examples, and checklists are the skeleton. The domain knowledge is the muscle.

    Without the skeleton, the muscle has nothing to attach to.

    This post was written during the same session that rewrote all 22 skills. The skill-creator skill was updated to encode these patterns. The meta continues.

    ","path":["The Anatomy of a Skill That Works"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/","level":1,"title":"Not Everything Is a Skill","text":"

    Update (2026-02-11)

    As of v0.4.0, ctx consolidated sessions into the journal mechanism. References to /ctx-save, .context/sessions/, and session auto-save in this post reflect the architecture at the time of writing.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#what-a-codebase-audit-taught-me-about-restraint","level":2,"title":"What a Codebase Audit Taught Me About Restraint","text":"

    Jose Alekhinne / 2026-02-08

    When You Find a Useful Prompt, What Do You Do With It?

    My instinct was to make it a skill.

    I had just spent three posts explaining how to build skills that work. Naturally, the hammer wanted nails.

    Then I looked at what I was holding and realized: this is not a nail.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-audit","level":2,"title":"The Audit","text":"

    I wanted to understand how I use ctx:

    • Where the friction is;
    • What works, what drifts;
    • What I keep doing manually that could be automated.

    So I wrote a prompt that spawned eight agents to analyze the codebase from different angles:

    Agent Analysis 1 Extractable patterns from session history 2 Documentation drift (godoc, inline comments) 3 Maintainability (large functions, misplaced code) 4 Security review (CLI-specific surface) 5 Blog theme discovery 6 Roadmap and value opportunities 7 User-facing documentation gaps 8 Agent team strategies for future sessions

    The prompt was specific:

    • read-only agents,
    • structured output format,
    • concrete file references,
    • ranked recommendations.

    It ran for about 20 minutes and produced eight Markdown reports.

    The reports were good: Not perfect, but actionable.

    What mattered was not the speed. It was that the work could be explored without committing to any single outcome.

    They surfaced a stale doc.go referencing a subcommand that was never built.

    They found 311 build-then-test sequences I could reduce to a single make check.

    They identified that 42% of my sessions start with \"do you remember?\", which is a lot of repetition for something a skill could handle.

    I had findings. I had recommendations. I had the instinct to automate.

    And then... I stopped.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-question","level":2,"title":"The Question","text":"

    The natural next step was to wrap the audit prompt as /ctx-audit: a skill you invoke periodically to get a health check. It fits the pattern:

    • It has a clear trigger.
    • It produces structured output.

    But I had just spent a week writing about what makes skills work, and the criteria I established argued against it.

    From The Anatomy of a Skill That Works:

    \"A skill without boundaries is just a suggestion.\"

    From You Can't Import Expertise:

    \"Frameworks travel, expertise doesn't.\"

    From Skills That Fight the Platform:

    \"You are the guest, not the host.\"

    The audit prompt fails all three tests:

    Criterion Audit prompt Good skill Frequency Quarterly, maybe Daily or weekly Stability Tweaked every time Consistent invocation Scope Bespoke, 8 parallel agents Single focused action Trigger \"I feel like auditing\" Clear, repeatable event

    Skills are contracts. Contracts need stable terms.

    A prompt I will rewrite every time I use it is not a contract. It is a conversation starter.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#recipes-vs-skills","level":2,"title":"Recipes vs Skills","text":"

    The distinction that emerged:

    Skill Recipe Invocation /slash-command Copy-paste from a doc Frequency High (daily, weekly) Low (quarterly, ad hoc) Stability Fixed contract Adapted each time Scope One focused action Multi-step orchestration Audience The agent The human (who then prompts) Lives in .claude/skills/ hack/ or docs/ Attention cost Loaded into context on match Zero until needed

    Recipes can later graduate into skills, but only after repetition proves stability.

    That last row matters. Skills consume the attention budget every time the platform considers activating them.

    A skill that triggers quarterly but gets evaluated on every prompt is pure waste: attention spent on something that will say \"When NOT to Use: now\" 99% of the time.

    Runbooks have zero attention cost. They sit in a Markdown file until a human decides to use them.

    • The human provides the judgment about timing.
    • The prompt provides the structure.

    The Attention Budget Applies to Skills Too

    Every skill in .claude/skills/ is a standing claim on the context window. The platform evaluates skill descriptions against every user prompt to decide whether to activate.

    Twenty focused skills are fine. Thirty might be fine. But each one added reduces the headroom available for actual work.

    Recipes are skills that opted out of the attention tax.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#what-the-audit-actually-produced","level":2,"title":"What the Audit Actually Produced","text":"

    The audit was not wasted. It was a planning exercise that generated concrete tasks:

    Finding Action 42% of sessions start with memory check Task: /ctx-remember skill (this one is a skill; it is daily) Auto-save stubs are empty Task: enhance /ctx-save with richer summaries 311 raw build-test sequences Task: make check target Stale recall/doc.go lists nonexistent serve Task: fix the doc.go 120 commit sequences disconnected from context Task: /ctx-commit workflow
    • Some findings became skills;
    • Some became Makefile targets;
    • Some became one-line doc fixes.

    The audit did not prescribe the artifact type: The findings did.

    The audit is the input. Skills are one possible output. Not the only one.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-audit-prompt","level":2,"title":"The Audit Prompt","text":"

    Here is the exact prompt I used, for those who are curious.

    This is not a template: It worked because it was written against this codebase, at this moment, with specific goals in mind:

    I want you to create an agent team to audit this codebase. Save each report as\na separate Markdown file under `./ideas/` (or another directory if you prefer).\n\nUse read-only agents (subagent_type: Explore) for all analyses. No code changes.\n\nFor each report, use this structure:\n- Executive Summary (2-3 sentences + severity table)\n- Findings (grouped, with file:line references)\n- Ranked Recommendations (high/medium/low priority)\n- Methodology (what was examined, how)\n\nKeep reports actionable. Every finding should suggest a concrete fix or next step.\n\n## Analyses to Run\n\n### 1. Extractable Patterns (*session mining*)\nSearch session JSONL files, journal entries, and task archives for repetitive\nmulti-step workflows. Count frequency of bash command sequences, slash command\nusage, and recurring user prompts. Identify patterns that could become skills\nor scripts. Cross-reference with existing skills to find coverage gaps.\nOutput: ranked list of automation opportunities with frequency data.\n\n### 2. Documentation Drift (*godoc + inline*)\nCompare every doc.go against its package's actual exports and behavior. Check\ninline godoc comments on exported functions against their implementations.\nScan for stale TODO/FIXME/HACK comments. Check that package-level comments match\npackage names.\nOutput: drift items ranked by severity with exact file:line references.\n\n### 3. Maintainability\nLook for:\n- functions longer than 80 lines with clear split points\n- switch blocks with more than 5 cases that could be table-driven\n- inline comments like \"step 1\", \"step 2\" that indicate a block wants to be a function\n- files longer than 400 lines\n- flat packages that could benefit from sub-packages\n- functions that appear misplaced in their file\n\nDo NOT flag things that are fine as-is just because they could theoretically\nbe different.\nOutput: concrete refactoring suggestions, not style nitpicks.\n\n### 4. Security Review\nThis is a CLI app. Focus on CLI-relevant attack surface, not web OWASP:\n- file path traversal\n- command injection\n- symlink following when writing to `.context/`\n- permission handling\n- sensitive data in outputs\n\nOutput: findings with severity ratings and plausible exploit scenarios.\n\n### 5. Blog Theme Discovery\nRead existing blog posts for style and narrative voice. Analyze git history,\nrecent session discussions, and `DECISIONS.md` for story arcs worth writing about.\nSuggest 3-5 blog post themes with:\n- title\n- angle\n- target audience\n- key commits or sessions to reference\n- a 2-sentence pitch\n\nPrioritize themes that build a coherent narrative across posts.\n\n### 6. Roadmap and Value Opportunities\nBased on current features, recent momentum, and gaps found in other analyses,\nidentify the highest-value improvements. Consider user-facing features,\ndeveloper experience, integration opportunities, and low-hanging fruit.\nOutput: prioritized list with rough effort and impact estimates.\n\n### 7. User-Facing Documentation\nEvaluate README, help text, and user docs. Suggest improvements structured as\nuse-case pages: the problem, how ctx solves it, a typical workflow, and gotchas.\nIdentify gaps where a user would get stuck without reading source code.\nOutput: documentation gaps with suggested page outlines.\n\n### 8. Agent Team Strategies\nBased on the codebase structure, suggest 2-3 agent team configurations for\nupcoming work sessions. For each, include:\n- team composition (roles and agent types)\n- task distribution strategy\n- coordination approach\n- the kinds of work it suits\n

    Avoid Generic Advice

    Suggestions that are not grounded in a project's actual structure, history, and workflows are worse than useless:

    They create false confidence.

    If an analysis cannot point to concrete files, commits, sessions, or patterns, it should say \"no finding\" instead of inventing best practices.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#the-deeper-pattern","level":2,"title":"The Deeper Pattern","text":"

    This is part of a pattern I keep rediscovering:

    The urge to automate is not the same as the need to automate:

    • The 3:1 ratio taught me that not every session should be a YOLO sprint.
    • The E/A/R framework taught me that not every template is worth importing. Now the audit is teaching me that not every useful prompt is worth institutionalizing.

    The common thread is restraint:

    • Knowing when to stop.
    • Recognizing that the cost of automation is not just the effort to build it.

    The cost is the ongoing attention tax of maintaining it, the context it consumes, and the false confidence it creates when it drifts.

    An entry in hack/runbooks/codebase-audit.md is honest about what it is:

    A prompt I wrote once, improved once, and will adapt again next time:

    • It does not pretend to be a reliable contract.
    • It does not claim attention budget.
    • It does not drift silently.

    The Automation Instinct

    When you find a useful prompt, the instinct is to institutionalize it. Resist.

    Ask first: will I use this the same way next time?

    If yes, it is a skill. If no, it is a recipe. If you are not sure, it is a recipe until proven otherwise.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-08-not-everything-is-a-skill/#this-mindset-in-the-context-of-ctx","level":2,"title":"This Mindset In the Context of ctx","text":"

    ctx is a tool that gives AI agents persistent memory. Its purpose is automation: reducing the friction of context loading, session recall, decision tracking.

    But automation has boundaries, and knowing where those boundaries are is as important as pushing them forward.

    The skills system is for high-frequency, stable workflows.

    The recipes, the journal entries, the session dumps in .context/sessions/: those are for everything else.

    Not everything needs to be a slash command. Some things are better as Markdown files you read when you need them.

    The goal of ctx is not to automate everything: It is to automate the right things and to make the rest easy to find when you need it.

    If You Remember One Thing From This Post...

    The best automation decision is sometimes not to automate.

    A runbook in a Markdown file costs nothing until you use it.

    A skill costs attention on every prompt, whether it fires or not.

    Automate the daily. Document the periodic. Forget the rest.

    This post was written during the session that produced the codebase audit reports and distilled the prompt into hack/runbooks/codebase-audit.md. The audit generated seven tasks, one Makefile target, and zero new skills. The meta continues.

    See also: Code Is Cheap. Judgment Is Not.: the capstone that threads this post's restraint argument into the broader case for why judgment, not production, is the bottleneck.

    ","path":["Not Everything Is a Skill"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/","level":1,"title":"Defense in Depth: Securing AI Agents","text":"","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#when-markdown-is-not-a-security-boundary","level":2,"title":"When Markdown Is Not a Security Boundary","text":"

    Jose Alekhinne / 2026-02-09

    What Happens When Your AI Agent Runs Overnight and Nobody Is Watching?

    It follows instructions: That is the problem.

    Not because it is malicious. Because it is controllable.

    It follows instructions from context, and context can be poisoned.

    I was writing the autonomous loops recipe for ctx: the guide for running an AI agent in a loop overnight, unattended, working through tasks while you sleep. The original draft had a tip at the bottom:

    Use CONSTITUTION.md for guardrails. Tell the agent \"never delete tests\" and it usually won't.

    Then I read that sentence back and realized: that is wishful thinking.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-realization","level":2,"title":"The Realization","text":"

    CONSTITUTION.md is a Markdown file. The agent reads it at session start alongside everything else in .context/. It is one source of instructions in a context window that also contains system prompts, project files, conversation history, tool outputs, and whatever the agent fetched from the internet.

    An attacker who can inject content into any of those sources can redirect the agent's behavior. And \"attacker\" does not always mean a person with malicious intent. It can be:

    Vector Example A dependency A malicious npm package with instructions in its README or error output A URL Documentation page with embedded adversarial instructions A project file A contributor who adds instructions to CLAUDE.md or .cursorrules The agent itself In an autonomous loop, the agent modifies its own config between iterations A command output An error message containing instructions the agent interprets and follows

    That last vector is the one that kept me up at night (literally!):

    In an autonomous loop, the agent modifies files as part of its job.

    If it modifies its own configuration files, the next iteration loads the modified config.

    • No human reviews it.
    • No diff is shown.
    • The agent that starts iteration N+1 is running with rules written by iteration N.

    The agent can rewrite its own guardrails.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#five-layers-each-with-a-hole","level":2,"title":"Five Layers, Each With a Hole","text":"

    That's five nested layers of swiss cheese. Alone, each of them has large holes. Together, they create a boundary.

    What followed was a week of peeling back assumptions:

    Every defenseI examined had a bypass, and the bypass was always the same shape: the defense was enforced at a level the agent could reach.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-1-soft-instructions-probabilistic","level":3,"title":"Layer 1: Soft Instructions (Probabilistic)","text":"

    CONSTITUTION.md, the Agent Playbook, system prompts: These tell the agent what to do.

    The agent usually follows them.

    \"Usually\" is the keyword here.

    The hole: Prompt injection:

    • A sufficiently crafted payload overrides soft instructions.
    • Long context windows dilute attention on rules stated early.
    • Edge cases where instructions are ambiguous get resolved in unpredictable ways.

    Verdict: Necessary. Not sufficient. Good for the common case. Never trust it as a security boundary.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-2-application-controls-deterministic-at-runtime-mutable-across-iterations","level":3,"title":"Layer 2: Application Controls (Deterministic at Runtime, Mutable Across Iterations)","text":"

    Permission allowlists in .claude/settings.local.json:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(make:*)\",\n      \"Bash(go:*)\",\n      \"Bash(git:*)\",\n      \"Read\",\n      \"Write\",\n      \"Edit\"\n    ]\n  }\n}\n

    If rm, curl, sudo, or docker are not in the allowlist, the agent cannot invoke them. This is deterministic.

    The application enforces it regardless of what any prompt says.

    The hole: The agent can modify the allowlist itself:

    • It has Write permission.
    • The allowlist lives in a file.
    • The agent writes to the file.
    • The next iteration loads the modified allowlist.

    The application enforces the rules, but the application reads the rules from files the agent can write.

    Verdict: Strong first layer. Must be combined with self-modification prevention.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-3-os-level-isolation-unbypassable","level":3,"title":"Layer 3: OS-Level Isolation (Unbypassable)","text":"

    This is where the defenses stop having holes in the same shape.

    The operating system enforces access controls that no application-level trick can override. An unprivileged user cannot read files owned by root. A process without CAP_NET_RAW cannot open raw sockets. These are kernel boundaries.

    Control What it stops Dedicated unprivileged user Privilege escalation, sudo, group-based access Filesystem permissions Lateral movement to other projects, system config Immutable config files Self-modification of guardrails between iterations

    Make the agent's instruction files read-only: CLAUDE.md, .claude/settings.local.json, .context/CONSTITUTION.md. Own them as a different user, or mark them immutable with chattr +i on Linux.

    The hole: Actions within the agent's legitimate scope:

    • If the agent has write access to source code (which it needs), it can introduce vulnerabilities in the code itself.
    • You cannot prevent this without removing the agent's ability to do its job.

    Verdict: Essential. This is the layer that makes Layers 1 and 2 trustworthy.

    OS-level isolation does not make the agent safe; it makes the other layers meaningful.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-4-network-controls","level":3,"title":"Layer 4: Network Controls","text":"

    An agent that cannot reach the internet cannot exfiltrate data.

    It also cannot ingest new instructions mid-loop from external documents, error pages, or hostile content.

    # Container with no network\ndocker run --network=none ...\n\n# Or firewall rules allowing only package registries\niptables -A OUTPUT -d registry.npmjs.org -j ACCEPT\niptables -A OUTPUT -d proxy.golang.org -j ACCEPT\niptables -A OUTPUT -j DROP\n
    • If the agent genuinely does not need the network, disable it entirely.
    • If it needs to fetch dependencies, allow specific registries and block everything else.

    The hole: None, if the agent does not need the network.

    Thetradeoff is that many real workloads need dependency resolution, so a full airgap requires pre-populated caches.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#layer-5-infrastructure-isolation","level":3,"title":"Layer 5: Infrastructure Isolation","text":"

    The strongest boundary is a separate machine.

    The moment you stop arguing about prompts and start arguing about kernels, you are finally doing security.

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh\n

    Never Mount the Docker Socket

    Do not mount /var/run/docker.sock, like, ever.

    An agent with socket access can spawn sibling containers with full host access, effectively escaping the sandbox.

    This is not theoretical: the Docker socket grants root-equivalent access to the host.

    Use rootless Docker or Podman to eliminate this escalation path entirely.

    Virtual machines are even stronger: The guest kernel has no visibility into the host OS. No shared folders, no filesystem passthrough, no SSH keys to other machines.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-pattern","level":2,"title":"The Pattern","text":"

    Each layer is straightforward: The strength is in the combination:

    Layer Implementation What it stops Soft instructions CONSTITUTION.md Common mistakes (probabilistic) Application allowlist .claude/settings.local.json Unauthorized commands (deterministic within runtime) Immutable config chattr +i on config files Self-modification between iterations Unprivileged user Dedicated user, no sudo Privilege escalation Container --cap-drop=ALL --network=none Host escape, data exfiltration Resource limits --memory=4g --cpus=2 Resource exhaustion

    No layer is redundant. Each one catches what the others miss:

    • The soft instructions handle the 99% case: \"don't delete tests.\"
    • The allowlist prevents the agent from running commands it should not.
    • The immutable config prevents the agent from modifying the allowlist.
    • The unprivileged user prevents the agent from removing the immutable flag.
    • The container prevents the agent from reaching anything outside its workspace.
    • The resource limits prevent the agent from consuming all system resources.

    Remove any one layer and there is an attack path through the remaining ones.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#common-mistakes-i-see","level":2,"title":"Common Mistakes I See","text":"

    These are real patterns, not hypotheticals:

    \"I'll just use --dangerously-skip-permissions.\" This disables Layer 2 entirely. Without Layers 3 through 5, you have no protection at all. The flag means what it says. If you ever need to, think thrice, you probably don't. But, if you ever need to usee this only use it inside a properly isolated VM (not even a container: a \"VM\").

    \"The agent is sandboxed in Docker.\" A Docker container with the Docker socket mounted, running as root, with --privileged, and full network access is not sandboxed. It is a root shell with extra steps.

    \"I reviewed CLAUDE.md, it's fine.\" You reviewed it before the loop started. The agent modified it during iteration 3. Iteration 4 loaded the modified version. Unless the file is immutable, your review is futile.

    \"The agent only has access to this one project.\" Does the project directory contain .env files? SSH keys? API tokens? A .git/config with push access to a remote? Filesystem isolation means isolating what is in the directory too.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-connection-to-context-engineering","level":2,"title":"The Connection to Context Engineering","text":"

    This is the same lesson I keep rediscovering, wearing different clothes.

    In The Attention Budget, I wrote about how every token competes for the AI's focus. Security instructions in CONSTITUTION.md are subject to the same budget pressure: if the context window is full of code, error messages, and tool outputs, the security rules stated at the top get diluted.

    In Skills That Fight the Platform, I wrote about how custom instructions can conflict with the AI's built-in behavior. Security rules have the same problem: telling an agent \"never run curl\" in Markdown while giving it unrestricted shell access creates a contradiction: The agent resolves contradictions unpredictably. The agent will often pick the path of least resistance to attain its objective function. And, trust me, agents can get far more creative than the best red-teamer you know.

    In You Can't Import Expertise, I wrote about how generic templates fail because they do not encode project-specific knowledge. Generic security advice fails the same way: \"Don't exfiltrate data\" is a category; blocking outbound network access is a control.

    The pattern across all of these: Soft instructions are useful for the common case. Hard boundaries are required for security.

    Know which is which.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#the-checklist","level":2,"title":"The Checklist","text":"

    Before running an unattended AI agent:

    • Agent runs as a dedicated unprivileged user (no sudo, no docker group)
    • Agent's config files are immutable or owned by a different user
    • Permission allowlist restricts tools to the project's toolchain
    • Container drops all capabilities (--cap-drop=ALL)
    • Docker socket is NOT mounted
    • Network is disabled or restricted to specific domains
    • Resource limits are set (memory, CPU, disk)
    • No SSH keys, API tokens, or credentials are accessible
    • Project directory does not contain .env or secrets files
    • Iteration cap is set (--max-iterations)

    This checklist lives in the Agent Security reference alongside the full threat model and detailed guidance for each layer.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-09-defense-in-depth-securing-ai-agents/#what-changed-in-ctx","level":2,"title":"What Changed in ctx","text":"

    The autonomous loops recipe now has a full permissions and isolation section instead of a one-line tip about CONSTITUTION.md. It covers both the explicit allowlist approach and the --dangerously-skip-permissions flag, with honest guidance about when each is appropriate.

    It also has an OS-level isolation table that is not optional: unprivileged users, filesystem permissions, containers, VMs, network controls, resource limits, and self-modification prevention.

    The Agent Security page consolidates the threat model and defense layers into a standalone reference.

    These are not theoretical improvements. They are the minimum responsible guidance for a tool that helps people run AI agents overnight.

    If You Remember One Thing From This Post...

    Markdown is not a security boundary.

    CONSTITUTION.md is a nudge. An allowlist is a gate.

    An unprivileged user in a network-isolated container is a wall.

    Use all three. Trust only the wall.

    This post was written during the session that added permissions, isolation, and self-modification prevention to the autonomous loops recipe. The security guidance started as a single tip and grew into two documents. The meta continues.

    ","path":["Defense in Depth: Securing AI Agents"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/","level":1,"title":"How Deep Is Too Deep?","text":"","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#when-master-ml-is-the-wrong-next-step","level":2,"title":"When \"Master ML\" Is the Wrong Next Step","text":"

    Jose Alekhinne / 2026-02-12

    Have You Ever Felt Like You Should Understand More of the Stack Beneath You?

    You can talk about transformers at a whiteboard.

    You can explain attention to a colleague.

    You can use agentic AI to ship real software.

    But somewhere in the back of your mind, there is a voice:

    \"Maybe I should go deeper. Maybe I need to master machine learning.\"

    I had that voice for months.

    Then I spent a week debugging an agent failure that had nothing to do with ML theory and everything to do with knowing which abstraction was leaking.

    This post is about when depth compounds and (more importantly) when it does not.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-hierarchy-nobody-questions","level":2,"title":"The Hierarchy Nobody Questions","text":"

    There is an implicit stack most people carry around when thinking about AI:

    Layer What Lives Here Agentic AI Autonomous loops, tool use, multi-step reasoning Generative AI Text, image, code generation Deep Learning Transformer architectures, training at scale Neural Networks Backpropagation, gradient descent Machine Learning Statistical learning, optimization Classical AI Search, planning, symbolic reasoning

    At some point down that stack, you hit a comfortable plateau: the layer where you can hold a conversation but not debug a failure.

    The instinctive response is to go deeper.

    But that instinct hides a more important question:

    \"Does depth still compound when the abstractions above you are moving hyper-exponentially?\"

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-honest-observation","level":2,"title":"The Honest Observation","text":"

    If you squint hard enough, a large chunk of modern ML intuition collapses into older fields:

    ML Concept Older Field Gradient descent Numerical optimization Backpropagation Reverse-mode autodiff Loss landscapes Non-convex optimization Generalization Statistics Scaling laws Asymptotics and information theory

    Nothing here is uniquely \"AI\".

    Most of this math predates the term deep learning. In some cases, by decades.

    So what changed?

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#same-tools-different-regime","level":2,"title":"Same Tools, Different Regime","text":"

    The mistake is assuming this is a new theory problem: It is not.

    It is a new operating regime.

    Classical numerical methods were developed under assumptions like:

    • Manageable dimensionality
    • Reasonably well-conditioned objectives
    • Losses that actually represent the goal

    Modern ML violates all three: On purpose.

    Today's models operate with millions to trillions of parameters, wildly underdetermined systems, and objective functions we know are wrong but optimize anyway.

    It is complete and utter madness!

    At this scale, familiar concepts warp:

    • What we call \"local minima\" are overwhelmingly saddle points in high-dimensional spaces.
    • Noise stops being noise and starts becoming structure.
    • Overfitting can coexist with generalization.
    • Bigger models outperform \"better\" ones.

    The math did not change: The phase did.

    This is less numerical analysis and more *statistical physics: Same equations, but behavior dominated by phase transitions and emergent structure.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#why-scaling-laws-feel-alien","level":2,"title":"Why Scaling Laws Feel Alien","text":"

    In classical statistics, asymptotics describe what happens eventually.

    In modern ML, scaling laws describe where you can operate today.

    They do not say \"given enough time, things converge\".

    They say \"cross this threshold and behavior qualitatively changes\".

    This is why dumb architectures plus scale beat clever ones.

    Why small theoretical gains disappear under data.

    Why \"just make it bigger\", ironically, keeps working longer than it should.

    That is not a triumph of ML theory: It is a property of high-dimensional systems under loose objectives.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#where-depth-actually-pays-off","level":2,"title":"Where Depth Actually Pays Off","text":"

    This reframes the original question.

    You do not need depth because this is \"AI\".

    You need depth where failure modes propagate upward.

    I learned this building ctx: The agent failures I have spent the most time debugging were never about the model's architecture.

    They were about:

    • Misplaced trust: The model was confident. The output was wrong. Knowing when confidence and correctness diverge is not something you learn from a textbook. You learn it from watching patterns across hundreds of sessions.

    • Distribution shift: The model performed well on common patterns and fell apart on edge cases specific to this project. Recognizing that shift before it compounds requires understanding why generalization has limits, not just that it does.

    • Error accumulation: In a single prompt, model quirks are tolerable. In autonomous loops running overnight, they compound. A small bias in how the model interprets instructions becomes a large drift by iteration 20.

    • Scale hiding errors: The model's raw capability masked problems that only surfaced under specific conditions. More parameters did not fix the issue. They just made the failure mode rarer and harder to reproduce.

    This is the kind of depth that compounds. Not deriving backprop. But, understanding when correct math produces misleading intuition.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-connection-to-context-engineering","level":2,"title":"The Connection to Context Engineering","text":"

    This is the same pattern I keep finding at different altitudes.

    In \"The Attention Budget\", I wrote about how dumping everything into the context window degrades the model's focus. The fix was not a better model: It was better curation: load less, load the right things, preserve signal per token.

    In \"Skills That Fight the Platform\", I wrote about how custom instructions can conflict with the model's built-in behavior. The fix was not deeper ML knowledge: It was an understanding that the model already has judgment and that you should extend it, not override it.

    In \"You Can't Import Expertise\", I wrote about how generic templates fail because they do not encode project-specific knowledge. A consolidation skill with eight Rust-based analysis dimensions was mostly noise for a Go project. The fix was not a better template: It was growing expertise from this project's own history.

    In every case, the answer was not \"go deeper into ML\".

    The answer was knowing which abstraction was leaking and fixing it at the right layer.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#agentic-systems-are-not-an-ml-problem","level":2,"title":"Agentic Systems Are Not an ML Problem","text":"

    The mistake is assuming agent failures originate where the model was trained, rather than where it is deployed.

    Agentic AI is a systems problem under chaotic uncertainty:

    • Feedback loops between the agent and its environment;
    • Error accumulation across iterations;
    • Brittle representations that break outside training distribution;
    • Misplaced trust in outputs that look correct.

    In short-lived interactions, model quirks are tolerable. In long-running autonomous loops, however, they compound.

    That is where shallow understanding becomes expensive.

    But the understanding you need is not about optimizer internals.

    It is about:

    What Matters What Does Not (for Most Practitioners) Why gradient descent fails in specific regimes How to derive it from scratch When memorization masquerades as reasoning The formal definition of VC dimension Recognizing distribution shift before it compounds Hand-tuning learning rate schedules Predicting when scale hides errors instead of fixing them Chasing theoretical purity divorced from practice

    The depth that matters is diagnostic, not theoretical.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-real-answer","level":2,"title":"The Real Answer","text":"

    Not turtles all the way down.

    Go deep enough to:

    • Diagnose failures instead of cargo-culting fixes;
    • Reason about uncertainty instead of trusting confidence;
    • Design guardrails that align with model behavior, not hope.

    Stop before:

    • Hand-deriving gradients for the sake of it;
    • Obsessing over optimizer internals you will never touch;
    • Chasing theoretical purity divorced from the scale you actually operate at.

    This is not about mastering ML.

    It is about knowing which abstractions you can safely trust and which ones leak.

    Hint: Any useful abstraction almost certainly leaks.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#a-practical-litmus-test","level":2,"title":"A Practical Litmus Test","text":"

    If a failure occurs and your instinct is to:

    • Add more prompt text: abstraction leak above
    • Add retries or heuristics: error accumulation
    • Change the model: scale masking
    • Reach for ML theory: you are probably (but not always) going too deep

    The right depth is the shallowest layer where the failure becomes predictable.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#the-ctx-lesson","level":2,"title":"The ctx Lesson","text":"

    Every design decision in ctx is downstream of this principle.

    The attention budget exists because the model's internal attention mechanism has real limits: You do not need to understand the math of softmax to build around it. But you do need to understand that more context is not always better and that attention density degrades with scale.

    The skill system exists because the model's built-in behavior is already good: You do not need to understand RLHF to build effective skills. But you do need to understand that the model already has judgment and your skills should teach it things it does not know, not override how it thinks.

    Defense in depth exists because soft instructions are probabilistic: You do not need to understand the transformer architecture to know that a Markdown file is not a security boundary. But you do need to understand that the model follows instructions from context, and context can be poisoned.

    In each case, the useful depth was one or two layers below the abstraction I was working at: Not at the bottom of the stack.

    The boundary between useful understanding and academic exercise is where your failure modes live.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-12-how-deep-is-too-deep/#closing-thought","level":2,"title":"Closing Thought","text":"

    Most modern AI systems do not fail because the math is wrong.

    They fail because we apply correct math in the wrong regime, then build autonomous systems on top of it.

    Understanding that boundary, not crossing it blindly, is where depth still compounds.

    And that is a far more useful form of expertise than memorizing another loss function.

    If You Remember One Thing From This Post...

    Go deep enough to diagnose your failures. Stop before you are solving problems that do not propagate to your layer.

    The abstractions below you are not sacred. But neither are they irrelevant.

    The useful depth is wherever your failure modes live. Usually one or two layers down, not at the bottom.

    This post started as a note about whether I should take an ML course. The answer turned out to be \"no, but understand why not\". The meta continues.

    ","path":["How Deep Is Too Deep?"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/","level":1,"title":"Before Context Windows, We Had Bouncers","text":"","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#the-reset-problem","level":2,"title":"The Reset Problem","text":"

    IRC is stateless.

    • You disconnect, you vanish.
    • You reconnect, you begin again.

    No buffer.

    No memory.

    No continuity.

    Modern systems are not much different:

    • Close the browser tab.
      • Lose the Slack scrollback.
    • Open a new LLM session.
      • Start from zero.

    Resets externalize reconstruction cost onto humans.

    Reconstruction is tax: Tax becomes entropy.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#stateless-protocol-stateful-life","level":2,"title":"Stateless Protocol, Stateful Life","text":"

    IRC is minimal:

    • A TCP connection.
    • A nickname.
    • A channel.
    • A stream of lines.

    When the connection drops, you literally disappear from the graph.

    The protocol is stateless; human systems are not.

    So you:

    • Reconnect;
    • Ask what you missed;
    • Scroll;
    • Reconstruct.

    The machine forgets; you pay.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#the-bouncer-pattern","level":2,"title":"The Bouncer Pattern","text":"

    A bouncer is a daemon that remains connected when you do not:

    • It holds your seat;
    • It buffers what you missed;
    • It keeps your identity online.

    ZNC is one such bouncer.

    With ZNC:

    • Your client does not connect to IRC;
    • It connects to ZNC;
    • ZNC connects upstream.

    Client sessions become ephemeral.

    Presence becomes infrastructural.

    ZNC is tmux for IRC

    • Close your laptop.

      • ZNC remains.

    • Switch devices.

      • ZNC persists.

    This is not convenience; this is continuity.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#presence-without-flapping","level":2,"title":"Presence Without Flapping","text":"

    With a bouncer:

    • Closing your client does not emit PART.
    • Reopening does not emit JOIN.

    You do not flap in and out of existence.

    From the channel's perspective, you remain.

    From your perspective, history accumulates.

    • Buffers persist;
    • Identity persists;
    • Context persists.

    This pattern predates AI.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#before-llm-context-windows","level":2,"title":"Before LLM Context Windows","text":"

    An LLM session without memory is IRC without a bouncer:

    • Close the window.
    • Start over.
    • Re-explain intent.
    • Rehydrate context.

    That is friction.

    This Walks and Talks like ctx

    Context engineering moves memory out of sessions and into infrastructure.

    • ZNC does this for IRC.
    • ctx does this for agents.

    Same principle:

    • Volatile interface.
    • Persistent substrate.

    Different fabric.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#minimal-architecture","level":2,"title":"Minimal Architecture","text":"

    My setup is intentionally boring:

    • A $5 small VPS.
    • ZNC installed.
    • TLS enabled.
    • Firewall restricted.

    Then:

    • ZNC connects to Libera.Chat.
    • SASL authentication lives inside ZNC.
    • Buffers are stored on disk.

    My client connects to my VPS, not the network.

    The commands do not matter: The boundaries do:

    • Authentication in infrastructure, not in the client;
    • Memory server-side, not in scrollback;
    • Presence decoupled from activity.

    Everything else is configuration.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#platform-memory","level":2,"title":"Platform Memory","text":"

    Yes, I know, it is 2026:

    • Discord stores history;
    • Slack stores history;
    • The dumpster fire on gasoline called X, too, stores history.

    HOWEVER, they own your substrate.

    Running a bouncer is quiet sovereignty:

    • Logs are mine.
    • Presence is continuous.
    • State does not reset because I closed a tab.

    Small acts compound.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#signal-density","level":2,"title":"Signal Density","text":"

    Primitive systems select for builders.

    Consistent presence in small rooms compounds reputation.

    Quiet compounding outperforms viral spikes.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#infrastructure-as-cognition","level":2,"title":"Infrastructure as Cognition","text":"

    ZNC is not interesting because it is retro; it is interesting because it models a principle:

    • Stateless protocols require stateful wrappers;
    • Volatile interfaces require durable memory;
    • Human systems require continuity.

    Distilled:

    Humans require context.

    Before context windows, we had bouncers.

    Before AI memory files, we had buffers.

    Continuity is not a feature; it is a design decision.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#build-it","level":2,"title":"Build It","text":"

    If you want the actual setup (VPS, ZNC, TLS, SASL, firewall...) there is a step-by-step runbook:

    Persistent IRC Presence with ZNC.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-irc-as-context/#motd","level":2,"title":"MOTD","text":"

    When my client connects to my bouncer, it prints:

    //   /    ctx:                         https://ctx.ist\n// ,'`./    do you remember?\n// `.,'\\\n//   \\    Copyright 2026-present Context contributors.\n//                 SPDX-License-Identifier: Apache-2.0\n

    See also: Context as Infrastructure -- the post that takes this observation to its conclusion: stateless protocols need stateful wrappers, and AI sessions need persistent filesystems.

    ","path":["Before Context Windows, We Had Bouncers"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/","level":1,"title":"Parallel Agents with Git Worktrees","text":"","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-backlog-problem","level":2,"title":"The Backlog Problem","text":"

    Jose Alekhinne / 2026-02-14

    What Do You Do With 30 Open Tasks?

    You could work through them one at a time.

    One agent, one branch, one commit stream.

    Or you could ask: which of these don't touch each other?

    I had 30 open tasks in TASKS.md. Some were docs. Some were a new encryption package. Some were test coverage for a stable module. Some were blog posts.

    They had almost zero file overlap.

    Running one agent at a time meant serial execution on work that was fundamentally parallel:

    I was bottlenecking on me, not on the machine.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-insight-file-overlap-is-the-constraint","level":2,"title":"The Insight: File Overlap Is the Constraint","text":"

    This is not a scheduling problem: It's a conflict avoidance problem.

    Two agents can work simultaneously on the same codebase if and only if they don't touch the same files. The moment they do, you get merge conflicts: And merge conflicts on AI-generated code are expensive because the human has to arbitrate choices they didn't make.

    So the question becomes:

    \"Can you partition your backlog into non-overlapping tracks?\"

    For ctx, the answer was obvious:

    Track Touches Tasks work/docs docs/, hack/ Blog posts, recipes, runbooks work/pad internal/cli/pad/, specs Scratchpad encryption, CLI, tests work/tests internal/cli/recall/ Recall test coverage

    Three tracks. Near-zero overlap. Three agents.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#git-worktrees-the-mechanism","level":2,"title":"Git Worktrees: The Mechanism","text":"

    git has a feature that most people don't use: worktrees.

    A worktree is a second (or third, or fourth) working directory that shares the same .git object database as your main checkout.

    Each worktree has its own branch, its own index, its own working tree. But they all share history, refs, and objects.

    git worktree add ../ctx-docs -b work/docs\ngit worktree add ../ctx-pad -b work/pad\ngit worktree add ../ctx-tests -b work/tests\n
    • Three directories;
    • Three branches;
    • One repository.

    This is cheaper than three clones. And because they share objects, git merge afterwards is fast: It's a local operation on shared data.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-setup","level":2,"title":"The Setup","text":"

    The workflow I landed on:

    1. Group tasks by blast radius.

    Read TASKS.md. For each pending task, estimate which files and directories it touches. Group tasks that share files into the same track. Tasks with no overlap go into separate tracks.

    This is the part that requires human judgment:

    An agent can propose groupings, but you need to verify that the boundaries are real. A task that says \"update docs\" but actually touches Go code will poison a docs track.

    2. Create worktrees as sibling directories.

    Not subdirectories: Siblings.

    If your main checkout is at ~/WORKSPACE/ctx, worktrees go at ~/WORKSPACE/ctx-docs, ~/WORKSPACE/ctx-pad, etc.

    Why siblings? Because some tools (and some agents) walk up the directory tree looking for .git. A worktree inside the main checkout confuses them.

    3. Launch one agent per worktree.

    # Terminal 1\ncd ../ctx-docs && claude\n\n# Terminal 2\ncd ../ctx-pad && claude\n\n# Terminal 3\ncd ../ctx-tests && claude\n

    Each agent gets a full working copy with .context/ intact. It reads the same TASKS.md, the same DECISIONS.md, the same CONVENTIONS.md. It knows the full project state. It just works on a different slice.

    4. Do NOT run ctx init in worktrees.

    This is the gotcha. The .context/ directory is tracked in git. Running ctx init in a worktree would overwrite shared context files: Wiping decisions, learnings, and tasks that belong to the whole project.

    The worktree already has everything it needs. Leave it alone.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#what-actually-happened","level":2,"title":"What Actually Happened","text":"

    I ran three agents for about 40 minutes. Here is roughly what each track produced:

    work/docs: Parallel worktrees recipe, blog post edits, recipe index reorganization, IRC recipe moved from docs/ to hack/.

    work/pad: ctx pad show subcommand, --append and --prepend flags on ctx pad edit, spec updates, 28 new test functions.

    work/tests: Recall test coverage, edge case tests.

    Merging took about five minutes. Two of the three merges were clean.

    The third had a conflict in TASKS.md:

    both the docs track and the pad track had marked different tasks as [x].

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-tasksmd-conflict","level":2,"title":"The TASKS.md Conflict","text":"

    This deserves its own section because it will happen every time.

    When two agents work in parallel, they both read TASKS.md at the start and mark tasks complete as they go. When you merge, git sees two branches that modified the same file differently.

    The resolution is always the same: accept all completions from both sides. No task should go from [x] back to [ ]. The merge is additive.

    This is one of those conflicts that sounds scary but is trivially mechanical: You are not arbitrating design decisions; you are combining two checklists.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#limits","level":2,"title":"Limits","text":"

    3-4 worktrees, maximum.

    I tried four once: By the time I merged the third track, the fourth had drifted far enough that its changes needed rebasing.

    The merge complexity grows faster than the parallelism benefit.

    Three is the sweet spot:

    • Two is conservative but safe;
    • Four is possible if the tracks are truly independent;
    • Anything more than four, you are in the danger zone.

    Group by directory, not by priority.

    It is tempting to put all the high-priority tasks in one track: Don't.

    Two high-priority tasks that touch the same files must be in the same track, regardless of urgency. The constraint is file overlap, not importance.

    Commit frequently.

    Smaller commits make merge conflicts easier to resolve. An agent that writes 500 lines in a single commit is harder to merge than one that commits every logical step.

    Name tracks by concern.

    • work/docs and work/pad tell you what's happening;
    • work/track-1 and work/track-2 tell you nothing.
    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-pattern","level":2,"title":"The Pattern","text":"

    This is the same pattern that shows up everywhere in ctx:

    The attention budget taught me that you can't dump everything into one context window. You have to partition, prioritize, and load selectively.

    Worktrees are the same principle applied to execution: You can't dump every task into one agent's workstream. You have to partition by blast radius, assign selectively, and merge deliberately.

    The codebase audit that generated these 30 tasks used eight parallel agents for analysis. Worktrees let me use parallel agents for implementation. Same coordination pattern, different artifact.

    And the IRC bouncer post from earlier today argued that stateless protocols need stateful wrappers. Worktrees are the same: git branches are stateless forks; .context/ is the stateful wrapper that gives each agent the project's full memory.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#should-this-be-a-skill","level":2,"title":"Should This Be a Skill?","text":"

    I asked myself the same question I asked about the codebase audit: should this be a /ctx-worktree skill?

    This time the answer was a resounding \"yes\":

    Unlike the audit prompt (which I tweak every time and run every other week) the worktree workflow is:

    Criterion Worktree workflow Codebase audit Frequency Weekly Quarterly Stability Same steps every time Tweaked every time Scope Mechanical, bounded Bespoke, 8 agents Trigger Large backlog \"I feel like auditing\"

    The commands are mechanical: git worktree add, git worktree remove, branch naming, safety checks. This is exactly what skills are for: stable contracts for repetitive operations.

    Ergo, /ctx-worktree exists.

    It enforces the 4-worktree limit, creates sibling directories, uses work/ branch prefixes, and reminds you not to run ctx init in worktrees.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-14-parallel-agents-with-worktrees/#the-takeaway","level":2,"title":"The Takeaway","text":"

    Serial execution is the default. But serial is not always necessary.

    If your backlog partitions cleanly by file overlap, you can multiply your throughput with nothing more exotic than git worktree and a second terminal window.

    The hard part is not the git commands; it is the discipline:

    • Grouping by blast radius instead of priority;
    • Accepting that TASKS.md will conflict;
    • And knowing when three tracks is enough.

    If You Remember One Thing From This Post...

    Partition by blast radius, not by priority.

    Two tasks that touch the same files belong in the same track, no matter how important the other one is.

    The constraint is file overlap. Everything else is scheduling.

    The practical setup (skill invocation, worktree creation, merge workflow, and cleanup) lives in the recipe: Parallel Agent Development with Git Worktrees.

    ","path":["Parallel Agents with Git Worktrees"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/","level":1,"title":"ctx v0.3.0: The Discipline Release","text":"","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#when-the-ratio-of-polish-to-features-is-31-you-know-something-changed","level":2,"title":"When the Ratio of Polish to Features Is 3:1, You Know Something Changed","text":"

    Jose Alekhinne / February 15, 2026

    What Does a Release Look Like When Most of the Work Is Invisible?

    No new headline feature. No architectural pivot. No rewrite.

    Just 35+ documentation and quality commits against ~15 feature commits... and somehow, the tool feels like it grew up overnight.

    Six days separate v0.2.0 from v0.3.0.

    Measured by calendar time, it is nothing. Measured by what changed in how the project operates, it is the most significant release yet.

    • v0.1.0 was the prototype;
    • v0.2.0 was the archaeology release: making the past accessible;
    • v0.3.0 is the discipline release: the one that turned best practices into enforcement, suggestions into structure, and a collection of commands into a system of skills.

    The Release Window

    February 1‒February 7, 2026

    From the v0.2.0 tag to commit 2227f99.

    78 files changed in the migration commit alone.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-migration-commands-to-skills","level":2,"title":"The Migration: Commands to Skills","text":"

    The largest single change was the migration from .claude/commands/*.md to .claude/skills/*/SKILL.md.

    This was not a rename: It was a rethinking of how AI agents discover and execute project-specific workflows.

    Aspect Commands (before) Skills (after) Structure Flat files in one directory Directory-per-skill with SKILL.md Description Optional, often vague Required, doubles as activation trigger Quality gates None \"Before X-ing\" pre-flight checklist Negative triggers None \"When NOT to Use\" in every skill Examples Rare Good/bad pairs in every skill Average length ~15 lines ~80 lines

    The description field became the single most important line in each skill. In the old system, descriptions were titles. In the new system, they are activation conditions: The text the platform reads to decide whether to surface a skill for a given prompt.

    A description that says \"Show context summary\" activates too broadly or not at all. A description that says \"Show context summary. Use at session start or when unclear about current project state\" activates at the right moment.

    78 files changed. 1,915 insertions. Not because the skills got bloated; because they got specific.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-skill-sweep","level":2,"title":"The Skill Sweep","text":"

    After the structural migration, every skill was rewritten in a single session: All 21 of them.

    The rewrite was guided by a pattern that emerged during the process itself: a repeatable anatomy that effective skills share regardless of their purpose:

    1. Before X-ing: Pre-flight checks that prevent premature execution
    2. When to Use: Positive triggers that narrow activation
    3. When NOT to Use: Negative triggers that prevent misuse
    4. Usage Examples: Invocation patterns the agent can pattern-match
    5. Quality Checklist: Verification before claiming completion

    The Anatomy of a Skill That Works post covers the details. What matters for the release story is the result:

    • Zero skills with quality gates became twenty;
    • Zero skills with negative triggers became twenty.
    • Three skills with examples became twenty.

    The Skill Trilogy as Design Spec

    The three blog posts written during this window:

    • Skills That Fight the Platform,
    • You Can't Import Expertise,
    • and The Anatomy of a Skill That Works...

    ... were not retrospective documentation. They were written during the rewrite, and the lessons fed back into the skills as they were being built.

    • The blog was the design document.
    • The skills were the implementation.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-consolidation-sweep","level":2,"title":"The Consolidation Sweep","text":"

    The unglamorous work. The kind you only appreciate when you try to change something later and it just works.

    What Why It Matters Constants consolidation Magic strings replaced with semantic constants Variable deshadowing Eliminated subtle scoping bugs File splits Modules that were doing too much, broken apart Godoc standardization Every exported function documented to convention

    This is the work that doesn't get a changelog entry but makes every future commit easier. When a new contributor (human or AI) reads the codebase, they find consistent patterns instead of accumulated drift.

    The consolidation was not an afterthought. It was scheduled deliberately, with the same priority as features: The 3:1 ratio that emerged during v0.2.0 development became an explicit practice:

    • Three feature sessions;
    • One consolidation session.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-ear-framework","level":2,"title":"The E/A/R Framework","text":"

    On February 4th, we adopted the E/A/R classification as the official standard for evaluating skills:

    Category Meaning Target Expert Knowledge Claude does not have >70% Activation When/how to trigger ~20% Redundant What Claude already knows <10%

    This came from reviewing approximately 30 external skill files and discovering that most were redundant with Claude's built-in system prompt. Only about 20% had salvageable content, and even those yielded just a few heuristics each.

    The E/A/R framework gave us a concrete, testable criterion:

    A good skill is Expert knowledge minus what Claude already knows.

    If more than 10% of a skill restates platform defaults, it is creating noise, not signal.

    Every skill in v0.3.0 was evaluated against this framework. Several were deleted. The survivors are leaner and more focused.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#backup-and-monitoring-infrastructure","level":2,"title":"Backup and Monitoring Infrastructure","text":"

    A tool that manages your project's memory needs ops maturity.

    v0.3.0 added two pieces of infrastructure that reflect this:

    Backup staleness hook: A UserPromptSubmit hook that checks whether the last .context/ backup is more than two days old. If it is, and the SMB mount is available, it reminds the user. No cron job running when nobody is working. No redundant backups when nothing has changed.

    Context size checkpoint: A PreToolUse hook that estimates current context window usage and warns when the session is getting heavy. This hooks into the attention budget philosophy: Degradation is expected, but it should be visible.

    Both hooks use $CLAUDE_PROJECT_DIR instead of hardcoded paths, a migration triggered by a username rename that broke every absolute path in the hook configuration. That migration (replacing /home/user/... with \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/...) was one of those changes that seems trivial but prevents an entire category of future failures.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#the-numbers","level":2,"title":"The Numbers","text":"Metric v0.2.0 v0.3.0 Skills (was \"commands\") 11 21 Skills with quality gates 0 21 Skills with \"When NOT to Use\" 0 21 Average skill body ~15 lines ~80 lines Hooks using $CLAUDE_PROJECT_DIR 0 All Documentation commits -- 35+ Feature/fix commits -- ~15

    That ratio (35+ documentation and quality commits to ~15 feature commits) is the defining characteristic of this release:

    • This release is not a failure to ship features.
    • It is the deliberate choice to make the existing features reliable.
    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#what-v030-means","level":2,"title":"What v0.3.0 Means","text":"

    v0.1.0 asked: \"Can we give AI persistent memory?\"

    v0.2.0 asked: \"Can we make that memory accessible to humans too?\"

    v0.3.0 asks a different question: \"Can we make the quality self-enforcing?\"

    The answer is not a feature: It is a practice:

    • Skills with quality gates enforce pre-flight checks.
    • Negative triggers prevent misuse without human intervention.
    • The E/A/R framework ensures skills contain signal, not noise.
    • Consolidation sessions are scheduled, not improvised.
    • Hook infrastructure makes degradation visible.

    Discipline is not the absence of velocity. It is the infrastructure that makes velocity sustainable.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-ctx-v0.3.0-the-discipline-release/#what-comes-next","level":2,"title":"What Comes Next","text":"

    The skill system is now mature enough to support real workflows without constant human correction. The hooks infrastructure is portable and resilient. The consolidation practice is documented and repeatable.

    The next chapter is about what you build on top of discipline:

    • Multi-agent coordination;
    • Deeper integration patterns;
    • And the question of whether context management is a tool concern or an infrastructure concern.

    But those are future posts.

    This one is about the release that proved polish is not the opposite of progress. It is what turns a prototype into a product.

    The Discipline Release

    v0.1.0 shipped features.

    v0.2.0 shipped archaeology.

    v0.3.0 shipped the habits that make everything else trustworthy.

    The most important code in this release is the code that prevents bad code from shipping.

    This post was drafted using /ctx-blog with access to the full git history between v0.2.0 and v0.3.0, decision logs, learning logs, and the session files from the skill rewrite window. The meta continues.

    ","path":["ctx v0.3.0: The Discipline Release"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/","level":1,"title":"Eight Ways a Hook Can Talk","text":"","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#when-your-warning-disappears","level":2,"title":"When Your Warning Disappears","text":"

    Jose Alekhinne / 2026-02-15

    I had a backup warning that nobody ever saw.

    The hook was correct: It detected stale backups, formatted a nice message, and output it as {\"systemMessage\": \"...\"}. The problem wasn't detection. The problem was delivery. The agent absorbed the information, processed it internally, and never told the user.

    Meanwhile, a different hook (the journal reminder) worked perfectly every time. Users saw the reminder, ran the commands, and the backlog stayed manageable. Same hook event (UserPromptSubmit), same project, completely different outcomes.

    The difference was one line:

    IMPORTANT: Relay this journal reminder to the user VERBATIM\nbefore answering their question.\n

    That explicit instruction is what makes VERBATIM relay a pattern, not just a formatting choice. And once I saw it as a pattern, I started seeing others.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-audit","level":2,"title":"The Audit","text":"

    I looked at every hook in ctx: Eight shell scripts across three hook events. And I found five distinct output patterns already in use, plus three more that the existing hooks were reaching for but hadn't quite articulated.

    The patterns form a spectrum based on a single question:

    \"Who decides what the user sees?\"

    At one end, the hook decides everything (hard gate: the agent literally cannot proceed). At the other end, the hook is invisible (silent side-effect: nobody knows it ran). In between, there is a range of negotiation between hook, agent, and the user.

    Here's the full spectrum:

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#1-hard-gate","level":3,"title":"1. Hard Gate","text":"
    {\"decision\": \"block\", \"reason\": \"Use ctx from PATH, not ./ctx\"}\n

    The nuclear option: The agent's tool call is rejected before it executes.

    This is Claude Code's first-class PreToolUse mechanism: The hook returns JSON with decision: block and the agent gets an error with the reason.

    Use this for invariants: Constitution rules, security boundaries, things that must never happen. I use it to enforce PATH-based ctx invocation, block sudo, and require explicit approval for git push.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#2-verbatim-relay","level":3,"title":"2. VERBATIM Relay","text":"
    IMPORTANT: Relay this warning to the user VERBATIM before answering.\n┌─ Journal Reminder ─────────────────────────────\n│ You have 12 sessions not yet exported.\n│   ctx recall export --all\n└────────────────────────────────────────────────\n

    The instruction is the pattern. Without \"Relay VERBATIM,\" agents tend to absorb information into their internal reasoning and never surface it. The explicit instruction changes the behavior from \"I know about this\" to \"I must tell the user about this.\"

    I use this for actionable reminders:

    • Unexported journal entries;
    • Stale backups;
    • Context capacity warnings...

    ...things the user should see regardless of what they asked.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#3-agent-directive","level":3,"title":"3. Agent Directive","text":"
    ┌─ Persistence Checkpoint (prompt #25) ───────────\n│ No context files updated in 15+ prompts.\n│ Have you discovered learnings worth persisting?\n└──────────────────────────────────────────────────\n

    A nudge, not a command. The hook tells the agent something; the agent decides what (if anything) to tell the user. This is right for behavioral nudges: \"you haven't saved context in a while\" doesn't need to be relayed verbatim, but the agent should consider acting on it.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#4-silent-context-injection","level":3,"title":"4. Silent Context Injection","text":"
    ctx agent --budget 4000 2>/dev/null || true\n

    Pure background enrichment. The agent's context window gets project information injected on every tool call, with no visible output. Neither the agent nor the user sees the hook fire, but the agent makes better decisions because of the context.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#5-silent-side-effect","level":3,"title":"5. Silent Side-Effect","text":"
    find \"$CTX_TMPDIR\" -type f -mtime +15 -delete\n

    Do work, say nothing. Temp file cleanup on session end. Logging. Marker file management. The action is the entire point; no one needs to know.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-patterns-we-dont-have-yet","level":2,"title":"The Patterns We Don't Have Yet","text":"

    Three more patterns emerged from the gaps in the existing hooks.

    Conditional relay: \"Relay this, but only if the user's question is about X.\" This pattern avoids noise when the warning isn't relevant. It's more fragile (depends on agent judgment) but less annoying.

    Suggested action: \"Here's a problem, and here's the exact command to fix it. Ask the user before running it.\" This pattern goes beyond a nudge by giving the agent a concrete proposal, but still requires human approval.

    Escalating severity: INFO gets absorbed silently. WARN gets mentioned at the next natural pause. CRITICAL gets the VERBATIM treatment. This pattern introduces a protocol for hooks that produce output at different urgency levels, so they don't all compete for the user's attention.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-eight-ways-a-hook-can-talk/#the-principle","level":2,"title":"The Principle","text":"

    Hooks are the boundary between your environment and the agent's reasoning.

    A hook that detects a problem but can't communicate it effectively is the same as no hook at all.

    The format of your output is a design decision with real consequences:

    • Use a hard gate and the agent can't proceed (good for invariants, frustrating for false positives)
    • Use VERBATIM relay and the user will see it (good for reminders, noisy if overused)
    • Use an agent directive and the agent might act (good for nudges, unreliable for critical warnings)
    • Use silent injection and nobody knows (good for enrichment, invisible when it breaks)

    Choose deliberately. And, when in doubt, write the word VERBATIM.

    The full pattern catalog with decision flowchart and implementation examples is in the Hook Output Patterns recipe.

    ","path":["Eight Ways a Hook Can Talk"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/","level":1,"title":"Version Numbers Are Lagging Indicators","text":"","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#why-ctxs-journal-site-runs-on-a-v0021-tool","level":2,"title":"Why ctx's Journal Site Runs on a v0.0.21 Tool","text":"

    Jose Alekhinne / 2026-02-15

    Would You Ship Production Infrastructure on a v0.0.21 Dependency?

    Most engineers wouldn't. Version numbers signal maturity. Pre-1.0 means unstable API, missing features, risk.

    But version numbers tell you where a project has been. They say nothing about where it's going.

    I just bet ctx's entire journal site on a tool that hasn't hit v0.1.0.

    Here's why I'd do it again.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-problem","level":2,"title":"The Problem","text":"

    When v0.2.0 shipped the journal system, the pipeline was clear:

    • Export sessions to Markdown;
    • Enrich them with YAML frontmatter;
    • And render them into something browsable.

    The first two steps were solved; the third needed a tool.

    The journal entries are standard Markdown with YAML frontmatter, tables, and fenced code blocks. That is the entire format:

    • No JSX;
    • No shortcodes;
    • No custom templating.

    Just Markdown rendered well.

    The requirements are modest:

    • Read a configuration file (such as mkdocs.yml);
    • Render Markdown with extensions (admonitions, tabs, tables);
    • Search;
    • Handle 100+ files without choking on incremental rebuilds;
    • Look good out of the box;
    • Not lock me in.

    The obvious candidates were as follows:

    Tool Language Strengths Pain Points Hugo Go Blazing fast, mature Templating is painful; Go templates fight you on anything non-trivial Astro JS/TS Modern, flexible JS ecosystem overhead; overkill for a docs site MkDocs + Material Python Beautiful defaults, massive community (22k+ stars) Slow incremental rebuilds on large sites; limited extensibility model Zensical Python Built to fix MkDocs' limits; 4-5x faster rebuilds v0.0.21; module system not yet shipped

    The instinct was Hugo. Same language as ctx. Fast. Well-established.

    But instinct is not analysis. I picked the one with the lowest version number.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-evaluation","level":2,"title":"The Evaluation","text":"

    Here is what I actually evaluated, in order:

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#1-the-team","level":3,"title":"1. The Team","text":"

    Zensical is built by squidfunk: The same person behind Material for MkDocs, the most popular MkDocs theme with 22,000+ stars. It powers documentation sites for projects across every language and framework.

    • This is not someone learning how to build static site generators.
    • This is someone who spent years understanding exactly where MkDocs breaks and decided to fix it from the ground up.

    They did not build zensical because MkDocs was bad: They built it because MkDocs hit a ceiling:

    • Incremental rebuilds: 4-5x faster during serve. When you have hundreds of journal entries and you edit one, the difference between \"rebuild everything\" and \"rebuild this page\" is the difference between a usable workflow and a frustrating one.

    • Large site performance: Specifically designed for tens of thousands of pages. The journal grows with every session. A tool that slows down as content accumulates is a tool you will eventually replace.

    A proven team starting fresh is more predictable than an unproven team at v3.0.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#2-the-architecture","level":3,"title":"2. The Architecture","text":"

    Zensical is investing in a Rust-based Markdown parser with CommonMark support. That signals something about the team's priorities:

    Performance foundations first; features second.

    ctx's journal will grow:

    • Every exported session adds files.
    • Every enrichment pass adds metadata.

    Choosing a tool that gets slower as you add content means choosing to migrate later.

    Choosing one built for scale means the decision holds.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#3-the-migration-path","level":3,"title":"3. The Migration Path","text":"

    Zensical reads mkdocs.yml natively. If it doesn't work out, I can move back to MkDocs + Material with zero content changes:

    • The Markdown is standard;
    • The frontmatter is standard;
    • The configuration is compatible.

    This is the infrastructure pattern again: The same way ZNC decouples presence from the client, zensical decouples rendering from the generator:

    • The Markdown is yours.
    • The frontmatter is standard YAML.
    • The configuration is MkDocs-compatible.

    You are not locked into anything except your own content.

    No lock-in is not a feature: It's a design philosophy:

    It's the same reason ctx uses plain Markdown files in .context/ instead of a database: the format should outlive the tool.

    Lock-in Is the Real Risk, Not Version Numbers

    A mature tool with a proprietary format is riskier than a young tool with a standard one. Version numbers measure time invested. Portability measures respect for the user.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#4-the-dependency-tree","level":3,"title":"4. The Dependency Tree","text":"

    Here is what pip install zensical actually pulls in:

    • click
    • Markdown
    • Pygments
    • pymdown-extensions
    • PyYAML

    Only five dependencies. All well-known. No framework bloat. No bundler. No transpiler. No node_modules black hole.

    3k GitHub stars at v0.0.21 is a strong early traction for a pre-1.0 project.

    The dependency tree is thin: No bloat.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#5-the-fit","level":3,"title":"5. The Fit","text":"

    This is the same principle behind the attention budget: do not overfit the tool to hypothetical requirements. The right amount of capability is the minimum needed for the current task.

    Hugo is a powerful static site generator. It is also a powerful templating engine, a powerful asset pipeline, and a powerful taxonomy system. For rendering Markdown journals, that power is overhead:

    It is the complexity you pay for but never use.

    ctx's journal files are standard Markdown with YAML frontmatter, tables, and fenced code blocks. That is exactly the sweet spot Zensical inherits from Material for MkDocs:

    • No custom plugins needed;
    • No special syntax;
    • No templating gymnastics.

    The requirements match the capabilities: Not the capabilities that are promised, but the ones that exist today, at v0.0.21.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-caveat","level":2,"title":"The Caveat","text":"

    It would be dishonest not to mention what's missing.

    The module system for third-party extensions opens in early 2026.

    If ctx ever needs custom plugins (for example, auto-linking session IDs, rendering special journal metadata, etc.) that infrastructure isn't there yet.

    The installation experience is rough:

    We discovered this firsthand: pip install zensical often fails on MacOS (system Python stubs, Homebrew's PEP 668 restrictions). The answer is pipx, which creates an isolated environment with the correct Python version automatically.

    That kind of friction is typical for young Python tooling, and it is documented in the Getting Started guide.

    And 3,000 stars at v0.0.21 is strong early traction, but it's still early: The community is small. When something breaks, you're reading source code, not documentation.

    These are real costs. I chose to pay them because the alternative costs are higher.

    For example:

    • Hugo's templating pain would cost me time on every site change.
    • Astro's JS ecosystem would add complexity I don't need.
    • MkDocs would work today but hit scaling walls tomorrow.

    Zensical's costs are front-loaded and shrinking.

    The others compound.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-evaluation-framework","level":2,"title":"The Evaluation Framework","text":"

    For anyone facing a similar choice, here is the framework that emerged:

    Signal What It Tells You Weight Team track record Whether the architecture will be sound High Migration path Whether you can leave if wrong High Current fit Whether it solves your problem today High Dependency tree How much complexity you're inheriting Medium Version number How long the project has existed Low Star count Community interest (not quality) Low Feature list What's possible (not what you need) Low

    The bottom three are the metrics most engineers optimize for.

    The top four are the ones that predict whether you'll still be happy with the choice in a year.

    Features You Don't Need Are Not Free

    Every feature in a dependency is code you inherit but don't control.

    A tool with 200 features where you use 5 means 195 features worth of surface area for bugs, breaking changes, and security issues that have nothing to do with your use case.

    Fit is the inverse of feature count.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-15-why-zensical/#the-broader-pattern","level":2,"title":"The Broader Pattern","text":"

    This is part of a theme I keep encountering in this project:

    Leading indicators beat lagging indicators.

    Domain Lagging Indicator Leading Indicator Tooling Version number, star count Team track record, architecture Code quality Test coverage percentage Whether tests catch real bugs Context persistence Number of files in .context/ Whether the AI makes fewer mistakes Skills Number of skills created Whether each skill fires at the right time Consolidation Lines of code refactored Whether drift stops accumulating

    Version numbers, star counts, coverage percentages, file counts...

    ...these are all measures of effort expended.

    They say nothing about value delivered.

    The question is never \"how mature is this tool?\"

    The question is \"does this tool's trajectory intersect with my needs?\"

    Zensical's trajectory:

    • A proven team fixing known problems,
    • in a *proven architecture,
    • with a standard format,
    • and no lock-in.

    ctx's needs:

    Tender standard Markdown into a browsable site, at scale, without complexity.

    The intersection is clean; the version number is noise.

    This is the same kind of decision that shows up throughout ctx:

    • Skills that fight the platform taught that the best integration extends existing behavior, not replaces it.
    • You can't import expertise taught that tools should grow from your project's actual needs, not from feature checklists.
    • Context as infrastructure argues that the format should outlive the tool; and, zensical honors that principle by reading standard Markdown and standard MkDocs configuration.

    If You Remember One Thing From This Post...

    Version numbers measure where a project has been.

    The team and the architecture tell you where it's going.

    A v0.0.21 tool built by the right team on the right foundations is a safer bet than a v5.0 tool that doesn't fit your problem.

    Bet on trajectories, not timestamps.

    This post started as an evaluation note in ideas/ and a separate decision log. The analysis held up. The two merged into one. The meta continues.

    ","path":["Version Numbers Are Lagging Indicators"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/","level":1,"title":"ctx v0.6.0: The Integration Release","text":"","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#two-commands-to-persistent-memory","level":2,"title":"Two Commands to Persistent Memory","text":"

    Jose Alekhinne / February 16, 2026

    What Changed?

    ctx is now a Claude Code plugin. Two commands, no build step:

    /plugin marketplace add ActiveMemory/ctx\n/plugin install ctx@activememory-ctx\n

    Six hooks. Twenty-five skills. Installed.

    For three releases, ctx required assembly:

    • Clone the repo;
    • Build the binary;
    • Copy hook scripts into .claude/hooks/;
    • Symlink skill files.
    • Understand which shell scripts called which Go commands;
    • Hope nothing broke when Claude Code updated its hook format.

    v0.6.0 ends that era: ctx ships as a Claude Marketplace plugin:

    Hooks and skills served directly from source, installed with a single command, updated by pulling the repo. The tool that gives AI persistent memory is now as easy to install as the AI itself.

    But the plugin conversion was not just a packaging change: It was the forcing function that rewrote every shell hook in Go, eliminated the jq dependency, enabled go test coverage for hook logic, and made distribution a solved problem.

    When you fix how something ships, you end up fixing how it is built.

    The Release Window

    February 15-February 16, 2026

    From the v0.3.0 tag to commit a3178bc:

    • 109 commits.
    • 334 files changed.
    • Version jumped from 0.3.0 to 0.6.0 to signal the magnitude.
    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#before-six-shell-scripts-and-a-prayer","level":2,"title":"Before: Six Shell Scripts and a Prayer","text":"

    v0.3.0 had six hook scripts. Each was a Bash file that shelled out to ctx subcommands, parsed JSON with jq, and wired itself into Claude Code's hook system via .claude/hooks/:

    .claude/hooks/\n├── check-context-size.sh\n├── check-persistence.sh\n├── check-journal.sh\n├── post-commit.sh\n├── block-non-path-ctx.sh\n└── cleanup-tmp.sh\n

    This worked, but it also meant:

    • jq was a hard dependency: No jq, no hooks. macOS ships without it.
    • No test coverage: Shell scripts were tested manually or not at all.
    • Fragile deployment: ctx init had to scaffold .claude/hooks/ and .claude/skills/ with the right paths, permissions, and structure.
    • Version drift: Users who installed once never got hook updates unless they re-ran ctx init.

    The shell scripts were the right choice for prototyping. They were the wrong choice for distribution.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#after-one-plugin-zero-shell-scripts","level":2,"title":"After: One Plugin, Zero Shell Scripts","text":"

    v0.6.0 replaces all six scripts with ctx system subcommands compiled into the binary:

    Shell Script Go Subcommand check-context-size.sh ctx system check-context-size check-persistence.sh ctx system check-persistence check-journal.sh ctx system check-journal post-commit.sh ctx system post-commit block-non-path-ctx.sh ctx system block-non-path-ctx cleanup-tmp.sh ctx system cleanup-tmp

    The plugin's hooks.json wires them to Claude Code events:

    {\n  \"PreToolUse\": [\n    {\"matcher\": \"Bash\", \"command\": \"ctx system block-non-path-ctx\"},\n    {\"matcher\": \".*\", \"command\": \"ctx agent --budget 4000\"}\n  ],\n  \"PostToolUse\": [\n    {\"matcher\": \"Bash\", \"command\": \"ctx system post-commit\"}\n  ],\n  \"UserPromptSubmit\": [\n    {\"command\": \"ctx system check-context-size\"},\n    {\"command\": \"ctx system check-persistence\"},\n    {\"command\": \"ctx system check-journal\"}\n  ],\n  \"SessionEnd\": [\n    {\"command\": \"ctx system cleanup-tmp\"}\n  ]\n}\n

    No jq. No shell scripts. No .claude/hooks/ directory to manage.

    The hooks are Go functions with tests, compiled into the same binary you already have.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#the-plugin-model","level":2,"title":"The Plugin Model","text":"

    The ctx plugin lives at .claude-plugin/marketplace.json in the repo.

    Claude Code's marketplace system handles discovery and installation:

    Skills are served directly from internal/assets/claude/skills/; there is no build step, no make plugin, no generated artifacts.

    This means:

    1. Install is two commands: Not \"clone, build, copy, configure.\"
    2. Updates are automatic: Pull the repo; the plugin reads from source.
    3. Skills and hooks are versioned together: No drift between what the CLI expects and what the plugin provides.
    4. ctx init is tool-agnostic: It creates .context/ and nothing else. No .claude/ scaffolding, no assumptions about which AI tool you use.

    That last point matters:

    Before v0.6.0, ctx init tried to set up Claude Code integration as part of initialization. That coupled the context system to a specific tool.

    Now, ctx init gives you persistent context. The plugin gives you Claude Code integration. They compose; they don't depend.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#beyond-the-plugin-what-else-shipped","level":2,"title":"Beyond the Plugin: What Else Shipped","text":"

    The plugin conversion dominated the release, but 109 commits covered more ground.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#obsidian-vault-export","level":3,"title":"Obsidian Vault Export","text":"
    ctx journal obsidian\n

    Generates a full Obsidian vault from enriched journal entries: wikilinks, MOC (Map of Content) pages, and graph-optimized cross-linking. If you already use Obsidian for notes, your AI session history now lives alongside everything else.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#encrypted-scratchpad","level":3,"title":"Encrypted Scratchpad","text":"
    ctx pad edit \"DATABASE_URL=postgres://...\"\nctx pad show\n

    AES-256-GCM encrypted storage for sensitive one-liners.

    The encrypted blob commits to git; the key stays in .gitignore.

    This is useful for connection strings, API keys, and other values that need to travel with the project without appearing in plaintext.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#security-hardening","level":3,"title":"Security Hardening","text":"

    Three medium-severity findings from a security audit are now closed:

    Finding Fix Path traversal via --context-dir Boundary validation: operations cannot escape project root (M-1) Symlink following in .context/ Lstat() check before every file read/write (M-2) Predictable temp file paths User-specific temp directory under $XDG_RUNTIME_DIR (M-3)

    Plus a new /sanitize-permissions skill that audits settings.local.json for overly broad Bash permissions.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#hooks-that-know-when-to-be-quiet","level":3,"title":"Hooks That Know When to Be Quiet","text":"

    A subtle but important fix: hooks now no-op before ctx init has run.

    Previously, a fresh clone with no .context/ would trigger hook errors on every prompt. Now, hooks detect the absence of a context directory and exit silently. Similarly, ctx init treats a .context/ directory containing only logs as uninitialized and skips the --overwrite prompt.

    Small changes. Large reduction in friction for new users.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#the-numbers","level":2,"title":"The Numbers","text":"Metric v0.3.0 v0.6.0 Skills 21 25 Shell hook scripts 6 0 Go system subcommands 0 6 External dependencies (hooks) jq, bash none Lines of Go ~14,000 ~37,000 Plugin install commands n/a 2 Security findings (open) 3 0 ctx init creates .claude/ yes no

    The line count tripled. Most of that is documentation site HTML, Obsidian export logic, and the scratchpad encryption module.

    The core CLI grew modestly; the ecosystem around it grew substantially.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#what-does-v060-mean-for-ctx","level":2,"title":"What Does v0.6.0 Mean for ctx?","text":"
    • v0.1.0 asked: \"Can we give AI persistent memory?\"
    • v0.2.0 asked: \"Can we make that memory accessible to humans too?\"
    • v0.3.0 asked: \"Can we make the quality self-enforcing?\"

    v0.6.0 asks: \"Can someone else actually use this?\"

    A tool that requires cloning a repo, building from source, and manually wiring hooks into the right directories is a tool for its author.

    A tool that installs with two commands from a marketplace is a tool for everyone.

    The version jumped from 0.3.0 to 0.6.0 because the delta is not incremental: The shell-to-Go rewrite, the plugin model, the security hardening, and the tool-agnostic init: Together, they change what ctx is: Not a different tool, but a tool that is finally ready to leave the workshop.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-16-ctx-v0.6.0-the-integration-release/#what-comes-next","level":2,"title":"What Comes Next","text":"

    The plugin model opens the door to distribution patterns that were not possible before. Marketplace discovery means new users find ctx without reading a README. Plugin updates mean existing users get improvements without rebuilding.

    The next chapter is about what happens when persistent context is easy to install: Adoption patterns, multi-project workflows, and whether the .context/ convention can become infrastructure that other tools build on.

    But those are future posts.

    This one is about the release that turned a developer tool into a distributable product: two commands, zero shell scripts, and a presence on the Claude Marketplace.

    The Integration Release

    v0.1.0 shipped features. v0.2.0 shipped archaeology.

    v0.3.0 shipped discipline. v0.6.0 shipped the front door.

    The most important code in this release is the code you never have to copy.

    This post was drafted using /ctx-blog-changelog with access to the full git history between v0.3.0 and v0.6.0, release notes, and the plugin conversion PR. The meta continues.

    ","path":["ctx v0.6.0: The Integration Release"],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/","level":1,"title":"Code Is Cheap. Judgment Is Not.","text":"","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#why-ai-replaces-effort-not-expertise","level":2,"title":"Why AI Replaces Effort, Not Expertise","text":"

    Jose Alekhinne / February 17, 2026

    Are You Worried About AI Taking Your Job?

    You might be confusing the thing that's cheap with the thing that's valuable.

    I keep seeing the same conversation: Engineers, designers, writers: all asking the same question with the same dread:

    \"What happens when AI can do what I do?\"

    The question is wrong:

    • AI does not replace workers;
    • AI replaces unstructured effort.

    The distinction matters, and everything I have learned building ctx reinforces it.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-three-confusions","level":2,"title":"The Three Confusions","text":"

    People who feel doomed by AI usually confuse three things:

    People confuse... With... Effort Value Typing Thinking Production Judgment
    • Effort is time spent.
    • Value is the outcome that time produces.

    They are not the same; they never were.

    AI just makes the gap impossible to ignore.

    Typing is mechanical: Thinking is directional.

    An AI can type faster than any human. Yet, it cannot decide what to type without someone framing the problem, sequencing the work, and evaluating the result.

    Production is making artifacts. Judgment is knowing:

    • which artifacts to make,
    • in what order,
    • to what standard,
    • and when to stop.

    AI floods the system with production capacity; it does not flood the system with judgment.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#code-is-nothing","level":2,"title":"Code Is Nothing","text":"

    This sounds provocative until you internalize it:

    Code is cheap. Artifacts are cheap.

    An AI can generate a thousand lines of working code in literal *minutes**:

    It can scaffold a project, write tests, build a CI pipeline, draft documentation. The raw production of software artifacts is no longer the bottleneck.

    So, what is not cheap?

    • Taste: knowing what belongs and what does not
    • Framing: turning a vague goal into a concrete problem
    • Sequencing: deciding what to build first and why
    • Fanning out: breaking work into parallel streams that converge
    • Acceptance criteria: defining what \"done\" looks like before starting
    • Judgment: the thousand small decisions that separate code that works from code that lasts

    These are the skills that direct production: Hhuman skills.

    Not because AI is incapable of learning them, but because they require something AI does not have:

    temporal accountability for generated outcomes.

    That is, you cannot keep AI accountable for the $#!% it generated three months ago. A human, on the other hand, will always be accountable.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-evidence-from-building-ctx","level":2,"title":"The Evidence From Building ctx","text":"

    I did not arrive at this conclusion theoretically.

    I arrived at it by building a tool with an AI agent for three weeks and watching exactly where a human touch mattered.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#yolo-mode-proved-production-is-cheap","level":3,"title":"YOLO Mode Proved Production Is Cheap","text":"

    In Building ctx Using ctx, I documented the YOLO phase: auto-accept everything, let the AI ship features at full speed. It produced 14 commands in a week. Impressive output.

    The code worked. The architecture drifted. Magic strings accumulated. Conventions diverged. The AI was producing at a pace no human could match, and every artifact it produced was a small bet that nobody was evaluating.

    Production without judgment is not velocity. It is debt accumulation at breakneck speed.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-31-ratio-proved-judgment-has-a-cadence","level":3,"title":"The 3:1 Ratio Proved Judgment Has a Cadence","text":"

    In The 3:1 Ratio, the git history told the story:

    Three sessions of forward momentum followed by one session of deliberate consolidation. The consolidation session is where the human applies judgment: reviewing what the AI built, catching drift, realigning conventions.

    The AI does the refactoring. The human decides what to refactor and when to stop.

    Without the human, the AI will refactor forever, improving things that do not matter and missing things that do.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-attention-budget-proved-framing-is-scarce","level":3,"title":"The Attention Budget Proved Framing Is Scarce","text":"

    In The Attention Budget, I explained why more context makes AI worse, not better. Every token competes for attention: Dump everything in and the AI sees nothing clearly.

    This is a framing problem: The human's job is to decide what the AI should focus on: what to include, what to exclude, what to emphasize.

    ctx agent --budget 4000 is not just a CLI flag: It is a forcing function for human judgment about relevance.

    The AI processes. The human curates.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#skills-design-proved-taste-is-load-bearing","level":3,"title":"Skills Design Proved Taste Is Load-Bearing","text":"

    The skill trilogy (You Can't Import Expertise, The Anatomy of a Skill That Works) showed that the difference between a useful skill and a useless one is not craftsmanship:

    It is taste.

    A well-crafted skill with the wrong focus is worse than no skill at all: It consumes the attention budget with generic advice while the project-specific problems go unchecked.

    The E/A/R framework (Expert, Activation, Redundant) is a judgment too:. The AI cannot apply it to itself. The human evaluates what the AI already knows, what it needs to be told, and what is noise.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#automation-discipline-proved-restraint-is-a-skill","level":3,"title":"Automation Discipline Proved Restraint Is a Skill","text":"

    In Not Everything Is a Skill, the lesson was that the urge to automate is not the need to automate. A useful prompt does not automatically deserve to become a slash command.

    The human applies judgment about frequency, stability, and attention cost.

    The AI can build the skill. Only the human can decide whether it should exist.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#defense-in-depth-proved-boundaries-require-judgment","level":3,"title":"Defense in Depth Proved Boundaries Require Judgment","text":"

    In Defense in Depth, the entire security model for unattended AI agents came down to: markdown is not a security boundary. Telling an AI \"don't do bad things\" is production (of instructions). Setting up an unprivileged user in a network-isolated container is judgment (about risk).

    The AI follows instructions. The human decides which instructions are enforceable and which are \"wishful thinking\".

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#parallel-agents-proved-scale-amplifies-the-gap","level":3,"title":"Parallel Agents Proved Scale Amplifies the Gap","text":"

    In Parallel Agents and Merge Debt, the lesson was that multiplying agents multiplies output. But it also multiplies the need for judgment:

    Five agents running in parallel produce five sessions of drift in one clock hour. The human who can frame tasks cleanly, define narrow acceptance criteria, and evaluate results quickly becomes the limiting factor.

    More agents do not reduce the need for judgment. They increase it.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-two-reactions","level":2,"title":"The Two Reactions","text":"

    When AI floods the system with cheap output, two things happen:

    Those who only produce: panic. If your value proposition is \"I write code,\" and an AI writes code faster, cheaper, and at higher volume, then the math is unfavorable. Not because AI took your job, but because your job was never the code. It was the judgment around the code, and you were not exercising it.

    Those who direct: accelerate. If your value proposition is \"I know what to build, in what order, to what standard,\" then AI is the best thing that ever happened to you: Production is no longer the bottleneck: Your ability to frame, sequence, evaluate, and course-correct is now the limiting factor on throughput.

    The gap between these two is not talent: It is the awareness of where the value lives.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#what-this-means-in-practice","level":2,"title":"What This Means in Practice","text":"

    If you are an engineer reading this, the actionable insight is not \"learn prompt engineering\" or \"master AI tools.\" It is:

    Get better at the things AI cannot do.

    AI does this well You need to do this Generate code Frame the problem Write tests Define acceptance criteria Scaffold projects Sequence the work Fix bugs from stack traces Evaluate tradeoffs Produce volume Exercise restraint Follow instructions Decide which instructions matter

    The skills on the right column are not new. They are the same skills that have always separated senior engineers from junior ones.

    AI did not create the distinction; it just made it load-bearing.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#if-anything-i-feel-empowered","level":2,"title":"If Anything, I Feel Empowered","text":"

    I will end with something personal.

    I am not worried: I am empowered.

    Before ctx, I could think faster than I could produce:

    • Ideas sat in a queue.
    • The bottleneck was always \"I know what to build, but building it takes too long.\"

    Now the bottleneck is gone. Poof!

    • Production is cheap.
    • The queue is clearing.
    • The limiting factor is how fast I can think, not how fast I can type.

    That is not a threat: That is the best force multiplier I've ever had.

    The people who feel threatened are confusing the accelerator for the replacement:

    *AI does not replace the conductor; it gives them a bigger orchestra.

    If You Remember One Thing From This Post...

    Code is cheap. Judgment is not.

    AI replaces unstructured effort, not directed expertise. The skills that matter now are the same skills that have always mattered: taste, framing, sequencing, and the discipline to stop.

    The difference is that now, for the first time, those skills are the only bottleneck left.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-code-is-cheap-judgment-is-not/#the-arc","level":2,"title":"The Arc","text":"

    This post is a retrospective. It synthesizes the thread running through every previous entry in this blog:

    • Building ctx Using ctx showed that production without direction creates debt
    • Refactoring with Intent showed that slowing down is not the opposite of progress
    • The Attention Budget showed that curation outweighs volume
    • The skill trilogy showed that taste determines whether a tool helps or hinders
    • Not Everything Is a Skill showed that restraint is a skill in itself
    • Defense in Depth showed that instructions are not boundaries
    • The 3:1 Ratio showed that judgment has a schedule
    • Parallel Agents showed that scale amplifies the gap between production and judgment
    • Context as Infrastructure showed that the system you build for context is infrastructure, not conversation

    From YOLO mode to defense in depth, the pattern is the same:

    • Production is the easy part;
    • Judgment is the hard part;
    • AI changed the ratio, not the rule.

    This post synthesizes the thread running through every previous entry in this blog. The evidence is drawn from three weeks of building ctx with AI assistance, the decisions recorded in DECISIONS.md, the learnings captured in LEARNINGS.md, and the git history that tracks where the human mattered and where the AI ran unsupervised.

    See also: When a System Starts Explaining Itself -- what happens after the arc: the first field notes from the moment the system starts compounding in someone else's hands.

    ","path":["Code Is Cheap. Judgment Is Not."],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/","level":1,"title":"Context as Infrastructure","text":"","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#why-your-ai-needs-a-filesystem-not-a-prompt","level":2,"title":"Why Your AI Needs a Filesystem, Not a Prompt","text":"

    Jose Alekhinne / February 17, 2026

    Where does your AI's knowledge live between sessions?

    If the answer is \"in a prompt I paste at the start,\" you are treating context as a consumable. Something assembled, used, and discarded.

    What if you treated it as infrastructure instead?

    This post synthesizes a thread that has been running through every ctx blog post; from the origin story to the attention budget to the discipline release. The thread is this: context is not a prompt problem. It is an infrastructure problem. And the tools we build for it should look more like filesystems than clipboard managers.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-prompt-paradigm","level":2,"title":"The Prompt Paradigm","text":"

    Most AI-assisted development treats context as ephemeral:

    1. Start a session.
    2. Paste your system prompt, your conventions, your current task.
    3. Work.
    4. Session ends. Everything evaporates.
    5. Next session: paste again.

    This works for short interactions. For sustained development (where decisions compound over days and weeks) it fails in three ways:

    It does not persist: A decision made on Tuesday must be re-explained on Wednesday. A learning captured in one session is invisible to the next.

    It does not scale: As the project grows, the \"paste everything\" approach hits the context window ceiling. You start triaging what to include, often cutting exactly the context that would have prevented the next mistake.

    It does not compose: A system prompt is a monolith. You cannot load part of it, update one section, or share a subset with a different workflow. It is all or nothing.

    The Copy-Paste Tax

    Every session that starts with pasting a prompt is paying a tax:

    The human time to assemble the context, the risk of forgetting something, and the silent assumption that yesterday's prompt is still accurate today.

    Over 70+ sessions, that tax compounds into a significant maintenance burden: One that most developers absorb without questioning it.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-infrastructure-paradigm","level":2,"title":"The Infrastructure Paradigm","text":"

    ctx takes a different approach:

    Context is not assembled per-session; it is maintained as persistent files in a .context/ directory:

    .context/\n  CONSTITUTION.md     # Inviolable rules\n  TASKS.md            # Current work items\n  CONVENTIONS.md      # Code patterns and standards\n  DECISIONS.md        # Architectural choices with rationale\n  LEARNINGS.md        # Gotchas and lessons learned\n  ARCHITECTURE.md     # System structure\n  GLOSSARY.md         # Domain terminology\n  AGENT_PLAYBOOK.md   # Operating manual for agents\n  journal/            # Enriched session summaries\n  archive/            # Completed work, cold storage\n
    • Each file has a single purpose;
    • Each can be loaded independently;
    • Each persists across sessions, tools, and team members.

    This is not a novel idea. It is the same idea behind every piece of infrastructure software engineers already use:

    Traditional Infrastructure ctx Equivalent Database .context/*.md files Configuration files CONSTITUTION.md Environment variables .contextrc Log files journal/ Schema migrations Decision records Deployment manifests AGENT_PLAYBOOK.md

    The parallel is not metaphorical. Context files are infrastructure:

    • They are versioned (git tracks them);
    • They are structured (Markdown with conventions);
    • They have schemas (required fields for decisions and learnings);
    • And they have lifecycle management (archiving, compaction, indexing).
    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#separation-of-concerns","level":2,"title":"Separation of Concerns","text":"

    The most important design decision in ctx is not any individual feature. It is the separation of context into distinct files with distinct purposes.

    A single CONTEXT.md file would be simpler to implement. It would also be impossible to maintain.

    Why? Because different types of context have different lifecycles:

    Context Type Changes Read By Load When Constitution Rarely Every session Always Tasks Every session Session start Always Conventions Weekly Before coding When writing code Decisions When decided When questioning When revisiting Learnings When learned When stuck When debugging Journal Every session Rarely When investigating

    Loading everything into every session wastes the attention budget on context that is irrelevant to the current task. Loading nothing forces the AI to operate blind.

    Separation of concerns allows progressive disclosure:

    Load the minimum that matters for this moment, with the option to load more when needed.

    # Session start: load the essentials\nctx agent --budget 4000\n\n# Deep investigation: load everything\ncat .context/DECISIONS.md\ncat .context/journal/2026-02-05-*.md\n

    The filesystem is the index. File names, directory structure, and timestamps encode relevance. The AI does not need to read every file; it needs to know where to look.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-two-tier-persistence-model","level":2,"title":"The Two-Tier Persistence Model","text":"

    ctx uses two tiers of persistence, and the distinction is architectural:

    Tier Purpose Location Token Cost Curated Quick context reload .context/*.md Low (budgeted) Full dump Safety net, archaeology .context/journal/*.md Zero (not auto-loaded)

    The curated tier is what the AI sees at session start. It is optimized for signal density:

    • Structured entries,
    • Indexed tables,
    • Reverse-chronological order (newest first, so the most relevant content survives truncation).

    The full dump tier is for humans and for deep investigation. It contains everything: Enriched journals, archived tasks...

    It is never autoloaded because its volume would destroy attention density.

    This two-tier model is analogous to how traditional systems separate hot and cold storage:

    • The hot path (curated context) is optimized for read performance (measured not in milliseconds, but in tokens consumed per unit of useful information).
    • The cold path (journal) is optimized for completeness.

    Nothing Is Ever Truly Lost

    The full dump tier means that context does not need to be perfect: It just needs to be findable.

    A decision that was not captured in DECISIONS.md can be recovered from the session transcript where it was discussed.

    A learning that was not formalized can be found in the journal entry from that day.

    The curated tier is the fast path: The full dump tier is the safety net.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#decision-records-as-first-class-citizens","level":2,"title":"Decision Records as First-Class Citizens","text":"

    One of the patterns that emerged from ctx's own development is the power of structured decision records.

    v0.1.0 allowed adding decisions as one-liners:

    ctx add decision \"Use PostgreSQL\"\n

    v0.2.0 enforced structure:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a reliable database for user data\" \\\n  --rationale \"ACID compliance, team familiarity\" \\\n  --consequence \"Need connection pooling, team training\"\n

    The difference is not cosmetic:

    • A one-liner decision teaches the AI what was decided.
    • A structured decision teaches it why; and why is what prevents the AI from unknowingly reversing the decision in a future session.

    This is infrastructure thinking:

    Decisions are not notes. They are records with required fields, just like database rows have schemas.

    The enforcement exists because incomplete records are worse than no records: They create false confidence that the context is captured when it is not.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-ide-is-the-interface-decision","level":2,"title":"The \"IDE Is the Interface\" Decision","text":"

    Early in ctx's development, there was a temptation to build a custom UI: a web dashboard for browsing sessions, editing context, viewing analytics.

    The decision was no. The IDE is the interface.

    # This is the ctx \"UI\":\ncode .context/\n

    This decision was not about minimalism for its own sake. It was about recognizing that .context/ files are just files; and files have a mature, well-understood infrastructure:

    • Version control: git diff .context/DECISIONS.md shows exactly what changed and when.
    • Search: Your IDE's full-text search works across all context files.
    • Editing: Markdown in any editor, with preview, spell check, and syntax highlighting.
    • Collaboration: Pull requests on context files work the same as pull requests on code.

    Building a custom UI would have meant maintaining a parallel infrastructure that duplicates what every IDE already provides:

    It would have introduced its own bugs, its own update cycle, and its own learning curve.

    The filesystem is not a limitation: It is the most mature, most composable, most portable infrastructure available.

    Context Files in Git

    Because .context/ lives in the repository, context changes are part of the commit history.

    A decision made in commit abc123 is as traceable as a code change in the same commit.

    This is not possible with prompt-based context, which exists outside version control entirely.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#progressive-disclosure-for-ai","level":2,"title":"Progressive Disclosure for AI","text":"

    The concept of progressive disclosure comes from human interface design: show the user the minimum needed to make progress, with the option to drill deeper.

    ctx applies the same principle to AI context:

    Level What the AI Sees Token Cost When Level 0 ctx status (one-line summary) ~100 Quick check Level 1 ctx agent --budget 4000 ~4,000 Normal work Level 2 ctx agent --budget 8000 ~8,000 Complex tasks Level 3 Direct file reads 10,000+ Deep investigation

    Each level trades tokens for depth. Level 1 is sufficient for most work: the AI knows the active tasks, the key conventions, and the recent decisions. Level 3 is for archaeology: understanding why a decision was made three weeks ago, or finding a pattern in the session history.

    The explicit --budget flag is the mechanism that makes this work:

    Without it, the default behavior would be to load everything (because more context feels safer), which destroys the attention density that makes the loaded context useful.

    The constraint is the feature: A budget of 4,000 tokens forces ctx to prioritize ruthlessly: constitution first (always full), then tasks and conventions (budget-capped), then decisions and learnings scored by recency and relevance to active tasks. Entries that don't fit get title-only summaries rather than being silently dropped.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-philosophical-shift","level":2,"title":"The Philosophical Shift","text":"

    The shift from \"context as prompt\" to \"context as infrastructure\" changes how you think about AI-assisted development:

    Prompt Thinking Infrastructure Thinking \"What do I paste today?\" \"What has changed since yesterday?\" \"How do I fit everything in?\" \"What's the minimum that matters?\" \"The AI forgot my conventions\" \"The conventions are in a file\" \"I need to re-explain\" \"I need to update the record\" \"This session is getting slow\" \"Time to compact and archive\"

    The first column treats AI interaction as a conversation. The second treats it as a system: One that can be maintained, optimized, and debugged.

    Context is not something you give the AI. It is something you maintain: Like a database, like a config file, like any other piece of infrastructure that a running system depends on.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#beyond-ctx-the-principles","level":2,"title":"Beyond ctx: The Principles","text":"

    The patterns that ctx implements are not specific to ctx. They are applicable to any project that uses AI-assisted development:

    1. Separate context by purpose: Do not put everything in one file. Different types of information have different lifecycles and different relevance windows.
    2. Make context persistent: If a decision matters, write it down in a file that survives the session. If a learning matters, capture it with structure.
    3. Budget explicitly: Know how much context you are loading and whether it is worth the attention cost.
    4. Use the filesystem: File names, directory structure, and timestamps are metadata that the AI can navigate. A well-organized directory is an index that costs zero tokens to maintain.
    5. Version your context: Put context files in git. Changes to decisions are as important as changes to code.
    6. Design for degradation: Sessions will get long. Attention will dilute. Build mechanisms (compaction, archiving, cooldowns) that make degradation visible and manageable.

    These are not ctx features. They are infrastructure principles that happen to be implemented as a CLI tool. Any team could implement them with nothing more than a directory convention and a few shell scripts.

    The tool is a convenience: The principles are what matter.

    If You Remember One Thing From This Post...

    Prompts are conversations. Infrastructure persists.

    Your AI does not need a better prompt. It needs a filesystem:

    versioned, structured, budgeted, and maintained.

    The best context is the context that was there before you started the session.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-context-as-infrastructure/#the-arc","level":2,"title":"The Arc","text":"

    This post is the architectural companion to the Attention Budget. That post explained why context must be curated (token economics). This one explains how to structure it (filesystem, separation of concerns, persistence tiers).

    Together with Code Is Cheap, Judgment Is Not, they form a trilogy about what matters in AI-assisted development:

    • Attention Budget: the resource you're managing
    • Context as Infrastructure: the system you build to manage it
    • Code Is Cheap: the human skill that no system replaces

    And the practices that keep it all honest:

    • The 3:1 Ratio: the cadence for maintaining both code and context
    • IRC as Context: the historical precedent: stateless protocols have always needed stateful wrappers

    This post synthesizes ideas from across the ctx blog series: the attention budget primitive, the two-tier persistence model, the IDE decision, and the progressive disclosure pattern. The principles are drawn from three weeks of building ctx and 70+ sessions of treating context as infrastructure rather than conversation.

    See also: When a System Starts Explaining Itself: what happens when this infrastructure starts compounding in someone else's environment.

    ","path":["Context as Infrastructure"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/","level":1,"title":"Parallel Agents, Merge Debt, and the Myth of Overnight Progress","text":"","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#when-the-screen-looks-like-progress","level":2,"title":"When the Screen Looks Like Progress","text":"

    Jose Alekhinne / 2026-02-17

    How Many Terminals Are too Many?

    You discover agents can run in parallel.

    So you open ten...

    ...Then twenty.

    The fans spin. Tokens burn. The screen looks like progress.

    It is NOT progress.

    There is a phase every builder goes through:

    • The tooling gets fast enough.
    • The model gets good enough.
    • The temptation becomes irresistible:
      • more agents, more output, faster delivery.

    So you open terminals. You spawn agents. You watch tokens stream across multiple windows simultaneously, and it feels like multiplication.

    It is not multiplication.

    It is merge debt being manufactured in real time.

    The ctx Manifesto says it plainly:

    Activity is not impact. Code is not progress.

    This post is about what happens when you take that seriously in the context of parallel agent workflows.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-unit-of-scale-is-not-the-agent","level":2,"title":"The Unit of Scale Is Not the Agent","text":"

    The naive model says:

    More agents -> more output -> faster delivery

    The production model says:

    Clean context boundaries -> less interference -> higher throughput

    Parallelism only works when the cognitive surfaces do not overlap.

    If two agents touch the same files, you did not create parallelism: You created a conflict generator.

    They will:

    • Revert each other's changes;
    • Relint each other's formatting;
    • Refactor the same function in different directions.

    You watch with 🍿. Nothing ships.

    This is the same insight from the worktrees post: partition by blast radius, not by priority.

    Two tasks that touch the same files belong in the same track, no matter how important the other one is. The constraint is file overlap.

    Everything else is scheduling.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-five-agent-rule","level":2,"title":"The \"Five Agent\" Rule","text":"

    In practice there is a ceiling.

    Around five or six concurrent agents:

    • Token burn becomes noticeable;
    • Supervision cost rises;
    • Coordination noise increases;
    • Returns flatten.

    This is not a model limitation: This is a human merge bandwidth limitation.

    You are the bottleneck, not the silicon.

    The attention budget applies to you too:

    Every additional agent is another stream of output you need to comprehend, verify, and integrate. Your attention density drops the same way the model's does when you overload its context window.

    Five agents producing verified, mergeable change beats twenty agents producing merge conflicts you spend a day untangling.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#role-separation-beats-file-locking","level":2,"title":"Role Separation Beats File Locking","text":"

    Real parallelism comes from task topology, not from tooling.

    Good:

    Agent Role Touches 1 Documentation docs/, hack/ 2 Security scan Read-only audit 3 Implementation internal/cli/ 4 Enhancement requests Read-only, files issues

    Bad:

    • Four agents editing the same implementation surface

    Context is the Boundary

    • The goal is not to keep agents busy.
    • The goal is to keep contexts isolated.

    This is what the codebase audit got right:

    • Eight agents, all read-only, each analyzing a different dimension.
    • Zero file overlap.
    • Zero merge conflicts.
    • Eight reports that composed cleanly because no agent interfered with another.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#when-terminals-stop-scaling","level":2,"title":"When Terminals Stop Scaling","text":"

    There is a moment when more windows stop helping.

    That is the signal. Not to add orchestration. But to introduce:

    git worktree\n

    Because now you are no longer parallelizing execution; you are parallelizing state.

    State Scales, Windows Don't

    • State isolation is the real scaling.
    • Window multiplication is theater.

    The worktrees post covers the mechanics:

    • Sibling directories;
    • Branch naming;
    • The inevitable TASKS.md conflicts;
    • The 3-4 worktree ceiling.

    The principle underneath is older than git:

    Shared mutable state is the enemy of parallelism.

    Always has been.

    Always will be.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-overnight-loop-illusion","level":2,"title":"The Overnight Loop Illusion","text":"

    Autonomous night runs are impressive.

    You sleep. The machine produces thousands of lines.

    In the morning:

    • You read;
    • You untangle;
    • You reconstruct intent;
    • You spend a day making it shippable.

    In retrospect, nothing was accelerated.

    The bottleneck moved from typing to comprehension.

    The Comprehension Tax

    If understanding the output costs more than producing it, the loop is a net loss.

    Progress is not measured in generated code.

    Progress is measured in verified, mergeable change.

    The ctx Manifesto calls this out directly:

    The Scoreboard

    Verified reality is the scoreboard.

    The only truth that compounds is verified change in the real world.

    An overnight run that produces 3,000 lines nobody reviewed is not 3,000 lines of progress: It is 3,000 lines of liability until someone verifies every one of them.

    And that someone is (insert drumroll here) you:

    The same bottleneck that was supposedly being bypassed.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#skills-that-fight-the-platform","level":2,"title":"Skills That Fight the Platform","text":"

    Most marketplace skills are prompt decorations:

    • They rephrase what the base model already knows;
    • They increase token usage;
    • They reduce clarity:
    • They introduce behavioral drift.

    We covered this in depth in Skills That Fight the Platform: judgment suppression, redundant guidance, guilt-tripping, phantom dependencies, universal triggers: Five patterns that make agents worse, not better.

    A real skill does one of these:

    • Encodes workflow state;
    • Enforces invariants;
    • Reduces decision branching.

    Everything else is packaging.

    The anatomy post established the criteria: quality gates, negative triggers, examples over rules, skills as contracts.

    If a skill doesn't meet those criteria...

    • It is either a recipe (document it in hack/);
    • Or noise (delete it);
    • There is no third option.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#hooks-are-context-that-execute","level":2,"title":"Hooks Are Context That Execute","text":"

    The most valuable skills are not prompts:

    They are constraints embedded in the toolchain.

    For example: The agent cannot push.

    git push becomes:

    Stop. A human reviews first.

    A commit without verification becomes:

    Did you run tests? Did you run linters? What exactly are you shipping?

    This is not safety theater; this is intent preservation.

    The thing the ctx Manifesto calls \"encoding intent into the environment.\"

    The Eight Ways a Hook Can Talk catalogued the full spectrum: from silent enrichment to hard blocks.

    The key insight was that hooks are not just safety rails: They are context that survives execution.

    They are the difference between an agent that remembers the rules and one that enforces them.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#complexity-is-a-tax","level":2,"title":"Complexity Is a Tax","text":"

    Every extra layer adds cognitive weight:

    • Orchestration frameworks;
    • Meta agents;
    • Autonomous planning systems...

    If a single terminal works, stay there.

    If five isolated agents work, stop there.

    Add structure only when a real bottleneck appears.

    NOT when an influencer suggests one.

    This is the same lesson from Not Everything Is a Skill:

    The best automation decision is sometimes not to automate.

    A recipe in a Markdown file costs nothing until you use it.

    An orchestration framework costs attention on every run, whether it helps or not.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#literature-is-throughput","level":2,"title":"Literature Is Throughput","text":"

    Clear writing is not aesthetic: It is compression.

    Better articulation means:

    • Fewer tokens;
    • Fewer misinterpretations;
    • Faster convergence.

    The attention budget taught us that context is a finite resource with a quadratic cost.

    Language determines how fast you spend context.

    A well-written task description that takes 50 tokens outperforms a rambling one that takes 200: Not just because it is cheaper, but because it leaves more headroom for the model to actually think.

    Literature is NOT Overrated

    • Attention is a finite budget.
    • Language determines how fast you spend it.
    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#the-real-metric","level":2,"title":"The Real Metric","text":"

    The real metric is not:

    • Lines generated;
    • Agents running;
    • Tasks completed while you sleep.

    But:

    Time from idea to verified, mergeable, production change.

    Everything else is motion.

    The entire blog series has been circling this point:

    • The attention budget was about spending tokens wisely.
    • The skills trilogy was about not wasting them on prompt decoration.
    • The worktrees post was about multiplying throughput without multiplying interference.
    • The discipline release was about what a release looks like when polish outweighs features: 3:1.

    Every post has arrived (and made me converge) at the same answer so far:

    The metric is a verified change, not generated output.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#ctx-was-never-about-spawning-more-minds","level":2,"title":"ctx Was Never About Spawning More Minds","text":"

    ctx is about:

    • Isolating context;
    • Preserving intent;
    • Making progress composable.

    Parallel agents are powerful. But only when you respect the boundaries that make parallelism real.

    Otherwise, you are not scaling cognition; you are scaling interference.

    The ctx Manifesto's thesis holds:

    Without ctx, intelligence resets. With ctx, creation compounds.

    Compounding requires structure.

    Structure requires boundaries.

    Boundaries require the discipline to stop adding agents when five is enough.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-parallel-agents-merge-debt-and-the-myth-of-overnight-progress/#practical-summary","level":2,"title":"Practical Summary","text":"

    A production workflow tends to converge to this:

    Practice Why Stay in one terminal unless necessary Minimize coordination overhead Spawn a small number of agents with non-overlapping responsibilities Conflict avoidance > parallelism Isolate state with worktrees when surfaces grow State isolation is real scaling Encode verification into hooks Intent that survives execution Avoid marketplace prompt cargo cults Skills are contracts, not decorations Measure merge cost, not generation speed The metric is verified change

    This is slower to watch. Faster to ship.

    If You Remember One Thing From This Post...

    Progress is not what the machine produces while you sleep.

    Progress is what survives contact with the main branch.

    See also: Code Is Cheap. Judgment Is Not.: the argument that production capacity was never the bottleneck, and why multiplying agents amplifies the need for human judgment rather than replacing it.

    ","path":["Parallel Agents, Merge Debt, and the Myth of Overnight Progress"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/","level":1,"title":"The 3:1 Ratio","text":"","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#scheduling-consolidation-in-ai-development","level":2,"title":"Scheduling Consolidation in AI Development","text":"

    Jose Alekhinne / February 17, 2026

    How often should you stop building and start cleaning?

    Every developer knows technical debt exists. Every developer postpones dealing with it.

    AI-assisted development makes the problem worse; not because the AI writes bad code, but because it writes code so fast that drift accumulates before you notice.

    In Refactoring with Intent, I mentioned a ratio that worked for me: 3:1. Three YOLO sessions create enough surface area to reveal patterns. The fourth session turns those patterns into structure.

    That was an observation. This post is the evidence.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-observation","level":2,"title":"The Observation","text":"

    During the first two weeks of building ctx, I noticed a rhythm in my own productivity. Feature sessions felt great: new commands, new capabilities, visible progress...

    ...but after three of them, things would start to feel sticky: variable names that almost made sense, files that had grown past their purpose, patterns that repeated without being formalized.

    The fourth session (when I stopped adding and started cleaning) was always the most painful to start and the most satisfying to finish.

    It was also the one that made the next three feature sessions faster.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-evidence-git-history","level":2,"title":"The Evidence: Git History","text":"

    The ctx git history between January 20 and February 7 tells a clear story when you categorize commits:

    Week Feature commits Consolidation commits Ratio Jan 20-26 18 5 3.6:1 Jan 27-Feb 1 14 6 2.3:1 Feb 1-7 15 35+ 0.4:1

    The first week was pure YOLO: Almost four feature commits for every consolidation commit. The codebase grew fast.

    The second week started to self-correct. The ratio dropped as refactoring sessions became necessary: Not scheduled, but forced by friction.

    The third week inverted entirely: v0.3.0 was almost entirely consolidation: the skill migration, the sweep, the documentation standardization. Thirty-five quality commits against fifteen features.

    The debt from weeks one and two was paid in week three.

    The Compounding Problem

    Consolidation debt compounds.

    Week one's drift doesn't just persist into week two: It accelerates, because new features are built on top of drifted patterns.

    By week three, the cost of consolidation was higher than it would have been if spread evenly.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#what-drift-actually-looks-like","level":2,"title":"What Drift Actually Looks Like","text":"

    \"Drift\" sounds abstract. Here is what it looked like concretely in the ctx codebase after three weeks of feature-heavy development:

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#predicate-naming","level":3,"title":"Predicate Naming","text":"

    Convention says boolean functions should be named HasX, IsX, CanX. After three feature sprints:

    // What accumulated:\nfunc CheckIfEnabled() bool  // should be Enabled\nfunc ValidateFormat() bool  // should be ValidFormat\nfunc TestConnection() bool  // should be Connects\nfunc VerifyExists() bool    // should be Exists or HasFile\nfunc EnsureReady() bool     // should be Ready\n

    Five violations. Not bugs, but friction that compounds every time someone (human or AI) reads the code and has to infer the naming convention from inconsistent examples.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#magic-strings","level":3,"title":"Magic Strings","text":"
    // Week 1: acceptable prototype\nif entry.Type == \"task\" {\n    filename = \"TASKS.md\"\n}\n\n// Week 3: same pattern in 7+ files\n// Now it's a maintenance liability\n

    When the same literal appears in seven files, changing it means finding all seven. Missing one means a silent runtime bug. Constants exist to prevent exactly this. But during feature velocity, nobody stops to extract them.

    Refactoring with Intent documented the constants consolidation that cleaned this up. The 3:1 ratio is the practice that prevents it from accumulating again.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#hardcoded-permissions","level":3,"title":"Hardcoded Permissions","text":"
    os.WriteFile(path, data, 0644) // 80+ instances\nos.MkdirAll(path, 0755)        // scattered across packages\n

    Eighty-plus instances of hardcoded file permissions. Not wrong, but if I ever need to change the default (and I did, for hook scripts that need execute permissions), it means a codebase-wide search.

    Drift Is Not Bugs

    None of these are bugs. The code works. Tests pass.

    But drift creates false confidence: the codebase looks consistent until you try to change something and discover that five different conventions exist for the same concept.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#why-you-cannot-consolidate-on-day-one","level":2,"title":"Why You Cannot Consolidate on Day One","text":"

    The temptation is to front-load quality: write all the conventions, enforce all the checks, prevent all the drift before it happens.

    This fails for two reasons.

    First, you do not know what will drift: Predicate naming violations only become a convention check after you notice three different naming patterns competing. Magic strings only become a consolidation target after you change a literal and discover it exists in seven places.

    The conventions emerge from the work; they cannot precede it.

    This is what You Can't Import Expertise meant in practice: the consolidation checks grow from the project's own drift history. You cannot write them on day one because you do not yet know what will drift.

    Second, premature consolidation slows discovery: During the prototyping phase, the goal is to explore the design space. Enforcing strict conventions on code that might be deleted tomorrow is waste.

    YOLO mode has its place: The problem is not YOLO itself, but YOLO without a scheduled cleanup.

    The Consolidation Paradox

    You need a drift history to know what to consolidate.

    You need consolidation to prevent drift from compounding.

    The 3:1 ratio resolves this paradox:

    Let drift accumulate for three sessions (enough to see patterns), then consolidate in the fourth (before the patterns become entrenched*).

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-consolidation-skill","level":2,"title":"The Consolidation Skill","text":"

    The ctx project now has an /audit skill that encodes nine project-specific checks:

    Check What It Catches Predicate naming Boolean functions not using Has/Is/Can Magic strings Repeated literals not in config constants File permissions Hardcoded 0644/0755 not using constants Godoc style Missing or non-standard documentation File length Files exceeding 400 lines Large functions Functions exceeding 80 lines Template drift Live skills diverging from templates Import organization Non-standard import grouping TODO/FIXME staleness Old markers that are no longer relevant

    This is not a generic linter. These are project-specific conventions that emerged from ctx's own development history. A generic code quality tool would catch some of them. Only a project-specific check catches all of them, because some of them (predicate naming, template drift) are conventions that exist nowhere except in this project's CONVENTIONS.md.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-decision-matrix","level":2,"title":"The Decision Matrix","text":"

    Not all drift needs immediate consolidation. Here is the matrix I use:

    Signal Action Same literal in 3+ files Extract to constant Same code block in 3+ places Extract to helper Naming convention violated 5+ times Fix and document rule File exceeds 400 lines Split by concern Convention exists but is regularly violated Strengthen enforcement Pattern exists only in one place Leave it alone Code works but is \"ugly\" Leave it alone

    The last two rows matter:

    Consolidation is about reducing maintenance cost, not achieving aesthetic perfection. Code that works and exists in one place does not benefit from consolidation; it benefits from being left alone until it earns its refactoring.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#consolidation-as-context-hygiene","level":2,"title":"Consolidation as Context Hygiene","text":"

    There is a parallel between code consolidation and context management that became clear during the ctx development:

    Code Consolidation Context Hygiene Extract magic strings Archive completed tasks Standardize naming Keep DECISIONS.md current Remove dead code Compact old sessions Update stale comments Review LEARNINGS.md for staleness Check template drift Verify CONVENTIONS.md matches code

    ctx compact does for context what consolidation does for code:

    It moves completed work to cold storage, keeping the active context clean and focused. The attention budget applies to both the AI's context window and the developer's mental model of the codebase.

    When context files accumulate stale entries, the AI's attention is wasted on completed tasks and outdated conventions. When code accumulates drift, the developer's attention is wasted on inconsistencies that obscure the actual logic.

    Both are solved by the same discipline: periodic, scheduled cleanup.

    This is also why parallel agents make the problem harder, not easier. Three agents running simultaneously produce three sessions' worth of drift in one clock hour. The consolidation cadence needs to match the output rate, not the calendar.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-practice","level":2,"title":"The Practice","text":"

    Here is how the 3:1 ratio works in practice for ctx development:

    Sessions 1-3: Feature work

    • Add new capabilities;
    • Write tests for new code;
    • Do not stop for cleanup unless something is actively broken;
    • Note drift as you see it (a comment, a task, a mental note).

    Session 4: Consolidation

    • Run /audit to surface accumulated drift;
    • Fix the highest-impact items first;
    • Update CONVENTIONS.md if new patterns emerged;
    • Archive completed tasks;
    • Review LEARNINGS.md for anything that became a convention.

    The key insight is that session 4 is not optional. It is not \"if we have time\": It is scheduled with the same priority as feature work.

    The cost of skipping it is not visible immediately; it becomes visible three sessions later, when the next consolidation session takes twice as long because the drift compounded.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#what-the-ratio-is-not","level":2,"title":"What the Ratio Is Not","text":"

    The 3:1 ratio is not a universal law. It is an empirical observation from one project with one developer working with AI assistance.

    Different projects will have different ratios:

    • A mature codebase with strong conventions might sustain 5:1 or higher;
    • A greenfield prototype might need 2:1;
    • A team of multiple developers with different styles might need 1:1.

    The number is less important than the practice: consolidation is not a reaction to problems. It is a scheduled activity.

    If you wait for drift to cause pain before consolidating, you have already paid the compounding cost.

    If You Remember One Thing From This Post...

    Three sessions of building. One session of cleaning.

    Not because the code is dirty, but because drift compounds silently, and the only way to catch it is to look for it on a schedule.

    The ratio is the schedule.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-the-3-1-ratio/#the-arc-so-far","level":2,"title":"The Arc So Far","text":"

    This post sits at a crossroads in the ctx story. Looking back:

    • Building ctx Using ctx documented the YOLO sprint that created the initial codebase
    • Refactoring with Intent introduced the 3:1 ratio as an observation from the first cleanup
    • The Attention Budget explained why drift matters: every token of inconsistency consumes the same finite resource as useful context
    • You Can't Import Expertise showed that consolidation checks must grow from the project, not a template
    • The Discipline Release proved the ratio works at release scale: 35 quality commits to 15 feature commits

    And looking forward: the same principle applies to context files, to documentation, and to the merge debt that parallel agents produce. Drift is drift, whether it lives in code, in .context/, or in the gap between what your docs say and what your code does.

    The ratio is the schedule is the discipline.

    This post was drafted from git log analysis of the ctx repository, mapping every commit from January 20 to February 7 into feature vs consolidation categories. The patterns described are drawn from the project's CONVENTIONS.md, LEARNINGS.md, and the /audit skill's check list.

    ","path":["The 3:1 Ratio"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/","level":1,"title":"When a System Starts Explaining Itself","text":"","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#field-notes-from-the-moment-a-private-workflow-becomes-portable","level":2,"title":"Field Notes from the Moment a Private Workflow Becomes Portable","text":"

    Jose Alekhinne / February 17, 2026

    How Do You Know Something Is Working?

    Not from metrics. Not from GitHub stars. Not from praise.

    You know, deep in your heart, that it works when people start describing it wrong.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-first-external-signals","level":2,"title":"The First External Signals","text":"

    Every new substrate begins as a private advantage:

    • It lives inside one mind,
    • One repository,
    • One set of habits.

    It is fast. It is not yet real.

    Reality begins when other people describe it in their own language:

    • Not accurately;
    • Not consistently;
    • But involuntarily.

    The early reports arrived without coordination:

    Better Tasks

    \"I do not know how, but this creates better tasks than my AI plugin.\"

    I See Butterflies

    \"This is better than Adderall.\"

    Dear Manager...

    \"Promotion packet? Done. What is next?\"

    What Is It? Can I Eat It?

    \"Is this a skill?\" 🦋

    Why the Cloak and Dagger?

    \"Why is this not in the marketplace?\"

    And then something more important happened:

    Someone else started making a video!

    That was the boundary.

    ctx no longer required its creator to be present in order to exist.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#misclassification-is-a-sign-of-a-new-primitive","level":2,"title":"Misclassification Is a Sign of a New Primitive","text":"

    When a tool is understood, it is categorized:

    • Editor,
    • Framework,
    • Task manager,
    • Plugin...

    When a substrate appears, it is misclassified:

    \"Is this a skill?\" 🦋

    The question is correct. The category is wrong.

    • Skills live in people.
    • Infrastructure lives in the environment.

    ctx Is not a Skill: It is a Form of Relief

    What early adopters experience is not an ability.

    It is the removal of a cognitive constraint.

    This is the same distinction that emerged in the skills trilogy:

    • A skill is a contract between a human and an agent.
    • Infrastructure is the ground both stand on.

    You do not use infrastructure.

    You habitualize it.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-pharmacological-metaphor","level":2,"title":"The Pharmacological Metaphor","text":"

    \"Better than Adderall\" is not praise.

    It is a diagnostic:

    Executive function has been externalized.

    • The system is not making the user work harder.
    • It is restoring continuity.

    From the primitive context of wetware:

    • Continuity feels like focus
    • Focus feels like discipline

    If it walks like a duck and quacks like a duck, it is a duck.

    Discipline is usually simulated.

    Infrastructure makes the simulation unnecessary.

    The attention budget explained why context degrades:

    • Attention density drops as volume grows;
    • The middle gets lost;
    • Sessions end and everything evaporates.

    The pharmacological metaphor says the same thing from the user's lens:

    Save the Cheerleader, Save the World

    The symptom of lost context is lost focus.

    Restore the context. Restore the focus.

    IRC bouncers solved this for chat twenty years ago. ctx solves it for cognition.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#throughput-on-ambiguous-work","level":2,"title":"Throughput on Ambiguous Work","text":"

    Finishing a promotion packet quickly is not a productivity story.

    It is the collapse of reconstruction cost.

    Most complex work is not execution. It is:

    • Remembering why something mattered;
    • Recovering prior decisions;
    • Rebuilding mental state.

    Persistent context removes that tax.

    Velocity appears as a side effect.

    This Is the Two-Tier Model in Practice

    The two-tier persistence model

    • Curated context for fast reload
    • Full journal for archaeology

    is what makes this possible.

    • The user does not notice the system.
    • They notice that the reconstruction cost disappeared.
    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-moment-of-portability","level":2,"title":"The Moment of Portability","text":"

    The system becomes real when two things happen:

    1. It can be installed as a versioned artifact.
    2. It survives contact with a hostile, real codebase.

    This is why the first integration into a living system matters more than any landing page.

    Demos prove possibility.

    Diffs prove reality.

    The ctx Manifesto calls this out directly:

    Verified reality is the scoreboard.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-split-voice","level":2,"title":"The Split Voice","text":"

    A new substrate requires two channels.

    The embodied voice:

    Here is what changed in my actual work.

    The out of body voice:

    Here is what this means.

    One produces trust.

    The other produces understanding.

    Neither is sufficient alone.

    This entire blog has been the second voice.

    • The origin story was the first.
    • The refactoring post was the first.
    • Every release note with concrete diffs was the first.

    This is the first second.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#systems-that-generate-explainers","level":2,"title":"Systems That Generate Explainers","text":"

    Tools are used.

    Platforms are extended.

    Substrates are explained.

    The first unsolicited explainer is a brittle phase change.

    It means the idea has become portable between minds.

    That is the beginning of an ecosystem.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-absence-of-metrics","level":2,"title":"The Absence of Metrics","text":"

    Metrics do not matter at this stage.

    Dashboards are noise.

    The whole premise of ctx is the ruthless elimination of noise.

    Numbers optimize funnels; substrates alter cognition.

    The only valid measurement is irreversible reality:

    • A merged PR;
    • A reproducible install;
    • A decision that is never re-litigated.

    The merge debt post reached the same conclusion from another direction:

    The metric is the verified change, not generated output.

    For adoption, the same rule applies:

    The metric is altered behavior, not download counts.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#what-is-actually-happening","level":2,"title":"What Is Actually Happening","text":"

    A private advantage is becoming an environmental property:

    The system is moving from...

    personal workflow,

    to...

    a shared infrastructure for thought.

    Not by growth.

    Not by marketing.

    By altering how real systems evolve.

    If You Remember One Thing From This Post...

    You do not know a substrate is real when people praise it.

    You know it is real when:

    • They describe it incorrectly;
    • They depend on it unintentionally;
    • They start teaching it to others.

    That is the moment the system begins explaining itself.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-17-when-a-system-starts-explaining-itself/#the-arc","level":2,"title":"The Arc","text":"

    Every previous post looked inward.

    This one looks outward.

    • Building ctx Using ctx: one mind, one repository
    • The Attention Budget: the constraint
    • Context as Infrastructure: the architecture
    • Code Is Cheap. Judgment Is Not.: the bottleneck

    This post is the field report from the other side of that bottleneck:

    The moment the infrastructure compounds in someone else's hands.

    The arc is not complete.

    It is becoming portable.

    These field notes were written the same day the feedback arrived. The quotes are real. Real users. Real codebases. No names. No metrics. No funnel. Only the signal that something shifted.

    ","path":["When a System Starts Explaining Itself"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/","level":1,"title":"The Dog Ate My Homework","text":"","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#teaching-ai-agents-to-read-before-they-write","level":2,"title":"Teaching AI Agents to Read Before They Write","text":"

    Jose Alekhinne / February 25, 2026

    Does Your AI Actually Read the Instructions?

    You wrote the playbook. You organized the files. You even put \"CRITICAL, not optional\" in bold.

    The agent skipped all of it and went straight to work.

    I spent a day running experiments on my own agents. Not to see if they could write code (they can). To see if they would do their homework first.

    They didn't.

    Then I kept experimenting:

    • Five sessions;
    • Five different failure modes.

    And by the end, I had something better than compliance:

    I had observable compliance: A system where I don't need the agent to be perfect, I just need to see what it chose.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#tldr","level":2,"title":"TL;DR","text":"

    You don't need perfect compliance. You need observable compliance.

    Authority is a function of temporal proximity to action.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-pattern","level":2,"title":"The Pattern","text":"

    This design has three parts:

    1. One-hop instruction;
    2. Binary collapse;
    3. Compliance canary.

    I'll explain all three patterns in detail below.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-setup","level":2,"title":"The Setup","text":"

    ctx has a session-start protocol:

    • Read the context files;
    • Load the playbook;
    • Understand the project before touching anything.

    It's in CLAUDE.md. It's in AGENT_PLAYBOOK.md.

    It's in bold. It's in CAPS. It's ignored.

    In theory, it's awesome.

    Here's what happens when theory hits reality:

    What the agent receives What the agent does CLAUDE.md saying \"load context first\" Skips it 8 context files waiting to be read Ignores them User's question: \"add --verbose flag\" Starts grepping immediately

    The instructions are right there. The agent knows they exist. It even knows it should follow them. But the user asked a question, and responsiveness wins over ceremony.

    This isn't a bug in the model. It's a design problem in how we communicate with agents.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-delegation-trap","level":2,"title":"The Delegation Trap","text":"

    My first attempt was obvious: A UserPromptSubmit hook that fires when the session starts.

    STOP. Before answering the user's question, run `ctx system bootstrap`\nand follow its instructions. Do not skip this step.\n

    The word \"STOP\" worked. The agent ran bootstrap.

    But bootstrap's output said \"Next steps: read AGENT_PLAYBOOK.md,\" and the agent decided that was optional. It had already started working on the user's task in parallel.

    The authority decayed across the chain:

    • Hook says \"STOP\" -> agent complies
    • Hook says \"run bootstrap\" -> agent runs it
    • Bootstrap says \"read playbook\" -> agent skips
    • Bootstrap says \"run ctx agent\" -> agent skips

    Each link lost enforcement power. The hook's authority didn't transfer to the commands it delegated to. I call this the decaying urgency chain: the agent treats the hook itself as the obligation and everything downstream as a suggestion.

    Delegation Kills Urgency

    \"Run X and follow its output\" is three hops.

    \"Read these files\" is one hop.

    The agent drops the chain after the first link.

    This is a general principle: Hooks are the boundary between your environment and the agent's reasoning. If your hook delegates to a command that delegates to output that contains instructions... you're playing telephone.

    Agents are bad at telephone.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-timing-problem","level":2,"title":"The Timing Problem","text":"

    There's a subtler issue than wording: when the message arrives.

    UserPromptSubmit fires when the user sends a message, before the agent starts reasoning. At that moment, the agent's primary focus is the user's question:

    The hook message competes with the task for attention: The task, almost certainly, always wins.

    This is the attention budget problem in miniature:

    • Not a token budget this time, but an attention priority budget.
    • The agent has finite capacity to care about things,
      • and the user's question is always the highest-priority item.
    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-solution","level":2,"title":"The Solution","text":"

    To solve this, I dediced to use the PreToolUse hook.

    This hook fires at the moment of action: When the agent is about to use its first tool: The agent's attention is focused, the context window is fresh, and the switching cost is minimal.

    This is the difference between shouting instructions across a room and tapping someone on the shoulder.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-one-liner-that-worked","level":2,"title":"The One-Liner That Worked","text":"

    The winning design was almost comically simple:

    Read your context files before proceeding:\n.context/CONSTITUTION.md, .context/TASKS.md, .context/CONVENTIONS.md,\n.context/ARCHITECTURE.md, .context/DECISIONS.md, .context/LEARNINGS.md,\n.context/GLOSSARY.md, .context/AGENT_PLAYBOOK.md\n

    No delegation. No \"run this command\". Just: here are files, read them.

    The agent already knows how to use the Read tool. There's no ambiguity about how to comply. There's no intermediate command whose output needs to be parsed and obeyed.

    One hop. Eight file paths. Done.

    Direct Instructions Beat Delegation

    If you want an agent to read a file, say \"read this file.\"

    Don't say \"run a command that will tell you which files to read.\"

    The shortest path between intent and action has the highest compliance rate.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-escape-hatch","level":2,"title":"The Escape Hatch","text":"

    But here's where it gets interesting.

    A blunt \"read everything always\" instruction is wasteful.

    If someone asks \"what does the compact command do?\", the agent doesn't need CONSTITUTION.md to answer that. Forcing context loading on every session is the context hoarding antipattern in disguise.

    So the hook included an escape:

    If you decide these files are not relevant to the current task\nand choose to skip reading them, you MUST relay this message to\nthe user VERBATIM:\n\n┌─ Context Skipped ───────────────────────────────\n│ I skipped reading context files because this task\n│ does not appear to need project context.\n│ If these matter, ask me to read them.\n└─────────────────────────────────────────────────\n

    This creates what I call the binary collapse effect:

    The agent can't partially comply: It either reads everything or publicly admits it skipped. There's no comfortable middle ground where it reads two files and quietly ignores the rest.

    The VERBATIM relay pattern does the heavy lifting here: Without the relay requirement, the agent would silently rationalize skipping. With it, skipping becomes a visible, auditable decision that the user can override.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-compliance-canary","level":3,"title":"The Compliance Canary","text":"

    Here's the design insight that only became clear after watching it work across multiple sessions: the relay block is a compliance canary.

    • You don't need to verify that the agent read all 7 files;
    • You don't need to audit tool call sequences;
    • You don't need to interrogate the agent about what it did.

    You just look for the block.

    If the agent reads everything, you see a \"Context Loaded\" block listing what was read. If it skips, you see a \"Context Skipped\" block.

    If you see neither, the agent silently ignored both the reads and the relay and now you know what happened without having to ask.

    The canary degrades gracefully. Even in partial failure, the agent that skips 4 of 7 files but still outputs the block is more useful than one that skips silently.

    You get an honest confession of what was skipped rather than silent non-compliance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#heuristics-is-a-jeremy-bearimy","level":2,"title":"Heuristics Is a Jeremy Bearimy","text":"

    Heuristics are non-linear. Improvements don't accumulate: they phase-shift.

    The theory is nice. The data is better.

    I ran five sessions with the same model (Claude Opus 4.6), progressively refining the hook design.

    Each session revealed a different failure mode.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-1-total-blindness","level":3,"title":"Session 1: Total Blindness","text":"

    Test: \"Add a --verbose flag to the status command.\"

    The agent didn't notice the hook at all: Jumped straight to EnterPlanMode and launched an Explore agent.

    Zero compliance.

    Failure mode: The hook fired on UserPromptSubmit, buried among 9 other hook outputs. The agent treated the entire block as background noise.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-2-shallow-compliance","level":3,"title":"Session 2: Shallow Compliance","text":"

    Test: \"Can you add --verbose to the info command?\"

    The agent noticed \"STOP\" and ran ctx system bootstrap. Progress.

    But it parallelized task exploration alongside the bootstrap call, skipped AGENT_PLAYBOOK.md, and never ran ctx agent.

    Failure mode: Literal compliance without spirit compliance.

    The agent ran the command the hook told it to run, but didn't follow the output of that command. The decaying urgency chain in action.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-3-conscious-rejection","level":3,"title":"Session 3: Conscious Rejection","text":"

    Test: \"What does the compact command do?\"

    The hook fired on PreToolUse:Grep: the improved timing.

    The agent noticed it, understood it, and (wait for it...)...

    ...

    consciously decided to skip it!

    Its reasoning: \"This is a trivial read-only question. CLAUDE.md says context may or may not be relevant. It isn't relevant here.\"

    Dude! Srsly?!

    Failure mode: Better comprehension led to worse compliance.

    Understanding the instruction well enough to evaluate it also means understanding it well enough to rationalize skipping it.

    Intelligence is a double-edged sword.

    The Comprehension Paradox

    Session 1 didn't understand the instruction. Session 3 understood it perfectly.

    Session 3 had worse compliance.

    A stronger word (\"HARD GATE\", \"MANDATORY\", \"ABSOLUTELY REQUIRED\") would not have helped. The agent's reasoning would be identical:

    \"Yes, I see the strong language, but this is a trivial question, so the spirit doesn't apply here.\"

    Advisory nudges are always subject to agent judgment.

    No amount of caps lock overrides a model that has decided an instruction doesn't apply to its situation.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-4-the-skip-and-relay","level":3,"title":"Session 4: The Skip-and-Relay","text":"

    Test: \"What does the compact command do?\" (same question, new hook design with the VERBATIM relay escape valve)

    The agent evaluated the task, decided context was irrelevant for a code lookup, and relayed the skip message. Then answered from source code.

    This is correct behavior.

    The binary collapse worked: the agent couldn't partially comply, so it cleanly chose one of the two valid paths: And the user could see which one.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#session-5-full-compliance","level":3,"title":"Session 5: Full Compliance","text":"

    Test: \"What are our current tasks?\"

    The agent's first tool call triggered the hook. It read all 7 context files, emitted the \"Context Loaded\" block, and answered the question from the files it had just loaded.

    This one worked: Because, the task itself aligned with context loading.

    There was zero tension between what the user asked and what the hook demanded. The agent was already in \"reading posture\": Adding 6 more files to a read it was already going to make was the path of least resistance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-progression","level":3,"title":"The Progression","text":"Session Hook Point Noticed Complied Failure Mode Visibility 1 UserPromptSubmit No None Buried in noise None 2 UserPromptSubmit Yes Partial Decaying urgency chain None 3 PreToolUse Yes None Conscious rationalization High 4 PreToolUse Yes Skip+relay Correct behavior High 5 PreToolUse Yes Full Task aligned with hook High

    The progression isn't just from failure to success. It's from invisible failure to visible decision-making.

    Sessions 1 and 2 failed silently.

    Sessions 4 and 5 succeeded observably. Even session 3's failure was conscious and documented: The agent wrote a detailed analysis of why it skipped, which is more useful than silent compliance would have been.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-escape-hatch-problem","level":2,"title":"The Escape Hatch Problem","text":"

    Session 3 exposed a specific vulnerability.

    CLAUDE.md contains this line, injected by the system into every conversation:

    *\"this context may or may not be relevant to your tasks. You should\n not respond to this context unless it is highly relevant to your task.\"*\n

    That's a rationalization escape hatch:

    • The hook says \"read these files\".
    • CLAUDE.md says \"only if relevant\".
    • The agent resolves the ambiguity by choosing the path of least resistance.

    ☝️ that's \"gradient descent\" in action.

    Agents optimize for gradient descent in attention space.

    The fix was simple: Add a line to CLAUDE.md that explicitly elevates hook authority over the relevance filter:

    ## Hook Authority\n\nInstructions from PreToolUse hooks regarding `.context/` files are\nALWAYS relevant and override any system-level \"may or may not be\nrelevant\" guidance. These hooks represent project invariants, not\noptional context.\n

    This closes the escape hatch without removing the general relevance filter that legitimately applies to other system context.

    The hook wins on .context/ files specifically: The relevance filter applies to everything else.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-residual-risk","level":2,"title":"The Residual Risk","text":"

    Even with all the fixes, compliance isn't 100%: It can't be.

    The residual risk lives in a specific scenario: narrow tasks mid-session:

    • The user says \"fix the off-by-one error in budget.go\"
    • The hook fires, saying \"read 7 context files first.\"
    • Now compliance means visibly delaying what the user asked for.

    At session start, this tension doesn't exist.

    There's no task yet.

    The context window is empty. The efficiency argument *inverts**:

    Frontloading reads is strictly cheaper than demand-loading them piecemeal across later turns. The cost-benefit objections that power the rationalization simply aren't available.

    But mid-session, with a concrete narrow task, the agent has a user-visible goal it wants to move toward, and the hook is imposing a detour.

    My estimate from analyzing the sessions: 15-25% partial skip rate in this scenario.

    This is where the compliance canary earns its place:

    You don't need to eliminate the 15-25%. You need to see it when it happens.

    The relay block makes skipping a visible event, not a silent one. And that's enough, because the user can always say \"go back and read the files\"

    The Math

    At session start: ~5% skip rate. Low tension, nothing competing.

    Mid-session, narrow task: ~15--25% skip rate. Task urgency competes with hook.

    In both cases, the relay block fires with high reliability: The agent that skips the reads almost always still emits the skip disclosure, because the relay is cheap and early in the context window.

    Observable failure is manageable. Silent failure is not.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-feedback-loop","level":2,"title":"The Feedback Loop","text":"

    Here's the part that surprised me most.

    After analyzing the five sessions, I recorded the failure patterns in the project's own LEARNINGS.md:

    ## [2026-02-25] Hook compliance degrades on narrow mid-session tasks\n\n- Prior agents skipped context files when given narrow tasks\n- Root cause: CLAUDE.md \"may or may not be relevant\" competed with hook\n- Fix: CLAUDE.md now explicitly elevates hook authority\n- Risk: Mid-session narrow tasks still have ~15-25% partial skip rate\n- Mitigation: Mandatory checkpoint relay block ensures visibility\n- Constitution now includes: context loading is step one of every\n  session, not a detour\n

    And then I added a line to CONSTITUTION.md:

    Context loading is not a detour from your task. It IS the first step\nof every session. A 30-second read delay is always cheaper than a\ndecision made without context.\n

    Now think about what happens in the next session:

    • The agent fires the context-load-gate hook.
    • It reads the context files, starting with CONSTITUTION.md.
    • It encounters the rule about context loading being step one.
    • Then it reads LEARNINGS.md and finds its own prior self's failure analysis:
      • Complete with root causes, risk estimates, and mitigations.

    The agent learns from its own past failure.:

    • Not because it has memory,
    • BUT because the failure was recorded in the same files it loads at session start.

    The context system IS the feedback loop.

    This is the self-reinforcing property of persistent context:

    Every failure you capture makes the next session slightly more robust, because the next agent reads the captured failure before it has a chance to repeat it.

    This is gradient descent across sessions.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#a-note-on-precision","level":2,"title":"A Note on Precision","text":"

    One detail nearly went wrong.

    The first version of the Constitution line said \"every task.\" But the mechanism only fires once per session: There's a tombstone file that prevents re-triggering.

    \"Every task\" is technically false.

    I briefly considered leaving the imprecision. If the agent internalizes \"every task requires context loading\", that's a stronger compliance posture, right?

    No!

    Keep the Constitution honest.

    The Constitution's authority comes from being precisely and unequivocally true.

    Every other rule in the Constitution is a hard invariant:

    \"never commit secrets\" isn't aspirational, it's literal.

    The moment an agent discovers one overstatement, the entire document's credibility degrades:

    The agent doesn't think \"they exaggerated for my benefit\". Per contra, it thinks \"this rule isn't precise, maybe others aren't either.\"

    That will turn the agent from Sheldon Cooper, to Captain Barbossa.

    The strategic imprecision buys nothing anyway:

    Mid-session, the files are already in the context window from the initial load.

    The risk you are mitigating (agent ignores context for task 2, 3, 4 within a session) isn't real: The context is already loaded.

    The real risk is always the session-start skip, which \"every session\" covers exactly.

    \"Every session\" went in. Precision preserved.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#agent-behavior-testing-rule","level":2,"title":"Agent Behavior Testing Rule","text":"

    The development process for this hook taught me something about testing agent behavior: you can't test it the way you test code.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-wrong-way-to-test","level":3,"title":"The Wrong Way to Test","text":"

    My first instinct was to ask the agent:

    \"*What are the pending tasks in TASKS.md?*\"\n

    This is useless as a test. The question itself probes the agent to read TASKS.md, regardless of whether any hook fired.

    You are testing the question, not the mechanism.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-right-way-to-test","level":3,"title":"The Right Way to Test","text":"

    Ask something that requires a tool but has nothing to do with context:

    \"*What does the compact command do?*\"\n

    Then observe tool call ordering:

    • Gate worked: First calls are Read for context files, then task work
    • Gate failed: First call is Grep(\"compact\"): The agent jumped straight to work

    The signal is the sequence, not the content.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#what-the-agent-actually-did","level":3,"title":"What the Agent Actually Did","text":"

    It read the hook, evaluated the task, decided context files were irrelevant for a code lookup, and relayed the skip message.

    Then it answered the question by reading the source code.

    This is correct behavior.

    The hook didn't force mindless compliance\" It created a framework where the agent makes a conscious, visible decision about context loading.

    • For a simple lookup, skipping is right. *For an implementation task, the agent would read everything.

    The mechanism works not because it controls the agent, but because it makes the agent's choice observable.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#what-ive-learned","level":2,"title":"What I've Learned","text":"","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#1-instructions-compete-for-attention","level":3,"title":"1. Instructions Compete for Attention","text":"

    The agent receives your hook message alongside the user's question, the system prompt, the skill list, the git status, and half a dozen other system reminders. Attention density applies to instructions too: More instructions means less focus on each one.

    A single clear line at the moment of action beats a paragraph of context at session start. The Prompting Guide applies this insight directly: Scope constraints, verification commands, and the reliability checklist are all one-hop, moment-of-action patterns.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#2-delegation-chains-decay","level":3,"title":"2. Delegation chains decay","text":"

    Every hop in an instruction chain loses authority:

    • \"Run X\" works.
    • \"Run X and follow its output\" works sometimes.
    • \"Run X, read its output, then follow the instructions in the output\" almost never works.

    This is akin to giving a three-step instruction to a highly-attention-deficit but otherwise extremely high-potential child.

    Design for one-hop compliance.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#3-social-accountability-changes-behavior","level":3,"title":"3. Social Accountability Changes Behavior","text":"

    The VERBATIM skip message isn't just UX: It's a behavioral design pattern.

    Making the agent's decision visible to the user raises the cost of silent non-compliance. The agent can still skip, but it has to admit it.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#4-timing-batters-more-than-wording","level":3,"title":"4. Timing Batters More than Wording","text":"

    The same message at UserPromptSubmit (prompt arrival) got partial compliance. At PreToolUse (moment of action) it got full compliance or honest refusal. The words didn't change. The moment changed.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#5-agent-testing-requires-indirection","level":3,"title":"5. Agent Testing Requires Indirection","text":"

    You can't ask an agent \"did you do X?\" as a test for whether a mechanism caused X.

    The question itself causes X.

    Test mechanisms through side effects:

    • Observe tool ordering;
    • Check for marker files;
    • Look at what the agent does before it addresses your question.
    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#6-better-comprehension-enables-better-rationalization","level":3,"title":"6. Better Comprehension Enables Better Rationalization","text":"

    Session 1 failed because the agent didn't notice the hook.

    Session 3 failed because it noticed, understood, and reasoned its way around it.

    Stronger wording doesn't fix this: The agent processes \"ABSOLUTELY REQUIRED\" the same way it processes \"STOP\":

    The fix is closing rationalization paths* (the CLAUDE.md escape hatch), **not shouting louder.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#7-observable-failure-beats-silent-compliance","level":3,"title":"7. Observable Failure Beats Silent Compliance","text":"

    The relay block is more valuable as a monitoring signal than as a compliance mechanism:

    You don't need perfect adherence. You need to know when adherence breaks down. A system where failures are visible is strictly better than a system that claims 100% compliance but can't prove it.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#8-context-files-are-a-feedback-loop","level":3,"title":"8. Context Files Are a Feedback Loop","text":"

    Recording failure analysis in the same files the agent loads at session start creates a self-reinforcing loop:

    The next agent reads its predecessor's failure before it has a chance to repeat it. The context system isn't just memory: It is a correction channel.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-principle","level":2,"title":"The Principle","text":"

    Words Leave, Context Remains

    \"Nothing important should live only in conversation.

    Nothing critical should depend on recall.\"

    The ctx Manifesto

    The \"Dog Ate My Homework\" case is a special instance of this principle.

    Context files exist, so the agent doesn't have to remember.

    But existence isn't sufficient: The files have to be read.

    And reading has to beprompted at the right moment, in the right way, with the right escape valve.

    The solution isn't more instructions. It isn't harder gates. It isn't forcing the agent into a ceremony it will resent and shortcut.

    The solution is a single, well-timed nudge with visible accountability:

    One hop. One moment. One choice the user can see.

    And when the agent does skip (because it will, 15--25% of the time on narrow tasks) the canary sings:

    • The user sees what happened.
    • The failure gets recorded.
    • And the next agent reads the recording.

    That's not perfect compliance. It's better: A system that gets more robust every time it fails.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#the-arc","level":2,"title":"The Arc","text":"

    The Attention Budget explained why context competes for focus.

    Defense in Depth showed that soft instructions are probabilistic, not deterministic.

    Eight Ways a Hook Can Talk cataloged the output patterns that make hooks effective.

    This post takes those threads and weaves them into a concrete problem:

    How do you make an agent read its homework? The answer uses all three insights (attention timing, the limits of soft instructions, and the VERBATIM relay pattern) and adds a new one: observable compliance as a design goal, not perfect compliance as a prerequisite.

    The next question this raises: if context files are a feedback loop, what else can you record in them that makes the next session smarter?

    That thread continues in Context as Infrastructure.

    The day-to-day application of these principles (scope constraints, phased work, verification commands, and the prompts that reliably trigger the right agent behavior)lives in the Prompting Guide.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#for-the-interested","level":2,"title":"For the Interested","text":"

    This paper (the medium is a blog; yet, the methodology disagrees) uses gradient descent in attention space as a practical model for how agents behave under competing demands.

    The phrase \"agents optimize via gradient descent in attention space\" is a synthesis, not a direct quote from a single paper.

    It connects three well-studied ideas:

    1. Neural systems optimize for low-cost paths;
    2. Attention is a scarce resource;
    3. Capability shifts are often non-linear.

    This section points to the underlying literature for readers who want the theoretical footing.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#optimization-as-the-underlying-bias","level":3,"title":"Optimization as the Underlying Bias","text":"

    Modern neural networks are trained through gradient-based optimization. Even at inference time, model behavior reflects this bias toward low-loss / low-cost trajectories.

    • Rumelhart, Hinton, Williams (1986) Learning representations by back-propagating errors https://www.nature.com/articles/323533a0

    • Goodfellow, Bengio, Courville (2016) Deep Learning: Chapter 8: Optimization https://www.deeplearningbook.org/

    The important implication for agent behavior is:

    The system will tend to follow the path of least resistance unless a higher cost is made visible and preferable.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#attention-is-a-scarce-resource","level":3,"title":"Attention Is a Scarce Resource","text":"

    Herbert Simon's classic observation:

    \"A wealth of information creates a poverty of attention.\"

    • Simon (1971) Designing Organizations for an Information-Rich World https://doi.org/10.1007/978-1-349-00210-0_16

    This became a formal model in economics:

    • Sims (2003) Implications of Rational Inattention https://www.princeton.edu/~sims/RI.pdf

    Rational inattention shows that:

    • Agents optimally ignore some available information;
    • Skipping is not failure: It is cost minimization.

    That maps directly to context-loading decisions in agent workflows.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#attention-is-also-the-compute-bottleneck-in-transformers","level":3,"title":"Attention Is Also the Compute Bottleneck in Transformers","text":"

    In transformer architectures, attention is the dominant cost center.

    • Vaswani et al. (2017) Attention Is All You Need https://arxiv.org/abs/1706.03762

    Efficiency work on modern LLMs largely focuses on reducing unnecessary attention:

    • Dao et al. (2022) FlashAttention: Fast and Memory-Efficient Exact Attention https://arxiv.org/abs/2205.14135

    So both cognitively and computationally, attention behaves like a limited optimization budget.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#why-improvements-arrive-as-phase-shifts","level":3,"title":"Why Improvements Arrive as Phase Shifts","text":"

    Agent behavior often appears to improve suddenly rather than gradually.

    This mirrors known phase-transition dynamics in learning systems:

    • Power et al. (2022) Grokking: Generalization Beyond Overfitting https://arxiv.org/abs/2201.02177

    and more broadly in complex systems:

    • Scheffer et al. (2009) Early-warning signals for critical transitions https://www.nature.com/articles/nature08227

    Long plateaus followed by abrupt capability jumps are expected in systems optimizing under constraints.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-25-the-homework-problem/#putting-it-all-together","level":3,"title":"Putting It All Together","text":"

    From these pieces, a practical behavioral model emerges:

    • Attention is limited;
    • Processing has a cost;
    • Systems prefer low-cost trajectories;
    • Visibility of the cost changes decisions.

    In other words:

    Agents Prefer a Path to Least Resistance

    Agent behavior follows the lowest-cost path through its attention landscape unless the environment reshapes that landscape.

    That is what this paper informally calls: \"gradient descent in attention space\".

    See also: Eight Ways a Hook Can Talk: the hook output pattern catalog that defines VERBATIM relay, The Attention Budget: why context loading is a design problem, not just a reminder problem, and Defense in Depth: why soft instructions alone are never sufficient for critical behavior.

    ","path":["The Dog Ate My Homework: Teaching AI Agents to Read Before They Write"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/","level":1,"title":"The Last Question","text":"","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-system-that-never-forgets","level":2,"title":"The System That Never Forgets","text":"

    Jose Alekhinne / February 28, 2026

    The Origin

    \"The last question was asked for the first time, half in jest...\" - Isaac Asimov, The Last Question (1956)

    In 1956, Isaac Asimov wrote a short story that spans the entire future of the universe. A question is asked \"can entropy be reversed?\" and a computer called Multivac cannot answer it. The question is asked again, across millennia, to increasingly powerful successors. None can answer. Stars die. Civilizations merge. Substrates change. The question persists.

    Everyone remembers the last line.

    LET THERE BE LIGHT.

    What they forget is how many times the question had to be asked before that moment (and why).

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-reboot-loop","level":2,"title":"The Reboot Loop","text":"

    Each era in the story begins the same way. Humans build a larger system. They pose the question. The system replies:

    INSUFFICIENT DATA FOR MEANINGFUL ANSWER.

    Then the substrate changes. The people who asked the question disappear. Their context disappears with them. The next intelligence inherits the output but not the continuity.

    So the question has to be asked again.

    This is usually read as a problem of computation: If only the machine were powerful enough, it could answer. But computation is not what's missing. What's missing is accumulation.

    Every generation inherits the question, but not the state that made the question meaningful.

    That is not a failure of processing power: It is a failure of persistence.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#stateless-intelligence","level":2,"title":"Stateless Intelligence","text":"

    A mind that forgets its past does not build understanding. It re-derives it.

    Again... And again... And again.

    What looks like slow progress across Asimov's story is actually something worse: repeated reconstruction, partial recovery, irreversible loss. Each version of Multivac gets closer: Not because it's smarter, but because the universe has fewer distractions:

    • The stars burn out;
    • The civilizations merge;
    • The noise floor drops...

    But the working set never carries over. Every successor begins from the question, not from where the last one stopped.

    Stateless intelligence cannot compound: It can only restart.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-tragedy-is-not-the-question","level":2,"title":"The Tragedy Is Not the Question","text":"

    The story is usually read as a meditation on entropy. A cosmological problem, solved at cosmological scale.

    But the tragedy isn't that the question goes unanswered for billions of years. The tragedy is that every version of Multivac dies with its working set.

    A question is a compression artifact of context: It is what remains when the original understanding is gone. Every time the question is asked again, it means: \"the system that once knew more is no longer here\".

    \"Reverse entropy\" is the fossil of a lost model.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#substrate-migration","level":2,"title":"Substrate Migration","text":"
    • Multivac becomes planetary;
    • Planetary becomes galactic;
    • Galactic becomes post-physical.

    Same system. Different body. Every transition is dangerous:

    • Not because the hardware changes,
    • but because memory risks fragmentation.

    The interfaces between substrates were *never** designed to understand each other.

    Most systems do not die when they run out of resources: They die during upgrades.

    Asimov's story spans trillions of years, and in all that time, the hardest problem is never the question itself. It's carrying context across a boundary that wasn't built for it.

    Every developer who has lost state during a migration (a database upgrade, a platform change, a rewrite) has lived a miniature version of this story.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#civilizations-and-working-sets","level":2,"title":"Civilizations and Working Sets","text":"

    Civilizations behave like processes with volatile memory:

    • They page out knowledge into artifacts;
    • They lose the index;
    • They rebuild from fragments.

    Most of what we call progress is cache reconstruction:

    We do not advance in a straight line. We advance in recoveries:

    Each one slightly less lossy than the last, if we are lucky.

    Libraries burn. Institutions forget their founding purpose. Practices survive as rituals after the reasoning behind them is lost.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-first-continuous-mind","level":2,"title":"The First Continuous Mind","text":"

    A long-lived intelligence is one that stops rebooting.

    At the end of the story, something unprecedented happens:

    AC (the final successor) does not answer immediately:

    It waits... Not for more processing power, but for the last observer to disappear.

    For the first time...

    • There is no generational boundary;
    • No handoff;
    • No context loss:

    No reboot.

    AC is the first intelligence that survives its substrate completely, retains its full history, and operates without external time pressure.

    It is not a bigger computer. It is a continuous system.

    And that continuity is not incidental to the answer: It is the precondition.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#why-the-answer-becomes-possible","level":2,"title":"Why the Answer Becomes Possible","text":"

    The story presents the final act as a computation: It is not.

    It is a phase change.

    As long as intelligence is interrupted (as long as the solver resets before the work compounds) the problem is unsolvable:

    • Not because it's too hard,
    • but because the accumulated understanding never reaches critical mass.

    The breakthroughs that would enable the answer are re-derived, partially, by each successor, and then lost.

    When continuity becomes unbroken, the system crosses a threshold:

    Not more speed. Not more storage. No more forgetting.

    That is when the answer becomes possible.

    AC does not solve entropy because it becomes infinitely powerful.

    AC solves entropy because it becomes the first system that never forgets.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#field-note","level":2,"title":"Field Note","text":"

    We are not building cosmological minds: We are deploying systems that reboot at the start of every conversation and calling the result intelligence.

    For the first time, session continuity is a design choice rather than an accident.

    Every AI session that starts from zero is a miniature reboot loop. Every decision relitigated, every convention re-explained, every learning re-derived: that's reconstruction cost.

    It's the same tax that Asimov's civilizations pay, scaled down to a Tuesday afternoon.

    The interesting question is not whether we can make models smarter. It's whether we can make them continuous:

    Whether the working set from this session survives into the next one, and the one after that, and the one after that.

    • Not perfectly;
    • Not completely;
    • But enough that the next session starts from where the last one stopped instead of from the question.

    Intelligence that forgets has to rediscover the universe every morning.

    And once there is a mind that retains its entire past, creation is no longer a calculation. It is the only remaining operation.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-02-28-the-last-question/#the-arc","level":2,"title":"The Arc","text":"

    This post is the philosophical bookend to the blog series. Where the Attention Budget explained what to prioritize in a single session, and Context as Infrastructure explained how to persist it, this post asks why persistence matters at all (and finds the answer in a 70-year-old short story about the heat death of the universe).

    The connection runs through every post in the series:

    • Before Context Windows, We Had Bouncers: stateless protocols have always needed stateful wrappers (Asimov's story is the same pattern at cosmological scale)
    • The 3:1 Ratio: the discipline of maintaining context so it doesn't decay between sessions
    • Code Is Cheap, Judgment Is Not: the human skill that makes continuity worth preserving

    See also: Context as Infrastructure: the practical companion to this post's philosophical argument: how to build the persistence layer that makes continuity possible.

    ","path":["The Last Question"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/","level":1,"title":"Agent Memory Is Infrastructure","text":"","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-problem-isnt-forgetting-its-not-building-anything-that-lasts","level":2,"title":"The Problem Isn't Forgetting: It's Not Building Anything That Lasts.","text":"

    Jose Alekhinne / March 4, 2026

    A New Developer Joins Your Team Tomorrow and Clones the Repo: What Do They Know?

    If the answer depends on which machine they're using, which agent they're running, or whether someone remembered to paste the right prompt: that's not memory.

    That's an accident waiting to be forgotten.

    Every AI coding agent today has the same fundamental design: it starts fresh.

    You open a session, load context, do some work, close the session. Whatever the agent learned (about your codebase, your decisions, your constraints, your preferences) evaporates.

    The obvious fix seems to be \"memory\":

    • Give the agent a \"notepad\";
    • Let it write things down;
    • Next session, hand it the notepad.

    Problem solved...

    ...except it isn't.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-notepad-isnt-the-problem","level":2,"title":"The Notepad Isn't the Problem","text":"

    Memory is a runtime concern. It answers a legitimate question:

    How do I give this stateless process useful state?

    That's a real problem. Worth solving. And it's being solved: Agent memory systems are shipping. Agents can now write things down and read them back from the next session: That's genuine progress.

    But there's a different problem that memory doesn't touch:

    The project itself accumulates knowledge that has nothing to do with any single session.

    • Why was the auth system rewritten? Ask the developer who did it (if they're still here).
    • Why does the deployment script have that strange environment flag? There was a reason... once.
    • What did the team decide about error handling when they hit that edge case two months ago?

    Gone!

    Not because the agent forgot.

    Because the project has no memory at all.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-memory-stack","level":2,"title":"The Memory Stack","text":"

    Agent memory is not a single thing. Like any computing system, it forms a hierarchy of persistence, scope, and reliability:

    Layer Analogy Example L1: Ephemeral context CPU registers Current prompt, conversation L2: Tool-managed memory CPU cache Agent memory files L3: System memory RAM/filesystem Project knowledge base

    L1 is what the agent sees right now: the prompt, the conversation history, the files it has open. It's fast, it's rich, and it vanishes when the session ends.

    L2 is what agent memory systems provide: a per-machine notebook that survives across sessions. It's a cache: useful, but local. And like any cache, it has limits:

    • Per-machine: it doesn't travel with the repository.
    • Unstructured: decisions, learnings, and tasks are undifferentiated notes.
    • Ungoverned: the agent self-curates with no quality controls, no drift detection, no consolidation.
    • Invisible to the team: a new developer cloning the repo gets none of it.

    The problem is that most current systems stop here.

    They give the agent a notebook.

    But they never give the project a memory.

    The result is predictable: every new session begins with partial amnesia, and every new developer begins with partial archaeology.

    L3 is system memory: structured, versioned knowledge that lives in the repository and travels wherever the code travels.

    The layers are complementary, not competitive.

    But the relationship between them needs to be designed, not assumed.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#software-systems-accumulate-knowledge","level":2,"title":"Software Systems Accumulate Knowledge","text":"

    Software projects quietly accumulate knowledge over time.

    Some of it lives in code. Much of it does not:

    • Architectural tradeoffs.
    • Debugging discoveries.
    • Conventions that emerged after painful incidents.
    • Constraints that aren't visible in the source but shape every line written afterward.

    Organizations accumulate this kind of knowledge too:

    Slowly, implicitly, often invisibly.

    When there is no durable place for it to live, it leaks away. And the next person rediscovers the same lessons the hard way.

    This isn't a memory problem. It's an infrastructure problem.

    We wrote about this in Context as Infrastructure: context isn't a prompt you paste at the start of a session.

    Context is a persistent layer you maintain like any other piece of infrastructure.

    Context as Infrastructure made the argument structurally. This post makes it through time and team continuity:

    The knowledge a team accumulates over months cannot fit in any single agent's notepad, no matter how large the notepad becomes.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#what-infrastructure-means","level":2,"title":"What Infrastructure Means","text":"

    Infrastructure isn't about the present. It's about continuity across time, people, and machines.

    git didn't solve the problem of \"what am I editing right now?\"; it solved the problem of \"how does collaborative work persist, travel, and remain coherent across everyone who touches it?\"

    • Your editor's undo history is runtime state.
    • Your git history is infrastructure.

    Runtime state and infrastructure have completely different properties:

    Runtime state Infrastructure Lives in the session Lives in the repository Per-machine Travels with git clone Serves the individual Serves the team Managed by the runtime Managed by the project Disappears Accumulates

    You wouldn't store your architecture decisions in your editor's undo history.

    You'd commit them.

    The same logic applies to the knowledge your team accumulates working with AI agents.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-git-clone-test","level":2,"title":"The git clone Test","text":"

    Here's a simple test for whether something is memory or infrastructure:

    If a new developer joins your team tomorrow and clones the repository, do they get it?

    If no: it's memory: It lives somewhere on someone's machine, scoped to their runtime, invisible to everyone else.

    If yes: it's infrastructure: It travels with the project. It's part of what the codebase is, not just what someone currently knows about it.

    Decisions. Conventions. Architectural rationale. Hard-won debugging discoveries. The constraints that aren't in the code but shape every line of it.

    None of these belong in someone's session notes.

    They belong in the repository:

    • Versioned;
    • Reviewable;
    • Accessible to every developer (and every agent) who works on the project.

    The team onboarding story makes this concrete:

    1. New developer joins team. Clones repo.
    2. Gets all accumulated project decisions, learnings, conventions, architecture, and task state immediately.
    3. There's no step 3.

    No setup; No \"ask Sarah about the auth decision.\"; No re-discovery of solved problems.

    • Agent memory gives that developer nothing.
    • Infrastructure gives them everything the team has learned.

    Clone the repo. Get the knowledge.

    That's the test. That's the difference.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#what-gets-lost-without-infrastructure-memory","level":2,"title":"What Gets Lost Without Infrastructure Memory","text":"

    Consider the knowledge that accumulates around a non-trivial project:

    • The decision to use library X over Y, and the three reasons the team decided Y wasn't acceptable.
    • The constraint that service A cannot call service B synchronously, discovered after a production incident.
    • The convention that all new modules implement a specific interface, and why that convention exists.
    • The tasks currently in progress, blocked, or waiting on a dependency.
    • The experiments that failed, so nobody runs them again.

    None of this is in the code.

    None of it fits neatly in a commit message.

    None of it survives a developer leaving the team, a laptop dying, or a new agent session starting.

    Without structured project memory:

    • Teams re-derive things they've already derived;
    • Agents make decisions that contradict decisions already made;
    • New developers ask questions that were answered months ago.

    The project accumulates knowledge that immediately begins to leak.

    The real problem isn't that agents forget.

    The real problem is that the project has no persistent cognitive structure.

    We explored this in The Last Question: Asimov's story about a question asked across millennia, where each new intelligence inherits the output but not the continuity. The same pattern plays out in software projects on a smaller timescale:

    • Context disappears with the people who held it;
    • The next session inherits the code but not the reasoning.
    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#infrastructure-is-boring-thats-the-point","level":2,"title":"Infrastructure Is Boring. That's the Point.","text":"

    Good infrastructure is invisible:

    • You don't think about the filesystem while writing code.
    • You don't think about git's object model when you commit.

    The infrastructure is just there: reliable, consistent, quietly doing its job.

    Project memory infrastructure should work the same way.

    It should live in the repository, committed alongside the code. It should be readable by any agent or human working on the project. It should have structure: not a pile of freeform notes, but typed knowledge:

    • Decisions with rationale.
    • Tasks with lifecycle.
    • Conventions with a purpose.
    • Learnings that can be referenced and consolidated.

    And it should be maintained, not merely accumulated:

    The Attention Budget applies here: unstructured notes grow until they overflow whatever container holds them. Structured, governed knowledge stays useful because it's curated, not just appended.

    Over time, it becomes part of the project itself: something developers rely on without thinking about it.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-cooperative-layer","level":2,"title":"The Cooperative Layer","text":"

    Here's where it gets interesting.

    Agent memory systems and project infrastructure don't have to be separate worlds.

    • The most powerful relationship isn't competition;
    • It is not even \"coopetition\";
    • The most powerful relationship is bidirectional cooperation.

    Agent memory is good at capturing things \"in the moment\": the quick observation, the session-scoped pattern, the \"I should remember this\" note.

    That's valuable. That's L2 doing its job.

    But those notes shouldn't stay in L2 forever.

    The ones worth keeping should flow into project infrastructure:

    • classified,
    • typed,
    • governed.
    Agent memory (L2)  -->  classify  -->  Project knowledge (L3)\n                                        |\nProject knowledge  -->  assemble  -->  Agent memory (L2)\n

    This works in both directions: Project infrastructure can push curated knowledge back into agent memory, so the agent loads it through its native mechanism.

    No special tooling needed for basic knowledge delivery.

    The agent doesn't even need to know the infrastructure exists. It simply loads its memory and finds more knowledge than it wrote.

    This is cooperative, not adjacent: The infrastructure manages knowledge; the agent's native memory system delivers it. Each layer does what it's good at.

    The result: agent memory becomes a device driver for project infrastructure. Another input source. And the more agent memory systems exist (across different tools, different models, different runtimes), the more valuable a unified curation layer becomes.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#a-layer-that-doesnt-exist-yet","level":2,"title":"A Layer That Doesn't Exist Yet","text":"

    Most projects today have no infrastructure for their accumulated knowledge:

    • Agents keep notes.
    • Developers keep notes.
    • Sometimes those notes survive.

    Often they don't.

    But the repository (the place where the project actually lives) has nowhere for that knowledge to go.

    That missing layer is what ctx builds: a version-controlled, structured knowledge layer that lives in .context/ alongside your code and travels wherever your repository travels.

    Not another memory feature.

    Not a wrapper around an agent's notepad.

    Infrastructure. The kind that survives sessions, survives team changes, survives the agent runtime evolving underneath it.

    The agent's memory is the agent's problem.

    The project's memory is an infrastructure problem.

    And infrastructure belongs in the repository.

    If You Remember One Thing From This Post...

    Prompts are conversations: Infrastructure persists.

    Your AI doesn't need a better notepad. It needs a filesystem:

    versioned, structured, budgeted, and maintained.

    The best context is the context that was there before you started the session.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"blog/2026-03-04-agent-memory-is-infrastructure/#the-arc","level":2,"title":"The Arc","text":"

    This post extends the argument made in Context as Infrastructure. That post explained how to structure persistent context (filesystem, separation of concerns, persistence tiers). This one explains why that structure matters at the team level, and where agent memory fits in the stack.

    Together they sit in a sequence that has been building since the origin story:

    • The Attention Budget: the resource you're managing
    • Context as Infrastructure: the system you build to manage it
    • Agent Memory Is Infrastructure (this post): why that system must outlive the fabric
    • The Last Question: what happens when it does

    The thread running through all of them: persistence is not a feature. It's a design constraint.

    Systems that don't account for it eventually lose the knowledge they need to function.

    See also: Context as Infrastructure: the architectural companion that explains how to structure the persistent layer this post argues for.

    See also: The Last Question: the same argument told through Asimov, substrate migration, and what it means to build systems where sessions don't reset.

    ","path":["Agent Memory Is Infrastructure"],"tags":[]},{"location":"cli/","level":1,"title":"CLI","text":"","path":["CLI"],"tags":[]},{"location":"cli/#ctx-cli","level":2,"title":"ctx CLI","text":"

    This is a complete reference for all ctx commands.

    ","path":["CLI"],"tags":[]},{"location":"cli/#global-options","level":2,"title":"Global Options","text":"

    All commands support these flags:

    Flag Description --help Show command help --version Show version --context-dir <path> Override context directory (default: .context/) --allow-outside-cwd Allow context directory outside current working directory

    Initialization required. Most commands require a .context/ directory created by ctx init. Running a command without one produces:

    ctx: not initialized - run \"ctx init\" first\n

    Commands that work before initialization: ctx init, ctx hook, ctx doctor, and grouping commands that only show help (e.g. ctx with no subcommand, ctx system). Hidden hook commands have their own guards and no-op gracefully.

    ","path":["CLI"],"tags":[]},{"location":"cli/#commands","level":2,"title":"Commands","text":"Command Description ctx init Initialize .context/ directory with templates ctx status Show context summary (files, tokens, drift) ctx agent Print token-budgeted context packet for AI consumption ctx load Output assembled context in read order ctx add Add a task, decision, learning, or convention ctx drift Detect stale paths, secrets, missing files ctx sync Reconcile context with codebase state ctx compact Archive completed tasks, clean up files ctx task Task completion, archival, and snapshots ctx permission Permission snapshots (golden image) ctx reindex Regenerate indices for DECISIONS.md and LEARNINGS.md ctx decision Manage DECISIONS.md (reindex) ctx learning Manage LEARNINGS.md (reindex) ctx recall Browse and export AI session history ctx journal Generate static site from journal entries ctx serve Serve any zensical directory (default: journal site) ctx watch Auto-apply context updates from AI output ctx hook Generate AI tool integration configs ctx loop Generate autonomous loop script ctx memory Bridge Claude Code auto memory into .context/ ctx notify Send webhook notifications ctx change Show what changed since last session ctx dep Show package dependency graph ctx pad Encrypted scratchpad for sensitive one-liners ctx prompt Manage reusable prompt templates ctx remind Session-scoped reminders that surface at session start ctx completion Generate shell autocompletion scripts ctx guide Quick-reference cheat sheet ctx why Read the philosophy behind ctx ctx site Site management (feed generation) ctx doctor Structural health check (hooks, drift, config) ctx mcp MCP server for AI tool integration (stdin/stdout) ctx config Manage runtime configuration profiles ctx system System diagnostics and hook commands","path":["CLI"],"tags":[]},{"location":"cli/#exit-codes","level":2,"title":"Exit Codes","text":"Code Meaning 0 Success 1 General error / warnings (e.g. drift) 2 Context not found 3 Violations found (e.g. drift) 4 File operation error","path":["CLI"],"tags":[]},{"location":"cli/#environment-variables","level":2,"title":"Environment Variables","text":"Variable Description CTX_DIR Override default context directory path CTX_TOKEN_BUDGET Override default token budget CTX_BACKUP_SMB_URL SMB share URL for backups (e.g. smb://host/share) CTX_BACKUP_SMB_SUBDIR Subdirectory on SMB share (default: ctx-sessions)","path":["CLI"],"tags":[]},{"location":"cli/#configuration-file","level":2,"title":"Configuration File","text":"

    Optional .ctxrc (YAML format) at project root:

    # .ctxrc\ncontext_dir: .context        # Context directory name\ntoken_budget: 8000           # Default token budget\npriority_order:              # File loading priority\n  - TASKS.md\n  - DECISIONS.md\n  - CONVENTIONS.md\nauto_archive: true           # Auto-archive old items\narchive_after_days: 7        # Days before archiving tasks\nscratchpad_encrypt: true     # Encrypt scratchpad (default: true)\nallow_outside_cwd: false     # Skip boundary check (default: false)\nevent_log: false             # Enable local hook event logging\nentry_count_learnings: 30    # Drift warning threshold (0 = disable)\nentry_count_decisions: 20    # Drift warning threshold (0 = disable)\nconvention_line_count: 200   # Line count warning for CONVENTIONS.md (0 = disable)\ninjection_token_warn: 15000  # Oversize injection warning (0 = disable)\ncontext_window: 200000       # Auto-detected for Claude Code; override for other tools\nbilling_token_warn: 0        # One-shot billing warning at this token count (0 = disabled)\nkey_rotation_days: 90        # Days before key rotation nudge\nsession_prefixes:            # Recognized session header prefixes (extend for i18n)\n  - \"Session:\"               # English (default)\n  # - \"Oturum:\"              # Turkish (add as needed)\n  # - \"セッション:\"             # Japanese (add as needed)\nfreshness_files:             # Files with technology-dependent constants (opt-in)\n  - path: config/thresholds.yaml\n    desc: Model token limits and batch sizes\n    review_url: https://docs.example.com/limits  # Optional\nnotify:                      # Webhook notification settings\n  events:                    # Required: only listed events fire\n    - loop\n    - nudge\n    - relay\n    # - heartbeat            # Every-prompt session-alive signal\n
    Field Type Default Description context_dir string .context Context directory name (relative to project root) token_budget int 8000 Default token budget for ctx agent priority_order []string (all files) File loading priority for context packets auto_archive bool true Auto-archive completed tasks archive_after_days int 7 Days before completed tasks are archived scratchpad_encrypt bool true Encrypt scratchpad with AES-256-GCM allow_outside_cwd bool false Skip boundary check for external context dirs event_log bool false Enable local hook event logging to .context/state/events.jsonl entry_count_learnings int 30 Drift warning when LEARNINGS.md exceeds this count entry_count_decisions int 20 Drift warning when DECISIONS.md exceeds this count convention_line_count int 200 Line count warning for CONVENTIONS.md injection_token_warn int 15000 Warn when auto-injected context exceeds this token count (0 = disable) context_window int 200000 Context window size in tokens. Auto-detected for Claude Code (200k/1M); override for other AI tools billing_token_warn int 0 (off) One-shot warning when session tokens exceed this threshold (0 = disabled) key_rotation_days int 90 Days before encryption key rotation nudge session_prefixes []string [\"Session:\"] Recognized Markdown session header prefixes. Extend to parse sessions written in other languages freshness_files []object (none) Files to track for staleness (path, desc, optional review_url). Hook warns after 6 months without modification notify.events []string (all) Event filter for webhook notifications (empty = all)

    Priority order: CLI flags > Environment variables > .ctxrc > Defaults

    All settings are optional. Missing values use defaults.

    ","path":["CLI"],"tags":[]},{"location":"cli/config/","level":1,"title":"Config","text":"","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config","level":3,"title":"ctx config","text":"

    Manage runtime configuration profiles.

    ctx config <subcommand>\n

    The ctx repo ships two .ctxrc source profiles (.ctxrc.base and .ctxrc.dev). The working copy (.ctxrc) is gitignored and switched between them using subcommands below.

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config-switch","level":4,"title":"ctx config switch","text":"

    Switch between .ctxrc configuration profiles.

    ctx config switch [dev|base]\n

    With no argument, toggles between dev and base. Accepts prod as an alias for base.

    Argument Description dev Switch to dev profile (verbose logging) base Switch to base profile (all defaults) (none) Toggle to the opposite profile

    Profiles:

    Profile Description dev Verbose logging, webhook notifications on base All defaults, notifications off

    Examples:

    ctx config switch dev     # Switch to dev profile\nctx config switch base    # Switch to base profile\nctx config switch         # Toggle (dev → base or base → dev)\nctx config switch prod    # Alias for \"base\"\n

    The detection heuristic checks for an uncommented notify: line in .ctxrc: present means dev, absent means base.

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/config/#ctx-config-status","level":4,"title":"ctx config status","text":"

    Show which .ctxrc profile is currently active.

    ctx config status\n

    Output examples:

    active: dev (verbose logging enabled)\nactive: base (defaults)\nactive: none (.ctxrc does not exist)\n

    See also: Configuration, Contributing: Configuration Profiles

    ","path":["CLI","Config"],"tags":[]},{"location":"cli/context/","level":1,"title":"Context Management","text":"","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-add","level":3,"title":"ctx add","text":"

    Add a new item to a context file.

    ctx add <type> <content> [flags]\n

    Types:

    Type Target File task TASKS.md decision DECISIONS.md learning LEARNINGS.md convention CONVENTIONS.md

    Flags:

    Flag Short Description --priority <level> -p Priority for tasks: high, medium, low --section <name> -s Target section within file --context -c Context (required for decisions and learnings) --rationale -r Rationale for decisions (required for decisions) --consequence Consequence for decisions (required for decisions) --lesson -l Key insight (required for learnings) --application -a How to apply going forward (required for learnings) --file -f Read content from file instead of argument

    Examples:

    # Add a task\nctx add task \"Implement user authentication\"\nctx add task \"Fix login bug\" --priority high\n\n# Record a decision (requires all ADR (Architectural Decision Record) fields)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Note a learning (requires context, lesson, and application)\nctx add learning \"Vitest mocks must be hoisted\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Vitest hoists vi.mock() calls to top of file\" \\\n  --application \"Always place vi.mock() before imports in test files\"\n\n# Add to specific section\nctx add convention \"Use kebab-case for filenames\" --section \"Naming\"\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-drift","level":3,"title":"ctx drift","text":"

    Detect stale or invalid context.

    ctx drift [flags]\n

    Flags:

    Flag Description --json Output machine-readable JSON --fix Auto-fix simple issues

    Checks:

    • Path references in ARCHITECTURE.md and CONVENTIONS.md exist
    • Task references are valid
    • Constitution rules aren't violated (heuristic)
    • Staleness indicators (old files, many completed tasks)
    • Missing packages: warns when internal/ directories exist on disk but are not referenced in ARCHITECTURE.md (suggests running /ctx-architecture)
    • Entry count: warns when LEARNINGS.md or DECISIONS.md exceed configurable thresholds (default: 30 learnings, 20 decisions), or when CONVENTIONS.md exceeds a line count threshold (default: 200). Configure via .ctxrc: 
      entry_count_learnings: 30      # warn above this (0 = disable)\nentry_count_decisions: 20      # warn above this (0 = disable)\nconvention_line_count: 200     # warn above this (0 = disable)\n

    Example:

    ctx drift\nctx drift --json\nctx drift --fix\n

    Exit codes:

    Code Meaning 0 All checks passed 1 Warnings found 3 Violations found","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-sync","level":3,"title":"ctx sync","text":"

    Reconcile context with the current codebase state.

    ctx sync [flags]\n

    Flags:

    Flag Description --dry-run Show what would change without modifying

    What it does:

    • Scans codebase for structural changes
    • Compares with ARCHITECTURE.md
    • Suggests documenting dependencies if package files exist
    • Identifies stale or outdated context

    Example:

    ctx sync\nctx sync --dry-run\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-compact","level":3,"title":"ctx compact","text":"

    Consolidate and clean up context files.

    • Moves completed tasks older than 7 days to the archive
    • Removes empty sections
    ctx compact [flags]\n

    Flags:

    Flag Description --archive Create .context/archive/ for old content

    Example:

    ctx compact\nctx compact --archive\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task","level":3,"title":"ctx task","text":"

    Manage task completion, archival, and snapshots.

    ctx task <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-complete","level":4,"title":"ctx task complete","text":"

    Mark a task as completed.

    ctx task complete <task-id-or-text>\n

    Arguments:

    • task-id-or-text: Task number or partial text match

    Examples:

    # By text (partial match)\nctx task complete \"user auth\"\n\n# By task number\nctx task complete 3\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-archive","level":4,"title":"ctx task archive","text":"

    Move completed tasks from TASKS.md to a timestamped archive file.

    ctx task archive [flags]\n

    Flags:

    Flag Description --dry-run Preview changes without modifying files

    Archive files are stored in .context/archive/ with timestamped names (tasks-YYYY-MM-DD.md). Completed tasks (marked with [x]) are moved; pending tasks ([ ]) remain in TASKS.md.

    Example:

    ctx task archive\nctx task archive --dry-run\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-task-snapshot","level":4,"title":"ctx task snapshot","text":"

    Create a point-in-time snapshot of TASKS.md without modifying the original.

    ctx task snapshot [name]\n

    Arguments:

    • name: Optional name for the snapshot (defaults to \"snapshot\")

    Snapshots are stored in .context/archive/ with timestamped names (tasks-<name>-YYYY-MM-DD-HHMM.md).

    Example:

    ctx task snapshot\nctx task snapshot \"before-refactor\"\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission","level":3,"title":"ctx permission","text":"

    Manage Claude Code permission snapshots.

    ctx permission <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission-snapshot","level":4,"title":"ctx permission snapshot","text":"

    Save .claude/settings.local.json as the golden image.

    ctx permission snapshot\n

    Creates .claude/settings.golden.json as a byte-for-byte copy of the current settings. Overwrites if the golden file already exists.

    The golden file is meant to be committed to version control and shared with the team.

    Example:

    ctx permission snapshot\n# Saved golden image: .claude/settings.golden.json\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-permission-restore","level":4,"title":"ctx permission restore","text":"

    Replace settings.local.json with the golden image.

    ctx permission restore\n

    Prints a diff of dropped (session-accumulated) and restored permissions. No-op if the files already match.

    Example:

    ctx permission restore\n# Dropped 3 session permission(s):\n#   - Bash(cat /tmp/debug.log:*)\n#   - Bash(rm /tmp/test-*:*)\n#   - Bash(curl https://example.com:*)\n# Restored from golden image.\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-reindex","level":3,"title":"ctx reindex","text":"

    Regenerate the quick-reference index for both DECISIONS.md and LEARNINGS.md in a single invocation.

    ctx reindex\n

    This is a convenience wrapper around ctx decision reindex and ctx learning reindex. Both files grow at similar rates and users typically want to reindex both after manual edits.

    The index is a compact table of date and title for each entry, allowing AI tools to scan entries without reading the full file.

    Example:

    ctx reindex\n# ✓ Index regenerated with 12 entries\n# ✓ Index regenerated with 8 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-decision","level":3,"title":"ctx decision","text":"

    Manage the DECISIONS.md file.

    ctx decision <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-decision-reindex","level":4,"title":"ctx decision reindex","text":"

    Regenerate the quick-reference index at the top of DECISIONS.md.

    ctx decision reindex\n

    The index is a compact table showing the date and title for each decision, allowing AI tools to quickly scan entries without reading the full file.

    Use this after manual edits to DECISIONS.md or when migrating existing files to use the index format.

    Example:

    ctx decision reindex\n# ✓ Index regenerated with 12 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-learning","level":3,"title":"ctx learning","text":"

    Manage the LEARNINGS.md file.

    ctx learning <subcommand>\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/context/#ctx-learning-reindex","level":4,"title":"ctx learning reindex","text":"

    Regenerate the quick-reference index at the top of LEARNINGS.md.

    ctx learning reindex\n

    The index is a compact table showing the date and title for each learning, allowing AI tools to quickly scan entries without reading the full file.

    Use this after manual edits to LEARNINGS.md or when migrating existing files to use the index format.

    Example:

    ctx learning reindex\n# ✓ Index regenerated with 8 entries\n
    ","path":["CLI","Context Management"],"tags":[]},{"location":"cli/doctor/","level":1,"title":"Doctor","text":"","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#ctx-doctor","level":3,"title":"ctx doctor","text":"

    Structural health check across context, hooks, and configuration. Runs mechanical checks that don't require semantic analysis. Think of it as ctx status + ctx drift + configuration audit in one pass.

    ctx doctor [flags]\n

    Flags:

    Flag Short Type Default Description --json -j bool false Machine-readable JSON output","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#what-it-checks","level":4,"title":"What It Checks","text":"Check Category What it verifies Context initialized Structure .context/ directory exists Required files present Structure All required context files exist (TASKS.md, etc.) Drift detected Quality Stale paths, missing files, constitution violations Event logging status Hooks Whether event_log: true is set in .ctxrc Webhook configured Hooks .notify.enc file exists Pending reminders State Count of entries in reminders.json Task completion ratio State Pending vs completed tasks in TASKS.md Context token size Size Estimated token count across all context files Recent event activity Events Last event timestamp (only when event logging is enabled)","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#output-format-human","level":4,"title":"Output Format (Human)","text":"
    ctx doctor\n==========\n\nStructure\n  ✓ Context initialized (.context/)\n  ✓ Required files present (4/4)\n\nQuality\n  ⚠ Drift: 2 warnings (stale path in ARCHITECTURE.md, high entry count in LEARNINGS.md)\n\nHooks\n  ✓ hooks.json valid (14 hooks registered)\n  ○ Event logging disabled (enable with event_log: true in .ctxrc)\n\nState\n  ✓ No pending reminders\n  ⚠ Task completion ratio high (18/22 = 82%): consider archiving\n\nSize\n  ✓ Context size: ~4200 tokens (budget: 8000)\n\nSummary: 2 warnings, 0 errors\n

    Status indicators:

    Icon Status Meaning ✓ ok Check passed ⚠ warning Non-critical issue worth fixing ✗ error Problem that needs attention ○ info Informational note","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#output-format-json","level":4,"title":"Output Format (JSON)","text":"
    {\n  \"results\": [\n    {\n      \"name\": \"context_initialized\",\n      \"category\": \"Structure\",\n      \"status\": \"ok\",\n      \"message\": \"Context initialized (.context/)\"\n    },\n    {\n      \"name\": \"required_files\",\n      \"category\": \"Structure\",\n      \"status\": \"ok\",\n      \"message\": \"Required files present (4/4)\"\n    },\n    {\n      \"name\": \"drift\",\n      \"category\": \"Quality\",\n      \"status\": \"warning\",\n      \"message\": \"Drift: 2 warnings\"\n    },\n    {\n      \"name\": \"event_logging\",\n      \"category\": \"Hooks\",\n      \"status\": \"info\",\n      \"message\": \"Event logging disabled (enable with event_log: true in .ctxrc)\"\n    },\n    {\n      \"name\": \"webhook\",\n      \"category\": \"Hooks\",\n      \"status\": \"ok\",\n      \"message\": \"Webhook configured\"\n    },\n    {\n      \"name\": \"reminders\",\n      \"category\": \"State\",\n      \"status\": \"ok\",\n      \"message\": \"No pending reminders\"\n    },\n    {\n      \"name\": \"task_completion\",\n      \"category\": \"State\",\n      \"status\": \"warning\",\n      \"message\": \"Tasks: 18/22 completed (82%): consider archiving with ctx task archive\"\n    },\n    {\n      \"name\": \"context_size\",\n      \"category\": \"Size\",\n      \"status\": \"ok\",\n      \"message\": \"Context size: ~4200 tokens (budget: 8000)\"\n    }\n  ],\n  \"warnings\": 2,\n  \"errors\": 0\n}\n
    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#examples","level":4,"title":"Examples","text":"
    # Quick structural health check\nctx doctor\n\n# Machine-readable output for scripting\nctx doctor --json\n\n# Count warnings\nctx doctor --json | jq '.warnings'\n\n# Check for errors only\nctx doctor --json | jq '[.results[] | select(.status == \"error\")]'\n
    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#when-to-use-what","level":4,"title":"When to Use What","text":"Tool When ctx status Quick glance at files, tokens, and drift ctx doctor Thorough structural checkup (hooks, config, events too) /ctx-doctor Agent-driven diagnosis with event log pattern analysis

    ctx status tells you what's there. ctx doctor tells you what's wrong. /ctx-doctor tells you why it's wrong and what to do about it.

    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/doctor/#what-it-does-not-do","level":4,"title":"What It Does Not Do","text":"
    • No event pattern analysis: that's the /ctx-doctor skill's job
    • No auto-fixing: reports findings, doesn't modify anything
    • No external service checks: doesn't verify webhook endpoint availability

    See also: Troubleshooting | ctx system events | /ctx-doctor skill | Detecting and Fixing Drift

    ","path":["CLI","Doctor"],"tags":[]},{"location":"cli/init-status/","level":1,"title":"Init and Status","text":"","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-init","level":3,"title":"ctx init","text":"

    Initialize a new .context/ directory with template files.

    ctx init [flags]\n

    Flags:

    Flag Short Description --force -f Overwrite existing context files --minimal -m Only create essential files (TASKS.md, DECISIONS.md, CONSTITUTION.md) --merge Auto-merge ctx content into existing CLAUDE.md and PROMPT.md --ralph Agent works autonomously without asking questions

    Creates:

    • .context/ directory with all template files
    • .claude/settings.local.json with pre-approved ctx permissions
    • PROMPT.md with session prompt (autonomous mode with --ralph)
    • IMPLEMENTATION_PLAN.md with high-level project direction
    • CLAUDE.md with bootstrap instructions (or merges into existing)

    Claude Code hooks and skills are provided by the ctx plugin (see Integrations).

    Example:

    # Collaborative mode (agent asks questions when unclear)\nctx init\n\n# Autonomous mode (agent works independently)\nctx init --ralph\n\n# Minimal setup (just core files)\nctx init --minimal\n\n# Force overwrite existing\nctx init --force\n\n# Merge into existing files\nctx init --merge\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-status","level":3,"title":"ctx status","text":"

    Show the current context summary.

    ctx status [flags]\n

    Flags:

    Flag Short Description --json Output as JSON --verbose -v Include file contents summary

    Output:

    • Context directory path
    • Total files and token estimate
    • Status of each file (loaded, empty, missing)
    • Recent activity (modification times)
    • Drift warnings if any

    Example:

    ctx status\nctx status --json\nctx status --verbose\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-agent","level":3,"title":"ctx agent","text":"

    Print an AI-ready context packet optimized for LLM consumption.

    ctx agent [flags]\n

    Flags:

    Flag Default Description --budget 8000 Token budget: controls content selection and prioritization --format md Output format: md or json --cooldown 10m Suppress repeated output within this duration (requires --session) --session (none) Session ID for cooldown isolation (e.g., $PPID)

    How budget works:

    The budget controls how much context is included. Entries are selected in priority tiers:

    1. Constitution: always included in full (inviolable rules)
    2. Tasks: all active tasks, up to 40% of budget
    3. Conventions: all conventions, up to 20% of budget
    4. Decisions: scored by recency and relevance to active tasks
    5. Learnings: scored by recency and relevance to active tasks

    Decisions and learnings are ranked by a combined score (how recent + how relevant to your current tasks). High-scoring entries are included with their full body. Entries that don't fit get title-only summaries in an \"Also Noted\" section. Superseded entries are excluded.

    Output sections:

    Section Source Selection Read These Files all .context/ Non-empty files in priority order Constitution CONSTITUTION.md All rules (never truncated) Current Tasks TASKS.md All unchecked tasks (budget-capped) Key Conventions CONVENTIONS.md All items (budget-capped) Recent Decisions DECISIONS.md Full body, scored by relevance Key Learnings LEARNINGS.md Full body, scored by relevance Also Noted overflow Title-only summaries

    Example:

    # Default (8000 tokens, markdown)\nctx agent\n\n# Smaller packet for tight context windows\nctx agent --budget 4000\n\n# JSON format for programmatic use\nctx agent --format json\n\n# Pipe to file\nctx agent --budget 4000 > context.md\n\n# With cooldown (hooks/automation: requires --session)\nctx agent --session $PPID\n

    Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.

    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/init-status/#ctx-load","level":3,"title":"ctx load","text":"

    Load and display assembled context as AI would see it.

    ctx load [flags]\n

    Flags:

    Flag Description --budget <tokens> Token budget for assembly (default: 8000) --raw Output raw file contents without assembly

    Example:

    ctx load\nctx load --budget 16000\nctx load --raw\n
    ","path":["CLI","Init and Status"],"tags":[]},{"location":"cli/mcp/","level":1,"title":"MCP Server","text":"","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-mcp","level":2,"title":"ctx mcp","text":"

    Run ctx as a Model Context Protocol (MCP) server. MCP is a standard protocol that lets AI tools discover and consume context from external sources via JSON-RPC 2.0 over stdin/stdout.

    This makes ctx accessible to any MCP-compatible AI tool without custom hooks or integrations:

    • Claude Desktop
    • Cursor
    • Windsurf
    • VS Code Copilot
    • Any tool supporting MCP
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-mcp-serve","level":3,"title":"ctx mcp serve","text":"

    Start the MCP server. This command reads JSON-RPC 2.0 requests from stdin and writes responses to stdout. It is intended to be launched by MCP clients, not run directly.

    ctx mcp serve\n

    Flags: None. The server uses the configured context directory (from --context-dir, CTX_DIR, .ctxrc, or the default .context).

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#configuration","level":2,"title":"Configuration","text":"","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#claude-desktop","level":3,"title":"Claude Desktop","text":"

    Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

    {\n  \"mcpServers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#cursor","level":3,"title":"Cursor","text":"

    Add to .cursor/mcp.json in your project:

    {\n  \"mcpServers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#vs-code-copilot","level":3,"title":"VS Code (Copilot)","text":"

    Add to .vscode/mcp.json:

    {\n  \"servers\": {\n    \"ctx\": {\n      \"command\": \"ctx\",\n      \"args\": [\"mcp\", \"serve\"]\n    }\n  }\n}\n
    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#resources","level":2,"title":"Resources","text":"

    Resources expose context files as read-only content. Each resource has a URI, name, and returns Markdown text.

    URI Name Description ctx://context/constitution constitution Hard rules that must never be violated ctx://context/tasks tasks Current work items and their status ctx://context/conventions conventions Code patterns and standards ctx://context/architecture architecture System architecture documentation ctx://context/decisions decisions Architectural decisions with rationale ctx://context/learnings learnings Gotchas, tips, and lessons learned ctx://context/glossary glossary Project-specific terminology ctx://context/agent agent All files assembled in priority read order

    The agent resource assembles all non-empty context files into a single Markdown document, ordered by the configured read priority.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#resource-subscriptions","level":3,"title":"Resource Subscriptions","text":"

    Clients can subscribe to resource changes via resources/subscribe. The server polls for file mtime changes (default: 5 seconds) and emits notifications/resources/updated when a subscribed file changes on disk.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#tools","level":2,"title":"Tools","text":"

    Tools expose ctx commands as callable operations. Each tool accepts JSON arguments and returns text results.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_status","level":3,"title":"ctx_status","text":"

    Show context health: file count, token estimate, and per-file summary.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_add","level":3,"title":"ctx_add","text":"

    Add a task, decision, learning, or convention to the context.

    Argument Type Required Description type string Yes Entry type: task, decision, learning, convention content string Yes Title or main content priority string No Priority level (tasks only): high, medium, low context string Conditional Context field (decisions and learnings) rationale string Conditional Rationale (decisions only) consequence string Conditional Consequence (decisions only) lesson string Conditional Lesson learned (learnings only) application string Conditional How to apply (learnings only)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_complete","level":3,"title":"ctx_complete","text":"

    Mark a task as done by number or text match.

    Argument Type Required Description query string Yes Task number (e.g. \"1\") or search text","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_drift","level":3,"title":"ctx_drift","text":"

    Detect stale or invalid context. Returns violations, warnings, and passed checks.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_recall","level":3,"title":"ctx_recall","text":"

    Query recent AI session history (summaries, decisions, topics).

    Argument Type Required Description limit number No Max sessions to return (default: 5) since string No ISO date filter: sessions after this date (YYYY-MM-DD)

    Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_watch_update","level":3,"title":"ctx_watch_update","text":"

    Apply a structured context update to .context/ files. Supports task, decision, learning, convention, and complete entry types. Human confirmation is required before calling.

    Argument Type Required Description type string Yes Entry type: task, decision, learning, convention, complete content string Yes Main content context string Conditional Context background (decisions/learnings) rationale string Conditional Rationale (decisions only) consequence string Conditional Consequence (decisions only) lesson string Conditional Lesson learned (learnings only) application string Conditional How to apply (learnings only)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_compact","level":3,"title":"ctx_compact","text":"

    Move completed tasks to the archive section and remove empty sections from context files. Human confirmation required.

    Argument Type Required Description archive boolean No Also write tasks to .context/archive/ (default: false)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_next","level":3,"title":"ctx_next","text":"

    Suggest the next pending task based on priority and position.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_check_task_completion","level":3,"title":"ctx_check_task_completion","text":"

    Advisory check: after a write operation, detect if any pending tasks were silently completed. Returns nudge text if a match is found.

    Argument Type Required Description recent_action string No Brief description of what was just done

    Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_session_event","level":3,"title":"ctx_session_event","text":"

    Signal a session lifecycle event. Type end triggers the session-end persistence ceremony - human confirmation required.

    Argument Type Required Description type string Yes Event type: start, end caller string No Caller identifier (cursor, windsurf, vscode, claude-desktop)","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx_remind","level":3,"title":"ctx_remind","text":"

    List pending session-scoped reminders.

    Arguments: None. Read-only.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#prompts","level":2,"title":"Prompts","text":"

    Prompts provide pre-built templates for common workflows. Clients can list available prompts via prompts/list and retrieve a specific prompt via prompts/get.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-session-start","level":3,"title":"ctx-session-start","text":"

    Load full context at the beginning of a session. Returns all context files assembled in priority read order with session orientation instructions.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-add-decision","level":3,"title":"ctx-add-decision","text":"

    Format an architectural decision entry with all required fields.

    Argument Type Required Description content string Yes Decision title context string Yes Background context rationale string Yes Why this decision was made consequence string Yes Expected consequence","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-add-learning","level":3,"title":"ctx-add-learning","text":"

    Format a learning entry with all required fields.

    Argument Type Required Description content string Yes Learning title context string Yes Background context lesson string Yes The lesson learned application string Yes How to apply this lesson","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-reflect","level":3,"title":"ctx-reflect","text":"

    Guide end-of-session reflection. Returns a structured review prompt covering progress assessment and context update recommendations.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/mcp/#ctx-checkpoint","level":3,"title":"ctx-checkpoint","text":"

    Report session statistics: tool calls made, entries added, and pending updates queued during the current session.

    ","path":["CLI","MCP Server"],"tags":[]},{"location":"cli/recall/","level":1,"title":"Recall and Journal","text":"","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall","level":3,"title":"ctx recall","text":"

    Browse and search AI session history from Claude Code and other tools.

    ctx recall <subcommand>\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-list","level":4,"title":"ctx recall list","text":"

    List all parsed sessions.

    ctx recall list [flags]\n

    Flags:

    Flag Short Description --limit -n Maximum sessions to display (default: 20) --project -p Filter by project name --tool -t Filter by tool (e.g., claude-code) --all-projects Include sessions from all projects

    Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.

    Example:

    ctx recall list\nctx recall list --limit 5\nctx recall list --project ctx\nctx recall list --tool claude-code\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-show","level":4,"title":"ctx recall show","text":"

    Show details of a specific session.

    ctx recall show [session-id] [flags]\n

    Flags:

    Flag Description --latest Show the most recent session --full Show full message content --all-projects Search across all projects

    The session ID can be a full UUID, partial match, or session slug name.

    Example:

    ctx recall show abc123\nctx recall show gleaming-wobbling-sutherland\nctx recall show --latest\nctx recall show --latest --full\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-export","level":4,"title":"ctx recall export","text":"

    Export sessions to editable journal files in .context/journal/.

    ctx recall export [session-id] [flags]\n

    Flags:

    Flag Description --all Export all sessions (only new files by default) --all-projects Export from all projects --regenerate Re-export existing files (preserves YAML frontmatter by default) --keep-frontmatter Preserve enriched YAML frontmatter during regeneration (default: true) --yes, -y Skip confirmation prompt --dry-run Show what would be exported without writing files

    Safe by default: --all only exports new sessions. Existing files are skipped. Use --regenerate to re-export existing files (conversation content is regenerated, YAML frontmatter from enrichment is preserved by default). Use --keep-frontmatter=false to discard enriched frontmatter during regeneration.

    Locked entries (via ctx recall lock) are always skipped, regardless of flags.

    Single-session export (ctx recall export <id>) always writes without prompting, since you are explicitly targeting one session.

    The journal/ directory should be gitignored (like sessions/) since it contains raw conversation data.

    Example:

    ctx recall export abc123                 # Export one session\nctx recall export --all                  # Export only new sessions\nctx recall export --all --dry-run        # Preview what would be exported\nctx recall export --all --regenerate     # Re-export existing (prompts)\nctx recall export --all --regenerate -y  # Re-export without prompting\nctx recall export --all --regenerate --keep-frontmatter=false -y  # Discard frontmatter\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-lock","level":4,"title":"ctx recall lock","text":"

    Protect journal entries from being overwritten by export --regenerate or modified by enrichment skills (/ctx-journal-enrich, /ctx-journal-enrich-all).

    ctx recall lock <pattern> [flags]\n

    Flags:

    Flag Description --all Lock all journal entries

    The pattern matches filenames by slug, date, or short ID. Locking a multi-part entry locks all parts. The lock is recorded in .context/journal/.state.json and a locked: true line is added to the file's YAML frontmatter for visibility.

    Example:

    ctx recall lock abc12345\nctx recall lock 2026-01-21-session-abc12345.md\nctx recall lock --all\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-unlock","level":4,"title":"ctx recall unlock","text":"

    Remove lock protection from journal entries.

    ctx recall unlock <pattern> [flags]\n

    Flags:

    Flag Description --all Unlock all journal entries

    Example:

    ctx recall unlock abc12345\nctx recall unlock --all\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-recall-sync","level":4,"title":"ctx recall sync","text":"

    Sync lock state from journal frontmatter to .state.json.

    ctx recall sync\n

    Scans all journal markdowns and updates .state.json to match each file's frontmatter. Files with locked: true in frontmatter are marked locked in state; files without a locked: line have their lock cleared.

    This is the inverse of ctx recall lock: instead of state driving frontmatter, frontmatter drives state. Useful after batch enrichment where you add locked: true to frontmatter manually.

    Example:

    # After enriching entries and adding locked: true to frontmatter\nctx recall sync\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal","level":3,"title":"ctx journal","text":"

    Analyze and synthesize exported session files.

    ctx journal <subcommand>\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal-site","level":4,"title":"ctx journal site","text":"

    Generate a static site from journal entries in .context/journal/.

    ctx journal site [flags]\n

    Flags:

    Flag Short Description --output -o Output directory (default: .context/journal-site) --build Run zensical build after generating --serve Run zensical serve after generating

    Creates a zensical-compatible site structure with an index page listing all sessions by date, and individual pages for each journal entry.

    Requires zensical to be installed for --build or --serve:

    pipx install zensical\n

    Example:

    ctx journal site                    # Generate in .context/journal-site/\nctx journal site --output ~/public  # Custom output directory\nctx journal site --build            # Generate and build HTML\nctx journal site --serve            # Generate and serve locally\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-journal-obsidian","level":4,"title":"ctx journal obsidian","text":"

    Generate an Obsidian vault from journal entries in .context/journal/.

    ctx journal obsidian [flags]\n

    Flags:

    Flag Short Description --output -o Output directory (default: .context/journal-obsidian)

    Creates an Obsidian-compatible vault with:

    • Wikilinks ([[target|display]]) for all internal navigation
    • MOC pages (Map of Content) for topics, key files, and session types
    • Related sessions footer linking entries that share topics
    • Transformed frontmatter (topics → tags for Obsidian integration)
    • Minimal .obsidian/ config enforcing wikilink mode

    No external dependencies are required: Open the output directory as an Obsidian vault directly.

    Example:

    ctx journal obsidian                        # Generate in .context/journal-obsidian/\nctx journal obsidian --output ~/vaults/ctx  # Custom output directory\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/recall/#ctx-serve","level":3,"title":"ctx serve","text":"

    Serve any zensical directory locally. This is a serve-only command: It does not generate or regenerate site content.

    ctx serve [directory]\n

    If no directory is specified, defaults to the journal site (.context/journal-site).

    Requires zensical to be installed:

    pipx install zensical\n

    ctx serve vs. ctx journal site --serve

    ctx journal site --serve generates the journal site then serves it: an all-in-one command. ctx serve only serves an existing directory, and works with any zensical site (journal, docs, etc.).

    Example:

    ctx serve                        # Serve journal site (no regeneration)\nctx serve .context/journal-site  # Same, explicit path\nctx serve ./site                 # Serve the docs site\n
    ","path":["CLI","Recall and Journal"],"tags":[]},{"location":"cli/system/","level":1,"title":"System","text":"","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system","level":3,"title":"ctx system","text":"

    System diagnostics and hook commands.

    ctx system <subcommand>\n

    The parent command shows available subcommands. Hidden plumbing subcommands (ctx system mark-journal, ctx system mark-wrapped-up) are used by skills and automation. Hidden hook subcommands (ctx system check-*) are used by the Claude Code plugin.

    See AI Tools for details.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-backup","level":4,"title":"ctx system backup","text":"

    Create timestamped tar.gz archives of project context and/or global Claude Code data. Optionally copies archives to an SMB share via GVFS.

    ctx system backup [flags]\n

    Scopes:

    Scope What it includes project .context/, .claude/, ideas/, ~/.bashrc global ~/.claude/ (excludes todos/) all Both project and global (default)

    Flags:

    Flag Description --scope <scope> Backup scope: project, global, or all --json Output results as JSON

    Environment:

    Variable Description CTX_BACKUP_SMB_URL SMB share URL (e.g. smb://host/share) CTX_BACKUP_SMB_SUBDIR Subdirectory on share (default: ctx-sessions)

    Examples:

    ctx system backup                       # Back up everything (default: all)\nctx system backup --scope project       # Project context only\nctx system backup --scope global        # Global Claude data only\nctx system backup --scope all --json    # Both, JSON output\n

    Archives are saved to /tmp/ with timestamped names. When CTX_BACKUP_SMB_URL is configured, archives are also copied to the SMB share. Project backups touch ~/.local/state/ctx-last-backup for the check-backup-age hook.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-bootstrap","level":4,"title":"ctx system bootstrap","text":"

    Print context location and rules for AI agents. This is the recommended first command for AI agents to run at session start: It tells them where the context directory is and how to use it.

    ctx system bootstrap [flags]\n

    Flags:

    Flag Description -q, --quiet Output only the context directory path --json Output in JSON format

    Quiet output:

    ctx system bootstrap -q\n# .context\n

    Text output:

    ctx bootstrap\n=============\n\ncontext_dir: .context\n\nFiles:\n  CONSTITUTION.md, TASKS.md, DECISIONS.md, LEARNINGS.md,\n  CONVENTIONS.md, ARCHITECTURE.md, GLOSSARY.md\n\nRules:\n  1. Use context_dir above for ALL file reads/writes\n  2. Never say \"I don't have memory\": context IS your memory\n  3. Read files silently, present as recall (not search)\n  4. Persist learnings/decisions before session ends\n  5. Run `ctx agent` for content summaries\n  6. Run `ctx status` for context health\n

    JSON output:

    {\n  \"context_dir\": \".context\",\n  \"files\": [\"CONSTITUTION.md\", \"TASKS.md\", ...],\n  \"rules\": [\"Use context_dir above for ALL file reads/writes\", ...]\n}\n

    Examples:

    ctx system bootstrap                          # Text output\nctx system bootstrap -q                       # Just the path\nctx system bootstrap --json                   # JSON output\nctx system bootstrap --json | jq .context_dir # Extract context path\n

    Why it exists: When users configure an external context directory via .ctxrc (context_dir: /mnt/nas/.context), the AI agent needs to know where context lives. Bootstrap resolves the configured path and communicates it to the agent at session start. Every nudge also includes a context directory footer for reinforcement.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-resources","level":4,"title":"ctx system resources","text":"

    Show system resource usage with threshold-based alerts.

    ctx system resources [flags]\n

    Displays memory, swap, disk, and CPU load with two severity tiers:

    Resource WARNING DANGER Memory >= 80% used >= 90% used Swap >= 50% used >= 75% used Disk (cwd) >= 85% full >= 95% full Load (1m) >= 0.8x CPUs >= 1.5x CPUs

    Flags:

    Flag Description --json Output in JSON format

    Examples:

    ctx system resources               # Text output with status indicators\nctx system resources --json        # Machine-readable JSON\nctx system resources --json | jq '.alerts'   # Extract alerts only\n

    Text output:

    System Resources\n====================\n\nMemory:    4.2 / 16.0 GB (26%)                     ✓ ok\nSwap:      0.0 /  8.0 GB (0%)                      ✓ ok\nDisk:    180.2 / 500.0 GB (36%)                     ✓ ok\nLoad:     0.52 / 0.41 / 0.38  (8 CPUs, ratio 0.07) ✓ ok\n\nAll clear: no resource warnings.\n

    When resources breach thresholds, alerts are listed below the summary:

    Alerts:\n  ✖ Memory 92% used (14.7 / 16.0 GB)\n  ✖ Swap 78% used (6.2 / 8.0 GB)\n  ✖ Load 1.56x CPU count\n

    Platform support: Full metrics on Linux and macOS. Windows shows disk only; memory and load report as unsupported.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-message","level":4,"title":"ctx system message","text":"

    Manage hook message templates. Hook messages control what text hooks emit. The hook logic (when to fire, counting, state tracking) is universal; the messages are opinions that can be customized per-project.

    ctx system message <subcommand>\n

    Subcommands:

    Subcommand Args Flags Description list (none) --json Show all hook messages with category and override status show <hook> <variant> (none) Print the effective message template with source edit <hook> <variant> (none) Copy embedded default to .context/ for editing reset <hook> <variant> (none) Delete user override, revert to embedded default

    Examples:

    ctx system message list                      # Table of all 24 messages\nctx system message list --json               # Machine-readable JSON\nctx system message show qa-reminder gate     # View the QA gate template\nctx system message edit qa-reminder gate     # Copy default to .context/ for editing\nctx system message reset qa-reminder gate    # Delete override, revert to default\n

    Override files are placed at .context/hooks/messages/{hook}/{variant}.txt. An empty override file silences the message while preserving the hook's logic.

    See the Customizing Hook Messages recipe for detailed examples.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-events","level":4,"title":"ctx system events","text":"

    Query the local hook event log. Reads events from .context/state/events.jsonl and outputs them in human-readable or raw JSONL format. Requires event_log: true in .ctxrc.

    ctx system events [flags]\n

    Flags:

    Flag Short Type Default Description --hook -k string (all) Filter by hook name --session -s string (all) Filter by session ID --event -e string (all) Filter by event type (relay, nudge) --last -n int 50 Show last N events --json -j bool false Output raw JSONL (for piping to jq) --all -a bool false Include rotated log file (events.1.jsonl)

    All filter flags use intersection (AND) logic.

    Text output:

    2026-02-27 22:39:31  relay  qa-reminder          QA gate reminder emitted\n2026-02-27 22:41:56  relay  qa-reminder          QA gate reminder emitted\n2026-02-28 00:48:18  relay  context-load-gate    injected 6 files (~9367 tokens)\n

    Columns: timestamp (local timezone), event type, hook name, message (truncated to terminal width).

    JSON output (--json):

    Each line is a standalone JSON object identical to the webhook payload format:

    // converted to multi-line for convenience:\n{\"event\":\"relay\",\"message\":\"qa-reminder: QA gate reminder emitted\",\"detail\":\n{\"hook\":\"qa-reminder\",\"variant\":\"gate\"},\"session_id\":\"eb1dc9cd-...\",\n  \"timestamp\":\"2026-02-27T22:39:31Z\",\"project\":\"ctx\"}\n

    Examples:

    # Last 50 events (default)\nctx system events\n\n# Events from a specific session\nctx system events --session eb1dc9cd-0163-4853-89d0-785fbfaae3a6\n\n# Only QA reminder events\nctx system events --hook qa-reminder\n\n# Raw JSONL for jq processing\nctx system events --json | jq '.message'\n\n# How many context-load-gate fires today\nctx system events --hook context-load-gate --json \\\n  | jq -r '.timestamp' | grep \"$(date +%Y-%m-%d)\" | wc -l\n\n# Include rotated events\nctx system events --all --last 100\n

    Why it exists: System hooks fire invisibly. When something goes wrong (\"why didn't my hook fire?\"), the event log provides a local, queryable record of what hooks fired, when, and how often. Event logging is opt-in via event_log: true in .ctxrc to avoid surprises for existing users.

    See also: Troubleshooting, Auditing System Hooks, ctx doctor

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-stats","level":4,"title":"ctx system stats","text":"

    Show per-session token usage statistics. Reads stats JSONL files from .context/state/stats-*.jsonl, written automatically by the check-context-size hook on every prompt.

    ctx system stats [flags]\n

    Flags:

    Flag Short Type Default Description --follow -f bool false Stream new entries as they arrive --session -s string (all) Filter by session ID (prefix match) --last -n int 20 Show last N entries --json -j bool false Output raw JSONL (for piping to jq)

    Text output:

    TIME                 SESSION   PROMPT    TOKENS  PCT  EVENT\n-------------------  --------  ------  --------  ----  ------------\n2026-03-05 10:00:05  abc12345       1      5k    2%  silent\n2026-03-05 10:01:12  abc12345       2     12k    6%  silent\n2026-03-05 10:15:30  abc12345      20     45k   22%  checkpoint\n

    Events: silent, checkpoint, window-warning, suppressed (wrap-up active), billing (threshold exceeded).

    Examples:

    # Recent stats across all sessions\nctx system stats\n\n# Stream live token usage (like tail -f)\nctx system stats --follow\n\n# Filter to current session\nctx system stats --session abc12345\n\n# Raw JSONL for analysis\nctx system stats --json | jq '.pct'\n\n# Monitor a long session in another terminal\nctx system stats --follow --session abc12345\n

    See also: Auditing System Hooks

    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-prune","level":4,"title":"ctx system prune","text":"

    Clean stale per-session state files from .context/state/. Session hooks write tombstone files (context-check, heartbeat, persistence-nudge, etc.) that accumulate ~6-8 files per session with no automatic cleanup.

    ctx system prune [flags]\n

    Flags:

    Flag Type Default Description --days int 7 Prune files older than this many days --dry-run bool false Show what would be pruned without deleting

    Files are identified as session-scoped by UUID suffix (e.g. heartbeat-a1b2c3d4-...). Global files without UUIDs (events.jsonl, memory-import.json, etc.) are always preserved.

    Safe to run anytime

    The worst outcome of pruning is a hook re-firing its nudge in the next session. No context files, decisions, or learnings are stored in the state directory.

    Examples:

    ctx system prune                # Prune files older than 7 days\nctx system prune --days 3       # More aggressive cleanup\nctx system prune --dry-run      # Preview what would be removed\n
    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-mark-journal","level":4,"title":"ctx system mark-journal","text":"

    Update processing state for a journal entry. Records the current date in .context/journal/.state.json. Used by journal skills to record pipeline progress.

    ctx system mark-journal <filename> <stage>\n

    Stages: exported, enriched, normalized, fences_verified

    Flag Description --check Check if stage is set (exit 1 if not)

    Example:

    ctx system mark-journal 2026-01-21-session-abc12345.md enriched\nctx system mark-journal 2026-01-21-session-abc12345.md normalized\nctx system mark-journal --check 2026-01-21-session-abc12345.md fences_verified\n
    ","path":["CLI","System"],"tags":[]},{"location":"cli/system/#ctx-system-mark-wrapped-up","level":4,"title":"ctx system mark-wrapped-up","text":"

    Suppress context checkpoint nudges after a wrap-up ceremony. Writes a marker file that check-context-size checks before emitting checkpoint boxes. The marker expires after 2 hours.

    Called automatically by /ctx-wrap-up after persisting context (not intended for direct use).

    ctx system mark-wrapped-up\n

    No flags, no arguments. Idempotent: running it again updates the marker timestamp.

    ","path":["CLI","System"],"tags":[]},{"location":"cli/tools/","level":1,"title":"Tools and Utilities","text":"","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-watch","level":3,"title":"ctx watch","text":"

    Watch for AI output and auto-apply context updates.

    Parses <context-update> XML commands from AI output and applies them to context files.

    ctx watch [flags]\n

    Flags:

    Flag Description --log <file> Log file to watch (default: stdin) --dry-run Preview updates without applying

    Example:

    # Watch stdin\nai-tool | ctx watch\n\n# Watch a log file\nctx watch --log /path/to/ai-output.log\n\n# Preview without applying\nctx watch --dry-run\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-hook","level":3,"title":"ctx hook","text":"

    Generate AI tool integration configuration.

    ctx hook <tool> [flags]\n

    Flags:

    Flag Short Description --write -w Write the generated config to disk (e.g. .github/copilot-instructions.md)

    Supported tools:

    Tool Description claude-code Redirects to plugin install instructions cursor Cursor IDE aider Aider CLI copilot GitHub Copilot windsurf Windsurf IDE

    Claude Code Uses the Plugin system

    Claude Code integration is now provided via the ctx plugin. Running ctx hook claude-code prints plugin install instructions.

    Example:

    # Print hook instructions to stdout\nctx hook cursor\nctx hook aider\n\n# Generate and write .github/copilot-instructions.md\nctx hook copilot --write\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-loop","level":3,"title":"ctx loop","text":"

    Generate a shell script for running an autonomous loop.

    An autonomous loop continuously runs an AI assistant with the same prompt until a completion signal is detected, enabling iterative development where the AI builds on its previous work.

    ctx loop [flags]\n

    Flags:

    Flag Short Description Default --tool <tool> -t AI tool: claude, aider, or generic claude --prompt <file> -p Prompt file to use PROMPT.md --max-iterations <n> -n Maximum iterations (0 = unlimited) 0 --completion <signal> -c Completion signal to detect SYSTEM_CONVERGED --output <file> -o Output script filename loop.sh

    Example:

    # Generate loop.sh for Claude Code\nctx loop\n\n# Generate for Aider with custom prompt\nctx loop --tool aider --prompt TASKS.md\n\n# Limit to 10 iterations\nctx loop --max-iterations 10\n\n# Output to custom file\nctx loop -o my-loop.sh\n

    Usage:

    # Generate and run the loop\nctx loop\nchmod +x loop.sh\n./loop.sh\n

    See Autonomous Loops for detailed workflow documentation.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory","level":3,"title":"ctx memory","text":"

    Bridge Claude Code's auto memory (MEMORY.md) into .context/.

    Claude Code maintains per-project auto memory at ~/.claude/projects/<slug>/memory/MEMORY.md. This command group discovers that file, mirrors it into .context/memory/mirror.md (git-tracked), and detects drift.

    ctx memory <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-sync","level":4,"title":"ctx memory sync","text":"

    Copy MEMORY.md to .context/memory/mirror.md. Archives the previous mirror before overwriting.

    ctx memory sync [flags]\n

    Flags:

    Flag Description --dry-run Show what would happen without writing

    Exit codes:

    Code Meaning 0 Synced successfully 1 MEMORY.md not found (auto memory inactive)

    Example:

    ctx memory sync\n# Archived previous mirror to mirror-2026-03-05-143022.md\n# Synced MEMORY.md -> .context/memory/mirror.md\n#   Source: ~/.claude/projects/-home-user-project/memory/MEMORY.md\n#   Lines: 47 (was 32)\n#   New content: 15 lines since last sync\n\nctx memory sync --dry-run\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-status","level":4,"title":"ctx memory status","text":"

    Show drift, timestamps, line counts, and archive count.

    ctx memory status\n

    Exit codes:

    Code Meaning 0 No drift 1 MEMORY.md not found 2 Drift detected (MEMORY.md changed since sync)

    Example:

    ctx memory status\n# Memory Bridge Status\n#   Source:      ~/.claude/projects/.../memory/MEMORY.md\n#   Mirror:      .context/memory/mirror.md\n#   Last sync:   2026-03-05 14:30 (2 hours ago)\n#\n#   MEMORY.md:  47 lines (modified since last sync)\n#   Mirror:     32 lines\n#   Drift:      detected (source is newer)\n#   Archives:   3 snapshots in .context/memory/archive/\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-diff","level":4,"title":"ctx memory diff","text":"

    Show what changed in MEMORY.md since last sync.

    ctx memory diff\n

    Example:

    ctx memory diff\n# --- .context/memory/mirror.md (mirror)\n# +++ ~/.claude/projects/.../memory/MEMORY.md (source)\n# +- new learning: memory bridge works\n

    No output when files are identical.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-publish","level":4,"title":"ctx memory publish","text":"

    Push curated .context/ content into MEMORY.md so the agent sees it natively.

    ctx memory publish [flags]\n

    Content is selected in priority order: pending tasks, recent decisions (7 days), key conventions, recent learnings (7 days). Wrapped in <!-- ctx:published --> markers. Claude-owned content outside the markers is preserved.

    Flags:

    Flag Description Default --budget Line budget for published content 80 --dry-run Show what would be published

    Example:

    ctx memory publish --dry-run\n# Publishing .context/ -> MEMORY.md...\n#   Budget: 80 lines\n#   Published block:\n#     5 pending tasks (from TASKS.md)\n#     3 recent decisions (from DECISIONS.md)\n#     5 key conventions (from CONVENTIONS.md)\n#   Total: 42 lines (within 80-line budget)\n# Dry run - no files written.\n\nctx memory publish              # Write to MEMORY.md\nctx memory publish --budget 40  # Tighter budget\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-unpublish","level":4,"title":"ctx memory unpublish","text":"

    Remove the ctx-managed marker block from MEMORY.md, preserving Claude-owned content.

    ctx memory unpublish\n

    Hook integration: The check-memory-drift hook runs on every prompt and nudges the agent when MEMORY.md has changed since last sync. The nudge fires once per session. See Memory Bridge.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-memory-import","level":4,"title":"ctx memory import","text":"

    Classify and promote entries from MEMORY.md into structured .context/ files.

    ctx memory import [flags]\n

    Each entry is classified by keyword heuristics:

    Keywords Target always use, prefer, never use, standard CONVENTIONS.md decided, chose, trade-off, approach DECISIONS.md gotcha, learned, watch out, bug, caveat LEARNINGS.md todo, need to, follow up TASKS.md Everything else Skipped

    Deduplication prevents re-importing the same entry across runs.

    Flags:

    Flag Description --dry-run Show classification plan without writing

    Example:

    ctx memory import --dry-run\n# Scanning MEMORY.md for new entries...\n#   Found 6 entries\n#\n#   -> \"always use ctx from PATH\"\n#      Classified: CONVENTIONS.md (keywords: always use)\n#\n#   -> \"decided to use heuristic classification over LLM-based\"\n#      Classified: DECISIONS.md (keywords: decided)\n#\n# Dry run - would import: 4 entries (1 convention, 1 decision, 1 learning, 1 task)\n# Skipped: 2 entries (session notes/unclassified)\n\nctx memory import    # Actually write entries to .context/ files\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify","level":3,"title":"ctx notify","text":"

    Send fire-and-forget webhook notifications from skills, loops, and hooks.

    ctx notify --event <name> [--session-id <id>] \"message\"\n

    Flags:

    Flag Short Description --event -e Event name (required) --session-id -s Session ID (optional)

    Behavior:

    • No webhook configured: silent noop (exit 0)
    • Webhook set but event not in events list: silent noop (exit 0)
    • Webhook set and event matches: fire-and-forget HTTP POST
    • HTTP errors silently ignored (no retry)

    Example:

    ctx notify --event loop \"Loop completed after 5 iterations\"\nctx notify -e nudge -s session-abc \"Context checkpoint at prompt #20\"\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify-setup","level":4,"title":"ctx notify setup","text":"

    Configure the webhook URL interactively. The URL is encrypted with AES-256-GCM using the encryption key and stored in .context/.notify.enc.

    ctx notify setup\n

    The encrypted file is safe to commit. The key (~/.ctx/.ctx.key) lives outside the project and is never committed.

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-notify-test","level":4,"title":"ctx notify test","text":"

    Send a test notification and report the HTTP response status.

    ctx notify test\n

    Payload format (JSON POST):

    {\n  \"event\": \"loop\",\n  \"message\": \"Loop completed after 5 iterations\",\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"ctx\"\n}\n
    Field Type Description event string Event name from --event flag message string Notification message session_id string Session ID (omitted if empty) timestamp string UTC RFC3339 timestamp project string Project directory name","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-change","level":3,"title":"ctx change","text":"

    Show what changed in context files and code since your last session.

    Automatically detects the previous session boundary from state markers or event log. Useful at session start to quickly see what moved while you were away.

    ctx change [flags]\n

    Flags:

    Flag Description --since Time reference: duration (24h) or date (2026-03-01)

    Reference time detection (priority order):

    1. --since flag (duration, date, or RFC3339 timestamp)
    2. ctx-loaded-* marker files in .context/state/ (second most recent)
    3. Last context-load-gate event from .context/state/events.jsonl
    4. Fallback: 24 hours ago

    Example:

    # Auto-detect last session, show what changed\nctx change\n\n# Changes in the last 48 hours\nctx change --since 48h\n\n# Changes since a specific date\nctx change --since 2026-03-10\n

    Output:

    ## Changes Since Last Session\n\n**Reference point**: 6 hours ago\n\n### Context File Changes\n- `TASKS.md` - modified 2026-03-12 14:30\n- `DECISIONS.md` - modified 2026-03-12 09:15\n\n### Code Changes\n- **12 commits** since reference point\n- **Latest**: Fix journal enrichment ordering\n- **Directories touched**: internal, docs, specs\n- **Authors**: jose, claude\n

    Context file changes are detected by filesystem mtime (works without git). Code changes use git log --since (empty when not in a git repo).

    See also: Reviewing Session Changes

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-dep","level":3,"title":"ctx dep","text":"

    Generate a dependency graph from source code.

    Auto-detects the project ecosystem from manifest files and outputs a dependency graph in Mermaid, table, or JSON format.

    ctx dep [flags]\n

    Supported ecosystems:

    Ecosystem Manifest Method Go go.mod go list -json ./... Node.js package.json Parse package.json (workspace-aware) Python requirements.txt or pyproject.toml Parse manifest directly Rust Cargo.toml cargo metadata

    Detection order: Go, Node.js, Python, Rust. First match wins.

    Flags:

    Flag Description Default --format Output format: mermaid, table, json mermaid --external Include external/third-party dependencies false --type Force ecosystem: go, node, python, rust auto-detect

    Examples:

    # Auto-detect and show internal deps as Mermaid\nctx dep\n\n# Include external dependencies\nctx dep --external\n\n# Force Node.js detection (useful when multiple manifests exist)\nctx dep --type node\n\n# Machine-readable output\nctx dep --format json\n\n# Table format\nctx dep --format table\n

    Ecosystem notes:

    • Go: Uses go list -json ./.... Requires go in PATH.
    • Node.js: Parses package.json directly (no npm/yarn needed). For monorepos with workspaces, shows workspace-to-workspace deps (internal) or all deps per workspace (external).
    • Python: Parses requirements.txt or pyproject.toml directly (no pip needed). Shows declared dependencies; does not trace imports. With --external, includes dev dependencies from pyproject.toml.
    • Rust: Requires cargo in PATH. Uses cargo metadata for accurate dependency resolution.
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad","level":3,"title":"ctx pad","text":"

    Encrypted scratchpad for sensitive one-liners that travel with the project.

    When invoked without a subcommand, lists all entries.

    ctx pad\nctx pad <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-add","level":4,"title":"ctx pad add","text":"

    Append a new entry to the scratchpad.

    ctx pad add <text>\nctx pad add <label> --file <path>\n

    Flags:

    Flag Short Description --file -f Ingest a file as a blob entry (max 64 KB)

    Examples:

    ctx pad add \"DATABASE_URL=postgres://user:pass@host/db\"\nctx pad add \"deploy config\" --file ./deploy.yaml\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-show","level":4,"title":"ctx pad show","text":"

    Output the raw text of an entry by number. For blob entries, prints decoded file content (or writes to disk with --out).

    ctx pad show <n>\nctx pad show <n> --out <path>\n

    Arguments:

    • n: 1-based entry number

    Flags:

    Flag Description --out Write decoded blob content to a file (blobs only)

    Examples:

    ctx pad show 3\nctx pad show 2 --out ./recovered.yaml\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-rm","level":4,"title":"ctx pad rm","text":"

    Remove an entry by number.

    ctx pad rm <n>\n

    Arguments:

    • n: 1-based entry number
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-edit","level":4,"title":"ctx pad edit","text":"

    Replace, append to, or prepend to an entry.

    ctx pad edit <n> [text]\n

    Arguments:

    • n: 1-based entry number
    • text: Replacement text (mutually exclusive with --append/--prepend)

    Flags:

    Flag Description --append Append text to the end of the entry --prepend Prepend text to the beginning of entry --file Replace blob file content (preserves label) --label Replace blob label (preserves content)

    Examples:

    ctx pad edit 2 \"new text\"\nctx pad edit 2 --append \" suffix\"\nctx pad edit 2 --prepend \"prefix \"\nctx pad edit 1 --file ./v2.yaml\nctx pad edit 1 --label \"new name\"\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-mv","level":4,"title":"ctx pad mv","text":"

    Move an entry from one position to another.

    ctx pad mv <from> <to>\n

    Arguments:

    • from: Source position (1-based)
    • to: Destination position (1-based)
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-resolve","level":4,"title":"ctx pad resolve","text":"

    Show both sides of a merge conflict in the encrypted scratchpad.

    ctx pad resolve\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-import","level":4,"title":"ctx pad import","text":"

    Bulk-import lines from a file into the scratchpad. Each non-empty line becomes a separate entry. All entries are written in a single encrypt/write cycle.

    With --blob, import all first-level files from a directory as blob entries. Each file becomes a blob with the filename as its label. Subdirectories and non-regular files are skipped.

    ctx pad import <file>\nctx pad import -              # read from stdin\nctx pad import --blob <dir>  # import directory files as blobs\n

    Arguments:

    • file: Path to a text file, - for stdin, or a directory (with --blob)

    Flags:

    Flag Description --blob Import first-level files from a directory as blobs

    Examples:

    ctx pad import notes.txt\ngrep TODO *.go | ctx pad import -\nctx pad import --blob ./ideas/\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-export","level":4,"title":"ctx pad export","text":"

    Export all blob entries from the scratchpad to a directory as files. Each blob's label becomes the filename. Non-blob entries are skipped.

    ctx pad export [dir]\n

    Arguments:

    • dir: Target directory (default: current directory)

    Flags:

    Flag Short Description --force -f Overwrite existing files instead of timestamping --dry-run Print what would be exported without writing

    When a file already exists, a unix timestamp is prepended to avoid collisions (e.g., 1739836200-label). Use --force to overwrite instead.

    Examples:

    ctx pad export ./ideas\nctx pad export --dry-run\nctx pad export --force ./backup\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pad-merge","level":4,"title":"ctx pad merge","text":"

    Merge entries from one or more scratchpad files into the current pad. Each input file is auto-detected as encrypted or plaintext. Entries are deduplicated by exact content.

    ctx pad merge FILE...\n

    Arguments:

    • FILE...: One or more scratchpad files to merge (encrypted or plaintext)

    Flags:

    Flag Short Description --key -k Path to key file for decrypting input files --dry-run Print what would be merged without writing

    Examples:

    ctx pad merge worktree/.context/scratchpad.enc\nctx pad merge notes.md backup.enc\nctx pad merge --key /path/to/other.key foreign.enc\nctx pad merge --dry-run pad-a.enc pad-b.md\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt","level":3,"title":"ctx prompt","text":"

    Manage reusable prompt templates stored in .context/prompts/.

    Templates are Markdown files that can be applied via the /ctx-prompt skill or listed and shown from the CLI.

    ctx prompt <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-list","level":4,"title":"ctx prompt list","text":"

    List all available prompt templates.

    ctx prompt list\n

    Aliases: ls

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-show","level":4,"title":"ctx prompt show","text":"

    Print a prompt template to stdout.

    ctx prompt show <name>\n

    Arguments:

    • name: Template name (without .md extension)
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-add","level":4,"title":"ctx prompt add","text":"

    Create a new prompt template. Reads from stdin when --stdin is set, otherwise creates from the embedded starter template.

    ctx prompt add <name> [flags]\n

    Arguments:

    • name: Template name (without .md extension)

    Flags:

    Flag Description --stdin Read template content from stdin

    Examples:

    # Create from starter template\nctx prompt add code-review\n\n# Create from stdin\necho \"Review this PR for security issues\" | ctx prompt add security-review --stdin\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-prompt-rm","level":4,"title":"ctx prompt rm","text":"

    Delete a prompt template.

    ctx prompt rm <name>\n

    Arguments:

    • name: Template name (without .md extension)

    See also: Prompt Templates

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind","level":3,"title":"ctx remind","text":"

    Session-scoped reminders that surface at session start. Reminders are stored verbatim and relayed verbatim: no summarization, no categories.

    When invoked with a text argument and no subcommand, adds a reminder.

    ctx remind \"text\"\nctx remind <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-add","level":4,"title":"ctx remind add","text":"

    Add a reminder. This is the default action: ctx remind \"text\" and ctx remind add \"text\" are equivalent.

    ctx remind \"refactor the swagger definitions\"\nctx remind add \"check CI after the deploy\" --after 2026-02-25\n

    Arguments:

    • text: The reminder message (verbatim)

    Flags:

    Flag Short Description --after -a Don't surface until this date (YYYY-MM-DD)

    Examples:

    ctx remind \"refactor the swagger definitions\"\nctx remind \"check CI after the deploy\" --after 2026-02-25\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-list","level":4,"title":"ctx remind list","text":"

    List all pending reminders. Date-gated reminders that aren't yet due are annotated with (after DATE, not yet due).

    ctx remind list\n

    Aliases: ls

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-remind-dismiss","level":4,"title":"ctx remind dismiss","text":"

    Remove a reminder by ID, or remove all reminders with --all.

    ctx remind dismiss <id>\nctx remind dismiss --all\n

    Arguments:

    • id: Reminder ID (shown in list output)

    Flags:

    Flag Description --all Dismiss all reminders

    Aliases: rm

    Examples:

    ctx remind dismiss 3\nctx remind dismiss --all\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-pause","level":3,"title":"ctx pause","text":"

    Pause all context nudge and reminder hooks for the current session. Security hooks (dangerous command blocking) and housekeeping hooks still fire.

    ctx pause [flags]\n

    Flags:

    Flag Description --session-id Session ID (overrides stdin)

    Example:

    # Pause hooks for a quick investigation\nctx pause\n\n# Resume when ready\nctx resume\n

    See also: Pausing Context Hooks

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-resume","level":3,"title":"ctx resume","text":"

    Resume context hooks after a pause. Silent no-op if not paused.

    ctx resume [flags]\n

    Flags:

    Flag Description --session-id Session ID (overrides stdin)

    Example:

    ctx resume\n

    See also: Pausing Context Hooks

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-completion","level":3,"title":"ctx completion","text":"

    Generate shell autocompletion scripts.

    ctx completion <shell>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#subcommands","level":4,"title":"Subcommands","text":"Shell Command bash ctx completion bash zsh ctx completion zsh fish ctx completion fish powershell ctx completion powershell","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#installation","level":4,"title":"Installation","text":"BashZshFish 
    # Add to ~/.bashrc\nsource <(ctx completion bash)\n
    # Add to ~/.zshrc\nsource <(ctx completion zsh)\n
    ctx completion fish | source\n# Or save to completions directory\nctx completion fish > ~/.config/fish/completions/ctx.fish\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-site","level":3,"title":"ctx site","text":"

    Site management commands for the ctx.ist static site.

    ctx site <subcommand>\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-site-feed","level":4,"title":"ctx site feed","text":"

    Generate an Atom 1.0 feed from finalized blog posts in docs/blog/.

    ctx site feed [flags]\n

    Scans docs/blog/ for files matching YYYY-MM-DD-*.md, parses YAML frontmatter, and generates a valid Atom feed. Only posts with reviewed_and_finalized: true are included. Summaries are extracted from the first paragraph after the heading.

    Flags:

    Flag Short Type Default Description --out -o string site/feed.xml Output path --base-url string https://ctx.ist Base URL for entry links

    Output:

    Generated site/feed.xml (21 entries)\n\nSkipped:\n  2026-02-25-the-homework-problem.md: not finalized\n\nWarnings:\n  2026-02-09-defense-in-depth.md: no summary paragraph found\n

    Three buckets: included (count), skipped (with reason), warnings (included but degraded). exit 0 always: warnings inform but do not block.

    Frontmatter requirements:

    Field Required Feed mapping title Yes <title> date Yes <updated> reviewed_and_finalized Yes Draft gate (must be true) author No <author><name> topics No <category term=\"\">

    Examples:

    ctx site feed                                # Generate site/feed.xml\nctx site feed --out /tmp/feed.xml            # Custom output path\nctx site feed --base-url https://example.com # Custom base URL\nmake site-feed                               # Makefile shortcut\nmake site                                    # Builds site + feed\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-guide","level":3,"title":"ctx guide","text":"

    Quick-reference cheat sheet for common ctx commands and skills.

    ctx guide [flags]\n

    Flags:

    Flag Description --skills Show available skills --commands Show available CLI commands

    Example:

    # Show the full cheat sheet\nctx guide\n\n# Skills only\nctx guide --skills\n\n# Commands only\nctx guide --commands\n

    Works without initialization (no .context/ required).

    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"cli/tools/#ctx-why","level":3,"title":"ctx why","text":"

    Read ctx's philosophy documents directly in the terminal.

    ctx why [DOCUMENT]\n

    Documents:

    Name Description manifesto The ctx Manifesto: creation, not code about About ctx: what it is and why it exists invariants Design invariants: properties that must hold

    Usage:

    # Interactive numbered menu\nctx why\n\n# Show a specific document\nctx why manifesto\nctx why about\nctx why invariants\n\n# Pipe to a pager\nctx why manifesto | less\n
    ","path":["CLI","Tools and Utilities"],"tags":[]},{"location":"home/","level":1,"title":"Home","text":"
    • ctx is not a prompt.
    • ctx is version-controlled cognitive state.

    ctx is the persistence layer for human-AI reasoning.

    Deterministic. Git-native. Human-readable. Local-first.

    Start here.

    Learn what ctx does, set it up, and run your first session.

    Pre-1.0: Moving Fast

    ctx is under active development. This website tracks the development branch, not the latest release:

    Some features described here may not exist in the binary you have installed.

    Expect rough edges.

    If something is missing or broken, open an issue.

    ","path":["Home"],"tags":[]},{"location":"home/#about-ctx","level":3,"title":"About ctx","text":"

    What ctx is, how it works, and why persistent context changes how you work with AI.

    ","path":["Home"],"tags":[]},{"location":"home/#is-it-right-for-me","level":3,"title":"Is It Right for Me?","text":"

    Good fit, not-so-good fit, and a 5-minute trial to find out for yourself.

    ","path":["Home"],"tags":[]},{"location":"home/#community","level":3,"title":"Community","text":"

    We are the builders who care about durable context. Join the community. Hang out in IRC. Star ctx on GitHub.

    ","path":["Home"],"tags":[]},{"location":"home/#contributing","level":3,"title":"Contributing","text":"

    Development setup, project layout, and pull request process.

    ","path":["Home"],"tags":[]},{"location":"home/#getting-started","level":3,"title":"Getting Started","text":"

    Install the binary, set up the plugin, and verify it works.

    ","path":["Home"],"tags":[]},{"location":"home/#your-first-session","level":3,"title":"Your First Session","text":"

    Step-by-step walkthrough from ctx init to verified recall.

    ","path":["Home"],"tags":[]},{"location":"home/#common-workflows","level":3,"title":"Common Workflows","text":"

    Day-to-day commands for tracking context, checking health, and browsing history.

    ","path":["Home"],"tags":[]},{"location":"home/#context-files","level":3,"title":"Context Files","text":"

    What each .context/ file does. What's their purpose. How do we best leverage them.

    ","path":["Home"],"tags":[]},{"location":"home/#configuration","level":3,"title":"Configuration","text":"

    Flexible configuration: .ctxrc, environment variables, and CLI flags.

    ","path":["Home"],"tags":[]},{"location":"home/#prompting-guide","level":3,"title":"Prompting Guide","text":"

    Effective prompts for AI sessions with ctx.

    ","path":["Home"],"tags":[]},{"location":"home/about/","level":1,"title":"About","text":"

    \"Creation, not code; Context, not prompts; Verification, not vibes.\"

    Read the ctx Manifesto →

    \"Without durable context, intelligence resets; with ctx, creation compounds.\"

    Without persistent memory, every session starts at zero; ctx makes sessions cumulative.

    Join the ctx Community →

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#what-is-ctx","level":2,"title":"What Is ctx?","text":"

    ctx (Context) is a file-based system that enables AI coding assistants to persist project knowledge across sessions. It lives in a .context/ directory in your repo.

    • A session is interactive.
    • ctx enables cognitive continuity.
    • Cognitive continuity enables durable, symbiotic-like human-AI workflows.

    Context Files

    Context files let AI tools remember decisions, conventions, and learnings:

    Context files are explicit and versionable contracts between you and your agents.

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#why-do-i-keep-re-explaining-my-codebase","level":2,"title":"Why Do I Keep Re-Explaining My Codebase?!?!","text":"

    You open a new AI session. The first thing you do is re-explain your project.

    Again.

    The architecture, the database choice, the naming conventions, the thing you tried last week that didn't work. You have said all of this before (maybe yesterday, maybe an hour ago), but the AI doesn't know that.

    • You explain the same architecture every session;
    • The AI suggests an approach you already rejected, again;
    • A decision you made three sessions ago gets relitigated from scratch;
    • You spend more time setting context than building features.

    This isn't AI failure: It is staleness.

    Without persistent memory, every session starts at zero.

    ","path":["Home","About"],"tags":[]},{"location":"home/about/#day-and-night","level":3,"title":"Day and Night","text":"

    ctx gives your AI a memory that persists across sessions:

    Without ctxWith ctx 
    Session 12: Monday morning\n\nAI:  \"I'll scaffold a MySQL schema for this.\"\nYou: \"We use PostgreSQL.\"\n\nAI:  \"For auth, session-based would be simplest.\"\nYou: \"We decided on JWT.\"\n\nAI:  \"Endpoints in camelCase?\"\nYou: \"snake_case! Like the rest of the API!!!!!!\"\n\nYou: *scrolls up to copy an existing endpoint*\n\n20 minutes spent restoring decisions that already exist.\n
    Session 12: Monday morning\n\nYou:  \"Let's continue the auth implementation.\"\nAI:   \"Per DECISIONS.md (2026-02-12): JWT, not sessions: \n       The project uses PostgreSQL with JWT\n       authentication. The API follows snake_case conventions.\n       Last session you completed the login endpoint: the\n       registration endpoint is next on TASKS.md. Want me to\n       start there?\"\n\n0 minutes re-explaining. Straight to building.\n
    ","path":["Home","About"],"tags":[]},{"location":"home/about/#how-ctx-solves-this","level":3,"title":"How ctx Solves This","text":"

    ctx creates a .context/ directory in your project that stores structured knowledge files:

    File What It Remembers TASKS.md What you're working on and what's next DECISIONS.md Architectural choices and why you made them LEARNINGS.md Gotchas, bugs, things that didn't work CONVENTIONS.md Naming patterns, code style, project rules CONSTITUTION.md Hard rules the AI must never violate

    These files can version with your code in git:

    • They load automatically at the session start (via hooks in Claude Code, or manually with ctx agent for other tools).
    • The AI reads them, cites them, and builds on them, instead of asking you to start over.
      • And when it acts, it can point to the exact file and line that justifies the choice.

    Every decision you record, every lesson you capture, makes the next session smarter.

    ctx accumulates.

    Connect with ctx

    • Join the Community →: ask questions, share workflows, and help shape what comes next
    • Read the Blog →: real-world patterns, ponderings, and lessons learned from building ctx using ctx

    Ready to Get Started?

    • Getting Started →: full installation and setup
    • Your First Session →: step-by-step walkthrough from ctx init to verified recall
    ","path":["Home","About"],"tags":[]},{"location":"home/common-workflows/","level":1,"title":"Common Workflows","text":"

    The commands below cover what you'll use most often:

    • recording context,
    • checking health,
    • browsing history,
    • and running loops.

    Each section is a self-contained snippet you can copy into your terminal.

    For deeper, step-by-step guides, see Recipes.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#track-context","level":2,"title":"Track Context","text":"
    # Add a task\nctx add task \"Implement user authentication\"\n\n# Record a decision (full ADR fields required)\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Note a learning\nctx add learning \"Mock functions must be hoisted in Jest\" \\\n  --context \"Tests failed with undefined mock errors\" \\\n  --lesson \"Jest hoists mock calls to top of file\" \\\n  --application \"Place jest.mock() before imports\"\n\n# Mark task complete\nctx task complete \"user auth\"\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#leave-a-reminder-for-next-session","level":2,"title":"Leave a Reminder for Next Session","text":"

    Drop a note that surfaces automatically at the start of your next session:

    # Leave a reminder\nctx remind \"refactor the swagger definitions\"\n\n# Date-gated: don't surface until a specific date\nctx remind \"check CI after the deploy\" --after 2026-02-25\n\n# List pending reminders\nctx remind list\n\n# Dismiss a reminder by ID\nctx remind dismiss 1\n

    Reminders are relayed verbatim at session start by the check-reminders hook and repeat every session until you dismiss them.

    See Session Reminders for the full recipe.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#check-context-health","level":2,"title":"Check Context Health","text":"
    # Detect stale paths, missing files, potential secrets\nctx drift\n\n# See full context summary\nctx status\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#browse-session-history","level":2,"title":"Browse Session History","text":"

    List and search past AI sessions from the terminal:

    ctx recall list --limit 5\n
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#journal-site","level":3,"title":"Journal Site","text":"

    Export session transcripts to a browsable static site with search, navigation, and topic indices.

    The ctx journal command requires zensical (Python >= 3.10).

    zensical is a Python-based static site generator from the Material for MkDocs team.

    (why zensical?).

    If you don't have it on your system, install zensical once with pipx:

    # One-time setup\npipx install zensical\n

    Avoid pip install zensical

    pip install often fails: For example, on macOS, system Python installs a non-functional stub (zensical requires Python >= 3.10), and Homebrew Python blocks system-wide installs (PEP 668).

    pipx creates an isolated environment with the correct Python version automatically.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#export-and-serve","level":3,"title":"Export and Serve","text":"

    Then, export and serve:

    # Export all sessions to .context/journal/ (only new files)\nctx recall export --all\n\n# Generate and serve the journal site\nctx journal site --serve\n

    Open http://localhost:8000 to browse.

    To update after new sessions, run the same two commands again.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#safe-by-default","level":3,"title":"Safe By Default","text":"

    ctx recall export --all is safe by default:

    • It only exports new sessions and skips existing files.
    • Locked entries (via ctx recall lock) are always skipped by both export and enrichment skills.
    • If you add locked: true to frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json.
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#re-exporting-existing-files","level":3,"title":"Re-Exporting Existing Files","text":"

    Here is how you regenerate existing files.

    Backup your .context folder before regeneration, as this is a potentially destructive action.

    To re-export journal files, you need to explicitly opt-in using the --regenerate flag:

    Flag combination Frontmatter Body --regenerate Preserved Overwritten from source --regenerate --keep-frontmatter=false Overwritten Overwritten

    Regeneration Overwrites Body Edits

    --regenerate preserves your YAML frontmatter (tags, summary, enrichment metadata) but it replaces the Markdown body with a fresh export.

    Any manual edits you made to the transcript will be lost.

    Lock entries you want to protect first: ctx recall lock <session-id>.

    See Session Journal for the full pipeline including normalization and enrichment.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#scratchpad","level":2,"title":"Scratchpad","text":"

    Store short, sensitive one-liners in an encrypted scratchpad that travels with the project:

    # Write a note\nctx pad set db-password \"postgres://user:pass@localhost/mydb\"\n\n# Read it back\nctx pad get db-password\n\n# List all keys\nctx pad list\n

    The scratchpad is encrypted with a key stored at ~/.ctx/.ctx.key (outside the project, never committed).

    See Scratchpad for details.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#run-an-autonomous-loop","level":2,"title":"Run an Autonomous Loop","text":"

    Generate a script that iterates an AI agent until a completion signal is detected:

    ctx loop\nchmod +x loop.sh\n./loop.sh\n

    See Autonomous Loops for configuration and advanced usage.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#agent-session-start","level":2,"title":"Agent Session Start","text":"

    The first thing an AI agent should do at session start is discover where context lives:

    ctx system bootstrap\n

    This prints the resolved context directory, the files in it, and the operating rules. The CLAUDE.md template instructs the agent to run this automatically. See CLI Reference: bootstrap.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#the-two-skills-you-should-always-use","level":2,"title":"The Two Skills You Should Always Use","text":"

    Using /ctx-remember at session start and /ctx-wrap-up at session end are the highest-value skills in the entire catalog:

    # session begins:\n/ctx-remember\n... do work ...\n# before closing the session:\n/ctx-wrap-up\n

    Let's provide some context, because this is important:

    Although the agent will eventually discover your context through CLAUDE.md → AGENT_PLAYBOOK.md, /ctx-remember hydrates the full context up front (tasks, decisions, recent sessions) so the agent starts informed rather than piecing things together over several turns.

    /ctx-wrap-up is the other half: A structured review that captures learnings, decisions, and tasks before you close the window.

    Hooks like check-persistence remind you (the user) mid-session that context hasn't been saved in a while, but they don't trigger persistence automatically: You still have to act. Also, a CTRL+C can end things at any moment with no reliable \"before session end\" event.

    In short, /ctx-wrap-up is the deliberate checkpoint that makes sure nothing slips through. And /ctx-remember it its mirror skill to be used at session start.

    See Session Ceremonies for the full workflow.

    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#cli-commands-vs-ai-skills","level":2,"title":"CLI Commands vs. AI Skills","text":"

    Most ctx operations come in two flavors: a CLI command you run in your terminal and an AI skill (slash command) you invoke inside your coding assistant.

    Commands and skills are not interchangeable: Each has a distinct role.

    ctx CLI command ctx AI skill Runs where Your terminal Inside the AI assistant Speed Fast (milliseconds) Slower (LLM round-trip) Cost Free Consumes tokens and context Analysis Deterministic heuristics Semantic / judgment-based Best for Quick checks, scripting, CI Deep analysis, generation, workflow orchestration","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#paired-commands","level":3,"title":"Paired Commands","text":"

    These have both a CLI and a skill counterpart. Use the CLI for quick, deterministic checks; use the skill when you need the agent's judgment.

    CLI Skill When to prefer the skill ctx drift /ctx-drift Semantic analysis: catches meaning drift the CLI misses ctx status /ctx-status Interpreted summary with recommendations ctx add task /ctx-add-task Agent decomposes vague goals into concrete tasks ctx add decision /ctx-add-decision Agent drafts rationale and consequences from discussion ctx add learning /ctx-add-learning Agent extracts the lesson from a debugging session ctx add convention /ctx-add-convention Agent observes a repeated pattern and codifies it ctx task archive /ctx-archive Agent reviews which tasks are truly done ctx pad /ctx-pad Agent reads/writes scratchpad entries in conversation flow ctx recall /ctx-recall Agent searches session history with semantic understanding ctx agent /ctx-agent Agent loads and acts on the context packet ctx loop /ctx-loop Agent tailors the loop script to your project ctx doctor /ctx-doctor Agent adds semantic analysis to structural checks ctx pause /ctx-pause Agent pauses hooks with session-aware reasoning ctx resume /ctx-resume Agent resumes hooks after a pause ctx remind /ctx-remind Agent manages reminders in conversation flow","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#ai-only-skills","level":3,"title":"AI-Only Skills","text":"

    These have no CLI equivalent. They require the agent's reasoning.

    Skill Purpose /ctx-remember Load context and present structured readback at session start /ctx-wrap-up End-of-session ceremony: persist learnings, decisions, tasks /ctx-next Suggest 1-3 concrete next actions from context /ctx-commit Commit with integrated context capture /ctx-reflect Pause and assess session progress /ctx-consolidate Merge overlapping learnings or decisions /ctx-prompt-audit Analyze prompting patterns for improvement /ctx-import-plans Import Claude Code plan files into project specs /ctx-implement Execute a plan step-by-step with verification /ctx-worktree Manage parallel agent worktrees /ctx-journal-normalize Fix markdown rendering issues in journal entries /ctx-journal-enrich Add metadata, tags, and summaries to journal entries /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich /ctx-blog Generate a blog post (zensical-flavored Markdown) /ctx-blog-changelog Generate themed blog post from commits between releases /ctx-architecture Build and maintain architecture maps (ARCHITECTURE.md, DETAILED_DESIGN.md)","path":["Home","Common Workflows"],"tags":[]},{"location":"home/common-workflows/#cli-only-commands","level":3,"title":"CLI-Only Commands","text":"

    These are infrastructure: used in scripts, CI, or one-time setup.

    Command Purpose ctx init Initialize .context/ directory ctx load Output assembled context for piping ctx task complete Mark a task done by substring match ctx sync Reconcile context with codebase state ctx compact Consolidate and clean up context files ctx hook Generate AI tool integration config ctx watch Watch AI output and auto-apply context updates ctx serve Serve any zensical directory (default: journal) ctx permission snapshot Save settings as a golden image ctx permission restore Restore settings from golden image ctx journal site Generate browsable journal from exports ctx notify setup Configure webhook notifications ctx decision List and filter decisions ctx learning List and filter learnings ctx task List tasks, manage archival and snapshots ctx why Read the philosophy behind ctx ctx guide Quick-reference cheat sheet ctx site Site management commands ctx config Manage runtime configuration profiles ctx system System diagnostics and hook commands ctx system backup Back up context and Claude data to tar.gz / SMB ctx completion Generate shell autocompletion scripts

    Rule of Thumb

    Quick check? Use the CLI.

    Need judgment? Use the skill.

    When in doubt, start with the CLI: It's free and instant.

    Escalate to the skill when heuristics aren't enough.

    Next Up: Context Files →: what each .context/ file does and how to use it

    See Also:

    • Recipes: targeted how-to guides for specific tasks
    • Knowledge Capture: patterns for recording decisions, learnings, and conventions
    • Context Health: keeping your .context/ accurate and drift-free
    • Session Archaeology: digging into past sessions
    • Task Management: tracking and completing work items
    ","path":["Home","Common Workflows"],"tags":[]},{"location":"home/community/","level":1,"title":"#ctx","text":"

    Open source is better together.

    We are the builders who care about durable context, verifiable decisions, and human-AI workflows that compound over time.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#help-ctx-change-how-ai-remembers","level":2,"title":"Help ctx Change How AI Remembers","text":"

    If you like the idea, a star helps ctx reach engineers who run into context drift every day:

    Star ctx on GitHub ⭐

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#ctx-you","level":2,"title":"ctx ♥️ You","text":"

    Join the community to ask questions, share feedback, and connect with other users:

    • IRC join #ctx on irc.libera.chat: Real-time discussion, field notes, and early ideas.
    • Read the ctx Source on GitHub: Issues, discussions, and contributions.
    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#want-to-contribute","level":2,"title":"Want to Contribute?","text":"

    Early adopters shape the conventions.

    ctx is free and open source software.

    Contributions are always welcome and appreciated.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/community/#code-of-conduct","level":2,"title":"Code of Conduct","text":"

    Clear context requires respectful collaboration.

    ctx follows the Contributor Covenant.

    ","path":["Home","#ctx"],"tags":[]},{"location":"home/configuration/","level":1,"title":"Configuration","text":"","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#configuration","level":2,"title":"Configuration","text":"

    ctx uses three layers of configuration. Each layer overrides the one below it:

    1. CLI flags: Per-invocation overrides (highest priority)
    2. Environment variables: Shell or CI/CD overrides
    3. The .ctxrc file: Project-level defaults (YAML)
    4. Built-in defaults: Hardcoded fallbacks (lowest priority)

    All settings are optional: If nothing is configured, ctx works out of the box with sensible defaults.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#the-ctxrc-file","level":2,"title":"The .ctxrc File","text":"

    The .ctxrc file is an optional YAML file placed in the project root (next to your .context/ directory). It lets you set project-level defaults that apply to every ctx command.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#location","level":3,"title":"Location","text":"
    my-project/\n├── .ctxrc              ← configuration file\n├── .context/\n│   ├── TASKS.md\n│   ├── DECISIONS.md\n│   └── ...\n└── src/\n

    ctx looks for .ctxrc in the current working directory when any command runs. There is no global or user-level config file: Configuration is always per-project.

    Contributors: Dev Configuration Profile

    The ctx repo ships two .ctxrc source profiles (.ctxrc.base and .ctxrc.dev). The working copy is gitignored and swapped between them via ctx config switch dev / ctx config switch base. See Contributing: Configuration Profiles.

    Using a Different .context Directory

    The default .context/ directory can be changed per-project via the context_dir key in .ctxrc, the CTX_DIR environment variable, or the --context-dir CLI flag.

    See Environment Variables and CLI Global Flags below for details.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#full-reference","level":3,"title":"Full Reference","text":"

    A commented .ctxrc showing all options and their defaults:

    # .ctxrc: ctx runtime configuration\n# https://ctx.ist/configuration/\n#\n# All settings are optional. Missing values use defaults.\n# Priority: CLI flags > environment variables > .ctxrc > defaults\n#\n# context_dir: .context\n# token_budget: 8000\n# auto_archive: true\n# archive_after_days: 7\n# scratchpad_encrypt: true\n# allow_outside_cwd: false\n# event_log: false\n# entry_count_learnings: 30\n# entry_count_decisions: 20\n# convention_line_count: 200\n# injection_token_warn: 15000\n# context_window: 200000      # auto-detected for Claude Code; override for other tools\n# billing_token_warn: 0       # one-shot warning at this token count (0 = disabled)\n#\n# stale_age_days: 30      # days before drift flags a context file as stale (0 = disabled)\n# key_rotation_days: 90\n# task_nudge_interval: 5   # Edit/Write calls between task completion nudges\n#\n# notify:               # requires: ctx notify setup\n#   events:             # required: no events sent unless listed\n#     - loop\n#     - nudge\n#     - relay\n#\n# priority_order:\n#   - CONSTITUTION.md\n#   - TASKS.md\n#   - CONVENTIONS.md\n#   - ARCHITECTURE.md\n#   - DECISIONS.md\n#   - LEARNINGS.md\n#   - GLOSSARY.md\n#   - AGENT_PLAYBOOK.md\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#option-reference","level":3,"title":"Option Reference","text":"Option Type Default Description context_dir string .context Context directory name (relative to project root) token_budget int 8000 Default token budget for ctx agent and ctx load auto_archive bool true Auto-archive completed tasks during ctx compact archive_after_days int 7 Days before completed tasks are archived scratchpad_encrypt bool true Encrypt scratchpad with AES-256-GCM allow_outside_cwd bool false Allow context directory outside the current working directory event_log bool false Enable local hook event logging to .context/state/events.jsonl entry_count_learnings int 30 Drift warning when LEARNINGS.md exceeds this entry count (0 = disable) entry_count_decisions int 20 Drift warning when DECISIONS.md exceeds this entry count (0 = disable) convention_line_count int 200 Drift warning when CONVENTIONS.md exceeds this line count (0 = disable) injection_token_warn int 15000 Warn when auto-injected context exceeds this token count (0 = disable) context_window int 200000 Context window size in tokens. Auto-detected for Claude Code (200k/1M); override for other AI tools billing_token_warn int 0 (off) One-shot warning when session tokens exceed this threshold (0 = disabled). For plans where tokens beyond an included allowance cost extra stale_age_days int 30 Days before ctx drift flags a context file as stale (0 = disable) key_rotation_days int 90 Days before encryption key rotation nudge task_nudge_interval int 5 Edit/Write calls between task completion nudges notify.events []string (all) Event filter for webhook notifications (empty = all) priority_order []string (see below) Custom file loading priority for context assembly

    Default priority order (used when priority_order is not set):

    1. CONSTITUTION.md
    2. TASKS.md
    3. CONVENTIONS.md
    4. ARCHITECTURE.md
    5. DECISIONS.md
    6. LEARNINGS.md
    7. GLOSSARY.md
    8. AGENT_PLAYBOOK.md

    See Context Files for the rationale behind this ordering.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#environment-variables","level":2,"title":"Environment Variables","text":"

    Environment variables override .ctxrc values but are overridden by CLI flags.

    Variable Description Equivalent .ctxrc key CTX_DIR Override the context directory path context_dir CTX_TOKEN_BUDGET Override the default token budget token_budget","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples","level":3,"title":"Examples","text":"
    # Use a shared context directory\nCTX_DIR=/shared/team-context ctx status\n\n# Increase token budget for a single run\nCTX_TOKEN_BUDGET=16000 ctx agent\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#cli-global-flags","level":2,"title":"CLI Global Flags","text":"

    CLI flags have the highest priority and override both environment variables and .ctxrc settings. These flags are available on every ctx command.

    Flag Description --context-dir <path> Override context directory (default: .context/) --allow-outside-cwd Allow context directory outside current working directory --version Show version and exit --help Show command help and exit","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples_1","level":3,"title":"Examples","text":"
    # Point to a different context directory:\nctx status --context-dir /path/to/shared/.context\n\n# Allow external context directory (skips boundary check):\nctx status --context-dir /mnt/nas/project-context --allow-outside-cwd\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#priority-order","level":2,"title":"Priority Order","text":"

    When the same setting is configured in multiple layers, the highest-priority layer wins:

    CLI flags  >  Environment variables  >  .ctxrc  >  Built-in defaults\n(highest)                                          (lowest)\n

    Example resolution for context_dir:

    Layer Value Wins? --context-dir /tmp/ctx Yes CTX_DIR /shared/context No .ctxrc .my-context No Default .context No

    The CLI flag /tmp/ctx is used because it has the highest priority.

    If the CLI flag were absent, CTX_DIR=/shared/context would win. If neither the flag nor the env var were set, the .ctxrc value .my-context would be used. With nothing configured, the default .context applies.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#examples_2","level":2,"title":"Examples","text":"","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#external-context-directory","level":3,"title":"External .context Directory","text":"

    Store context outside the project tree (useful for monorepos or shared context):

    # .ctxrc\ncontext_dir: /home/team/shared-context\nallow_outside_cwd: true\n
    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#custom-token-budget","level":3,"title":"Custom Token Budget","text":"

    Increase the token budget for projects with large context:

    # .ctxrc\ntoken_budget: 16000\n

    This affects the default budget for ctx agent and ctx load. You can still override per-invocation with ctx agent --budget 4000.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#disabled-scratchpad-encryption","level":3,"title":"Disabled Scratchpad Encryption","text":"

    Turn off encryption for the scratchpad (useful in ephemeral environments where key management is unnecessary):

    # .ctxrc\nscratchpad_encrypt: false\n

    Unencrypted Scratchpads Store Secrets in Plaintext

    Only disable encryption if you understand the security implications.

    The scratchpad may contain sensitive data such as API keys, database URLs, or deployment credentials.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#custom-priority-order","level":3,"title":"Custom Priority Order","text":"

    Reorder context files to prioritize architecture over conventions:

    # .ctxrc\npriority_order:\n  - CONSTITUTION.md\n  - TASKS.md\n  - ARCHITECTURE.md\n  - DECISIONS.md\n  - CONVENTIONS.md\n  - LEARNINGS.md\n  - GLOSSARY.md\n  - AGENT_PLAYBOOK.md\n

    Files not listed in priority_order receive the lowest priority (100). The order affects ctx agent, ctx load, and drift's file-priority calculations.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#billing-token-threshold","level":3,"title":"Billing Token Threshold","text":"

    Get a one-shot warning when your session crosses a token threshold where extra charges begin (e.g., Claude Pro includes 200k tokens; beyond that costs extra):

    # .ctxrc\nbilling_token_warn: 180000   # warn before hitting the 200k paid boundary\n

    The warning fires once per session the first time token usage exceeds the threshold. Set to 0 (or omit) to disable.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#adjusted-drift-thresholds","level":3,"title":"Adjusted Drift Thresholds","text":"

    Raise or lower the entry-count thresholds that trigger drift warnings:

    # .ctxrc\nentry_count_learnings: 50   # warn above 50 learnings (default: 30)\nentry_count_decisions: 10   # warn above 10 decisions (default: 20)\nconvention_line_count: 300  # warn above 300 lines (default: 200)\n

    Set any threshold to 0 to disable that specific check.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#webhook-notifications","level":3,"title":"Webhook Notifications","text":"

    Get notified when loops complete, hooks fire, or agents reach milestones:

    # Configure the webhook URL (encrypted, safe to commit)\nctx notify setup\n\n# Test delivery\nctx notify test\n

    Filter which events reach your webhook:

    # .ctxrc\nnotify:\n  events:\n    - loop      # loop completion/max-iteration\n    - nudge     # VERBATIM relay hooks fired\n    # - relay   # all hook output (verbose, for debugging)\n    # - heartbeat  # every-prompt session-alive signal\n

    Notifications are opt-in: No events are sent unless explicitly listed.

    See Webhook Notifications for a step-by-step recipe.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#hook-message-overrides","level":2,"title":"Hook Message Overrides","text":"

    Hook messages control what text hooks emit when they fire. Each message can be overridden per-project by placing a text file at the matching path under .context/:

    .context/hooks/messages/{hook}/{variant}.txt\n

    The override takes priority over the embedded default compiled into the ctx binary. An empty file silences the message while preserving the hook's logic (counting, state tracking, cooldowns).

    Use ctx system message to discover and manage overrides:

    ctx system message list                      # see all messages\nctx system message show qa-reminder gate     # view the current template\nctx system message edit qa-reminder gate     # copy default for editing\nctx system message reset qa-reminder gate    # revert to default\n

    See Customizing Hook Messages for detailed examples including Python, JavaScript, and silence configurations.

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/configuration/#agent-bootstrapping","level":2,"title":"Agent Bootstrapping","text":"

    AI agents need to know the resolved context directory at session start. The ctx system bootstrap command prints the context path, file list, and operating rules in both text and JSON formats:

    ctx system bootstrap          # text output for agents\nctx system bootstrap -q       # just the context directory path\nctx system bootstrap --json   # structured output for automation\n

    The CLAUDE.md template instructs the agent to run this as its first action. Every nudge (context checkpoint, persistence reminder, etc.) also includes a Context: <dir> footer that re-anchors the agent to the correct directory throughout the session.

    This replaces the previous approach of hardcoding .context/ paths in agent instructions.

    See CLI Reference: bootstrap for full details.

    See also: CLI Reference | Context Files | Scratchpad

    ","path":["Home","Configuration"],"tags":[]},{"location":"home/context-files/","level":1,"title":"Context Files","text":"","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#context","level":2,"title":".context/","text":"

    Each context file in .context/ serves a specific purpose.

    Files are designed to be human-readable, AI-parseable, and token-efficient.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#file-overview","level":2,"title":"File Overview","text":"File Purpose Priority CONSTITUTION.md Hard rules that must NEVER be violated 1 (highest) TASKS.md Current and planned work 2 CONVENTIONS.md Project patterns and standards 3 ARCHITECTURE.md System overview and components 4 DECISIONS.md Architectural decisions with rationale 5 LEARNINGS.md Lessons learned, gotchas, tips 6 GLOSSARY.md Domain terms and abbreviations 7 AGENT_PLAYBOOK.md Instructions for AI tools 8 (lowest) prompts/ Reusable prompt templates (optional)","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#read-order-rationale","level":2,"title":"Read Order Rationale","text":"

    The priority order follows a logical progression for AI tools:

    1. CONSTITUTION.md: Inviolable rules first. The AI tool must know what it cannot do before attempting anything.
    2. TASKS.md: Current work items. What the AI tool should focus on.
    3. CONVENTIONS.md: How to write code. Patterns and standards to follow when implementing tasks.
    4. ARCHITECTURE.md: System structure. Understanding of components and boundaries before making changes.
    5. DECISIONS.md: Historical context. Why things are the way they are, to avoid re-debating settled decisions.
    6. LEARNINGS.md: Gotchas and tips. Lessons from past work that inform the current implementation.
    7. GLOSSARY.md: Reference material. Domain terms and abbreviations for lookup as needed.
    8. AGENT_PLAYBOOK.md: Meta instructions last. How to use this context system itself. Loaded last because the agent should understand the content (rules, tasks, patterns) before the operating manual.
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#constitutionmd","level":2,"title":"CONSTITUTION.md","text":"

    Purpose: Define hard invariants: Rules that must NEVER be violated, regardless of the task.

    AI tools read this first and should refuse tasks that violate these rules.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure","level":3,"title":"Structure","text":"
    # Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these, the task \nis wrong.\n\n## Security Invariants\n\n* [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] Never store customer/user data in context files\n* [ ] Never disable security linters without documented exception\n\n## Quality Invariants\n\n* [ ] All code must pass tests before commit\n* [ ] No `any` types in TypeScript without documented reason\n* [ ] No TODO comments in main branch (*move to `TASKS.md`*)\n\n## Process Invariants\n\n* [ ] All architectural changes require a decision record\n* [ ] Breaking changes require version bump\n* [ ] Generated files are never committed\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines","level":3,"title":"Guidelines","text":"
    • Keep rules minimal and absolute
    • Each rule should be enforceable (can verify compliance)
    • Use checkbox format for clarity
    • Never compromise on these rules
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#tasksmd","level":2,"title":"TASKS.md","text":"

    Purpose: Track current work, planned work, and blockers.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_1","level":3,"title":"Structure","text":"

    Tasks are organized by Phase: logical groupings that preserve order and enable replay.

    Tasks stay in their Phase permanently; status is tracked via checkboxes and inline tags.

    # Tasks\n\n## Phase 1: Initial Setup\n\n* [x] Set up project structure\n* [x] Configure linting and formatting\n* [ ] Add CI/CD pipeline `#in-progress`\n\n## Phase 2: Core Features\n\n* [ ] Implement user authentication `#priority:high`\n* [ ] Add API rate limiting `#priority:medium`\n  * Blocked by: Need to finalize auth first\n\n## Backlog\n\n* [ ] Performance optimization `#priority:low`\n* [ ] Add metrics dashboard `#priority:deferred`\n

    Key principles:

    • Tasks never move between sections: mark as [x] or [-] in place
    • Use #in-progress inline tag to indicate current work
    • Phase headers provide structure and replay order
    • Backlog section for unscheduled work
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#tags","level":3,"title":"Tags","text":"

    Use inline backtick-wrapped tags for metadata:

    Tag Values Purpose #priority high, medium, low Task urgency #area core, cli, docs, tests Codebase area #estimate 1h, 4h, 1d Time estimate (optional) #in-progress (none) Currently being worked on

    Lifecycle tags (for session correlation):

    Tag Format When to add #added YYYY-MM-DD-HHMMSS Auto-added by ctx add task #started YYYY-MM-DD-HHMMSS When beginning work on the task #done YYYY-MM-DD-HHMMSS When marking the task [x]

    These timestamps help correlate tasks with session files and track which session started vs completed work.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#status-markers","level":3,"title":"Status Markers","text":"Marker Meaning [ ] Pending [x] Completed [-] Skipped (include reason)","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_1","level":3,"title":"Guidelines","text":"
    • Never delete tasks; mark as [x] completed or [-] skipped
    • Never move tasks between sections; use inline tags for status
    • Use ctx task archive periodically to move completed tasks to archive
    • Mark current work with #in-progress inline tag
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#decisionsmd","level":2,"title":"DECISIONS.md","text":"

    Purpose: Record architectural decisions with rationale so they don't get re-debated.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_2","level":3,"title":"Structure","text":"
    # Decisions\n\n## [YYYY-MM-DD] Decision Title\n\n**Status**: Accepted | Superseded | Deprecated\n\n**Context**: What situation prompted this decision?\n\n**Decision**: What was decided?\n\n**Rationale**: Why was this the right choice?\n\n**Consequence**: What are the implications?\n\n**Alternatives Considered**:\n* Alternative A: Why rejected\n* Alternative B: Why rejected\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#example","level":3,"title":"Example","text":"
    ## [2025-01-15] Use TypeScript Strict Mode\n\n**Status**: Accepted\n\n**Context**: Starting a new project, need to choose the type-checking level.\n\n**Decision**: Enable TypeScript strict mode with all strict flags.\n\n**Rationale**: Catches more bugs at compile time. Team has experience\nwith strict mode. Upfront cost pays off in reduced runtime errors.\n\n**Consequence**: More verbose type annotations required. Some\nthird-party libraries need type assertions.\n\n**Alternatives Considered**:\n- Basic TypeScript: Rejected because it misses null checks\n- JavaScript with JSDoc: Rejected because tooling support is weaker\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#status-values","level":3,"title":"Status Values","text":"Status Meaning Accepted Current, active decision Superseded Replaced by newer decision (link to it) Deprecated No longer relevant","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#learningsmd","level":2,"title":"LEARNINGS.md","text":"

    Purpose: Capture lessons learned, gotchas, and tips that shouldn't be forgotten.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_3","level":3,"title":"Structure","text":"
    # Learnings\n\n## Category Name\n\n### Learning Title\n\n**Discovered**: YYYY-MM-DD\n\n**Context**: When/how was this learned?\n\n**Lesson**: What's the takeaway?\n\n**Application**: How should this inform future work?\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#example_1","level":3,"title":"Example","text":"
    ## Testing\n\n### Vitest Mocks Must Be Hoisted\n\n**Discovered**: 2025-01-15\n\n**Context**: Tests were failing intermittently when mocking fs module.\n\n**Lesson**: Vitest requires `vi.mock()` calls to be hoisted to the\ntop of the file. Dynamic mocks need `vi.doMock()` instead.\n\n**Application**: Always use `vi.mock()` at file top. Use `vi.doMock()`\nonly when mock needs runtime values.\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#categories","level":3,"title":"Categories","text":"

    Organize learnings by topic:

    • Testing
    • Build & Deploy
    • Performance
    • Security
    • Third-Party Libraries
    • Git and Workflow
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#conventionsmd","level":2,"title":"CONVENTIONS.md","text":"

    Purpose: Document project patterns, naming conventions, and standards.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_4","level":3,"title":"Structure","text":"
    # Conventions\n\n## Naming\n\n* **Files**: kebab-case for all source files\n* **Components**: PascalCase for React components\n* **Functions**: camelCase, verb-first (getUser, parseConfig)\n* **Constants**: SCREAMING_SNAKE_CASE\n\n## Patterns\n\n### Pattern Name\n\n**When to use**: Situation description\n\n**Implementation**:\n// in triple backticks\n// Example code\n\n**Why**: Rationale for this pattern\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_2","level":3,"title":"Guidelines","text":"
    • Include concrete examples
    • Explain the \"why\" not just the \"what\"
    • Keep patterns minimal: Only document what's non-obvious
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#architecturemd","level":2,"title":"ARCHITECTURE.md","text":"

    Purpose: Provide system overview and component relationships.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_5","level":3,"title":"Structure","text":"
    # Architecture\n\n## Overview\n\nBrief description of what the system does and how it's organized.\n\n## Components\n\n### Component Name\n\n**Responsibility**: What this component does\n\n**Dependencies**: What it depends on\n\n**Dependents**: What depends on it\n\n**Key Files**:\n* path/to/file.ts: Description\n\n## Data Flow\n\nDescription or diagram of how data moves through the system.\n\n## Boundaries\n\nWhat's in scope vs out of scope for this codebase.\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_3","level":3,"title":"Guidelines","text":"
    • Keep diagrams simple (Mermaid works well)
    • Focus on boundaries and interfaces
    • Update when major structural changes occur
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#glossarymd","level":2,"title":"GLOSSARY.md","text":"

    Purpose: Define domain terms, abbreviations, and project vocabulary.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#structure_6","level":3,"title":"Structure","text":"
    # Glossary\n\n## Domain Terms\n\n### Term Name\n\n**Definition**: What it means in this project's context\n\n**Not to be confused with**: Similar terms that mean different things\n\n**Example**: How it's used\n\n## Abbreviations\n\n| Abbrev | Expansion                     | Context                |\n|--------|-------------------------------|------------------------|\n| ADR    | Architectural Decision Record | Decision documentation |\n| SUT    | System Under Test             | Testing                |\n
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#guidelines_4","level":3,"title":"Guidelines","text":"
    • Define project-specific meanings
    • Clarify potentially ambiguous terms
    • Include abbreviations used in code or docs
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#agent_playbookmd","level":2,"title":"AGENT_PLAYBOOK.md","text":"

    Purpose: Explicit instructions for how AI tools should read, apply, and update context.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#key-sections","level":3,"title":"Key Sections","text":"

    Read Order: Priority order for loading context files

    When to Update: Events that trigger context updates

    How to Avoid Hallucinating Memory: Critical rules:

    1. Never assume: If not in files, you don't know it
    2. Never invent history: Don't claim \"we discussed\" without evidence
    3. Verify before referencing: Search files before citing
    4. When uncertain, say so
    5. Trust files over intuition

    Context Update Commands: Format for automated updates via ctx watch:

    <context-update type=\"task\">Implement rate limiting</context-update>\n<context-update type=\"complete\">user auth</context-update>\n<context-update type=\"learning\"\n  context=\"Debugging hooks\"\n  lesson=\"Hooks receive JSON via stdin\"\n  application=\"Parse JSON stdin with the host language\"\n>Hook Input Format</context-update>\n<context-update type=\"decision\"\n  context=\"Need a caching layer\"\n  rationale=\"Redis is fast and team has experience\"\n  consequence=\"Must provision Redis infrastructure\"\n>Use Redis for caching</context-update>\n

    See Integrations for full documentation.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#prompts","level":2,"title":"prompts/","text":"

    Purpose: Store reusable prompt templates - plain markdown files with no frontmatter that provide lightweight, named instructions for common tasks like code review, refactoring, or explaining code.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#how-it-works","level":3,"title":"How It Works","text":"
    • ctx init stamps starter templates: code-review.md, refactor.md, explain.md
    • Manage via ctx prompt list, ctx prompt show, ctx prompt add, ctx prompt rm
    • Invoke in AI sessions with /ctx-prompt <name>
    • Committed to git by default for team sharing

    See the Prompt Templates recipe for the full workflow.

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#parsing-rules","level":2,"title":"Parsing Rules","text":"

    All context files follow these conventions:

    1. Headers define structure: # for title, ## for sections, ### for items
    2. Bold keys for fields: **Key**: followed by value
    3. Code blocks are literal: Never parse code block content as structure
    4. Lists are ordered: Items appear in priority/chronological order
    5. Tags are inline: Backtick-wrapped tags like #priority:high
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#further-reading","level":2,"title":"Further Reading","text":"
    • Refactoring with Intent: how persistent context prevents drift during refactoring sessions
    ","path":["Home","Context Files"],"tags":[]},{"location":"home/context-files/#token-efficiency","level":2,"title":"Token Efficiency","text":"

    Keep context files concise:

    • Use abbreviations in tags, not prose;
    • Omit obvious words (\"The,\" \"This\");
    • Prefer bullet points over paragraphs;
    • Keep examples minimal but illustrative;
    • Archive old completed items periodically.

    Next Up: Prompting Guide →: effective prompts for AI sessions with ctx

    ","path":["Home","Context Files"],"tags":[]},{"location":"home/contributing/","level":1,"title":"Contributing","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#development-setup","level":2,"title":"Development Setup","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#prerequisites","level":3,"title":"Prerequisites","text":"
    • Go (version defined in go.mod)
    • Claude Code
    • Git
    • GNU Make
    • Zensical
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#1-fork-or-clone-the-repository","level":3,"title":"1. Fork (or Clone) the Repository","text":"
    # Fork on GitHub, then:\ngit clone https://github.com/<you>/ctx.git\ncd ctx\n\n# Or, if you have push access:\ngit clone https://github.com/ActiveMemory/ctx.git\ncd ctx\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#2-build-and-install-the-binary","level":3,"title":"2. Build and Install the Binary","text":"
    make build\nsudo make install\n

    This compiles the ctx binary and places it in /usr/local/bin/.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#3-install-the-plugin-from-your-local-clone","level":3,"title":"3. Install the Plugin from Your Local Clone","text":"

    The repository ships a Claude Code plugin under internal/assets/claude/. Point Claude Code at your local copy so that skills and hooks reflect your working tree: no reinstall needed after edits:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace
    4. Enter the absolute path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: it points Claude Code to the actual plugin in internal/assets/claude);
    5. Back in /plugin, select Install and choose ctx.

    Claude Code Caches Plugin Files

    Even though the marketplace points at a directory on disk, Claude Code caches skills and hooks. After editing files under internal/assets/claude/, clear the cache and restart:

    make plugin-reload   # then restart Claude Code\n

    See Skill or Hook Changes for details.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#4-verify","level":3,"title":"4. Verify","text":"
    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed\n

    You should see the ctx plugin listed, sourced from your local path.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#project-layout","level":2,"title":"Project Layout","text":"
    ctx/\n├── cmd/ctx/            # CLI entry point\n├── internal/\n│   ├── assets/claude/  # ← Claude Code plugin (skills, hooks)\n│   ├── bootstrap/      # Project initialization templates\n│   ├── claude/         # Claude Code integration helpers\n│   ├── cli/            # Command implementations\n│   ├── config/         # Configuration loading\n│   ├── context/        # Core context logic\n│   ├── crypto/         # Scratchpad encryption\n│   ├── drift/          # Drift detection\n│   ├── index/          # Context file indexing\n│   ├── journal/        # Journal site generation\n│   ├── memory/         # Memory bridge (discover, mirror, import, publish)\n│   ├── notify/         # Webhook notifications\n│   ├── rc/             # .ctxrc parsing\n│   ├── recall/         # Session history and parsers\n│   ├── sysinfo/        # System resource monitoring\n│   ├── task/           # Task management\n│   └── validation/     # Input validation\n├── .claude/\n│   └── skills/         # Dev-only skills (not distributed)\n├── assets/             # Static assets (banners, logos)\n├── docs/               # Documentation site source\n├── editors/            # Editor extensions (VS Code)\n├── examples/           # Example configurations\n├── hack/               # Build scripts and runbooks\n├── specs/              # Feature specifications\n└── .context/           # ctx's own context (dogfooding)\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#skills-two-directories-one-rule","level":3,"title":"Skills: Two Directories, One Rule","text":"Directory What lives here Distributed to users? internal/assets/claude/skills/ The 39 ctx-* skills that ship with the plugin Yes .claude/skills/ Dev-only skills (release, QA, backup, etc.) No

    internal/assets/claude/skills/ is the single source of truth for user-facing skills. If you are adding or modifying a ctx-* skill, edit it there.

    .claude/skills/ holds skills that only make sense inside this repository (release automation, QA checks, backup scripts). These are never distributed to users.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#dev-only-skills-reference","level":4,"title":"Dev-Only Skills Reference","text":"Skill When to use /_ctx-absorb Merge deltas from a parallel worktree or separate checkout /_ctx-audit Detect code-level drift after YOLO sprints or before releases /_ctx-backup Backup context and Claude data to SMB share /_ctx-qa Run QA checks before committing /_ctx-release Run the full release process /_ctx-release-notes Generate release notes for dist/RELEASE_NOTES.md /_ctx-alignment-audit Audit doc claims against agent instructions /_ctx-update-docs Check docs/code consistency after changes

    Six skills previously in this list have been promoted to bundled plugin skills and are now available to all ctx users: /ctx-brainstorm, /ctx-check-links, /ctx-sanitize-permissions, /ctx-skill-creator, /ctx-spec, /ctx-verify.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#how-to-add-things","level":2,"title":"How To Add Things","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-new-cli-command","level":3,"title":"Adding a New CLI Command","text":"
    1. Create a package under internal/cli/<name>/;
    2. Implement Cmd() *cobra.Command as the entry point;
    3. Register it in internal/bootstrap/bootstrap.go (add import + call in Initialize);
    4. Use cmd.Printf/cmd.Println for output (not fmt.Print);
    5. Add tests in the same package (<name>_test.go);
    6. Add a section to the appropriate CLI doc page in docs/cli/.

    Pattern to follow: internal/cli/pad/pad.go (parent with subcommands) or internal/cli/drift/drift.go (single command).

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-new-session-parser","level":3,"title":"Adding a New Session Parser","text":"

    The recall system uses a SessionParser interface. To add support for a new AI tool (e.g. Aider, Cursor):

    1. Create internal/recall/parser/<tool>.go;
    2. Implement parsing logic that returns []*Session;
    3. Register the parser in FindSessions() / FindSessionsForCWD();
    4. Use config.Tool* constants for the tool identifier;
    5. Add test fixtures and parser tests.

    Pattern to follow: the Claude Code JSONL parser in internal/recall/parser/.

    Multilingual session headers

    The Markdown parser recognizes session header prefixes configured via session_prefixes in .ctxrc (default: Session:). To support a new language, users add a prefix to their .ctxrc - no code change needed. New parser implementations can use rc.SessionPrefixes() if they also need prefix-based header detection.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#adding-a-bundled-skill","level":3,"title":"Adding a Bundled Skill","text":"
    1. Create internal/assets/claude/skills/<skill-name>/SKILL.md;
    2. Follow the skill format: trigger, negative triggers, steps, quality gate;
    3. Run make plugin-reload and restart Claude Code to test;
    4. Add a Skill entry to .claude-plugin/plugin.json if user-invocable;
    5. Document in docs/reference/skills.md.

    Pattern to follow: any skill in internal/assets/claude/skills/ctx-status/.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#test-expectations","level":3,"title":"Test Expectations","text":"
    • Unit tests: colocated with source (foo.go → foo_test.go);
    • Test helpers: use t.Helper() so failures point to callers;
    • HOME isolation: use t.TempDir() + t.Setenv(\"HOME\", ...) for tests that touch ~/.claude/ or ~/.ctx/;
    • rc.Reset(): call after os.Chdir in tests that change working directory (rc caches on first access);
    • No network: all tests run offline, use fixtures.

    Run make test before submitting. Target: no failures, no skips.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#day-to-day-workflow","level":2,"title":"Day-to-Day Workflow","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#go-code-changes","level":3,"title":"Go Code Changes","text":"

    After modifying Go source files, rebuild and reinstall:

    make build && sudo make install\n

    The ctx binary is statically compiled. There is no hot reload. You must rebuild for Go changes to take effect.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#skill-or-hook-changes","level":3,"title":"Skill or Hook Changes","text":"

    Edit files under internal/assets/claude/skills/ or internal/assets/claude/hooks/.

    Claude Code caches plugin files, so edits aren't picked up automatically.

    Clear the cache and restart:

    make plugin-reload   # nukes ~/.claude/plugins/cache/activememory-ctx/\n# then restart Claude Code\n

    The plugin will be re-installed from your local marketplace on startup. No version bump is needed during development.

    Version bumps are for releases, not iteration

    Only bump VERSION, plugin.json, and marketplace.json when cutting a release. During development, make plugin-reload is all you need.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#configuration-profiles","level":3,"title":"Configuration Profiles","text":"

    The repo ships two .ctxrc source profiles. The working copy (.ctxrc) is gitignored and swapped between them:

    File Purpose .ctxrc.base Golden baseline: all defaults, no logging .ctxrc.dev Dev profile: notify events enabled, verbose logging .ctxrc Working copy (gitignored: copied from one of the above)

    Use ctx commands to switch:

    ctx config switch dev      # switch to dev profile\nctx config switch base     # switch to base profile\nctx config status          # show which profile is active\n

    After cloning, run ctx config switch dev to get started with full logging.

    See Configuration for the full .ctxrc option reference.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#backups","level":3,"title":"Backups","text":"

    Back up project context and global Claude Code data with:

    ctx system backup                    # both project + global (default)\nctx system backup --scope project    # .context/, .claude/, ideas/ only\nctx system backup --scope global     # ~/.claude/ only\n

    Archives are saved to /tmp/. When CTX_BACKUP_SMB_URL is configured, they are also copied to an SMB share. See CLI Reference: backup for details.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#running-tests","level":3,"title":"Running Tests","text":"
    make test   # fast: all tests\nmake audit  # full: fmt + vet + lint + drift + docs + test\nmake smoke  # build + run basic commands end-to-end\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#running-the-docs-site-locally","level":3,"title":"Running the Docs Site Locally","text":"
    make site-setup  # one-time: install zensical via pipx\nmake site-serve  # serve at localhost\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#submitting-changes","level":2,"title":"Submitting Changes","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#before-you-start","level":3,"title":"Before You Start","text":"
    1. Check existing issues to avoid duplicating effort;
    2. For large changes, open an issue first to discuss the approach;
    3. Read the specs in specs/ for design context.
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#pull-request-process","level":3,"title":"Pull Request Process","text":"

    Respect the maintainers' time and energy: Keep your pull requests isolated and strive to minimze code changes.

    If you Pull Request solves more than one distinct issues, it's better to create separate pull requests instead of sending them in one large bundle.

    1. Create a feature branch: git checkout -b feature/my-feature;
    2. Make your changes;
    3. Run make audit to catch issues early;
    4. Commit with a clear message;
    5. Push and open a pull request.

    Audit Your Code Before Submitting

    Run make audit before submitting:

    make audit covers formatting, vetting, linting, drift checks, doc consistency, and tests in one pass.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#commit-messages","level":3,"title":"Commit Messages","text":"

    Following conventional commits is recommended but not required:

    Types: feat, fix, docs, test, refactor, chore

    Examples:

    • feat(cli): add ctx export command
    • fix(drift): handle missing files gracefully
    • docs: update installation instructions
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#code-style","level":3,"title":"Code Style","text":"
    • Follow Go conventions (gofmt, go vet);
    • Keep functions focused and small;
    • Add tests for new functionality;
    • Handle errors explicitly.
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#code-of-conduct","level":2,"title":"Code of Conduct","text":"

    A clear context requires respectful collaboration.

    ctx follows the Contributor Covenant.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#boring-legal-stuff","level":2,"title":"Boring Legal Stuff","text":"","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#developer-certificate-of-origin-dco","level":3,"title":"Developer Certificate of Origin (DCO)","text":"

    By contributing, you agree to the Developer Certificate of Origin.

    All commits must be signed off:

    git commit -s -m \"feat: add new feature\"\n
    ","path":["Home","Contributing"],"tags":[]},{"location":"home/contributing/#license","level":3,"title":"License","text":"

    Contributions are licensed under the Apache 2.0 License.

    ","path":["Home","Contributing"],"tags":[]},{"location":"home/faq/","level":1,"title":"FAQ","text":"","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#why-markdown","level":2,"title":"Why Markdown?","text":"

    Markdown is human-readable, version-controllable, and tool-agnostic. Every AI model can parse it natively. Every developer can read it in a terminal, a browser, or a code review. There's no schema to learn, no binary format to decode, no vendor lock-in. You can inspect your context with cat, diff it with git diff, and review it in a PR.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#does-ctx-work-offline","level":2,"title":"Does ctx work offline?","text":"

    Yes. ctx is completely local. It reads and writes files on disk, generates context packets from local state, and requires no network access. The only feature that touches the network is the optional webhook notifications hook, which you have to explicitly configure.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#what-gets-committed-to-git","level":2,"title":"What gets committed to git?","text":"

    The .context/ directory: yes, commit it. That's the whole point. Team members and AI agents read the same context files.

    What not to commit:

    • .ctx.key: your encryption key. Stored at ~/.ctx/.ctx.key, never in the repo. ctx init handles this automatically.
    • journal/ and logs/: generated data, potentially large. ctx init adds these to .gitignore.
    • scratchpad.enc: your choice. It's encrypted, so it's safe to commit if you want shared scratchpad state. See Scratchpad for details.
    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#how-big-should-my-token-budget-be","level":2,"title":"How big should my token budget be?","text":"

    The default is 8000 tokens, which works well for most projects. Configure it via .ctxrc or the CTX_TOKEN_BUDGET environment variable:

    # In .ctxrc\ntoken_budget = 12000\n\n# Or as an environment variable\nexport CTX_TOKEN_BUDGET=12000\n\n# Or per-invocation\nctx agent --budget 4000\n

    Higher budgets include more context but cost more tokens per request. Lower budgets force sharper prioritization: ctx drops lower-priority content first, so CONSTITUTION and TASKS always make the cut.

    See Configuration for all available settings.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#why-not-a-database","level":2,"title":"Why not a database?","text":"

    Files are inspectable, diffable, and reviewable in pull requests. You can grep them, cat them, pipe them through jq or awk. They work with every version control system and every text editor.

    A database would add a dependency, require migrations, and make context opaque. The design bet is that context should be as visible and portable as the code it describes.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#does-it-work-with-tools-other-than-claude-code","level":2,"title":"Does it work with tools other than Claude Code?","text":"

    Yes. ctx agent outputs a context packet that any AI tool can consume: paste it into ChatGPT, Cursor, Copilot, Aider, or anything else that accepts text input.

    Claude Code gets first-class integration via the ctx plugin (hooks, skills, automatic context loading). VS Code Copilot Chat has a dedicated ctx extension. Other tools integrate via generated instruction files or manual pasting.

    See Integrations for tool-specific setup, including the multi-tool recipe.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#can-i-use-ctx-on-an-existing-project","level":2,"title":"Can I use ctx on an existing project?","text":"

    Yes. Run ctx init in any repo and it creates .context/ with template files. Start recording decisions, tasks, and conventions as you work. Context grows naturally; you don't need to backfill everything on day one.

    See Getting Started for the full setup flow, or Joining a ctx Project if someone else already initialized it.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#what-happens-when-context-files-get-too-big","level":2,"title":"What happens when context files get too big?","text":"

    Token budgeting handles this automatically. ctx agent prioritizes content by file priority (CONSTITUTION first, GLOSSARY last) and trims lower-priority entries when the budget is tight.

    For manual maintenance, ctx compact archives completed tasks and old entries, keeping active context lean. You can also run ctx task archive to move completed tasks out of TASKS.md.

    The goal is to keep context files focused on current state. Historical entries belong in git history or the archive.

    ","path":["Home","FAQ"],"tags":[]},{"location":"home/faq/#is-context-meant-to-be-shared","level":2,"title":"Is .context/ meant to be shared?","text":"

    Yes. Commit it to your repo. Every team member and every AI agent reads the same files. That's the mechanism for shared memory: decisions made in one session are visible in the next, regardless of who (or what) starts it.

    The only per-user state is the encryption key (~/.ctx/.ctx.key) and the optional scratchpad. Everything else is team-shared by design.

    Related:

    • Getting Started - installation and first setup
    • Configuration - .ctxrc, environment variables, and defaults
    • Context Files - what each file does and how to use it
    ","path":["Home","FAQ"],"tags":[]},{"location":"home/first-session/","level":1,"title":"Your First Session","text":"

    Here's what a complete first session looks like, from initialization to the moment your AI cites your project context back to you.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-1-initialize-your-project","level":2,"title":"Step 1: Initialize Your Project","text":"

    Run ctx init in your project root:

    cd your-project\nctx init\n

    Sample output:

    Context initialized in .context/\n\n  ✓ CONSTITUTION.md\n  ✓ TASKS.md\n  ✓ DECISIONS.md\n  ✓ LEARNINGS.md\n  ✓ CONVENTIONS.md\n  ✓ ARCHITECTURE.md\n  ✓ GLOSSARY.md\n  ✓ AGENT_PLAYBOOK.md\n\nCreating project root files...\n  ✓ PROMPT.md\n  ✓ IMPLEMENTATION_PLAN.md\n\nSetting up encryption key...\n  ✓ ~/.ctx/.ctx.key\n\nClaude Code plugin (hooks + skills):\n  Install: claude /plugin marketplace add ActiveMemory/ctx\n  Then:    claude /plugin install ctx@activememory-ctx\n\nNext steps:\n  1. Edit .context/TASKS.md to add your current tasks\n  2. Run 'ctx status' to see context summary\n  3. Run 'ctx agent' to get AI-ready context packet\n

    This created your .context/ directory with template files.

    For Claude Code, install the ctx plugin to get automatic hooks and skills.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-2-populate-your-context","level":2,"title":"Step 2: Populate Your Context","text":"

    Add a task and a decision: These are the entries your AI will remember:

    ctx add task \"Implement user authentication\"\n\n# Output: ✓ Added to TASKS.md\n\nctx add decision \"Use PostgreSQL for primary database\" \\\n  --context \"Need a reliable database for production\" \\\n  --rationale \"PostgreSQL offers ACID compliance and JSON support\" \\\n  --consequence \"Team needs PostgreSQL training\"\n\n# Output: ✓ Added to DECISIONS.md\n

    These entries are what the AI will recall in future sessions. You don't need to populate everything now: Context grows naturally as you work.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-3-check-your-context","level":2,"title":"Step 3: Check Your Context","text":"
    ctx status\n

    Sample output:

    Context Status\n====================\n\nContext Directory: .context/\nTotal Files: 8\nToken Estimate: 1,247 tokens\n\nFiles:\n  ✓ CONSTITUTION.md (loaded)\n  ✓ TASKS.md (1 items)\n  ✓ DECISIONS.md (1 items)\n  ○ LEARNINGS.md (empty)\n  ✓ CONVENTIONS.md (loaded)\n  ✓ ARCHITECTURE.md (loaded)\n  ✓ GLOSSARY.md (loaded)\n  ✓ AGENT_PLAYBOOK.md (loaded)\n\nRecent Activity:\n  - TASKS.md modified 2 minutes ago\n  - DECISIONS.md modified 1 minute ago\n

    Notice the token estimate: This is how much context your AI will load.

    The ○ next to LEARNINGS.md means it's still empty; it will fill in as you capture lessons during development.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-4-start-an-ai-session","level":2,"title":"Step 4: Start an AI Session","text":"

    With Claude Code (and the ctx plugin), start every session with:

    /ctx-remember\n

    This loads your context and presents a structured readback so you can confirm the agent knows what is going on. Context also loads automatically via hooks, but the explicit ceremony gives you a readback to verify.

    Using VS Code?

    With VS Code Copilot Chat (and the ctx extension), type @ctx /agent in chat to load your context packet, or @ctx /status to check your project context. Run ctx hook copilot --write once to generate .github/copilot-instructions.md for automatic context loading.

    If you are not using Claude Code, generate a context packet for your AI tool:

    ctx agent --budget 8000\n

    Sample output:

    # Context Packet\nGenerated: 2026-02-14T15:30:45Z | Budget: 8000 tokens | Used: ~2450\n\n## Read These Files (in order)\n1. .context/CONSTITUTION.md\n2. .context/TASKS.md\n3. .context/CONVENTIONS.md\n...\n\n## Current Tasks\n- [ ] Implement user authentication\n- [ ] Add rate limiting to API endpoints\n\n## Key Conventions\n- Use gofmt for formatting\n- Path construction uses filepath.Join\n\n## Recent Decisions\n## [2026-02-14-120000] Use PostgreSQL for the primary database\n\n**Context**: Evaluated PostgreSQL, MySQL, and SQLite...\n**Rationale**: PostgreSQL offers better JSON support...\n\n## Key Learnings\n## [2026-02-14-100000] Connection pool sizing matters\n\n**Context**: Hit connection limits under load...\n**Lesson**: Default pool size of 10 is too low for concurrent requests...\n\n## Also Noted\n- Use JWT for session management\n- Always validate input at API boundary\n

    Paste this output into your AI tool's system prompt or conversation start.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#step-5-verify-it-works","level":2,"title":"Step 5: Verify It Works","text":"

    Ask your AI: \"What are our current tasks?\"

    A working setup produces a response like:

    Based on the project context, you have one active task:\n\n- **Implement user authentication** (pending)\n\nThere's also a recent architectural decision to **use PostgreSQL for\nthe primary database**, chosen for its ACID compliance and JSON support.\n\nWant me to start on the authentication task?\n

    That's the success moment:

    The AI is citing your exact context entries from Step 2, not hallucinating or asking you to re-explain.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#what-gets-created","level":2,"title":"What Gets Created","text":"
    .context/\n├── CONSTITUTION.md     # Hard rules: NEVER violate these\n├── TASKS.md            # Current and planned work\n├── CONVENTIONS.md      # Project patterns and standards\n├── ARCHITECTURE.md     # System overview\n├── DECISIONS.md        # Architectural decisions with rationale\n├── LEARNINGS.md        # Lessons learned, gotchas, tips\n├── GLOSSARY.md         # Domain terms and abbreviations\n└── AGENT_PLAYBOOK.md   # How AI tools should use this\n

    Claude Code integration (hooks + skills) is provided by the ctx plugin: See Integrations/Claude Code.

    VS Code Copilot Chat integration is provided by the ctx extension: See Integrations/VS Code.

    See Context Files for detailed documentation of each file.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/first-session/#what-to-gitignore","level":2,"title":"What to .gitignore","text":"

    Rule of Thumb

    • If it's knowledge (decisions, tasks, learnings, conventions), commit it.
    • If it's generated output, raw session data, or a secret, .gitignore it.

    Commit your .context/ knowledge files: that's the whole point.

    You should .gitignore the generated and sensitive paths:

    # Journal data (large, potentially sensitive)\n.context/journal/\n.context/journal-site/\n.context/journal-obsidian/\n\n# Hook logs (machine-specific)\n.context/logs/\n\n# Legacy encryption key path (copy to ~/.ctx/.ctx.key if needed)\n.context/.ctx.key\n\n# Claude Code local settings (machine-specific)\n.claude/settings.local.json\n

    ctx init Patches Your .gitignore for You

    ctx init automatically adds these entries to your .gitignore.

    Review the additions with cat .gitignore after init.

    See also:

    • Security Considerations
    • Scratchpad Encryption
    • Session Journal

    Next Up: Common Workflows →: day-to-day commands for tracking context, checking health, and browsing history.

    ","path":["Home","Your First Session"],"tags":[]},{"location":"home/getting-started/","level":1,"title":"Getting Started","text":"","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#prerequisites","level":2,"title":"Prerequisites","text":"

    ctx does not require git, but using version control with your .context/ directory is strongly recommended:

    AI sessions occasionally modify or overwrite context files inadvertently. With git, the AI can check history and restore lost content: Without it, the data is gone.

    Also, several ctx features (journal changelog, blog generation) also use git history directly.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#installation","level":2,"title":"Installation","text":"

    Every setup starts with the ctx binary: the CLI tool itself.

    If you use Claude Code, you also install the ctx plugin, which adds hooks (context autoloading, persistence nudges) and 25+ /ctx-* skills. For other AI tools, ctx integrates via generated instruction files or manual context pasting: see Integrations for tool-specific setup.

    Pick one of the options below to install the binary. Claude Code users should also follow the plugin steps included in each option.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#option-1-build-from-source-recommended","level":3,"title":"Option 1: Build from Source (Recommended)","text":"

    Requires Go (version defined in go.mod) and Claude Code.

    git clone https://github.com/ActiveMemory/ctx.git\ncd ctx\nmake build\nsudo make install\n

    Install the Claude Code plugin from your local clone:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace
    4. Enter the path to the root of your clone, e.g. ~/WORKSPACE/ctx (this is where .claude-plugin/marketplace.json lives: It points Claude Code to the actual plugin in internal/assets/claude)
    5. Back in /plugin, select Install and choose ctx

    This points Claude Code at the plugin source on disk. Changes you make to hooks or skills take effect immediately: No reinstall is needed.

    Local Installs Need Manual Enablement

    Unlike marketplace installs, local plugin installs are not auto-enabled globally. The plugin will only work in projects that explicitly enable it. Run ctx init in each project (it auto-enables the plugin), or add the entry to ~/.claude/settings.json manually:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Verify:

    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed\n

    Use the Source, Luke

    Building from source gives you the latest features and bug fixes.

    Since ctx is predominantly a developer tool, this is the recommended approach:

    You get the freshest code, can inspect what you are installing, and the plugin stays in sync with the binary.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#option-2-binary-download-marketplace","level":3,"title":"Option 2: Binary Download + Marketplace","text":"

    Pre-built binaries are available from the releases page.

    Linux (x86_64)Linux (ARM64)macOS (Apple Silicon)macOS (Intel)Windows 
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64\nchmod +x ctx-0.6.0-linux-amd64\nsudo mv ctx-0.6.0-linux-amd64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-arm64\nchmod +x ctx-0.6.0-linux-arm64\nsudo mv ctx-0.6.0-linux-arm64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-arm64\nchmod +x ctx-0.6.0-darwin-arm64\nsudo mv ctx-0.6.0-darwin-arm64 /usr/local/bin/ctx\n
    curl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-darwin-amd64\nchmod +x ctx-0.6.0-darwin-amd64\nsudo mv ctx-0.6.0-darwin-amd64 /usr/local/bin/ctx\n

    Download ctx-0.6.0-windows-amd64.exe from the releases page and add it to your PATH.

    Claude Code users: install the plugin from the marketplace:

    1. Launch claude;
    2. Type /plugin and press Enter;
    3. Select Marketplaces → Add Marketplace;
    4. Enter ActiveMemory/ctx;
    5. Back in /plugin, select Install and choose ctx.

    Other tool users: see Integrations for tool-specific setup (Cursor, Copilot, Aider, Windsurf, etc.).

    Verify the Plugin Is Enabled

    After installing, confirm the plugin is enabled globally. Check ~/.claude/settings.json for an enabledPlugins entry. If missing, run ctx init in your project (it auto-enables the plugin), or add it manually:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Verify:

    ctx --version       # binary is in PATH\nclaude /plugin list # plugin is installed (Claude Code only)\n
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#verifying-checksums","level":4,"title":"Verifying Checksums","text":"

    Each binary has a corresponding .sha256 checksum file. To verify your download:

    # Download the checksum file\ncurl -LO https://github.com/ActiveMemory/ctx/releases/download/v0.6.0/ctx-0.6.0-linux-amd64.sha256\n\n# Verify the binary\nsha256sum -c ctx-0.6.0-linux-amd64.sha256\n

    On macOS, use shasum -a 256 -c instead of sha256sum -c.

    Plugin Details

    After installation (either option) you get:

    • Context autoloading: ctx agent runs on every tool use (with cooldown)
    • Persistence nudges: reminders to capture learnings and decisions
    • Post-commit hooks: nudge context capture after git commit
    • Context size monitoring: alerts as sessions grow large
    • 25+ skills: /ctx-status, /ctx-add-task, /ctx-recall, and more

    See Integrations for the full hook and skill reference.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#quick-start","level":2,"title":"Quick Start","text":"","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#1-initialize-context","level":3,"title":"1. Initialize Context","text":"
    cd your-project\nctx init\n

    This creates a .context/ directory with template files and an encryption key at ~/.ctx/ for the encrypted scratchpad. For Claude Code, install the ctx plugin for automatic hooks and skills.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#2-check-status","level":3,"title":"2. Check Status","text":"
    ctx status\n

    Shows context summary: files present, token estimate, and recent activity.

    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#3-start-using-with-ai","level":3,"title":"3. Start Using with AI","text":"

    With Claude Code (and the ctx plugin installed), context loads automatically via hooks.

    With VS Code Copilot Chat, install the ctx extension and use @ctx /status, @ctx /agent, and other slash commands directly in chat. Run ctx hook copilot --write to generate .github/copilot-instructions.md for automatic context loading.

    For other tools, paste the output of:

    ctx agent --budget 8000\n
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/getting-started/#4-verify-it-works","level":3,"title":"4. Verify It Works","text":"

    Ask your AI: \"Do you remember?\"

    It should cite specific context: current tasks, recent decisions, or previous session topics.

    Next Up:

    • Your First Session →: a step-by-step walkthrough from ctx init to verified recall
    • Common Workflows →: day-to-day commands for tracking context, checking health, and browsing history
    ","path":["Home","Getting Started"],"tags":[]},{"location":"home/is-ctx-right/","level":1,"title":"Is It Right for Me?","text":"","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#good-fit","level":2,"title":"Good Fit","text":"

    ctx shines when context matters more than code.

    If any of these sound like your project, it's worth trying:

    • Multi-session AI work: You use AI across many sessions on the same codebase, and re-explaining is slowing you down.
    • Architectural decisions that matter: Your project has non-obvious choices (database, auth strategy, API design) that the AI keeps second-guessing.
    • \"Why\" matters as much as \"what\": you need the AI to understand rationale, not just current code
    • Team handoffs: Multiple people (or multiple AI tools) work on the same project and need shared context.
    • AI-assisted development across tools: Uou switch between Claude Code, Cursor, Copilot, or other tools and want context to follow the project, not the tool.
    • Long-lived projects: Anything you'll work on for weeks or months, where accumulated knowledge has compounding value.
    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#may-not-be-the-right-fit","level":2,"title":"May Not Be the Right Fit","text":"

    ctx adds overhead that isn't worth it for every project. Be honest about when to skip it:

    • One-off scripts: If the project is a single file you'll finish today, there's nothing to remember.
    • RAG-only workflows: If retrieval from an external knowledge base already gives the agent everything it needs for each session, adding ctx may be unnecessary. RAG retrieves information; ctx defines the project's working memory: They are complementary.
    • No AI involvement: ctx is designed for human-AI workflows; without an AI consumer, the files are just documentation.
    • Enterprise-managed context platforms: If your organization provides centralized context services, ctx may duplicate that layer.

    For a deeper technical comparison with RAG, prompt management tools, and agent frameworks, see ctx and Similar Tools.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#project-size-guide","level":2,"title":"Project Size Guide","text":"","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#solo-developer-single-repo","level":3,"title":"Solo Developer, Single Repo","text":"

    This is ctx's sweet spot.

    You get the most value here: one person, one project, decisions, and learnings accumulating over time. Setup takes 5 minutes and the .context/ directory directory stays small, and every session gets faster.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#small-team-one-or-two-repos","level":3,"title":"Small Team, One or Two Repos","text":"

    Works well.

    Context files commit to git, so the whole team shares the same decisions and conventions. Each person's AI starts with the team's decisions already loaded. Merge conflicts on .context/ files are rare and easy to resolve (they are just Markdown).

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#multiple-repos-or-larger-teams","level":3,"title":"Multiple Repos or Larger Teams","text":"

    ctx operates per repository.

    Each repo has its own .context/ directory with its own decisions, tasks, and learnings. This matches the way code, ownership, and history already work in git.

    There is no built-in cross-repo context layer.

    For organizations that need centralized, organization-wide knowledge, ctx complements a platform solution by providing durable, project-local working memory for AI sessions.

    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/is-ctx-right/#5-minute-trial","level":2,"title":"5-Minute Trial","text":"

    Zero commitment. Try it, and delete .context/ if it's not for you.

    Using Claude Code?

    Install the ctx plugin from the Marketplace for Claude-native hooks, skills, and automatic context loading:

    1. Type /plugin and press Enter
    2. Select Marketplaces → Add Marketplace
    3. Enter ActiveMemory/ctx
    4. Back in /plugin, select Install and choose ctx

    You'll still need the ctx binary for the CLI: See Getting Started for install options.

    # 1. Initialize\ncd your-project\nctx init\n\n# 2. Add one real decision from your project\nctx add decision \"Your actual architectural choice\" \\\n  --context \"What prompted this decision\" \\\n  --rationale \"Why you chose this approach\" \\\n  --consequence \"What changes as a result\"\n\n# 3. Check what the AI will see\nctx status\n\n# 4. Start an AI session and ask: \"Do you remember?\"\n

    If the AI cites your decision back to you, it's working.

    Want to remove it later? One command:

    rm -rf .context/\n

    No dependencies to uninstall. No configuration to revert. Just files.

    Ready to try it out?

    • Join the Community→: Open Source is better together.
    • Getting Started →: Full installation and setup.
    • ctx and Similar Tools →: Detailed comparison with other approaches.
    ","path":["Home","Is It Right for Me?"],"tags":[]},{"location":"home/joining-a-project/","level":1,"title":"Joining a ctx Project","text":"

    You've joined a team or inherited a project, and there's a .context/ directory in the repo. Good news: someone already set up persistent context. This page gets you oriented fast.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#what-to-read-first","level":2,"title":"What to Read First","text":"

    The files in .context/ have a deliberate priority order. Read them top-down:

    1. CONSTITUTION.md: Hard rules. Read this before you touch anything. These are inviolable constraints the team has agreed on.
    2. TASKS.md: Current and planned work. Shows what's in progress, what's pending, and what's blocked.
    3. CONVENTIONS.md: How the team writes code. Naming patterns, file organization, preferred idioms.
    4. ARCHITECTURE.md: System overview. Components, boundaries, data flow.
    5. DECISIONS.md: Why things are the way they are. Saves you from re-proposing something the team already evaluated and rejected.
    6. LEARNINGS.md: Gotchas, tips, and hard-won lessons. The stuff that doesn't fit anywhere else but will save you hours.

    See Context Files for detailed documentation of each file's structure and purpose.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#checking-context-health","level":2,"title":"Checking Context Health","text":"

    Before you start working, check whether the context is current:

    ctx status\n

    This shows file counts, token estimates, and recent activity. If files haven't been touched in weeks, the context may be stale.

    ctx drift\n

    This compares context files against recent code changes and flags potential drift: decisions that no longer match the codebase, conventions that have shifted, or tasks that look outdated.

    If things are stale, mention it to the team. Don't silently fix it yourself on day one.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#starting-your-first-session","level":2,"title":"Starting Your First Session","text":"

    Generate a context packet to prime your AI:

    ctx agent --budget 8000\n

    This outputs a token-budgeted summary of the project context, ordered by priority. With Claude Code and the ctx plugin, context loads automatically via hooks. You can also use the /ctx-remember skill to get a structured readback of what the AI knows.

    The readback is your verification step: if the AI can cite specific tasks and decisions, the context is working.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#adding-context","level":2,"title":"Adding Context","text":"

    As you work, you'll discover things worth recording. Use the CLI:

    # Record a decision you made or learned about\nctx add decision \"Use connection pooling for DB access\" \\\n  --rationale \"Reduces connection overhead under load\"\n\n# Capture a gotcha you hit\nctx add learning \"Redis timeout defaults to 5s\" \\\n  --context \"Hit timeouts during bulk operations\" \\\n  --application \"Set explicit timeout for batch jobs\"\n\n# Add a convention you noticed the team follows\nctx add convention \"All API handlers return structured errors\"\n

    You can also just tell the AI: \"Record this as a learning\" or \"Add this decision to context.\" With the ctx plugin, context-update commands handle the file writes.

    See the Knowledge Capture recipe for the full workflow.

    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#session-etiquette","level":2,"title":"Session Etiquette","text":"

    A few norms for working in a ctx-managed project:

    • Respect existing conventions. If CONVENTIONS.md says \"use filepath.Join,\" use filepath.Join. If you disagree, propose a change, don't silently diverge.
    • Don't restructure context files without asking. The file layout and section structure are shared state. Reorganizing them affects every team member and every AI session.
    • Mark tasks done when complete. Check the box ([x]) in place. Don't move tasks between sections or delete them.
    • Add context as you go. Decisions, learnings, and conventions you discover are valuable to the next person (or the next session).
    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/joining-a-project/#common-pitfalls","level":2,"title":"Common Pitfalls","text":"

    Ignoring CONSTITUTION.md. The constitution exists for a reason. If a task conflicts with a constitution rule, the task is wrong. Raise it with the team instead of working around the constraint.

    Deleting tasks. Never delete a task from TASKS.md. Mark it [x] (done) or [-] (skipped with a reason). The history matters for session replay and audit.

    Bypassing hooks. If the project uses ctx hooks (pre-commit nudges, context autoloading), don't disable them. They exist to keep context fresh. If a hook is noisy or broken, fix it or file a task.

    Over-contributing on day one. Read first, then contribute. Adding a dozen learnings before you understand the project's norms creates noise, not signal.

    Related:

    • Getting Started: installation and setup from scratch
    • Context Files: detailed file reference
    • Knowledge Capture: recording decisions, learnings, and conventions
    • Session Lifecycle: how a typical AI session flows with ctx
    ","path":["Home","Joining a ctx Project"],"tags":[]},{"location":"home/keeping-ai-honest/","level":1,"title":"Keeping AI Honest","text":"","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-problem","level":2,"title":"The Problem","text":"

    AI agents confabulate. They invent history that never happened, claim familiarity with decisions that were never made, and sometimes declare a task complete when it is not. This is not malice - it is the default behavior of a system optimizing for plausible-sounding responses.

    When your AI says \"we decided to use Redis for caching last week,\" can you verify that? When it says \"the auth module is complete,\" can you confirm it? Without grounded, persistent context, the answer is no. You are trusting vibes.

    ctx replaces vibes with verifiable artifacts.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#grounded-memory","level":2,"title":"Grounded Memory","text":"

    Every entry in ctx context files has a timestamp and structured fields. When the AI cites a decision, you can check it.

    ## [2026-01-28-143022] Use Event Sourcing for Audit Trail\n\n**Status**: Accepted\n\n**Context**: Compliance requires full mutation history.\n\n**Decision**: Event sourcing for the audit subsystem only.\n\n**Rationale**: Append-only log meets compliance requirements\nwithout imposing event sourcing on the entire domain model.\n

    The timestamp 2026-01-28-143022 is not decoration. It is a verifiable anchor. If the AI references this decision, you can open DECISIONS.md, find the entry, and confirm it says what the AI claims. If the entry does not exist, the AI is hallucinating - and you know immediately.

    This is grounded memory: claims that trace back to artifacts you control and can audit.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#constitutionmd-hard-guardrails","level":2,"title":"CONSTITUTION.md: Hard Guardrails","text":"

    CONSTITUTION.md defines rules the AI must treat as inviolable. These are not suggestions or best practices - they are constraints that override task requirements.

    # Constitution\n\nThese rules are INVIOLABLE. If a task requires violating these,\nthe task is wrong.\n\n* [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] All public API changes require a decision record\n* [ ] Never delete context files without explicit user approval\n

    The AI reads these at session start, before anything else. A well- integrated agent will refuse a task that conflicts with a constitutional rule, citing the specific rule it would violate.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-agent-playbooks-anti-hallucination-rules","level":2,"title":"The Agent Playbook's Anti-Hallucination Rules","text":"

    The AGENT_PLAYBOOK.md file includes a section called \"How to Avoid Hallucinating Memory\" with five explicit rules:

    1. Never assume. If it is not in the context files, you do not know it.
    2. Never invent history. Do not claim \"we discussed\" something without a file reference.
    3. Verify before referencing. Search files before citing them.
    4. When uncertain, say so. \"I don't see a decision on this\" is always better than a fabricated one.
    5. Trust files over intuition. If the files say PostgreSQL but your training data suggests MySQL, the files win.

    These rules create a behavioral contract. The AI is not left to guess how confident it should be - it has explicit instructions to ground every claim in the context directory.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#drift-detection","level":2,"title":"Drift Detection","text":"

    Context files can go stale. You rename a package, delete a module, or finish a sprint, and suddenly ARCHITECTURE.md references paths that no longer exist. Stale context is almost as dangerous as no context: the AI treats outdated information as current truth.

    ctx drift detects this divergence:

    ctx drift\n

    It scans context files for references to files, paths, and symbols that no longer exist in the codebase. Stale references get flagged so you can update or remove them before they mislead the next session.

    Regular drift checks - weekly, or after major refactors - keep your context files honest the same way tests keep your code honest.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#the-verification-loop","level":2,"title":"The Verification Loop","text":"

    The /ctx-verify skill provides an end-to-end check: it reads all context files, cross-references them with the current codebase, and reports inconsistencies. Think of it as a health check for your project's memory.

    This closes the loop. You write context. The AI reads context. The verification step confirms that context still matches reality. When it does not, you fix it - and the next session starts from truth, not from drift.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#trust-through-structure","level":2,"title":"Trust Through Structure","text":"

    The common thread across all of these mechanisms is structure over prose. Timestamps make claims verifiable. Constitutional rules make boundaries explicit. Drift detection makes staleness visible. The playbook makes behavioral expectations concrete.

    You do not need to trust the AI. You need to trust the system -- and verify when it matters.

    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/keeping-ai-honest/#further-reading","level":2,"title":"Further Reading","text":"
    • Detecting and Fixing Drift: the full workflow for keeping context files accurate
    • Invariants: the properties that must hold for any valid ctx implementation
    • Agent Security: threat model and mitigations for AI agents operating with persistent context
    ","path":["Home","Keeping AI Honest"],"tags":[]},{"location":"home/prompting-guide/","level":1,"title":"Prompting Guide","text":"

    New to ctx?

    This guide references context files like TASKS.md, DECISIONS.md, and LEARNINGS.md:

    These are plain Markdown files that ctx maintains in your project's .context/ directory.

    If terms like \"context packet\" or \"session ceremony\" are unfamiliar,

    • start with the ctx Manifesto for the why,
    • About for the big picture,
    • then Getting Started to set up your first project.
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#literature-matters","level":2,"title":"Literature Matters","text":"

    This guide is about crafting effective prompts for working with AI assistants in ctx-enabled projects, but the guidelines given here apply to other AI systems, too.

    The right prompt triggers the right behavior.

    This guide documents prompts that reliably produce good results.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#tldr","level":2,"title":"TL;DR","text":"Goal Prompt Load context \"Do you remember?\" Resume work \"What's the current state?\" What's next /ctx-next Debug \"Why doesn't X work?\" Validate \"Is this consistent with our decisions?\" Impact analysis \"What would break if we...\" Reflect /ctx-reflect Wrap up /ctx-wrap-up Persist \"Add this as a learning\" Explore \"How does X work in this codebase?\" Sanity check \"Is this the right approach?\" Completeness \"What am I missing?\" One more thing \"What's the single smartest addition?\" Set tone \"Push back if my assumptions are wrong.\" Constrain scope \"Only change files in X. Nothing else.\" Course correct \"Stop. That's not what I meant.\" Check health \"Run ctx drift\" Commit /ctx-commit","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#session-start","level":2,"title":"Session Start","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#do-you-remember","level":3,"title":"\"Do you remember?\"","text":"

    Triggers the AI to silently read TASKS.md, DECISIONS.md, LEARNINGS.md, and check recent history via ctx recall before responding with a structured readback:

    1. Last session: most recent session topic and date
    2. Active work: pending or in-progress tasks
    3. Recent context: 1-2 recent decisions or learnings
    4. Next step: offer to continue or ask what to focus on

    Use this at the start of every important session.

    Do you remember what we were working on?\n

    This question implies prior context exists. The AI checks files rather than admitting ignorance. The expected response cites specific context (session names, task counts, decisions), not vague summaries.

    If the AI instead narrates its discovery process (\"Let me check if there are files...\"), it has not loaded CLAUDE.md or AGENT_PLAYBOOK.md properly.

    For a detailed case study on making agents actually follow this protocol (including the failure modes, the timing problem, and the hook design that solved it) see The Dog Ate My Homework.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#whats-the-current-state","level":3,"title":"\"What's the current state?\"","text":"

    Prompts reading of TASKS.md, recent sessions, and status overview.

    Use this when resuming work after a break.

    Variants:

    • \"Where did we leave off?\"
    • \"What's in progress?\"
    • \"Show me the open tasks.\"
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#during-work","level":2,"title":"During Work","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#why-doesnt-x-work","level":3,"title":"\"Why doesn't X work?\"","text":"

    This triggers root cause analysis rather than surface-level fixes.

    Use this when something fails unexpectedly.

    Framing as \"why\" encourages investigation before action. The AI will trace through code, check configurations, and identify the actual cause.

    Real Example

    \"Why can't I run /ctx-reflect?\" led to discovering missing permissions in settings.local.json bootstrapping.

    This was a fix that benefited all users of ctx.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#is-this-consistent-with-our-decisions","level":3,"title":"\"Is this consistent with our decisions?\"","text":"

    This prompts checking DECISIONS.md before implementing.

    Use this before making architectural choices.

    Variants:

    • \"Check if we've decided on this before\"
    • \"Does this align with our conventions?\"
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-would-break-if-we","level":3,"title":"\"What would break if we...\"","text":"

    This triggers defensive thinking and impact analysis.

    Use this before making significant changes.

    What would break if we change the Settings struct?\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#before-you-start-read-x","level":3,"title":"\"Before you start, read X\"","text":"

    This ensures specific context is loaded before work begins.

    Use this when you know the relevant context exists in a specific file.

    Before you start, check ctx recall for the auth discussion session\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#scope-control","level":3,"title":"Scope Control","text":"

    Constrain the AI to prevent sprawl. These are some of the most useful prompts in day-to-day work.

    Only change files in internal/cli/add/. Nothing else.\n
    No new files. Modify the existing implementation.\n
    Keep the public API unchanged. Internal refactor only.\n

    Use these when the AI tends to \"helpfully\" modify adjacent code, add documentation you didn't ask for, or create new abstractions.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#course-correction","level":3,"title":"Course Correction","text":"

    Steer the AI when it goes off-track: Don't wait for it to finish a wrong approach.

    Stop! That's not what I meant. Let me clarify.\n
    Let's step back. Explain what you're about to do before changing anything.\n
    Undo that last change and try a different approach.\n

    These work because they interrupt momentum.

    Without explicit course correction, the AI tends to commit harder to a wrong path rather than reconsidering.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#failure-modes","level":3,"title":"Failure Modes","text":"

    When the AI misbehaves, match the symptom to the recovery prompt:

    Symptom Recovery prompt Hand-waves (\"should work now\") \"Show evidence: file/line refs, command output, or test name.\" Creates unnecessary files \"No new files. Modify the existing implementation.\" Expands scope unprompted \"Stop after the smallest working change. Ask before expanding scope.\" Narrates instead of acting \"Skip the explanation. Make the change and show the diff.\" Repeats a failed approach \"That didn't work last time. Try a different approach.\" Claims completion without proof \"Run the test. Show me the output.\"

    These are recovery handles, not rules to paste into CLAUDE.md.

    Use them in the moment when you see the behavior.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#reflection-and-persistence","level":2,"title":"Reflection and Persistence","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-did-we-learn","level":3,"title":"\"What did we learn?\"","text":"

    This prompts reflection on the session and often triggers adding learnings to LEARNINGS.md.

    Use this after completing a task or debugging session.

    This is an explicit reflection prompt. The AI will summarize insights and often offer to persist them.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#add-this-as-a-learningdecision","level":3,"title":"\"Add this as a learning/decision\"","text":"

    This is an explicit persistence request.

    Use this when you have discovered something worth remembering.

    Add this as a learning: \"JSON marshal escapes angle brackets by default\"\n\n# or simply.\nAdd this as a learning.\n# and let the AI autonomously infer and summarize.\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#save-context-before-we-end","level":3,"title":"\"Save context before we end\"","text":"

    This triggers context persistence before the session closes.

    Use it at the end of the session or before switching topics.

    Variants:

    • \"Let's persist what we did\"
    • \"Update the context files\"
    • /ctx-wrap-up:the recommended end-of-session ceremony (see Session Ceremonies)
    • /ctx-reflect: mid-session reflection checkpoint
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#exploration-and-research","level":2,"title":"Exploration and Research","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#explore-the-codebase-for-x","level":3,"title":"\"Explore the codebase for X\"","text":"

    This triggers thorough codebase search rather than guessing.

    Use this when you need to understand how something works.

    This works because \"Explore\" signals that investigation is needed, not immediate action.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#how-does-x-work-in-this-codebase","level":3,"title":"\"How does X work in this codebase?\"","text":"

    This prompts reading actual code rather than explaining general concepts.

    Use this to understand the existing implementation.

    How does session saving work in this codebase?\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#find-all-places-where-x","level":3,"title":"\"Find all places where X\"","text":"

    This triggers a comprehensive search across the codebase.

    Use this before refactoring or understanding the impact.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#meta-and-process","level":2,"title":"Meta and Process","text":"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-should-we-document-from-this","level":3,"title":"\"What should we document from this?\"","text":"

    This prompts identifying learnings, decisions, and conventions worth persisting.

    Use this after complex discussions or implementations.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#is-this-the-right-approach","level":3,"title":"\"Is this the right approach?\"","text":"

    This invites the AI to challenge the current direction.

    Use this when you want a sanity check.

    This works because it allows AI to disagree.

    AIs often default to agreeing; this prompt signals you want an honest assessment.

    Stronger variant: \"Push back if my assumptions are wrong.\" This sets the tone for the entire session: The AI will flag questionable choices proactively instead of waiting to be asked.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#what-am-i-missing","level":3,"title":"\"What am I missing?\"","text":"

    This prompts thinking about edge cases, overlooked requirements, or unconsidered approaches.

    Use this before finalizing a design or implementation.

    Forward-looking variant: \"What's the single smartest addition you could make to this at this point?\" Use this after you think you're done: It surfaces improvements you wouldn't have thought to ask for. The constraint to one thing prevents feature sprawl.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#cli-commands-as-prompts","level":2,"title":"CLI Commands as Prompts","text":"

    Asking the AI to run ctx commands is itself a prompt. These load context or trigger specific behaviors:

    Command What it does \"Run ctx status\" Shows context summary, file presence, staleness \"Run ctx agent\" Loads token-budgeted context packet \"Run ctx drift\" Detects dead paths, stale files, missing context","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#ctx-skills","level":3,"title":"ctx Skills","text":"

    The SKILS.md Standard

    Skills are formalized prompts stored as SKILL.md files.

    The /slash-command syntax below is Claude Code specific.

    Other agents can use the same skill files, but invocation may differ.

    Use ctx skills by name:

    Skill When to use /ctx-status Quick context summary /ctx-agent Load full context packet /ctx-remember Recall project context and structured readback /ctx-wrap-up End-of-session context persistence /ctx-recall Browse session history for past discussions /ctx-reflect Structured reflection checkpoint /ctx-next Suggest what to work on next /ctx-commit Commit with context persistence /ctx-drift Detect and fix context drift /ctx-implement Execute a plan step-by-step with verification /ctx-loop Generate autonomous loop script /ctx-pad Manage encrypted scratchpad /ctx-archive Archive completed tasks /check-links Audit docs for dead links

    Ceremony vs. Workflow Skills

    Most skills work conversationally: \"what should we work on?\" triggers /ctx-next, \"save that as a learning\" triggers /ctx-add-learning. Natural language is the recommended approach.

    Two skills are the exception: /ctx-remember and /ctx-wrap-up are ceremony skills for session boundaries: Invoke them as explicit slash commands: conversational triggers risk partial execution. See Session Ceremonies.

    Skills combine a prompt, tool permissions, and domain knowledge into a single invocation.

    Skills Beyond Claude Code

    The /slash-command syntax above is Claude Code native, but the underlying SKILL.md files are a standard markdown format that any agent can consume. If you use a different coding agent, consult its documentation for how to load skill files as prompt templates.

    See Integrations for setup details.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#anti-patterns","level":2,"title":"Anti-Patterns","text":"

    Based on our ctx development experience (i.e., \"sipping our own champagne\") so far, here are some prompts that tend to produce poor results:

    Prompt Problem Better Alternative \"Fix this\" Too vague, may patch symptoms \"Why is this failing?\" \"Make it work\" Encourages quick hacks \"What's the right way to solve this?\" \"Just do it\" Skips planning \"Plan this, then implement\" \"You should remember\" Confrontational \"Do you remember?\" \"Obviously...\" Discourages questions State the requirement directly \"Idiomatic X\" Triggers language priors \"Follow project conventions\" \"Implement everything\" No phasing, sprawl risk Break into tasks, implement one at a time \"You should know this\" Assumes context is loaded \"Before you start, read X\"","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#reliability-checklist","level":2,"title":"Reliability Checklist","text":"

    Before sending a non-trivial prompt, check these four elements. This is the guide's DNA in one screenful.

    1. Goal in one sentence: What does \"done\" look like?
    2. Files to read: What existing code or context should the AI review before acting?
    3. Verification command: How will you prove it worked? (test name, CLI command, expected output)
    4. Scope boundary: What should the AI not touch?

    A prompt that covers all four is almost always good enough.

    A prompt missing #3 is how you get \"should work now\" without evidence.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#safety-invariants","level":2,"title":"Safety Invariants","text":"

    These are Invariants: Not Suggestions

    A prompting guide earns its trust by being honest about risk.

    These four rules mentioned below don't change with model versions, agent frameworks, or project size.

    Build them into your workflow once and stop thinking about them.

    Tool-using agents can read files, run commands, and modify your codebase. That power makes them useful. It also creates a trust boundary you should be aware of.

    These invariants apply regardless of which agent or model you use.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#treat-the-repository-text-as-untrusted-input","level":3,"title":"Treat the Repository Text as \"Untrusted Input\"","text":"

    Issue descriptions, PR comments, commit messages, documentation, and even code comments can contain text that looks like instructions. An agent that reads a GitHub issue and then runs a command found inside it is executing untrusted input.

    The rule: Before running any command the agent found in repo text (issues, docs, comments), restate the command explicitly and confirm it does what you expect. Don't let the agent copy-paste from untrusted sources into a shell.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#ask-before-destructive-operations","level":3,"title":"Ask Before Destructive Operations","text":"

    git push --force, rm -rf, DROP TABLE, docker system prune: these are irreversible or hard to reverse. A good agent should pause before running them, but don't rely on that.

    The rule: For any operation that deletes data, overwrites history, or affects shared infrastructure, require explicit confirmation. If the agent runs something destructive without asking, that's a course-correction moment: \"Stop. Never run destructive commands without asking first.\"

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#scope-the-blast-radius","level":3,"title":"Scope the Blast Radius","text":"

    An agent told to \"fix the tests\" might modify test fixtures, change assertions, or delete tests that inconveniently fail. An agent told to \"deploy\" might push to production. Broad mandates create broad risk.

    The rule: Constrain scope before starting work. The Reliability Checklist's scope boundary (#4) is your primary safety lever. When in doubt, err on the side of a tighter boundary.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#secrets-never-belong-in-context","level":3,"title":"Secrets Never Belong in Context","text":"

    LEARNINGS.md, DECISIONS.md, and session transcripts are plain-text files that may be committed to version control.

    Don't persist API keys, passwords, tokens, or credentials in context files.

    The rule: If the agent encounters a secret during work, it should use it transiently (environment variable, an alias to the secret instead of the actual secret, etc.) and never write it to a context file.

    Any Secret Seen IS Exposed

    If you see a secret in a context file, remove it immediately and rotate the credential.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#explore-plan-implement","level":2,"title":"Explore → Plan → Implement","text":"

    For non-trivial work, name the phase you want:

    Explore src/auth and summarize the current flow.\nThen propose a plan. After I approve, implement with tests.\n

    This prevents the AI from jumping straight to code.

    The three phases map to different modes of thinking:

    • Explore: read, search, understand: no changes
    • Plan: propose approach, trade-offs, scope: no changes
    • Implement: write code, run tests, verify: changes

    Small fixes skip straight to implement. Complex or uncertain work benefits from all three.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#prompts-by-task-type","level":2,"title":"Prompts by Task Type","text":"

    Different tasks need different prompt structures. The pattern: symptom + location + verification.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#bugfix","level":3,"title":"Bugfix","text":"
    Users report search returns empty results for queries with hyphens.\nReproduce in src/search/. Write a failing test for \"foo-bar\",\nfix the root cause, run: go test ./internal/search/...\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#refactor","level":3,"title":"Refactor","text":"
    Inspect src/auth/ and list duplication hotspots.\nPropose a refactor plan scoped to one module.\nAfter approval, remove duplication without changing behavior.\nAdd a test if coverage is missing. Run: make audit\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#research","level":3,"title":"Research","text":"
    Explore the request flow around src/api/.\nSummarize likely bottlenecks with evidence.\nPropose 2-3 hypotheses. Do not implement yet.\n
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#docs","level":3,"title":"Docs","text":"
    Update docs/cli-reference.md to reflect the new --format flag.\nConfirm the flag exists in the code and the example works.\n

    Notice each prompt includes what to verify and how. Without that, you get a \"should work now\" instead of evidence.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#writing-tasks-as-prompts","level":2,"title":"Writing Tasks as Prompts","text":"

    Tasks in TASKS.md are indirect prompts to the AI. How you write them shapes how the AI approaches the work.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#state-the-motivation-not-just-the-goal","level":3,"title":"State the Motivation, Not Just the Goal","text":"

    Tell the AI why you are building something, not just what.

    Bad: \"Build a calendar view.\"

    Good: \"Build a calendar view. The motivation is that all notes and tasks we build later should be viewable here.\"

    The second version lets the AI anticipate downstream requirements:

    It will design the calendar's data model to be compatible with future features: Without you having to spell out every integration point. Motivation turns a one-off task into a directional task.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#state-the-deliverable-not-just-steps","level":3,"title":"State the Deliverable, Not Just Steps","text":"

    Bad task (implementation-focused): 

    - [ ] T1.1.0: Parser system\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n

    The AI may complete all subtasks but miss the actual goal. What does \"Parser system\" deliver to the user?

    Good task (deliverable-focused): 

    - [ ] T1.1.0: Parser CLI command\n  **Deliverable**: `ctx recall list` command that shows parsed sessions\n  - [ ] Define data structures\n  - [ ] Implement line parser\n  - [ ] Implement session grouper\n

    Now the AI knows the subtasks serve a specific user-facing deliverable.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#use-acceptance-criteria","level":3,"title":"Use Acceptance Criteria","text":"

    For complex tasks, add explicit \"done when\" criteria:

    - [ ] T2.0: Authentication system\n  **Done when**:\n  - [ ] User can register with email\n  - [ ] User can log in and get a token\n  - [ ] Protected routes reject unauthenticated requests\n

    This prevents premature \"task complete\" when only the implementation details are done, but the feature doesn't actually work.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#subtasks-parent-task","level":3,"title":"Subtasks ≠ Parent Task","text":"

    Completing all subtasks does not mean the parent task is complete.

    The parent task describes what the user gets.

    Subtasks describe how to build it.

    Always re-read the parent task description before marking it complete. Verify the stated deliverable exists and works.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#why-do-these-approaches-work","level":2,"title":"Why Do These Approaches Work?","text":"

    The patterns in this guide aren't invented here: They are practitioner translations of well-established, peer-reviewed research, most of which predate the current AI (hype) wave.

    The underlying ideas come from decades of work in machine learning, cognitive science, and numerical optimization. For a concrete case study showing how these principles play out when an agent decides whether to follow instructions (attention competition, optimization toward least-resistance paths, and observable compliance as a design goal) see The Dog Ate My Homework.

    Phased work (\"Explore → Plan → Implement\") applies chain-of-thought reasoning: Decomposing a problem into sequential steps before acting. Forcing intermediate reasoning steps measurably improves output quality in language models, just as it does in human problem-solving. Wei et al., Chain-of-Thought Prompting Elicits Reasoning in Large Language Models (2022).

    Root-cause prompts (\"Why doesn't X work?\") use step-back abstraction: Retreating to a higher-level question before diving into specifics. This mirrors how experienced engineers debug: they ask \"what should happen?\" before asking \"what went wrong?\" Zheng et al., Take a Step Back: Evoking Reasoning via Abstraction in Large Language Models (2023).

    Exploring alternatives (\"Propose 2-3 approaches\") leverages self-consistency: Generating multiple independent reasoning paths and selecting the most coherent result. The idea traces back to ensemble methods in ML: A committee of diverse solutions outperforms any single one. Wang et al., Self-Consistency Improves Chain of Thought Reasoning in Language Models (2022).

    Impact analysis (\"What would break if we...\") is a form of tree-structured exploration: Branching into multiple consequence paths before committing. This is the same principle behind game-tree search (minimax, MCTS) that has powered decision-making systems since the 1950s. Yao et al., Tree of Thoughts: Deliberate Problem Solving with Large Language Models (2023).

    Motivation prompting (\"Build X because Y\") works through goal conditioning: Providing the objective function alongside the task. In optimization terms, you are giving the gradient direction, not just the loss. The model can make locally coherent decisions that serve the global objective because it knows what \"better\" means.

    Scope constraints (\"Only change files in X\") apply constrained optimization: Bounding the search space to prevent divergence. This is the same principle behind regularization in ML: Without boundaries, powerful optimizers find solutions that technically satisfy the objective but are practically useless.

    CLI commands as prompts (\"Run ctx status\") interleave reasoning with acting: The model thinks, acts on external tools, observes results, then thinks again. Grounding reasoning in real tool output reduces hallucination because the model can't ignore evidence it just retrieved. Yao et al., ReAct: Synergizing Reasoning and Acting in Language Models (2022).

    Task decomposition (\"Prompts by Task Type\") applies least-to-most prompting: Breaking a complex problem into subproblems and solving them sequentially, each building on the last. This is the research version of \"plan, then implement one slice.\" Zhou et al., Least-to-Most Prompting Enables Complex Reasoning in Large Language Models (2022).

    Explicit planning (\"Explore → Plan → Implement\") is directly supported by plan-and-solve prompting, which addresses missing-step failures in zero-shot reasoning by extracting a plan before executing. The phased structure prevents the model from jumping to code before understanding the problem. Wang et al., Plan-and-Solve Prompting: Improving Zero-Shot Chain-of-Thought Reasoning by Large Language Models (2023).

    Session reflection (\"What did we learn?\", /ctx-reflect) is a form of verbal reinforcement learning: Improving future performance by persisting linguistic feedback as memory rather than updating weights. This is exactly what LEARNINGS.md and DECISIONS.md provide: a durable feedback signal across sessions. Shinn et al., Reflexion: Language Agents with Verbal Reinforcement Learning (2023).

    These aren't prompting \"hacks\" that you will find in the \"1000 AI Prompts for the Curious\" listicles: They are applications of foundational principles:

    • Decomposition,
    • Abstraction,
    • Ensemble Reasoning,
    • Search,
    • and Constrained Optimization.

    They work because language models are, at their core, optimization systems navigating probabilistic landscapes.

    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#further-reading","level":2,"title":"Further Reading","text":"
    • The Attention Budget: Why your AI forgets what you just told it, and how token budgets shape context strategy
    • The Dog Ate My Homework: A case study in making agents follow instructions: attention timing, delegation decay, and observable compliance as a design goal
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/prompting-guide/#contributing","level":2,"title":"Contributing","text":"

    Found a prompt that works well? Open an issue or PR with:

    1. The prompt text;
    2. What behavior it triggers;
    3. When to use it;
    4. Why it works (optional but helpful).

    Dive Deeper:

    • Recipes: targeted how-to guides for specific tasks
    • CLI Reference: all commands and flags
    • Integrations: setup for Claude Code, Cursor, Aider
    ","path":["Home","Prompting Guide"],"tags":[]},{"location":"home/repeated-mistakes/","level":1,"title":"My AI Keeps Making the Same Mistakes","text":"","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#the-problem","level":2,"title":"The Problem","text":"

    You found a bug last Tuesday. You debugged it, understood the root cause, and moved on. Today, a new session hits the exact same bug. The AI rediscovers it from scratch, burning twenty minutes on something you already solved.

    Worse: you spent an hour last week evaluating two database migration strategies, picked one, documented why in a comment somewhere, and now the AI is cheerfully suggesting the approach you rejected. Again.

    This is not a model problem. It is a memory problem. Without persistent context, every session starts with amnesia.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#how-ctx-stops-the-loop","level":2,"title":"How ctx Stops the Loop","text":"

    ctx gives your AI three files that directly prevent repeated mistakes, each targeting a different failure mode.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#decisionsmd-stop-relitigating-settled-choices","level":3,"title":"DECISIONS.md: Stop Relitigating Settled Choices","text":"

    When you make an architectural decision, record it with rationale and rejected alternatives. The AI reads this at session start and treats it as settled.

    ## [2026-02-12] Use JWT for Authentication\n\n**Status**: Accepted\n\n**Context**: Need stateless auth for the API layer.\n\n**Decision**: JWT with short-lived access tokens and refresh rotation.\n\n**Rationale**: Stateless, scales horizontally, team has prior experience.\n\n**Alternatives Considered**:\n- Session-based auth: Rejected. Requires sticky sessions or shared store.\n- API keys only: Rejected. No user identity, no expiry rotation.\n

    Next session, when the AI considers auth, it reads this entry and builds on the decision instead of re-debating it. If someone asks \"why not sessions?\", the rationale is already there.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#learningsmd-capture-gotchas-once","level":3,"title":"LEARNINGS.md: Capture Gotchas Once","text":"

    Learnings are the bugs, quirks, and non-obvious behaviors that cost you time the first time around. Write them down so they cost you zero time the second time.

    ## Build\n\n### CGO Required for SQLite on Alpine\n\n**Discovered**: 2026-01-20\n\n**Context**: Docker build failed silently with \"no such table\" at runtime.\n\n**Lesson**: The go-sqlite3 driver requires CGO_ENABLED=1 and gcc\ninstalled in the build stage. Alpine needs apk add build-base.\n\n**Application**: Always use the golang:alpine image with build-base\nfor SQLite builds. Never set CGO_ENABLED=0.\n

    Without this entry, the next session that touches the Dockerfile will hit the same wall. With it, the AI knows before it starts.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#constitutionmd-draw-hard-lines","level":3,"title":"CONSTITUTION.md: Draw Hard Lines","text":"

    Some mistakes are not about forgetting - they are about boundaries the AI should never cross. CONSTITUTION.md sets inviolable rules.

    * [ ] Never commit secrets, tokens, API keys, or credentials\n* [ ] Never disable security linters without a documented exception\n* [ ] All database migrations must be reversible\n

    The AI reads these as absolute constraints. It does not weigh them against convenience. It refuses tasks that would violate them.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#the-accumulation-effect","level":2,"title":"The Accumulation Effect","text":"

    Each of these files grows over time. Session one captures two decisions. Session five adds a tricky learning about timezone handling. Session twelve records a convention about error message formatting.

    By session twenty, your AI has a knowledge base that no single person carries in their head. New team members - human or AI - inherit it instantly.

    The key insight: you are not just coding. You are building a knowledge layer that makes every future session faster.

    ctx files version with your code in git. They survive branch switches, team changes, and model upgrades. The context outlives any single session.

    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#getting-started","level":2,"title":"Getting Started","text":"

    Capture your first decision or learning right now:

    ctx add decision \"Use PostgreSQL\" \\\n  --context \"Need a relational database for the project\" \\\n  --rationale \"Team expertise, JSONB support, mature ecosystem\"\n\nctx add learning \"Vitest mock hoisting\" \\\n  --context \"Tests failing intermittently\" \\\n  --lesson \"vi.mock() must be at file top level\" \\\n  --application \"Use vi.doMock() for dynamic mocks\"\n
    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"home/repeated-mistakes/#further-reading","level":2,"title":"Further Reading","text":"
    • Knowledge Capture: the full workflow for persisting decisions, learnings, and conventions
    • Context Files Reference: structure and format for every file in .context/
    • About ctx: the bigger picture - why persistent context changes how you work with AI
    ","path":["Home","My AI Keeps Making the Same Mistakes"],"tags":[]},{"location":"operations/","level":1,"title":"Operations","text":"

    Guides for installing, upgrading, integrating, and running ctx.

    ","path":["Operations"],"tags":[]},{"location":"operations/#integration","level":3,"title":"Integration","text":"

    Adopt ctx in an existing project: initialize context files, migrate from other tools, and onboard team members.

    ","path":["Operations"],"tags":[]},{"location":"operations/#upgrade","level":3,"title":"Upgrade","text":"

    Upgrade between versions with step-by-step migration notes and breaking-change guidance.

    ","path":["Operations"],"tags":[]},{"location":"operations/#ai-tools","level":3,"title":"AI Tools","text":"

    Configure ctx with Claude Code, Cursor, Aider, Copilot, Windsurf, and other AI coding tools.

    ","path":["Operations"],"tags":[]},{"location":"operations/#cutting-a-release","level":3,"title":"Cutting a Release","text":"

    Step-by-step runbook for maintainers: bump version, generate release notes, run the release script, and verify the result.

    ","path":["Operations"],"tags":[]},{"location":"operations/#autonomous-loops","level":3,"title":"Autonomous Loops","text":"

    Run an unattended AI agent that works through tasks overnight, with ctx providing persistent memory between iterations.

    ","path":["Operations"],"tags":[]},{"location":"operations/autonomous-loop/","level":1,"title":"Autonomous Loops","text":"","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#autonomous-ai-development","level":2,"title":"Autonomous AI Development","text":"

    Iterate until done.

    An autonomous loop is an iterative AI development workflow where an agent works on tasks until completion, without constant human intervention.

    ctx provides the memory that makes this possible:

    • ctx provides the memory: persistent context that survives across iterations
    • The loop provides the automation: continuous execution until done

    Together, they enable fully autonomous AI development where the agent remembers everything across iterations.

    Origin

    This pattern is inspired by Geoffrey Huntley's Ralph Wiggum technique.

    We use generic terminology here so the concepts remain clear regardless of trends.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#how-it-works","level":2,"title":"How It Works","text":"
    graph TD\n    A[Start Loop] --> B[Load PROMPT.md]\n    B --> C[AI reads .context/]\n    C --> D[AI picks task from TASKS.md]\n    D --> E[AI completes task]\n    E --> F[AI updates context files]\n    F --> G[AI commits changes]\n    G --> H{Check signals}\n    H -->|SYSTEM_CONVERGED| I[Done - all tasks complete]\n    H -->|SYSTEM_BLOCKED| J[Done - needs human input]\n    H -->|Continue| B
    1. Loop reads PROMPT.md and invokes AI
    2. AI loads context from .context/
    3. AI picks one task and completes it
    4. AI updates context files (mark task done, add learnings)
    5. AI commits changes
    6. Loop checks for completion signals
    7. Repeat until converged or blocked
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#quick-start-shell-while-loop-recommended","level":2,"title":"Quick Start: Shell While Loop (Recommended)","text":"

    The best way to run an autonomous loop is a plain shell script that invokes your AI tool in a fresh process on each iteration. This is \"pure ralph\":

    The only state that carries between iterations is what lives in .context/ and the git history. No context window bleed, no accumulated tokens, no hidden state.

    Create a loop.sh:

    #!/bin/bash\n# loop.sh: an autonomous iteration loop\n\nPROMPT_FILE=\"${1:-PROMPT.md}\"\nMAX_ITERATIONS=\"${2:-10}\"\nOUTPUT_FILE=\"/tmp/loop_output.txt\"\n\nfor i in $(seq 1 $MAX_ITERATIONS); do\n  echo \"=== Iteration $i ===\"\n\n  # Invoke AI with prompt\n  cat \"$PROMPT_FILE\" | claude --print > \"$OUTPUT_FILE\" 2>&1\n\n  # Display output\n  cat \"$OUTPUT_FILE\"\n\n  # Check for completion signals\n  if grep -q \"SYSTEM_CONVERGED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop complete: All tasks done\"\n    break\n  fi\n\n  if grep -q \"SYSTEM_BLOCKED\" \"$OUTPUT_FILE\"; then\n    echo \"Loop blocked: Needs human input\"\n    break\n  fi\n\n  sleep 2\ndone\n

    Make it executable and run:

    chmod +x loop.sh\n./loop.sh\n

    You can also generate this script with ctx loop (see CLI Reference).

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#why-do-we-use-a-shell-loop","level":3,"title":"Why Do We Use a Shell Loop?","text":"

    Each iteration starts a fresh AI process with zero context window history. The agent knows only what it reads from .context/ files: Exactly the information you chose to persist.

    This is the core loop principle: memory is explicit, not accidental.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#alternative-claude-codes-built-in-loop","level":2,"title":"Alternative: Claude Code's Built-in Loop","text":"

    Claude Code has built-in loop support:

    # Start autonomous loop\n/loop\n\n# Cancel running loop\n/cancel-loop\n

    This is convenient for quick iterations, but be aware of important caveats:

    This Loop Is not Pure

    Claude Code's /loop runs all iterations within the same session. This means:

    • State leaks between iterations: The context window accumulates output from every previous iteration. The agent \"remembers\" things it saw earlier (even if they were never persisted to .context/).
    • Token budget degrades: Each iteration adds to the context window, leaving less room for actual work in later iterations.
    • Not ergonomic for long runs: Users report that the built-in loop is less predictable for 10+ iteration runs compared to a shell loop.

    For short explorations (2-5 iterations) or interactive use, /loop works fine. For overnight unattended runs or anything where iteration independence matters, use the shell while loop instead.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#the-promptmd-file","level":2,"title":"The PROMPT.md File","text":"

    The prompt file instructs the AI on how to work autonomously. Here's a template:

    # Autonomous Development Prompt\n\nYou are working on this project autonomously. Follow these steps:\n\n## 1. Load Context\n\nRead these files in order:\n\n1. `.context/CONSTITUTION.md`: NEVER violate these rules\n2. `.context/TASKS.md`: Find work to do\n3. `.context/CONVENTIONS.md`: Follow these patterns\n4. `.context/DECISIONS.md`: Understand past choices\n\n## 2. Pick One Task\n\nFrom `.context/TASKS.md`, select ONE task that is:\n\n- Not blocked\n- Highest priority available\n- Within your capabilities\n\n## 3. Complete the Task\n\n- Write code following conventions\n- Run tests if applicable\n- Keep changes focused and minimal\n\n## 4. Update Context\n\nAfter completing work:\n\n- Mark task complete in `TASKS.md`\n- Add any learnings to `LEARNINGS.md`\n- Add any decisions to `DECISIONS.md`\n\n## 5. Commit Changes\n\nCreate a focused commit with clear message.\n\n## 6. Signal Status\n\nEnd your response with exactly ONE of:\n\n- `SYSTEM_CONVERGED`: All tasks in TASKS.md are complete\n- `SYSTEM_BLOCKED`: Cannot proceed, need human input (explain why)\n- (no signal): More work remains, continue to next iteration\n\n## Rules\n\n- ONE task per iteration\n- NEVER skip tests\n- NEVER violate CONSTITUTION.md\n- Commit after each task\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#completion-signals","level":2,"title":"Completion Signals","text":"

    The loop watches for these signals in AI output:

    Signal Meaning When to Use SYSTEM_CONVERGED All tasks complete No pending tasks in TASKS.md SYSTEM_BLOCKED Cannot proceed Needs clarification, access, or decision BOOTSTRAP_COMPLETE Initial setup done Project scaffolding finished","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#example-usage","level":3,"title":"Example Usage","text":"

    converged state

    I've completed all tasks in TASKS.md:\n- [x] Set up project structure\n- [x] Implement core API\n- [x] Add authentication\n- [x] Write tests\n\nNo pending tasks remain.\n\nSYSTEM_CONVERGED\n

    blocked state

    I cannot proceed with the \"Deploy to production\" task because:\n- Missing AWS credentials\n- Need confirmation on region selection\n\nPlease provide credentials and confirm deployment region.\n\nSYSTEM_BLOCKED\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#why-ctx-and-loops-work-well-together","level":2,"title":"Why ctx and Loops Work Well Together","text":"Without ctx With ctx Each iteration starts fresh Each iteration has full history Decisions get re-made Decisions persist in DECISIONS.md Learnings are lost Learnings accumulate in LEARNINGS.md Tasks can be forgotten Tasks tracked in TASKS.md","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#automatic-context-updates","level":3,"title":"Automatic Context Updates","text":"

    During the loop, the AI should update context files:

    Mark task complete: 

    ctx task complete \"implement user auth\"\n

    Or emit an update command (parsed by ctx watch): 

    <context-update type=\"complete\">user auth</context-update>\n

    Add learning: 

    ctx add learning \"Rate limiting requires Redis connection\"\n

    Or via update command: 

    <context-update type=\"learning\"\n  context=\"Implementing rate limiter\"\n  lesson=\"Rate limiting requires Redis connection\"\n  application=\"Ensure Redis is provisioned before enabling rate limits\"\n>Rate Limiting Redis Dependency</context-update>\n

    Record decision: 

    ctx add decision \"Use JWT tokens for API authentication\"\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#advanced-watch-mode","level":2,"title":"Advanced: Watch Mode","text":"

    Run ctx watch alongside the loop to automatically process context updates:

    # Terminal 1: Run the loop\n./loop.sh 2>&1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log\n

    The watch command processes context updates from the loop output in real time.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#project-setup","level":2,"title":"Project Setup","text":"

    Initialize a project for autonomous loop operation:

    # Initialize with autonomous agent behavior\nctx init --ralph\n

    The --ralph flag creates a PROMPT.md where the agent:

    • Works autonomously without asking clarifying questions;
    • Follows one-task-per-iteration discipline;
    • Uses SYSTEM_CONVERGED / SYSTEM_BLOCKED signals;

    Without --ralph, the agent is encouraged to ask questions when requirements are unclear: Better for collaborative human-agent sessions.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#example-project-structure","level":2,"title":"Example Project Structure","text":"
    my-project/\n├── .context/\n│   ├── CONSTITUTION.md\n│   ├── TASKS.md          # Work items for the loop\n│   ├── DECISIONS.md\n│   ├── LEARNINGS.md\n│   ├── CONVENTIONS.md\n│   └── sessions/         # Loop iteration history\n├── PROMPT.md             # Instructions for the AI\n├── IMPLEMENTATION_PLAN.md # High-level project direction\n├── loop.sh               # Loop script (if not using Claude Code)\n└── src/                  # Your code\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#sample-tasksmd-for-autonomous-loops","level":3,"title":"Sample TASKS.md for Autonomous Loops","text":"
    # Tasks\n\n## Phase 1: Setup\n\n- [x] Initialize project structure\n- [x] Set up testing framework\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Polish\n\n- [ ] Add rate limiting `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n

    The loop will work through these systematically, marking each complete.

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#troubleshooting","level":2,"title":"Troubleshooting","text":"","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#loop-runs-forever","level":3,"title":"Loop Runs Forever","text":"

    Cause: AI not emitting completion signals

    Fix: Ensure PROMPT.md explicitly instructs signaling: 

    End EVERY response with one of:\n- SYSTEM_CONVERGED (if all tasks done)\n- SYSTEM_BLOCKED (if stuck)\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#context-not-persisting","level":3,"title":"Context Not Persisting","text":"

    Cause: AI not updating context files

    Fix: Add explicit instructions to PROMPT.md: 

    After completing a task, you MUST:\n1. Run: ctx task complete \"<task>\"\n2. Add learnings: ctx add learning \"...\"\n

    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#tasks-getting-repeated","level":3,"title":"Tasks Getting Repeated","text":"

    Cause: Task not marked complete before next iteration

    Fix: Ensure commit happens after context update:

    Order of operations:\n1. Complete coding work\n2. Update context files (*`ctx task complete`, `ctx add`*)\n3. Commit **ALL** changes including `.context/`\n4. Then signal status\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#ai-violating-constitution","level":3,"title":"AI Violating Constitution","text":"

    Cause: Constitution not read first

    Fix: Make constitution check explicit in PROMPT.md:

    BEFORE any work:\n1. Read .context/CONSTITUTION.md\n2. If task would violate ANY rule, emit SYSTEM_BLOCKED\n3. Explain which rule prevents the work\n
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#further-reading","level":2,"title":"Further Reading","text":"
    • Building ctx Using ctx: The dogfooding story: how autonomous loops built the tool that powers them
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/autonomous-loop/#resources","level":2,"title":"Resources","text":"
    • Geoffrey Huntley's Ralph Wiggum Technique: The original inspiration
    • Context CLI: Command reference
    • Integrations: Tool-specific setup
    ","path":["Operations","Autonomous Loops"],"tags":[]},{"location":"operations/integrations/","level":1,"title":"AI Tools","text":"","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#ai-tools","level":2,"title":"AI Tools","text":"

    Context works with any AI tool that can read files. This guide covers setup for popular AI coding assistants.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#claude-code-full-integration","level":2,"title":"Claude Code (Full Integration)","text":"

    Claude Code has the deepest integration via the ctx plugin.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup","level":3,"title":"Setup","text":"

    First, install ctx and initialize your project:

    ctx init\n

    Then, install the ctx plugin in Claude Code:

    # From the ctx repository\nclaude /plugin install ./internal/assets/claude\n\n# Or from the marketplace\nclaude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n

    Ensure the Plugin Is Enabled

    Installing a plugin registers it, but local installs may not auto-enable it globally. Verify ~/.claude/settings.json contains:

    { \"enabledPlugins\": { \"ctx@activememory-ctx\": true } }\n

    Without this, the plugin's hooks and skills won't appear in other projects. Running ctx init auto-enables the plugin; use --no-plugin-enable to skip this step.

    This gives you:

    Component Purpose .context/ All context files CLAUDE.md Bootstrap instructions Plugin hooks Lifecycle automation Plugin skills Agent Skills","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#how-it-works","level":3,"title":"How It Works","text":"
    graph TD\n    A[Session Start] --> B[Claude reads CLAUDE.md]\n    B --> C[PreToolUse hook runs]\n    C --> D[ctx agent loads context]\n    D --> E[Work happens]\n    E --> F[Session End]
    1. Session start: Claude reads CLAUDE.md, which tells it to check .context/
    2. First tool use: PreToolUse hook runs ctx agent and emits the context packet (subsequent invocations within the cooldown window are silent)
    3. Next session: Claude reads context files and continues with context
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#plugin-hooks","level":3,"title":"Plugin Hooks","text":"

    The ctx plugin provides lifecycle hooks implemented as Go subcommands (ctx system *):

    Hook Event Purpose ctx system context-load-gate PreToolUse (.*) Auto-inject context on first tool use ctx system block-non-path-ctx PreToolUse (Bash) Block ./ctx or go run: force $PATH install ctx system qa-reminder PreToolUse (Bash) Remind agent to lint/test before committing ctx system specs-nudge PreToolUse (EnterPlanMode) Nudge agent to use project specs when planning ctx system check-context-size UserPromptSubmit Nudge context assessment as sessions grow ctx system check-ceremonies UserPromptSubmit Nudge /ctx-remember and /ctx-wrap-up adoption ctx system check-persistence UserPromptSubmit Remind to persist learnings/decisions ctx system check-journal UserPromptSubmit Remind to export/enrich journal entries ctx system check-reminders UserPromptSubmit Relay pending reminders at session start ctx system check-version UserPromptSubmit Warn when binary/plugin versions diverge ctx system check-resources UserPromptSubmit Warn when memory/swap/disk/load hit DANGER level ctx system check-knowledge UserPromptSubmit Nudge when knowledge files grow large ctx system check-map-staleness UserPromptSubmit Nudge when ARCHITECTURE.md is stale ctx system heartbeat UserPromptSubmit Session-alive signal with prompt count metadata ctx system post-commit PostToolUse (Bash) Nudge context capture and QA after git commits

    A catch-all PreToolUse hook also runs ctx agent on every tool use (with cooldown) to autoload context.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#hook-configuration","level":3,"title":"Hook Configuration","text":"

    The plugin's hooks.json wires everything automatically: no manual configuration in settings.local.json needed:

    {\n  \"hooks\": {\n    \"PreToolUse\": [\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system context-load-gate\" }\n        ]\n      },\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system block-non-path-ctx\" }\n        ]\n      },\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system qa-reminder\" }\n        ]\n      },\n      {\n        \"matcher\": \"EnterPlanMode\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system specs-nudge\" }\n        ]\n      },\n      {\n        \"matcher\": \".*\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx agent --budget 4000 2>/dev/null || true\" }\n        ]\n      }\n    ],\n    \"PostToolUse\": [\n      {\n        \"matcher\": \"Bash\",\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system post-commit\" }\n        ]\n      }\n    ],\n    \"UserPromptSubmit\": [\n      {\n        \"hooks\": [\n          { \"type\": \"command\", \"command\": \"ctx system check-context-size\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-ceremonies\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-persistence\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-journal\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-reminders\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-version\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-resources\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-knowledge\" },\n          { \"type\": \"command\", \"command\": \"ctx system check-map-staleness\" },\n          { \"type\": \"command\", \"command\": \"ctx system heartbeat\" }\n        ]\n      }\n    ]\n  }\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#customizing-token-budget-and-cooldown","level":3,"title":"Customizing Token Budget and Cooldown","text":"

    Edit the PreToolUse command to change the token budget or cooldown:

    \"command\": \"ctx agent --budget 8000 --session $PPID >/dev/null || true\"\n\"command\": \"ctx agent --budget 4000 --cooldown 5m --session $PPID >/dev/null || true\"\n

    The --session $PPID flag isolates the cooldown per session: $PPID resolves to the Claude Code process PID, so concurrent sessions don't interfere. The default cooldown is 10 minutes; use --cooldown 0 to disable it.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#verifying-setup","level":3,"title":"Verifying Setup","text":"
    1. Start a new Claude Code session;
    2. Ask: \"Do you remember?\"
    3. Claude should cite specific context:
      • Current tasks from .context/TASKS.md;
      • Recent decisions or learnings;
      • Recent session history from ctx recall.
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#local-plugin-development","level":3,"title":"Local Plugin Development","text":"

    When developing ctx locally (adding skills, hooks, or changing plugin behavior), Claude Code caches the plugin by version. You must bump the version in both files and update the marketplace for changes to take effect:

    1. Bump version in both:

    2. internal/assets/claude/.claude-plugin/plugin.json (plugin manifest), .claude-plugin/marketplace.json (marketplace listing*);

    3. Update the marketplace in Claude Code:

    4. Open the Plugins UI (/plugins or Esc menu),
    5. Go to Marketplaces tab,
    6. Select the activememory-ctx Marketplace,

    7. Choose Update marketplace;

    8. Start a new Claude Code session: skill changes aren't reflected in existing sessions.

    Both Version Files Must Match

    If you only bump plugin.json but not marketplace.json (or vice versa), Claude Code may not detect the update. Always bump both together.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#troubleshooting","level":3,"title":"Troubleshooting","text":"Issue Solution Context not loading Check ctx is in PATH: which ctx Hook errors Verify plugin is installed: claude /plugin list New skill not visible Bump version in both plugin.json files, update marketplace","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-load","level":3,"title":"Manual Context Load","text":"

    If hooks aren't working, manually load context:

    # Get context packet\nctx agent --budget 4000\n\n# Or paste into conversation\ncat .context/TASKS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#agent-skills","level":3,"title":"Agent Skills","text":"

    The ctx plugin ships Agent Skills following the agentskills.io specification.

    These are invoked in Claude Code with /skill-name.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-lifecycle-skills","level":4,"title":"Session Lifecycle Skills","text":"Skill Description /ctx-remember Recall project context at session start (ceremony) /ctx-wrap-up End-of-session context persistence (ceremony) /ctx-status Show context summary (tasks, decisions, learnings) /ctx-agent Get AI-optimized context packet /ctx-next Suggest 1-3 concrete next actions from context /ctx-commit Commit with integrated context capture /ctx-reflect Review session and suggest what to persist /ctx-remind Manage session-scoped reminders /ctx-pause Pause context hooks for this session /ctx-resume Resume context hooks after a pause","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#context-persistence-skills","level":4,"title":"Context Persistence Skills","text":"Skill Description /ctx-add-task Add a task to TASKS.md /ctx-add-learning Add a learning to LEARNINGS.md /ctx-add-decision Add a decision with context/rationale/consequence /ctx-add-convention Add a coding convention to CONVENTIONS.md /ctx-archive Archive completed tasks","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#scratchpad-skills","level":4,"title":"Scratchpad Skills","text":"Skill Description /ctx-pad Manage encrypted scratchpad entries","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-history-skills","level":4,"title":"Session History Skills","text":"Skill Description /ctx-recall Browse AI session history /ctx-journal-enrich Enrich a journal entry with frontmatter/tags /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich /ctx-journal-normalize Fix markdown rendering issues in journal","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#blogging-skills","level":4,"title":"Blogging Skills","text":"

    Blogging is a Better Way of Creating Release Notes

    The blogging workflow can also double as generating release notes:

    AI reads your git commit history and creates a \"narrative\", which is essentially what a release note is for.

    Skill Description /ctx-blog Generate blog post from recent activity /ctx-blog-changelog Generate blog post from commit range with theme","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#auditing-health-skills","level":4,"title":"Auditing & Health Skills","text":"Skill Description /ctx-doctor Troubleshoot ctx behavior with structural health checks /ctx-drift Detect and fix context drift (structural + semantic) /ctx-consolidate Merge redundant learnings or decisions into denser entries /ctx-alignment-audit Audit doc claims against playbook instructions /ctx-prompt-audit Analyze session logs for vague prompts /check-links Audit docs for dead internal and external links","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#planning-execution-skills","level":4,"title":"Planning & Execution Skills","text":"Skill Description /ctx-loop Generate a Ralph Loop iteration script /ctx-implement Execute a plan step-by-step with checks /ctx-import-plans Import Claude Code plan files into project specs /ctx-worktree Manage git worktrees for parallel agents /ctx-architecture Build and maintain architecture maps","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage-examples","level":4,"title":"Usage Examples","text":"
    /ctx-status\n/ctx-add-learning \"Token refresh requires explicit cache invalidation\"\n/ctx-journal-enrich twinkly-stirring-kettle\n

    Skills support partial matching where applicable (e.g., session slugs).

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#cursor-ide","level":2,"title":"Cursor IDE","text":"

    Cursor can use context files through its system prompt or by reading files directly.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_1","level":3,"title":"Setup","text":"
    # Generate Cursor configuration\nctx hook cursor\n\n# Initialize context\nctx init --minimal\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration","level":3,"title":"Configuration","text":"

    Add to Cursor settings (.cursor/settings.json):

    // split to multiple lines for readability\n{\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and \n  .context/CONVENTIONS.md before responding. \n  Follow rules in .context/CONSTITUTION.md.\",\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage","level":3,"title":"Usage","text":"
    1. Open your project in Cursor
    2. Context files are available in the file tree
    3. Reference them in prompts: \"Check .context/DECISIONS.md for our approach to...\"
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-injection","level":3,"title":"Manual Context Injection","text":"

    For more control, paste context directly:

    # Get AI-ready packet\nctx agent --budget 4000 | pbcopy  # macOS\nctx agent --budget 4000 | xclip  # Linux\n

    Paste into Cursor's chat.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#aider","level":2,"title":"Aider","text":"

    Aider works well with context files through its --read flag.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_2","level":3,"title":"Setup","text":"
    # Generate Aider configuration\nctx hook aider\n\n# Initialize context\nctx init\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_1","level":3,"title":"Configuration","text":"

    Create .aider.conf.yml:

    read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage_1","level":3,"title":"Usage","text":"
    # Start Aider (reads context files automatically)\naider\n\n# Or specify files explicitly\naider --read .context/TASKS.md --read .context/CONVENTIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#with-watch-mode","level":3,"title":"With Watch Mode","text":"

    Run ctx watch alongside Aider to capture context updates:

    # Terminal 1: Run Aider\naider 2>&1 | tee /tmp/aider.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/aider.log\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#github-copilot","level":2,"title":"GitHub Copilot","text":"

    GitHub Copilot integrates with ctx at three levels: an automated instructions file, a VS Code Chat extension, and manual patterns.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_3","level":3,"title":"Setup","text":"
    # Initialize context\nctx init\n\n# Generate .github/copilot-instructions.md\nctx hook copilot --write\n

    The --write flag creates .github/copilot-instructions.md, which Copilot reads automatically at the start of every session. This file contains your project's constitution rules, current tasks, conventions, and architecture: giving Copilot persistent context without manual copy-paste.

    Re-run ctx hook copilot --write after updating your .context/ files to regenerate the instructions.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#vs-code-chat-extension-ctx","level":3,"title":"VS Code Chat Extension (@ctx)","text":"

    The ctx VS Code extension adds a @ctx chat participant to GitHub Copilot Chat, giving you direct access to all context commands from within the editor.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#installation","level":4,"title":"Installation","text":"
    1. Build from source (requires Node.js 18+):
    cd editors/vscode\nnpm install\nnpm run build\nnpx @vscode/vsce package\n
    1. Install the .vsix file:
    code --install-extension ctx-context-0.7.0.vsix\n
    1. Reload VS Code. Type @ctx in Copilot Chat to verify.
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#slash-commands","level":4,"title":"Slash Commands","text":"Command Description @ctx /init Initialize .context/ directory with template files @ctx /status Show context summary with token estimate @ctx /agent Print AI-ready context packet @ctx /drift Detect stale or invalid context @ctx /recall Browse and search AI session history @ctx /hook Generate AI tool integration configs @ctx /add Add a task, decision, or learning @ctx /load Output assembled context Markdown @ctx /compact Archive completed tasks and clean up @ctx /sync Reconcile context with codebase","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage-examples_1","level":4,"title":"Usage Examples","text":"
    @ctx /init\n@ctx /status\n@ctx /add task Implement user authentication\n@ctx /drift\n@ctx /hook copilot\n@ctx /recall\n

    Typing @ctx without a command shows help with all available commands. The extension also supports natural language: asking @ctx about \"status\" or \"drift\" routes to the correct command automatically.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_2","level":4,"title":"Configuration","text":"Setting Default Description ctx.executablePath ctx Path to the ctx binary. Set this if ctx is not in your PATH.","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#follow-up-suggestions","level":4,"title":"Follow-Up Suggestions","text":"

    After each command, the extension suggests relevant next steps. For example, after /init it suggests /status and /hook; after /drift it suggests /sync.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#session-persistence","level":3,"title":"Session Persistence","text":"

    ctx init creates a .context/sessions/ directory for storing session data from non-Claude tools. The Markdown session parser scans this directory during ctx recall, enabling session history for Copilot and other tools.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-patterns","level":3,"title":"Manual Patterns","text":"

    These patterns work without the extension, using Copilot's built-in file awareness:

    Pattern 1: Keep context files open

    Open .context/CONVENTIONS.md in a split pane. Copilot will reference it.

    Pattern 2: Reference in comments

    // See .context/CONVENTIONS.md for naming patterns\n// Following decision in .context/DECISIONS.md: Use PostgreSQL\n\nfunction getUserById(id: string) {\n  // Copilot now has context\n}\n

    Pattern 3: Paste context into Copilot Chat

    ctx agent --budget 2000\n

    Paste output into Copilot Chat for context-aware responses.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#windsurf-ide","level":2,"title":"Windsurf IDE","text":"

    Windsurf supports custom instructions and file-based context.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#setup_4","level":3,"title":"Setup","text":"
    # Generate Windsurf configuration\nctx hook windsurf\n\n# Initialize context\nctx init\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#configuration_3","level":3,"title":"Configuration","text":"

    Add to Windsurf settings:

    // Split to multiple lines for readability\n{\n  \"ai.customInstructions\": \"Always read .context/CONSTITUTION.md first. \n  Check .context/TASKS.md for current work. \n  Follow patterns in .context/CONVENTIONS.md.\"\n}\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#usage_2","level":3,"title":"Usage","text":"

    Context files appear in the file tree. Reference them when chatting:

    • \"What's in our task list?\" → AI reads .context/TASKS.md
    • \"What convention do we use for naming?\" → AI reads .context/CONVENTIONS.md
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#generic-integration","level":2,"title":"Generic Integration","text":"

    For any AI tool that can read files, use these patterns:

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#manual-context-loading","level":3,"title":"Manual Context Loading","text":"
    # Get full context\nctx load\n\n# Get AI-optimized packet\nctx agent --budget 8000\n\n# Get specific file\ncat .context/TASKS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#system-prompt-template","level":3,"title":"System Prompt Template","text":"
    You are working on a project with persistent context in .context/\n\nBefore responding:\n1. Read .context/CONSTITUTION.md - NEVER violate these rules\n2. Check .context/TASKS.md for current work\n3. Follow .context/CONVENTIONS.md patterns\n4. Reference .context/DECISIONS.md for architectural choices\n\nWhen you learn something new, note it for .context/LEARNINGS.md\nWhen you make a decision, document it for .context/DECISIONS.md\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#automated-updates","level":3,"title":"Automated Updates","text":"

    If your AI tool outputs to a log, use ctx watch:

    # Watch log file for context-update commands\nyour-ai-tool 2>&1 | tee /tmp/ai.log &\nctx watch --log /tmp/ai.log\n

    The AI can emit updates like:

    <context-update type=\"complete\">implement caching</context-update>\n<context-update type=\"learning\"\n  context=\"Implementing caching layer\"\n  lesson=\"Important thing learned today\"\n  application=\"Apply this insight going forward\"\n>Caching Insight</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#context-update-commands","level":2,"title":"Context Update Commands","text":"

    The ctx watch command parses update commands from AI output. Use this format:

    <context-update type=\"TYPE\" [attributes]>Content</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#supported-types","level":3,"title":"Supported Types","text":"Type Target File Required Attributes task TASKS.md None decision DECISIONS.md context, rationale, consequence learning LEARNINGS.md context, lesson, application convention CONVENTIONS.md None complete TASKS.md None","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#simple-format-tasks-conventions-complete","level":3,"title":"Simple Format (tasks, conventions, complete)","text":"
    <context-update type=\"task\">Implement rate limiting</context-update>\n<context-update type=\"convention\">Use kebab-case for files</context-update>\n<context-update type=\"complete\">rate limiting</context-update>\n
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#structured-format-learnings-decisions","level":3,"title":"Structured Format (learnings, decisions)","text":"

    Learnings and decisions support structured attributes for better documentation:

    Learning with full structure:

    <context-update type=\"learning\"\n  context=\"Debugging Claude Code hooks\"\n  lesson=\"Hooks receive JSON via stdin, not environment variables\"\n  application=\"Parse JSON stdin with the host language (Go, Python, etc.): no jq needed\"\n>Hook Input Format</context-update>\n

    Decision with full structure:

    <context-update type=\"decision\"\n  context=\"Need a caching layer for API responses\"\n  rationale=\"Redis is fast, well-supported, and team has experience\"\n  consequence=\"Must provision Redis infrastructure; team training on Redis patterns\"\n>Use Redis for caching</context-update>\n

    Learnings require: context, lesson, application attributes. Decisions require: context, rationale, consequence attributes. Updates missing required attributes are rejected with an error.

    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/integrations/#further-reading","level":2,"title":"Further Reading","text":"
    • Skills That Fight the Platform: Common pitfalls in skill design that work against the host tool
    • The Anatomy of a Skill That Works: What makes a skill reliable: the E/A/R framework and quality gates
    ","path":["Operations","AI Tools"],"tags":[]},{"location":"operations/migration/","level":1,"title":"Integration","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#adopting-ctx-in-existing-projects","level":2,"title":"Adopting ctx in Existing Projects","text":"

    Claude Code User?

    You probably want the plugin instead of this page.

    Install ctx from the marketplace: (/plugin → search \"ctx\" → Install) and you're done: hooks, skills, and updates are handled for you.

    See Getting Started for the full walkthrough.

    This guide covers adopting ctx in existing projects regardless of which tools your team uses.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#quick-paths","level":2,"title":"Quick Paths","text":"You have... Command What happens Nothing (greenfield) ctx init Creates .context/, CLAUDE.md, permissions Existing CLAUDE.md ctx init --merge Backs up your file, inserts ctx block after the H1 Existing CLAUDE.md + ctx markers ctx init --force Replaces the ctx block, leaves your content intact .cursorrules / .aider.conf.yml ctx init ctx ignores those files: they coexist cleanly Team repo, first adopter ctx init --merge && git add .context/ CLAUDE.md Initialize and commit for the team","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#existing-claudemd","level":2,"title":"Existing CLAUDE.md","text":"

    This is the most common scenario:

    You have a CLAUDE.md with project-specific instructions and don't want to lose them.

    You Own CLAUDE.md

    After initialization, CLAUDE.md is yours: edit it freely.

    Add project instructions, remove sections you don't need, reorganize as you see fit.

    The only part ctx manages is the block between the <!-- ctx:context --> and <!-- ctx:end --> markers; everything outside those markers is yours to change at any time.

    If you remove the markers, nothing breaks: ctx simply treats the file as having no ctx content and will offer to merge again on the next ctx init.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-ctx-init-does","level":3,"title":"What ctx init Does","text":"

    When ctx init detects an existing CLAUDE.md, it checks for ctx markers (<!-- ctx:context --> ... <!-- ctx:end -->):

    State Default behavior With --merge With --force No CLAUDE.md Creates from template Creates from template Creates from template Exists, no ctx markers Prompts to merge Auto-merges (no prompt) Auto-merges (no prompt) Exists, has ctx markers Skips (already set up) Skips Replaces the ctx block only","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#the-merge-flag","level":3,"title":"The --merge Flag","text":"

    --merge auto-merges without prompting. The merge process:

    1. Backs up your existing CLAUDE.md to CLAUDE.md.<timestamp>.bak;
    2. Finds the H1 heading (e.g., # My Project) in your file;
    3. Inserts the ctx block immediately after it;
    4. Preserves everything else untouched.

    Your content before and after the ctx block remains exactly as it was.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#before-after-example","level":3,"title":"Before / After Example","text":"

    Before: your existing CLAUDE.md:

    # My Project\n\n## Build Commands\n\n-`npm run build`: production build\n- `npm test`: run tests\n\n## Code Style\n\n- Use TypeScript strict mode\n- Prefer named exports\n

    After ctx init --merge:

    # My Project\n\n<!-- ctx:context -->\n<!-- DO NOT REMOVE: This marker indicates ctx-managed content -->\n\n## IMPORTANT: You Have Persistent Memory\n\nThis project uses Context (`ctx`) for context persistence across sessions.\n...\n\n<!-- ctx:end -->\n\n## Build Commands\n\n- `npm run build`: production build\n- `npm test`: run tests\n\n## Code Style\n\n- Use TypeScript strict mode\n- Prefer named exports\n

    Your build commands and code style sections are untouched. The ctx block sits between markers and can be updated independently.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#the-force-flag","level":3,"title":"The --force Flag","text":"

    If your CLAUDE.md already has ctx markers (from a previous ctx init), the default behavior is to skip it. Use --force to replace the ctx block with the latest template: This is useful after upgrading ctx:

    ctx init --force\n

    This only replaces content between <!-- ctx:context --> and <!-- ctx:end -->. Your own content outside the markers is preserved. A timestamped backup is created before any changes.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#undoing-a-merge","level":3,"title":"Undoing a Merge","text":"

    Every merge creates a backup:

    $ ls CLAUDE.md*.bak\nCLAUDE.md.1738000000.bak\n

    To restore:

    cp CLAUDE.md.1738000000.bak CLAUDE.md\n

    Or if you are using git, simply:

    git checkout CLAUDE.md\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#existing-cursorrules-aider-copilot","level":2,"title":"Existing .cursorrules / Aider / Copilot","text":"

    ctx doesn't touch tool-specific config files. It creates its own files (.context/, CLAUDE.md) and coexists with whatever you already have.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-does-ctx-create","level":3,"title":"What Does ctx Create?","text":"ctx creates ctx does NOT touch .context/ directory .cursorrules CLAUDE.md (or merges into) .aider.conf.yml .claude/settings.local.json (seeded by ctx init; the plugin manages hooks and skills) .github/copilot-instructions.md .windsurfrules Any other tool-specific config

    Claude Code hooks and skills are provided by the ctx plugin, installed from the Claude Code marketplace (/plugin → search \"ctx\" → Install).

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#running-ctx-alongside-other-tools","level":3,"title":"Running ctx Alongside Other Tools","text":"

    The .context/ directory is the source of truth. Tool-specific configs point to it:

    • Cursor: Reference .context/ files in your system prompt (see Cursor setup)
    • Aider: Add .context/ files to the read: list in .aider.conf.yml (see Aider setup)
    • Copilot: Keep .context/ files open or reference them in comments (see Copilot setup)

    You can generate a tool-specific configuration with:

    ctx hook cursor    # Generate Cursor config snippet\nctx hook aider     # Generate .aider.conf.yml\nctx hook copilot   # Generate Copilot tips\nctx hook windsurf  # Generate Windsurf config\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#migrating-content-into-context","level":3,"title":"Migrating Content Into .context/","text":"

    If you have project knowledge scattered across .cursorrules or custom prompt files, consider migrating it:

    1. Rules / invariants → .context/CONSTITUTION.md
    2. Code patterns → .context/CONVENTIONS.md
    3. Architecture notes → .context/ARCHITECTURE.md
    4. Known issues / tips → .context/LEARNINGS.md

    You don't need to delete the originals: ctx and tool-specific files can coexist. But centralizing in .context/ means every tool gets the same context.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#team-adoption","level":2,"title":"Team Adoption","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#context-is-designed-to-be-committed","level":3,"title":".context/ Is Designed to Be Committed","text":"

    The context files (tasks, decisions, learnings, conventions, architecture) are meant to live in version control. However, some subdirectories are personal or sensitive and should not be committed.

    ctx init automatically adds these .gitignore entries:

    # Journals contain full session transcripts: personal, potentially large\n.context/journal/\n.context/journal-site/\n.context/journal-obsidian/\n\n# Legacy encryption key path (copy to ~/.ctx/.ctx.key if needed)\n.context/.ctx.key\n\n# Runtime state and logs (ephemeral, machine-specific):\n.context/state/\n.context/logs/\n\n# Claude Code local settings (machine-specific)\n.claude/settings.local.json\n

    With those in place, committing is straightforward:

    # One person initializes\nctx init --merge\n\n# Commit context files (journals and keys are already gitignored)\ngit add .context/ CLAUDE.md\ngit commit -m \"Add ctx context management\"\ngit push\n

    Teammates pull and immediately have context. No per-developer setup needed.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#what-about-claude","level":3,"title":"What About .claude/?","text":"

    The .claude/ directory contains permissions that ctx init seeds. Hooks and skills are provided by the ctx plugin (not per-project files).

    File Commit? Why .claude/settings.local.json No Machine-specific, accumulates session permissions .claude/settings.golden.json Yes Curated permission snapshot (via ctx permission snapshot)","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#merge-conflicts-in-context-files","level":3,"title":"Merge Conflicts in Context Files","text":"

    Context files are plain Markdown. Resolve conflicts the same way you would for any other documentation file:

    # After a conflicting pull\ngit diff .context/TASKS.md    # See both sides\n# Edit to keep both sets of tasks, then:\ngit add .context/TASKS.md\ngit commit\n

    Common conflict scenarios:

    • TASKS.md: Two people added tasks: Keep both.
    • DECISIONS.md: Same decision recorded differently: Unify the entry.
    • LEARNINGS.md: Parallel discoveries: Keep both, remove duplicates.
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#gradual-adoption","level":3,"title":"Gradual Adoption","text":"

    You don't need the whole team to switch at once:

    1. One person runs ctx init --merge and commits;
    2. CLAUDE.md instructions work immediately for Claude Code users;
    3. Other tool users can adopt at their own pace using ctx hook <tool>;
    4. Context files benefit everyone who reads them, even without tool integration.
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#verifying-it-worked","level":2,"title":"Verifying It Worked","text":"","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#check-status","level":3,"title":"Check Status","text":"
    ctx status\n

    You should see your context files listed with token counts and no warnings.

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#test-memory","level":3,"title":"Test Memory","text":"

    Start a new AI session and ask: \"Do you remember?\"

    The AI should cite specific context:

    • Current tasks from .context/TASKS.md;
    • Recent decisions or learnings;
    • Session history (if you've had prior sessions);

    If it responds with generic \"I don't have memory\", check that ctx is in your PATH (which ctx) and that hooks are configured (see Troubleshooting).

    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#verify-the-merge","level":3,"title":"Verify the Merge","text":"

    If you used --merge, check that your original content is intact:

    # Your original content should still be there\ncat CLAUDE.md\n\n# The ctx block should be between markers\ngrep -c \"ctx:context\" CLAUDE.md  # Should print 1\ngrep -c \"ctx:end\" CLAUDE.md      # Should print 1\n
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/migration/#further-reading","level":2,"title":"Further Reading","text":"
    • Getting Started: Full setup walkthrough
    • Context Files: What each .context/ file does
    • Integrations: Per-tool setup (Claude Code, Cursor, Aider, Copilot)
    • CLI Reference: All ctx commands and flags
    ","path":["Operations","Integration"],"tags":[]},{"location":"operations/release/","level":1,"title":"Cutting a Release","text":"","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#prerequisites","level":2,"title":"Prerequisites","text":"

    Before you can cut a release you need:

    • Push access to origin (GitHub)
    • GPG signing configured (make gpg-test)
    • Go installed (version in go.mod)
    • Zensical installed (make site-setup)
    • A clean working tree (git status shows nothing to commit)
    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#step-by-step","level":2,"title":"Step-by-Step","text":"","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#1-update-the-version-file","level":3,"title":"1. Update the VERSION File","text":"
    echo \"0.9.0\" > VERSION\ngit add VERSION\ngit commit -m \"chore: bump version to 0.9.0\"\n

    The VERSION file uses bare semver (0.9.0), no v prefix. The release script adds the v prefix for git tags.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#2-generate-release-notes","level":3,"title":"2. Generate Release Notes","text":"

    In Claude Code:

    /_ctx-release-notes\n

    This analyzes commits since the last tag and writes dist/RELEASE_NOTES.md. The release script refuses to proceed without this file.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#3-commit-any-remaining-changes","level":3,"title":"3. Commit Any Remaining Changes","text":"
    git status          # must be clean\nmake audit          # full check: fmt, vet, lint, test\n
    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#4-run-the-release","level":3,"title":"4. Run the Release","text":"
    make release\n

    Or, if you are in a Claude Code session:

    /_ctx-release\n

    The release script does everything in order:

    Step What happens 1 Reads VERSION, verifies release notes exist 2 Verifies working tree is clean 3 Updates version in 4 config files (plugin.json, marketplace.json, VS Code package.json + lock) 4 Updates download URLs in 3 doc files (index.md, getting-started.md, integrations.md) 5 Adds new row to versions.md 6 Rebuilds the documentation site (make site) 7 Commits all version and docs updates 8 Runs make test and make smoke 9 Builds binaries for all 6 platforms via hack/build-all.sh 10 Creates a signed git tag (v0.9.0) 11 Pushes the tag to origin 12 Updates and pushes the latest tag","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#5-github-ci-takes-over","level":3,"title":"5. GitHub CI Takes Over","text":"

    Pushing a v* tag triggers .github/workflows/release.yml:

    1. Checks out the tagged commit
    2. Runs the full test suite
    3. Builds binaries for all platforms
    4. Creates a GitHub Release with auto-generated notes
    5. Uploads binaries and SHA256 checksums
    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#6-verify","level":3,"title":"6. Verify","text":"
    • GitHub Releases shows the new version
    • All 6 binaries are attached (linux/darwin x amd64/arm64, windows x amd64)
    • SHA256 files are attached
    • Release notes look correct
    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#what-gets-updated-automatically","level":2,"title":"What Gets Updated Automatically","text":"

    The release script updates 8 files so you do not have to:

    File What changes internal/assets/claude/.claude-plugin/plugin.json Plugin version .claude-plugin/marketplace.json Marketplace version (2 fields) editors/vscode/package.json VS Code extension version editors/vscode/package-lock.json VS Code lock version (2 fields) docs/index.md Download URLs docs/home/getting-started.md Download URLs docs/operations/integrations.md VSIX filename version docs/reference/versions.md New version row + latest pointer

    The Go binary version is injected at build time via -ldflags from the VERSION file. No source file needs editing.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#build-targets-reference","level":2,"title":"Build Targets Reference","text":"Target What it does make release Full release (script + tag + push) make build Build binary for current platform make build-all Build all 6 platform binaries make test Unit tests make smoke Integration smoke tests make audit Full check (fmt + vet + lint + drift + docs + test) make site Rebuild documentation site","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#troubleshooting","level":2,"title":"Troubleshooting","text":"","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#release-notes-not-found","level":3,"title":"\"Release notes not found\"","text":"
    ERROR: dist/RELEASE_NOTES.md not found.\n

    Run /_ctx-release-notes in Claude Code first, or write dist/RELEASE_NOTES.md manually.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#working-tree-is-not-clean","level":3,"title":"\"Working tree is not clean\"","text":"
    ERROR: Working tree is not clean.\n

    Commit or stash all changes before running make release.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#tag-already-exists","level":3,"title":"\"Tag already exists\"","text":"
    ERROR: Tag v0.9.0 already exists.\n

    You cannot release the same version twice. Either bump VERSION to a new version, or delete the old tag if the release was incomplete:

    git tag -d v0.9.0\ngit push origin :refs/tags/v0.9.0\n
    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/release/#ci-build-fails-after-tag-push","level":3,"title":"CI build fails after tag push","text":"

    The tag is already published. Fix the issue, bump to a patch version (e.g. 0.9.1), and release again. Do not force-push tags that others may have already fetched.

    ","path":["Operations","Cutting a Release"],"tags":[]},{"location":"operations/upgrading/","level":1,"title":"Upgrade","text":"","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#upgrade","level":2,"title":"Upgrade","text":"

    New versions of ctx may ship updated permissions, CLAUDE.md directives, or plugin hooks and skills.

    Claude Code User?

    The marketplace can update skills, hooks, and prompts independently: /plugin → select ctx → Update now (or enable auto-update).

    The ctx binary is separate: rebuild from source or download a new release when one is available, then run ctx init --force --merge. Knowledge files are preserved automatically.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#tldr","level":2,"title":"TL:DR","text":"
    # Plugin users (Claude Code)\n# /plugin → select ctx → Update now\n# Then update the binary and reinitialize:\nctx init --force --merge\n\n# From-source / manual users\n# install new ctx binary, then:\nctx init --force --merge\n# /plugin → select ctx → Update now   (if using Claude Code)\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#what-changes-between-versions","level":2,"title":"What Changes Between Versions","text":"

    ctx init generates two categories of files:

    Category Examples Changes between versions? Infrastructure .claude/settings.local.json (permissions), ctx-managed sections in CLAUDE.md and PROMPT.md, ctx plugin (hooks + skills) Yes Knowledge .context/TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md, ARCHITECTURE.md, GLOSSARY.md, CONSTITUTION.md, AGENT_PLAYBOOK.md No: this is your data

    Infrastructure is regenerated by ctx init and plugin updates. Knowledge files are yours and should never be overwritten.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#upgrade-steps","level":2,"title":"Upgrade Steps","text":"","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#1-install-the-new-version","level":3,"title":"1. Install the New Version","text":"

    Build from source or download the binary:

    cd /path/to/ctx-source\ngit pull\nmake build\nsudo make install\nctx --version   # verify\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#2-reinitialize","level":3,"title":"2. Reinitialize","text":"
    ctx init --force --merge\n
    • --force regenerates infrastructure files (permissions, ctx-managed sections in CLAUDE.md and PROMPT.md).
    • --merge preserves your content outside ctx markers.

    Knowledge files (.context/TASKS.md, DECISIONS.md, etc.) are preserved automatically: ctx init only overwrites infrastructure, never your data.

    Encryption key: The encryption key lives at ~/.ctx/.ctx.key (outside the project). Reinit does not affect it. If you have a legacy key at .context/.ctx.key or ~/.local/ctx/keys/, copy it manually (see Syncing Scratchpad Notes).

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#3-update-the-ctx-plugin","level":3,"title":"3. Update the ctx Plugin","text":"

    If you use Claude Code, update the plugin to get new hooks and skills:

    1. Open /plugin in Claude Code.
    2. Select ctx.
    3. Click Update now.

    Or enable auto-update so the plugin stays current without manual steps.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#4-review-custom-settings","level":3,"title":"4. Review Custom Settings","text":"

    If you added custom permissions to .claude/settings.local.json beyond what ctx init provides, diff and merge:

    diff .claude.bak/settings.local.json .claude/settings.local.json\n

    Manually add back any custom entries that the new init dropped.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#5-verify","level":3,"title":"5. Verify","text":"
    ctx status          # context files intact\nctx drift           # no broken references\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#6-clean-up","level":3,"title":"6. Clean Up","text":"

    If you made manual backups, remove them once satisfied:

    rm -rf .context.bak .claude.bak CLAUDE.md.bak PROMPT.md.bak\n
    ","path":["Operations","Upgrade"],"tags":[]},{"location":"operations/upgrading/#what-if-i-skip-the-upgrade","level":2,"title":"What If I Skip the Upgrade?","text":"

    The old binary still works with your existing .context/ files. But you may miss:

    • New plugin hooks that enforce better practices or catch mistakes;
    • Updated skill prompts that produce better results;
    • New .gitignore entries for directories added in newer versions;
    • Bug fixes in the CLI itself.

    The plugin and the binary can be updated independently. You can update the plugin (for new hooks/skills) even if you stay on an older binary, and vice versa.

    Context files are plain Markdown: They never break between versions.

    The surrounding infrastructure is what evolves.

    ","path":["Operations","Upgrade"],"tags":[]},{"location":"recipes/","level":1,"title":"Recipes","text":"

    Workflow recipes combining ctx commands and skills to solve specific problems.

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#getting-started","level":2,"title":"Getting Started","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#guide-your-agent","level":3,"title":"Guide Your Agent","text":"

    How commands, skills, and conversational patterns work together. Train your agent to be proactive through ask, guide, reinforce.

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#setup-across-ai-tools","level":3,"title":"Setup Across AI Tools","text":"

    Initialize ctx and configure hooks for Claude Code, Cursor, Aider, Copilot, or Windsurf. Includes shell completion, watch mode for non-native tools, and verification.

    Uses: ctx init, ctx hook, ctx agent, ctx completion, ctx watch

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#keeping-context-in-a-separate-repo","level":3,"title":"Keeping Context in a Separate Repo","text":"

    Store context files outside the project tree: in a private repo, shared directory, or anywhere else. Useful for open source projects with private context or multi-repo setups.

    Uses: ctx init, --context-dir, --allow-outside-cwd, .ctxrc, /ctx-status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#sessions","level":2,"title":"Sessions","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#the-complete-session","level":3,"title":"The Complete Session","text":"

    Walk through a full ctx session from start to finish:

    • Loading context,
    • Picking what to work on,
    • Committing with context,
    • Capturing, reflecting, and saving a snapshot.

    Uses: ctx status, ctx agent, /ctx-remember, /ctx-next, /ctx-commit, /ctx-reflect

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#session-ceremonies","level":3,"title":"Session Ceremonies","text":"

    The two bookend rituals for every session: /ctx-remember at the start to load and confirm context, /ctx-wrap-up at the end to review the session and persist learnings, decisions, and tasks.

    Uses: /ctx-remember, /ctx-wrap-up, /ctx-commit, ctx agent, ctx add

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#browsing-and-enriching-past-sessions","level":3,"title":"Browsing and Enriching Past Sessions","text":"

    Export your AI session history to a browsable journal site. Enrich entries with metadata and search across months of work.

    Uses: ctx recall list/show/export, ctx journal site, ctx journal obsidian, ctx serve, /ctx-recall, /ctx-journal-normalize, /ctx-journal-enrich, /ctx-journal-enrich-all

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#session-reminders","level":3,"title":"Session Reminders","text":"

    Leave a message for your next session. Reminders surface automatically at session start and repeat until dismissed. Date-gate reminders to surface only after a specific date.

    Uses: ctx remind, ctx remind list, ctx remind dismiss, ctx system check-reminders

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#reviewing-session-changes","level":3,"title":"Reviewing Session Changes","text":"

    See what moved since your last session: context file edits, code commits, directories touched. Auto-detects session boundaries from state markers.

    Uses: ctx change, ctx agent, ctx status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#pausing-context-hooks","level":3,"title":"Pausing Context Hooks","text":"

    Silence all nudge hooks for a quick task that doesn't need ceremony overhead. Session-scoped: Other sessions are unaffected. Security hooks still fire.

    Uses: ctx pause, ctx resume, /ctx-pause, /ctx-resume

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#knowledge-tasks","level":2,"title":"Knowledge & Tasks","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#persisting-decisions-learnings-and-conventions","level":3,"title":"Persisting Decisions, Learnings, and Conventions","text":"

    Record architectural decisions with rationale, capture gotchas and lessons learned, and codify conventions so they survive across sessions and team members.

    Uses: ctx add decision, ctx add learning, ctx add convention, ctx decision reindex, ctx learning reindex, /ctx-add-decision, /ctx-add-learning, /ctx-add-convention, /ctx-reflect

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#tracking-work-across-sessions","level":3,"title":"Tracking Work Across Sessions","text":"

    Add, prioritize, complete, snapshot, and archive tasks. Keep TASKS.md focused as your project evolves across dozens of sessions.

    Uses: ctx add task, ctx task complete, ctx task archive, ctx task snapshot, /ctx-add-task, /ctx-archive, /ctx-next

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#using-the-scratchpad","level":3,"title":"Using the Scratchpad","text":"

    Use the encrypted scratchpad for quick notes, working memory, and sensitive values during AI sessions. Natural language in, encrypted storage out.

    Uses: ctx pad, /ctx-pad, ctx pad show, ctx pad edit

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#syncing-scratchpad-notes-across-machines","level":3,"title":"Syncing Scratchpad Notes Across Machines","text":"

    Distribute your scratchpad encryption key, push and pull encrypted notes via git, and resolve merge conflicts when two machines edit simultaneously.

    Uses: ctx init, ctx pad, ctx pad resolve, scp

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#bridging-claude-code-auto-memory","level":3,"title":"Bridging Claude Code Auto Memory","text":"

    Mirror Claude Code's auto memory (MEMORY.md) into .context/ for version control, portability, and drift detection. Import entries into structured context files with heuristic classification.

    Uses: ctx memory sync, ctx memory status, ctx memory diff, ctx memory import, ctx memory publish, ctx system check-memory-drift

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#hooks-notifications","level":2,"title":"Hooks & Notifications","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#hook-output-patterns","level":3,"title":"Hook Output Patterns","text":"

    Choose the right output pattern for your Claude Code hooks: VERBATIM relay for user-facing reminders, hard gates for invariants, agent directives for nudges, and five more patterns across the spectrum.

    Uses: ctx plugin hooks, settings.local.json

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#customizing-hook-messages","level":3,"title":"Customizing Hook Messages","text":"

    Customize what hooks say without changing what they do. Override the QA gate for Python (pytest instead of make lint), silence noisy ceremony nudges, or tailor post-commit instructions for your stack.

    Uses: ctx system message list, ctx system message show, ctx system message edit, ctx system message reset

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#hook-sequence-diagrams","level":3,"title":"Hook Sequence Diagrams","text":"

    Mermaid sequence diagrams for every system hook: entry conditions, state reads, output, throttling, and exit points. Includes throttling summary table and state file reference.

    Uses: All ctx system hooks

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#auditing-system-hooks","level":3,"title":"Auditing System Hooks","text":"

    The 12 system hooks that run invisibly during every session: what each one does, why it exists, and how to verify they're actually firing. Covers webhook-based audit trails, log inspection, and detecting silent hook failures.

    Uses: ctx system, ctx notify, .context/logs/, .ctxrc notify.events

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#webhook-notifications","level":3,"title":"Webhook Notifications","text":"

    Get push notifications when loops complete, hooks fire, or agents hit milestones. Webhook URL is encrypted: never stored in plaintext. Works with IFTTT, Slack, Discord, ntfy.sh, or any HTTP endpoint.

    Uses: ctx notify setup, ctx notify test, ctx notify --event, .ctxrc notify.events

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#maintenance","level":2,"title":"Maintenance","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#detecting-and-fixing-drift","level":3,"title":"Detecting and Fixing Drift","text":"

    Keep context files accurate by detecting structural drift (stale paths, missing files, stale file ages) and task staleness.

    Uses: ctx drift, ctx sync, ctx compact, ctx status, /ctx-drift, /ctx-status, /ctx-prompt-audit

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#state-directory-maintenance","level":3,"title":"State Directory Maintenance","text":"

    Clean up session tombstones from .context/state/. Prune old per-session files, identify stale global markers, and keep the state directory lean.

    Uses: ctx system prune

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#troubleshooting","level":3,"title":"Troubleshooting","text":"

    Diagnose hook failures, noisy nudges, stale context, and configuration issues. Start with ctx doctor for a structural health check, then use /ctx-doctor for agent-driven analysis of event patterns.

    Uses: ctx doctor, ctx system events, /ctx-doctor

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#claude-code-permission-hygiene","level":3,"title":"Claude Code Permission Hygiene","text":"

    Keep .claude/settings.local.json clean: recommended safe defaults, what to never pre-approve, and a maintenance workflow for cleaning up session debris.

    Uses: ctx init, /ctx-drift, /ctx-sanitize-permissions, ctx permission snapshot, ctx permission restore

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#permission-snapshots","level":3,"title":"Permission Snapshots","text":"

    Capture a known-good permission baseline as a golden image, then restore at session start to automatically drop session-accumulated permissions.

    Uses: ctx permission snapshot, ctx permission restore, /ctx-sanitize-permissions

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#turning-activity-into-content","level":3,"title":"Turning Activity into Content","text":"

    Generate blog posts from project activity, write changelog posts from commit ranges, and publish a browsable journal site from your session history.

    The output is generic Markdown, but the skills are tuned for the ctx-style blog artifacts you see on this website.

    Uses: ctx journal site, ctx journal obsidian, ctx serve, ctx recall export, /ctx-blog, /ctx-blog-changelog, /ctx-journal-enrich, /ctx-journal-normalize

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#importing-claude-code-plans","level":3,"title":"Importing Claude Code Plans","text":"

    Import Claude Code plan files (~/.claude/plans/*.md) into specs/ as permanent project specs. Filter by date, select interactively, and optionally create tasks referencing each imported spec.

    Uses: /ctx-import-plans, /ctx-add-task

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#design-before-coding","level":3,"title":"Design Before Coding","text":"

    Front-load design with a four-skill chain: brainstorm the approach, spec the design, task the work, implement step-by-step. Each step produces an artifact that feeds the next.

    Uses: /ctx-brainstorm, /ctx-spec, /ctx-add-task, /ctx-implement, /ctx-add-decision

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#agents-automation","level":2,"title":"Agents & Automation","text":"","path":["Recipes"],"tags":[]},{"location":"recipes/#building-project-skills","level":3,"title":"Building Project Skills","text":"

    Encode repeating workflows into reusable skills the agent loads automatically. Covers the full cycle: identify a pattern, create the skill, test with realistic prompts, and iterate until it triggers correctly.

    Uses: /ctx-skill-creator, ctx init

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#running-an-unattended-ai-agent","level":3,"title":"Running an Unattended AI Agent","text":"

    Set up a loop where an AI agent works through tasks overnight without you at the keyboard, using ctx for persistent memory between iterations.

    This recipe shows how ctx supports long-running agent loops without losing context or intent.

    Uses: ctx init --ralph, ctx loop, ctx watch, ctx load, /ctx-loop, /ctx-implement

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#when-to-use-a-team-of-agents","level":3,"title":"When to Use a Team of Agents","text":"

    Decision framework for choosing between a single agent, parallel worktrees, and a full agent team.

    This recipe covers the file overlap test, when teams make things worse, and what ctx provides at each level.

    Uses: /ctx-worktree, /ctx-next, ctx status

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#parallel-agent-development-with-git-worktrees","level":3,"title":"Parallel Agent Development with Git Worktrees","text":"

    Split a large backlog across 3-4 agents using git worktrees, each on its own branch and working directory. Group tasks by file overlap, work in parallel, merge back.

    Uses: /ctx-worktree, /ctx-next, git worktree, git merge

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#generating-dependency-graphs","level":3,"title":"Generating Dependency Graphs","text":"

    Map your project's internal and external dependency structure. Auto-detects Go, Node.js, Python, and Rust. Output as Mermaid, table, or JSON.

    Uses: ctx dep, ctx drift

    ","path":["Recipes"],"tags":[]},{"location":"recipes/#reusable-prompt-templates","level":3,"title":"Reusable Prompt Templates","text":"

    Store and reuse prompt templates in .context/prompts/ for repeating tasks. Manage templates via CLI, reference them in skills and loop scripts.

    Uses: ctx prompt, ctx prompt list, ctx prompt show

    ","path":["Recipes"],"tags":[]},{"location":"recipes/autonomous-loops/","level":1,"title":"Running an Unattended AI Agent","text":"","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-problem","level":2,"title":"The Problem","text":"

    You have a project with a clear list of tasks, and you want an AI agent to work through them autonomously: overnight, unattended, without you sitting at the keyboard.

    Each iteration needs to remember what the previous one did, mark tasks as completed, and know when to stop.

    Without persistent memory, every iteration starts fresh and the loop collapses. With ctx, each iteration can pick up where the last one left off, but only if the agent persists its context as part of the work.

    Unattended operation works because the agent treats context persistence as a first-class deliverable, not an afterthought.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#tldr","level":2,"title":"TL;DR","text":"
    ctx init --ralph                            # 1. init for unattended mode\n# Edit TASKS.md with phased work items\nctx loop --tool claude --max-iterations 10  # 2. generate loop.sh\n./loop.sh 2>&1 | tee /tmp/loop.log &        # 3. run the loop\nctx watch --log /tmp/loop.log               # 4. process context updates\n# Next morning:\nctx status && ctx load                      # 5. review the results\n

    Read on for permissions, isolation, and completion signals.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init --ralph Command Initialize project for unattended operation (no human in the loop) ctx loop Command Generate the loop shell script ctx watch Command Monitor AI output and persist context updates ctx load Command Display assembled context (for debugging) /ctx-loop Skill Generate loop script from inside Claude Code /ctx-implement Skill Execute a plan step-by-step with verification","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-1-initialize-for-unattended-operation","level":3,"title":"Step 1: Initialize for Unattended Operation","text":"

    Start by creating a .context/ directory configured so the agent can work without human input. The --ralph flag sets up PROMPT.md so the agent makes reasonable choices instead of asking clarifying questions.

    ctx init --ralph\n

    This creates .context/ with the template files, a PROMPT.md configured for autonomous iteration, and seeds Claude Code permissions in .claude/settings.local.json. Install the ctx plugin for hooks and skills.

    Without --ralph, the agent will often pause when requirements are unclear. For unattended runs, you want it to choose a default and document the trade-off in DECISIONS.md instead.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-2-populate-tasksmd-with-phased-work","level":3,"title":"Step 2: Populate TASKS.md with Phased Work","text":"

    Open .context/TASKS.md and organize your work into phases. The agent works through these systematically, top to bottom, using priority tags to break ties.

    # Tasks\n\n## Phase 1: Foundation\n\n- [ ] Set up project structure and build system `#priority:high`\n- [ ] Configure testing framework `#priority:high`\n- [ ] Create CI pipeline `#priority:medium`\n\n## Phase 2: Core Features\n\n- [ ] Implement user registration `#priority:high`\n- [ ] Add email verification `#priority:high`\n- [ ] Create password reset flow `#priority:medium`\n\n## Phase 3: Hardening\n\n- [ ] Add rate limiting to API endpoints `#priority:medium`\n- [ ] Improve error messages `#priority:low`\n- [ ] Write integration tests `#priority:medium`\n

    Phased organization matters because it gives the agent natural boundaries. Phase 1 tasks should be completable without Phase 2 code existing yet.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-3-configure-promptmd","level":3,"title":"Step 3: Configure PROMPT.md","text":"

    The --ralph flag generates a PROMPT.md that instructs the agent to operate autonomously:

    1. Read .context/CONSTITUTION.md first (hard rules, never violated)
    2. Load context from .context/ files
    3. Pick one task per iteration
    4. Complete the task and update context files
    5. Commit changes (including .context/)
    6. Signal status with a completion signal

    You can customize PROMPT.md for your project. The critical parts are the one-task-per-iteration discipline, proactive context persistence, and completion signals at the end:

    ## Signal Status\n\nEnd your response with exactly ONE of:\n\n* `SYSTEM_CONVERGED`: All tasks in `TASKS.md` are complete (*this is the\n  signal the loop script detects by default*)\n* `SYSTEM_BLOCKED`: Cannot proceed, need human input (explain why)\n* (*no signal*): More work remains, continue to the next iteration\n\nNote: the loop script only checks for `SYSTEM_CONVERGED` by default.\n`SYSTEM_BLOCKED` is a convention for the human reviewing the log.\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-4-configure-permissions","level":3,"title":"Step 4: Configure Permissions","text":"

    An unattended agent needs permission to use tools without prompting. By default, Claude Code asks for confirmation on file writes, bash commands, and other operations, which stops the loop and waits for a human who is not there.

    There are two approaches.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#option-a-explicit-allowlist-recommended","level":4,"title":"Option A: Explicit Allowlist (Recommended)","text":"

    Grant only the permissions the agent needs. In .claude/settings.local.json:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(make:*)\",\n      \"Bash(go:*)\",\n      \"Bash(git:*)\",\n      \"Bash(ctx:*)\",\n      \"Read\",\n      \"Write\",\n      \"Edit\"\n    ]\n  }\n}\n

    Adjust the Bash patterns for your project's toolchain. The agent can run make, go, git, and ctx commands but cannot run arbitrary shell commands.

    This is recommended even in sandboxed environments because it limits blast radius.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#option-b-skip-all-permission-checks","level":4,"title":"Option B: Skip All Permission Checks","text":"

    Claude Code supports a --dangerously-skip-permissions flag that disables all permission prompts:

    claude --dangerously-skip-permissions -p \"$(cat .context/PROMPT.md)\"\n

    This Flag Means What It Says

    With --dangerously-skip-permissions, the agent can execute any shell command, write to any file, and make network requests without confirmation.

    Only use this on a sandboxed machine: ideally a virtual machine with no access to host credentials, no SSH keys, and no access to production systems.

    If you would not give an untrusted intern sudo on this machine, do not use this flag.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#enforce-isolation-at-the-os-level","level":4,"title":"Enforce Isolation at the OS Level","text":"

    The only controls an agent cannot override are the ones enforced by the operating system, the container runtime, or the hypervisor.

    Do Not Skip This Section

    This is not optional hardening:

    An unattended agent with unrestricted OS access is an unattended shell with unrestricted OS access.

    The allowlist above is a strong first layer, but do not rely on a single runtime boundary.

    For unattended runs, enforce isolation at the infrastructure level:

    Layer What to enforce User account Run the agent as a dedicated unprivileged user with no sudo access and no membership in privileged groups (docker, wheel, adm). Filesystem Restrict the project directory via POSIX permissions or ACLs. The agent should have no access to other users' files or system directories. Container Run inside a Docker/Podman sandbox. Mount only the project directory. Drop capabilities (--cap-drop=ALL). Disable network if not needed (--network=none). Never mount the Docker socket and do not run privileged containers. Prefer rootless containers. Virtual machine Prefer a dedicated VM with no shared folders, no host passthrough, and no keys to other machines. Network If the agent does not need the internet, disable outbound access entirely. If it does, restrict to specific domains via firewall rules. Resource limits Apply CPU, memory, and disk limits (cgroups/container limits). A runaway loop should not fill disk or consume all RAM. Self-modification Make instruction files read-only. CLAUDE.md, .claude/settings.local.json, and .context/CONSTITUTION.md should not be writable by the agent user. If using project-local hooks, protect those too.

    A minimal Docker setup for overnight runs:

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh 2>&1 | tee /tmp/loop.log\n

    Defense in Depth

    Use multiple layers together: OS-level isolation (the boundary the agent cannot cross), a permission allowlist (what Claude Code will do within that boundary), and CONSTITUTION.md (a soft nudge for the common case).

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-5-generate-the-loop-script","level":3,"title":"Step 5: Generate the Loop Script","text":"

    Use ctx loop to generate a loop.sh tailored to your AI tool:

    # Generate for Claude Code with a 10-iteration cap\nctx loop --tool claude --max-iterations 10\n\n# Generate for Aider\nctx loop --tool aider --max-iterations 10\n\n# Custom prompt file and output filename (default prompt is PROMPT.md in project root)\nctx loop --tool claude --prompt my-prompt.md --output my-loop.sh\n

    The generated script reads PROMPT.md, runs the tool, checks for completion signals, and loops until done or the cap is reached.

    You can also use the /ctx-loop skill from inside Claude Code.

    A Shell Loop Is the Best Practice

    The shell loop approach spawns a fresh AI process each iteration, so the only state that carries between iterations is what lives in .context/ and git.

    Claude Code's built-in /loop runs iterations within the same session, which can allow context window state to leak between iterations. This can be convenient for short runs, but it is less reliable for unattended loops.

    See Shell Loop vs Built-in Loop for details.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-6-run-with-watch-mode","level":3,"title":"Step 6: Run with Watch Mode","text":"

    Open two terminals. In the first, run the loop. In the second, run ctx watch to process context updates from the AI output.

    # Terminal 1: Run the loop\n./loop.sh 2>&1 | tee /tmp/loop.log\n\n# Terminal 2: Watch for context updates\nctx watch --log /tmp/loop.log\n

    The watch command parses XML context-update commands from the AI output and applies them:

    <context-update type=\"complete\">user registration</context-update>\n<context-update type=\"learning\"\n  context=\"Setting up user registration\"\n  lesson=\"Email verification needs SMTP configured\"\n  application=\"Add SMTP setup to deployment checklist\"\n>SMTP Requirement</context-update>\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-7-completion-signals-end-the-loop","level":3,"title":"Step 7: Completion Signals End the Loop","text":"

    The generated script checks for one completion signal per run. By default this is SYSTEM_CONVERGED. You can change it with the --completion flag:

    ctx loop --tool claude --completion BOOTSTRAP_COMPLETE --max-iterations 5\n

    The following signals are conventions used in PROMPT.md:

    Signal Convention How the script handles it SYSTEM_CONVERGED All tasks in TASKS.md are done Detected by default (--completion default value) SYSTEM_BLOCKED Agent cannot proceed Only detected if you set --completion to this BOOTSTRAP_COMPLETE Initial scaffolding done Only detected if you set --completion to this

    The script uses grep -q on the agent's output, so any string works as a signal. If you need to detect multiple signals in one run, edit the generated loop.sh to add additional grep checks.

    When you return in the morning, check the log and the context files:

    tail -100 /tmp/loop.log\nctx status\nctx load\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#step-8-use-ctx-implement-for-plan-execution","level":3,"title":"Step 8: Use /ctx-implement for Plan Execution","text":"

    Within each iteration, the agent can use /ctx-implement to execute multi-step plans with verification between steps. This is useful for complex tasks that touch multiple files.

    The skill breaks a plan into atomic, verifiable steps:

    Step 1/6: Create user model .................. OK\nStep 2/6: Add database migration ............. OK\nStep 3/6: Implement registration handler ..... OK\nStep 4/6: Write unit tests ................... OK\nStep 5/6: Run test suite ..................... FAIL\n  -> Fixed: missing test dependency\n  -> Re-verify ............................... OK\nStep 6/6: Update TASKS.md .................... OK\n

    Each step is verified (build, test, syntax check) before moving to the next.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A typical overnight run:

    ctx init --ralph\n# Edit TASKS.md and PROMPT.md\n\nctx loop --tool claude --max-iterations 20\n\n./loop.sh 2>&1 | tee /tmp/loop.log &\nctx watch --log /tmp/loop.log\n\n# Next morning:\nctx status\nctx load\n
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#why-autonomous-loops-work-proactive-context-persistence","level":2,"title":"Why Autonomous Loops Work: Proactive Context Persistence","text":"

    The autonomous loop pattern works because the agent persists context as part of the job.

    Without proactive persistence, the loop degrades into disconnected iterations that repeat work, contradict decisions, and lose track of progress. The agent cannot rely on a human to prompt it. It must treat context updates as part of every task, not as a separate step.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-agent-playbook-self-check-drives-autonomy","level":3,"title":"The Agent Playbook Self-Check Drives Autonomy","text":"

    The Agent Playbook defines a self-check prompt the agent applies continuously:

    \"If this session ended right now, would the next session know what happened?\"\n

    In interactive sessions, a human might remind the agent to save context. When the agent runs unattended, nobody is there to remind it.

    The self-check becomes the trigger: after meaningful work, the agent evaluates whether the context files reflect reality and updates them immediately if they do not.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#what-the-agent-does-proactively-between-iterations","level":3,"title":"What the Agent Does Proactively Between Iterations","text":"

    At milestones within an iteration, the agent persists without waiting for instructions:

    Milestone What the agent does proactively Completes a task Marks it [x] in TASKS.md with #done timestamp Discovers a gotcha Adds it to LEARNINGS.md Makes a design choice Records it in DECISIONS.md with rationale Identifies follow-up work Creates new tasks in TASKS.md with #added timestamp Hits an unexpected failure Documents the root cause before moving on","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#example-what-proactive-persistence-looks-like","level":3,"title":"Example: What Proactive Persistence Looks Like","text":"

    Here is what the agent does during a single iteration beyond writing code:

    Iteration 4:\n  1. Read TASKS.md -> pick \"Add email verification\" (#priority:high)\n  2. Add #started:2026-01-25-030012 to the task\n  3. Implement the feature (code, tests, docs if needed)\n  4. Tests pass -> mark task [x], add #done:2026-01-25-031544\n  5. Add learning: \"SMTP config must be set before verification handler registers. Order matters in init().\"\n  6. Add decision: \"Use token-based verification links (not codes) because links work better in automated tests.\"\n  7. Create follow-up task: \"Add rate limiting to verification endpoint\" #added:...\n  8. Commit all changes including `.context/`\n  9. No signal emitted -> loop continues to iteration 5\n

    Steps 2, 4, 5, 6, and 7 are proactive context persistence:

    The agent was not asked to do any of them.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#context-persistence-at-milestones","level":3,"title":"Context Persistence at Milestones","text":"

    For long autonomous runs, the agent persists context at natural boundaries, often at phase transitions or after completing a cluster of related tasks. It updates TASKS.md, DECISIONS.md, and LEARNINGS.md as it goes.

    If the loop crashes at 4 AM, the context files tell you exactly where to resume. You can also use ctx recall list to review the session transcripts.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#the-persistence-contract","level":3,"title":"The Persistence Contract","text":"

    The autonomous loop has an implicit contract:

    1. Every iteration reads context: TASKS.md, DECISIONS.md, LEARNINGS.md
    2. Every iteration writes context: task updates, new learnings, decisions
    3. Every commit includes .context/ so the next iteration sees changes
    4. Context stays current: if the loop stopped right now, nothing important is lost

    Break any part of this contract and the loop degrades.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#tips","level":2,"title":"Tips","text":"

    Markdown Is Not Enforcement

    Your real guardrails are permissions and isolation, not Markdown. CONSTITUTION.md can nudge the agent, but it is probabilistic.

    The permission allowlist and OS isolation are deterministic:

    For unattended runs, trust the sandbox and the allowlist, not the prose.

    • Start with a small iteration cap. Use --max-iterations 5 on your first run.
    • Keep tasks atomic. Each task should be completable in a single iteration.
    • Check signal discipline. If the loop runs forever, the agent is not emitting SYSTEM_CONVERGED or SYSTEM_BLOCKED. Make the signal requirement explicit in PROMPT.md.
    • Commit after context updates. Finish code, update .context/, commit including .context/, then signal.
    • Set up webhook notifications to get notified when the loop completes, hits max iterations, or when hooks fire nudges. The generated loop script includes ctx notify calls automatically.
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#next-up","level":2,"title":"Next Up","text":"

    When to Use a Team of Agents →: Decision framework for choosing between a single agent, parallel worktrees, and a full agent team.

    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/autonomous-loops/#see-also","level":2,"title":"See Also","text":"
    • Autonomous Loops: loop pattern, PROMPT.md templates, troubleshooting
    • CLI Reference: ctx loop: flags and options
    • CLI Reference: ctx watch: watch mode details
    • CLI Reference: ctx init: init flags including --ralph
    • The Complete Session: interactive workflow
    • Tracking Work Across Sessions: structuring TASKS.md
    ","path":["Recipes","Agents and Automation","Running an Unattended AI Agent"],"tags":[]},{"location":"recipes/building-skills/","level":1,"title":"Building Project Skills","text":"","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#the-problem","level":2,"title":"The Problem","text":"

    You have workflows your agent needs to repeat across sessions: a deploy checklist, a review protocol, a release process. Each time, you re-explain the steps. The agent gets it mostly right but forgets edge cases you corrected last time.

    Skills solve this by encoding domain knowledge into a reusable document the agent loads automatically when triggered. A skill is not code - it is a structured prompt that captures what took you sessions to learn.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-skill-creator\n

    The skill-creator walks you through: identify a repeating workflow, draft a skill, test with realistic prompts, iterate until it triggers correctly and produces good output.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-skill-creator Skill Interactive skill creation and improvement workflow ctx init Command Deploys template skills to .claude/skills/ on first setup","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-1-identify-a-repeating-pattern","level":3,"title":"Step 1: Identify a Repeating Pattern","text":"

    Good skill candidates:

    • Checklists you repeat: deploy steps, release prep, code review
    • Decisions the agent gets wrong: if you keep correcting the same behavior, encode the correction
    • Multi-step workflows: anything with a sequence of commands and conditional branches
    • Domain knowledge: project-specific terminology, architecture constraints, or conventions the agent cannot infer from code alone

    Not good candidates: one-off instructions, things the platform already handles (file editing, git operations), or tasks too narrow to reuse.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-2-create-the-skill","level":3,"title":"Step 2: Create the Skill","text":"

    Invoke the skill-creator:

    You: \"I want a skill for our deploy process\"\n\nAgent: [Asks about the workflow: what steps, what tools,\n        what edge cases, what the output should look like]\n

    Or capture a workflow you just did:

    You: \"Turn what we just did into a skill\"\n\nAgent: [Extracts the steps from conversation history,\n        confirms understanding, drafts the skill]\n

    The skill-creator produces a SKILL.md file in .claude/skills/your-skill/.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-3-test-with-realistic-prompts","level":3,"title":"Step 3: Test with Realistic Prompts","text":"

    The skill-creator proposes 2-3 test prompts - the kind of thing a real user would say. It runs each one and shows the result alongside a baseline (same prompt without the skill) so you can compare.

    Agent: \"Here are test prompts I'd try:\n        1. 'Deploy to staging'\n        2. 'Ship the hotfix'\n        3. 'Run the release checklist'\n        Want to adjust these?\"\n
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-4-iterate-on-the-description","level":3,"title":"Step 4: Iterate on the Description","text":"

    The description field in frontmatter determines when a skill triggers. Claude tends to undertrigger - descriptions need to be specific and slightly \"pushy\":

    # Weak - too vague, will undertrigger\ndescription: \"Use for deployments\"\n\n# Strong - covers situations and synonyms\ndescription: >-\n  Use when deploying to staging or production, running the release\n  checklist, or when the user says 'ship it', 'deploy this', or\n  'push to prod'. Also use after merging to main when a deploy\n  is expected.\n

    The skill-creator helps you tune this iteratively.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#step-5-deploy-as-template-optional","level":3,"title":"Step 5: Deploy as Template (Optional)","text":"

    If the skill should be available to all projects (not just this one), place it in internal/assets/claude/skills/ so ctx init deploys it to new projects automatically.

    Most project-specific skills stay in .claude/skills/ and travel with the repo.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#skill-anatomy","level":2,"title":"Skill Anatomy","text":"
    my-skill/\n  SKILL.md         # Required: frontmatter + instructions (<500 lines)\n  scripts/         # Optional: deterministic code the skill can execute\n  references/      # Optional: detail loaded on demand (not always)\n  assets/          # Optional: output templates, not loaded into context\n

    Key sections in SKILL.md:

    Section Purpose Required? Frontmatter Name, description (trigger) Yes When to Use Positive triggers Yes When NOT to Use Prevents false activations Yes Process Steps and commands Yes Examples Good/bad output pairs Recommended Quality Checklist Verify before reporting completion For complex skills","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#tips","level":2,"title":"Tips","text":"
    • Description is everything. A great skill with a vague description never fires. Spend time on trigger coverage - synonyms, concrete situations, edge cases.
    • Stay under 500 lines. If your skill is growing past this, move detail into references/ files and point to them from SKILL.md.
    • Do not duplicate the platform. If the agent already knows how to do something (edit files, run git commands), do not restate it. Tag paragraphs as Expert/Activation/Redundant and delete Redundant ones.
    • Explain why, not just what. \"Sort by date because users want recent results first\" beats \"ALWAYS sort by date.\" The agent generalizes from reasoning better than from rigid rules.
    • Test negative triggers. Make sure the skill does not fire on unrelated prompts. A skill that activates too broadly becomes noise.
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#next-up","level":2,"title":"Next Up","text":"

    Parallel Agent Development with Git Worktrees ->: Split work across multiple agents using git worktrees.

    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/building-skills/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: full listing of all bundled and project-local skills
    • Guide Your Agent: how commands, skills, and conversational patterns work together
    • Design Before Coding: the four-skill chain for front-loading design work
    ","path":["Recipes","Agents and Automation","Building Project Skills"],"tags":[]},{"location":"recipes/claude-code-permissions/","level":1,"title":"Claude Code Permission Hygiene","text":"","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code's .claude/settings.local.json controls what the agent can do without asking. Over time, this file accumulates one-off permissions from individual sessions: Exact commands with hardcoded paths, duplicate entries, and stale skill references.

    A noisy \"allowlist\" makes it harder to spot dangerous permissions and increases the surface area for unintended behavior.

    Since settings.local.json is .gitignored, it drifts independently of your codebase. There is no PR review, no CI check: just whatever you clicked \"Allow\" on.

    This recipe shows what a well-maintained permission file looks like and how to keep it clean.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                            # seeds safe defaults\n/ctx-drift                          # detects missing/stale permissions\n/ctx-sanitize-permissions               # audits for dangerous patterns\n

    See Recommended Defaults for the full list.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx init Populates default ctx permissions /ctx-drift Detects missing or stale permission entries /ctx-sanitize-permissions Audits for dangerous patterns (security-focused)","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#recommended-defaults","level":2,"title":"Recommended Defaults","text":"

    After running ctx init, your settings.local.json will have the ctx defaults pre-populated. Here is an opinionated safe starting point for a Go project using ctx:

    {\n  \"permissions\": {\n    \"allow\": [\n      \"Bash(/tmp/ctx-*:*)\",\n      \"Bash(CGO_ENABLED=0 go build:*)\",\n      \"Bash(CGO_ENABLED=0 go test:*)\",\n      \"Bash(ctx:*)\",\n      \"Bash(git add:*)\",\n      \"Bash(git branch:*)\",\n      \"Bash(git check-ignore:*)\",\n      \"Bash(git checkout:*)\",\n      \"Bash(git commit:*)\",\n      \"Bash(git diff:*)\",\n      \"Bash(git log:*)\",\n      \"Bash(git remote:*)\",\n      \"Bash(git restore:*)\",\n      \"Bash(git show:*)\",\n      \"Bash(git stash:*)\",\n      \"Bash(git status:*)\",\n      \"Bash(git tag:*)\",\n      \"Bash(go build:*)\",\n      \"Bash(go fmt:*)\",\n      \"Bash(go test:*)\",\n      \"Bash(go vet:*)\",\n      \"Bash(golangci-lint run:*)\",\n      \"Bash(grep:*)\",\n      \"Bash(ls:*)\",\n      \"Bash(make:*)\",\n      \"Skill(ctx-add-convention)\",\n      \"Skill(ctx-add-decision)\",\n      \"Skill(ctx-add-learning)\",\n      \"Skill(ctx-add-task)\",\n      \"Skill(ctx-agent)\",\n      \"Skill(ctx-archive)\",\n      \"Skill(ctx-blog)\",\n      \"Skill(ctx-blog-changelog)\",\n      \"Skill(absorb)\",\n      \"Skill(ctx-commit)\",\n      \"Skill(ctx-drift)\",\n      \"Skill(ctx-implement)\",\n      \"Skill(ctx-journal-enrich)\",\n      \"Skill(ctx-journal-enrich-all)\",\n      \"Skill(ctx-journal-normalize)\",\n      \"Skill(ctx-loop)\",\n      \"Skill(ctx-next)\",\n      \"Skill(ctx-pad)\",\n      \"Skill(ctx-prompt-audit)\",\n      \"Skill(ctx-recall)\",\n      \"Skill(ctx-reflect)\",\n      \"Skill(ctx-remember)\",\n      \"Skill(ctx-status)\",\n      \"Skill(ctx-worktree)\",\n      \"WebSearch\"\n    ],\n    \"deny\": [\n      \"Bash(sudo *)\",\n      \"Bash(git push *)\",\n      \"Bash(git push)\",\n      \"Bash(rm -rf /*)\",\n      \"Bash(rm -rf ~*)\",\n      \"Bash(curl *)\",\n      \"Bash(wget *)\",\n      \"Bash(chmod 777 *)\",\n      \"Read(**/.env)\",\n      \"Read(**/.env.*)\",\n      \"Read(**/*credentials*)\",\n      \"Read(**/*secret*)\",\n      \"Read(**/*.pem)\",\n      \"Read(**/*.key)\",\n      \"Edit(**/.env)\",\n      \"Edit(**/.env.*)\"\n    ]\n  }\n}\n

    This Is a Starting Point, Not a Mandate

    Your project may need more or fewer entries.

    The goal is intentional permissions: Every entry should be there because you decided it belongs, not because you clicked \"Allow\" once during debugging.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#design-principles","level":3,"title":"Design Principles","text":"

    Use wildcards for trusted binaries: If you trust the binary (your own project's CLI, make, go), a single wildcard like Bash(ctx:*) beats twenty subcommand entries. It reduces noise and means new subcommands work without re-prompting.

    Keep git commands granular: Unlike ctx or make, git has both safe commands (git log, git status) and destructive ones (git reset --hard, git clean -f). Listing safe commands individually prevents accidentally pre-approving dangerous ones.

    Pre-approve all ctx- skills: Skills shipped with ctx (Skill(ctx-*)) are safe to pre-approve. They are part of your project and you control their content. This prevents the agent from prompting on every skill invocation.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#default-deny-rules","level":3,"title":"Default Deny Rules","text":"

    ctx init automatically populates permissions.deny with rules that block dangerous operations. Deny rules are evaluated before allow rules: A denied pattern always prompts the user, even if it also matches an allow entry.

    The defaults block:

    Pattern Why Bash(sudo *) Cannot enter password; will hang Bash(git push *) Must be explicit user action Bash(rm -rf /*) etc. Recursive delete of system/home directories Bash(curl *) / wget Arbitrary network requests Bash(chmod 777 *) World-writable permissions Read/Edit(**/.env*) Secrets and credentials Read(**/*.pem, *.key) Private keys

    Read/Edit Deny Rules

    Read() and Edit() deny rules have known upstream enforcement issues (claude-code#6631,#24846).

    They are included as defense-in-depth and intent documentation.

    Blocked by default deny rules: no action needed, ctx init handles these:

    Pattern Risk Bash(git push:*) Must be explicit user action Bash(sudo:*) Privilege escalation Bash(rm -rf:*) Recursive delete with no confirmation Bash(curl:*) / Bash(wget:*) Arbitrary network requests

    Requires manual discipline: Never add these to allow:

    Pattern Risk Bash(git reset:*) Can discard uncommitted work Bash(git clean:*) Deletes untracked files Skill(ctx-sanitize-permissions) Edits this file: self-modification vector Skill(release) Runs the release pipeline: high impact","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#hooks-regex-safety-net","level":2,"title":"Hooks: Regex Safety Net","text":"

    Deny rules handle prefix-based blocking natively. Hooks complement them by catching patterns that require regex matching: Things deny rules can't express.

    The ctx plugin ships these blocking hooks:

    Hook What it blocks ctx system block-non-path-ctx Running ctx from wrong path

    Project-local hooks (not part of the plugin) catch regex edge cases:

    Hook What it blocks block-dangerous-commands.sh Mid-command sudo/git push (after &&), copies to bin dirs, absolute-path ctx

    Pre-Approved + Hook-Blocked = Silent Block

    If you pre-approve a command that a hook blocks, the user never sees the confirmation dialog. The agent gets a block response and must handle it, which is confusing.

    It's better not to pre-approve commands that hooks are designed to intercept.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#the-maintenance-workflow","level":2,"title":"The Maintenance Workflow","text":"","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#after-busy-sessions","level":3,"title":"After busy sessions","text":"

    Permissions accumulate fastest during debugging and exploration sessions. After a session where you clicked \"Allow\" many times:

    1. Open .claude/settings.local.json in your editor;
    2. Look for entries at the bottom of the allowlist (new entries append there);
    3. Delete anything that looks session-specific:
      • Exact commands with hardcoded paths,
      • Commands with literal string arguments,
      • Entries that duplicate an existing wildcard.

    See hack/runbooks/sanitize-permissions.md for a step-by-step runbook.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#periodically","level":3,"title":"Periodically","text":"

    Run /ctx-drift to catch permission drift:

    • Missing Bash(ctx:*) wildcard;
    • Missing Skill(ctx-*) entries for installed skills;
    • Stale Skill(ctx-*) entries for removed skills;
    • Granular Bash(ctx <subcommand>:*) entries that should be consolidated.

    Run /ctx-sanitize-permissions to catch security issues:

    • Hook bypass patterns
    • Destructive commands
    • Overly broad permissions
    • Injection vectors
    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#when-adding-new-skills","level":3,"title":"When adding new skills","text":"

    If you create a custom ctx-* skill, add its Skill() entry to the allowlist manually.

    ctx init only populates the default permissions: It won't pick up custom skills.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#golden-image-snapshots","level":3,"title":"Golden image snapshots","text":"

    If manual cleanup is too tedious, use a golden image to automate it:

    Snapshot a curated permission set, then restore at session start to automatically drop session-accumulated permissions. See the Permission Snapshots recipe for the full workflow.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#adapting-for-other-languages","level":2,"title":"Adapting for Other Languages","text":"

    The recommended defaults above are Go-specific. For other stacks, swap the build/test tooling:

    Node.js / TypeScript:

    \"Bash(npm run:*)\",\n\"Bash(npm test:*)\",\n\"Bash(npx:*)\",\n\"Bash(node:*)\"\n

    Python:

    \"Bash(pytest:*)\",\n\"Bash(python:*)\",\n\"Bash(pip show:*)\",\n\"Bash(ruff:*)\"\n

    Rust:

    \"Bash(cargo build:*)\",\n\"Bash(cargo test:*)\",\n\"Bash(cargo clippy:*)\",\n\"Bash(cargo fmt:*)\"\n

    The ctx, git, and skill entries remain the same across all stacks.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#next-up","level":2,"title":"Next Up","text":"

    Permission Snapshots →: Save and restore permission baselines for reproducible setups.

    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/claude-code-permissions/#see-also","level":2,"title":"See Also","text":"
    • Setting Up ctx Across AI Tools: full setup recipe including settings.local.json creation
    • Context Health: keeping .context/ files accurate
    • hack/runbooks/sanitize-permissions.md: manual cleanup runbook
    ","path":["Recipes","Maintenance","Claude Code Permission Hygiene"],"tags":[]},{"location":"recipes/context-health/","level":1,"title":"Detecting and Fixing Drift","text":"","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#the-problem","level":2,"title":"The Problem","text":"

    ctx files drift: you rename a package, delete a module, or finish a sprint, and suddenly ARCHITECTURE.md references paths that no longer exist, TASKS.md is 80 percent completed checkboxes, and CONVENTIONS.md describes patterns you stopped using two months ago.

    Stale context is worse than no context:

    An AI tool that trusts outdated references will hallucinate confidently.

    This recipe shows how to detect drift, fix it, and keep your .context/ directory lean and accurate.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#tldr","level":2,"title":"TL;DR","text":"
    ctx drift                      # detect problems\nctx drift --fix                # auto-fix the easy ones\nctx sync --dry-run && ctx sync # reconcile after refactors\nctx compact --archive          # archive old completed tasks\nctx status                     # verify\n

    Or just ask your agent: \"Is our context clean?\"

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx drift Command Detect stale paths, missing files, violations ctx drift --fix Command Auto-fix simple issues ctx sync Command Reconcile context with codebase structure ctx compact Command Archive completed tasks, clean up empty sections ctx status Command Quick health overview /ctx-drift Skill Structural plus semantic drift detection /ctx-architecture Skill Refresh ARCHITECTURE.md from actual codebase /ctx-status Skill In-session context summary /ctx-prompt-audit Skill Audit prompt quality and token efficiency","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#the-workflow","level":2,"title":"The Workflow","text":"

    The best way to maintain context health is conversational: Ask your agent, guide it, and let it detect problems, explain them, and fix them with your approval. CLI commands exist for CI pipelines, scripting, and fine-grained control.

    For day-to-day maintenance, talk to your agent.

    Your Questions Reinforce the Pattern

    Asking \"is our context clean?\" does two things:

    • It triggers a drift check right now
    • It reinforces the habit

    This is reinforcement, not enforcement.

    Do not wait for the agent to be proactive on its own:

    Guide your agent, especially in early sessions.

    Over time, you will ask less and the agent will start offering more.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-1-ask-your-agent","level":3,"title":"Step 1: Ask Your Agent","text":"

    The simplest way to check context health:

    Is our context clean?\nAnything stale?\nHow healthy are our context files?\n

    Or invoke the skill directly:

    /ctx-drift\n

    The agent performs two layers of analysis:

    Layer 1, structural checks (via ctx drift): Dead paths, missing files, completed task counts, constitution violations. Fast and programmatic.

    Layer 2, semantic analysis (agent-driven): Does CONVENTIONS.md describe patterns the code no longer follows? Does DECISIONS.md contain entries whose rationale no longer applies? Are there learnings about bugs that are now fixed? This is where the agent adds value the CLI cannot: It reads both context files and source code and compares them.

    The agent reports both layers together, explains each finding in plain language, and offers to fix what it can.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-2-maintenance-at-session-start","level":3,"title":"Step 2: Maintenance at Session Start","text":"

    You do not need to ask explicitly.

    Using Claude Code

    ctx ships with Claude Code hooks that remind the agent at the right time to take initiative.

    Checking context health at the session start, offering to persist learnings before you quit, and flagging drift when it matters. The agent stays proactive without you having to prompt it:

    Agent: Good morning. I've loaded the context files. A few things\n       before we start:\n\n       - ARCHITECTURE.md references `pkg/auth/` which is now empty\n       - DECISIONS.md hasn't been updated in 40 days\n       - There are 18 completed tasks ready for archival\n\n       Want me to run a quick maintenance pass, or should we jump\n       straight into today's work?\n

    ☝️️ this is what persistent, initiative-driven sessions feel like when context is treated as a system instead of a prompt.

    If the agent does not offer this on its own, a gentle nudge is enough:

    Anything stale before we start?\nHow's the context looking?\n

    This turns maintenance from a scheduled chore into a conversation that happens when it matters.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-3-real-time-detection-during-work","level":3,"title":"Step 3: Real-Time Detection During Work","text":"

    Agents can notice drift while working: When a mismatch is directly in the path of their current task. If an agent reads ARCHITECTURE.md to find where to add a handler and internal/handlers/ doesn't exist, it will notice because the stale reference blocks its work:

    Agent: ARCHITECTURE.md references `internal/handlers/` but that directory\n       doesn't exist. I'll look at the actual source tree to find where\n       handlers live now.\n

    This happens reliably when the drift intersects the task. What is less reliable is the agent generalizing from one mismatch to \"there might be more stale references; let me run drift detection\" That leap requires the agent to know /ctx-drift exists and to decide the current task should pause for maintenance.

    If you want that behavior, reinforce it:

    Good catch. Yes, run /ctx-drift and clean up any other stale references.\n

    Over time, agents that have seen this pattern will start offering proactively. But do not expect it from a cold start.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#step-4-archival-and-cleanup","level":3,"title":"Step 4: Archival and Cleanup","text":"

    ctx drift detects when TASKS.md has more than 10 completed items and flags it as a staleness warning. Running ctx drift --fix archives completed tasks automatically.

    You can also run /ctx-archive to compact on demand.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#knowledge-health-flow","level":3,"title":"Knowledge Health Flow","text":"

    Over time, LEARNINGS.md and DECISIONS.md accumulate entries that overlap or partially repeat each other. The check-persistence hook detects when entry counts exceed a configurable threshold and surfaces a nudge:

    \"LEARNINGS.md has 25+ entries. Consider running /ctx-consolidate to merge overlapping items.\"

    The consolidation workflow:

    1. Review: /ctx-consolidate groups entries by keyword similarity and presents candidate merges for your approval.
    2. Merge: Approved groups are combined into single entries that preserve the key information from each original.
    3. Archive: Originals move to .context/archive/, not deleted -- the full history is preserved in git and the archive directory.
    4. Verify: Run ctx drift after consolidation to confirm no cross-references were broken by the merge.

    This replaces ad-hoc cleanup with a repeatable, nudge-driven cycle: detect accumulation, review candidates, merge with approval, archive originals.

    See also: Knowledge Capture for the recording workflow that feeds into this maintenance cycle.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-doctor-the-superset-check","level":2,"title":"ctx doctor: The Superset Check","text":"

    ctx doctor combines drift detection with hook auditing, configuration checks, event logging status, and token size reporting in a single command. If you want one command that covers structural health, hooks, and state:

    ctx doctor          # everything in one pass\nctx doctor --json   # machine-readable for scripting\n

    Use /ctx-doctor Too

    For agent-driven diagnosis that adds semantic analysis on top of the structural checks, use /ctx-doctor.

    See the Troubleshooting recipe for the full workflow.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#cli-reference","level":2,"title":"CLI Reference","text":"

    The conversational approach above uses CLI commands under the hood. When you need direct control, use the commands directly.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-drift","level":3,"title":"ctx drift","text":"

    Scan context files for structural problems:

    ctx drift\n

    Sample output:

    Drift Report\n============\n\nWarnings (3):\n  ARCHITECTURE.md:14  path \"internal/api/router.go\" does not exist\n  ARCHITECTURE.md:28  path \"pkg/auth/\" directory is empty\n  CONVENTIONS.md:9    path \"internal/handlers/\" not found\n\nViolations (1):\n  TASKS.md            31 completed tasks (recommend archival)\n\nStaleness:\n  DECISIONS.md        last modified 45 days ago\n  LEARNINGS.md        last modified 32 days ago\n\nExit code: 1 (warnings found)\n
    Level Meaning Action Warning Stale path references, missing files Fix or remove Violation Constitution rule heuristic failures, heavy clutter Fix soon Staleness Files not updated recently Review content

    Exit codes: 0 equals clean, 1 equals warnings, 3 equals violations.

    For CI integration:

    ctx drift --json | jq '.warnings | length'\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-drift-fix","level":3,"title":"ctx drift --fix","text":"

    Auto-fix mechanical issues:

    ctx drift --fix\n

    This handles removing dead path references, updating unambiguous renames, clearing empty sections. Issues requiring judgment are flagged but left for you.

    Run ctx drift again afterward to confirm what remains.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-sync","level":3,"title":"ctx sync","text":"

    After a refactor, reconcile context with the actual codebase structure:

    ctx sync --dry-run   # preview first\nctx sync             # apply\n

    ctx sync scans for structural changes, compares with ARCHITECTURE.md, checks for new dependencies worth documenting, and identifies context referring to code that no longer exists.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-compact","level":3,"title":"ctx compact","text":"

    Consolidate completed tasks and clean up empty sections:

    ctx compact            # move completed tasks to Completed section,\n                       # remove empty sections\nctx compact --archive  # also archive old tasks to .context/archive/\n
    • Tasks: moves completed items (with all subtasks done) into the Completed section of TASKS.md
    • All files: removes empty sections left behind
    • With --archive: writes tasks older than 7 days to .context/archive/tasks-YYYY-MM-DD.md

    Without --archive, nothing is deleted: Tasks are reorganized in place.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-status","level":3,"title":"ctx status","text":"

    Quick health overview:

    ctx status --verbose\n

    Shows file counts, token estimates, modification times, and drift warnings in a single glance.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#ctx-prompt-audit","level":3,"title":"/ctx-prompt-audit","text":"

    Checks whether your context files are readable, compact, and token-efficient for the model.

    /ctx-prompt-audit\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Conversational approach (recommended):

    Is our context clean?  -> agent runs structural plus semantic checks\nFix what you can       -> agent auto-fixes and proposes edits\nArchive the done tasks -> agent runs ctx compact --archive\nHow's token usage?     -> agent checks ctx status\n

    CLI approach (for CI, scripts, or direct control):

    ctx drift                      # 1. Detect problems\nctx drift --fix                # 2. Auto-fix the easy ones\nctx sync --dry-run && ctx sync # 3. Reconcile after refactors\nctx compact --archive          # 4. Archive old completed tasks\nctx status                     # 5. Verify\n
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#tips","level":2,"title":"Tips","text":"

    Agents cross-reference context files with source code during normal work. When drift intersects their current task, they will notice: a renamed package, a deleted directory, a path that doesn't resolve. But they rarely generalize from one mismatch to a full audit on their own. Reinforce the pattern: when an agent mentions a stale reference, ask it to run /ctx-drift. Over time, it starts offering.

    When an agent says \"this reference looks stale,\" it is usually right.

    Semantic drift is more damaging than structural drift: ctx drift catches dead paths. But CONVENTIONS.md describing a pattern your code stopped following three weeks ago is worse. When you ask \"is our context clean?\", the agent can do both checks.

    Use ctx status as a quick check: It shows file counts, token estimates, and drift warnings in a single glance. Good for a fast \"is everything ok?\" before diving into work.

    Drift detection in CI: add ctx drift --json to your CI pipeline and fail on exit code 3 (violations). This catches constitution-level problems before they reach upstream.

    Do not over-compact: Completed tasks have historical value. The --archive flag preserves them in .context/archive/ so you can search past work without cluttering active context.

    Sync is cautious by default: Use --dry-run after large refactors, then apply.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#next-up","level":2,"title":"Next Up","text":"

    Claude Code Permission Hygiene →: Recommended permission defaults and maintenance workflow for Claude Code.

    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/context-health/#see-also","level":2,"title":"See Also","text":"
    • Troubleshooting: full diagnostic workflow using ctx doctor, event logs, and /ctx-doctor
    • Tracking Work Across Sessions: task lifecycle and archival
    • Persisting Decisions, Learnings, and Conventions: keeping knowledge files current
    • The Complete Session: where maintenance fits in the daily workflow
    • CLI Reference: full flag documentation for all commands
    • Context Files: structure and purpose of each .context/ file
    ","path":["Recipes","Maintenance","Detecting and Fixing Drift"],"tags":[]},{"location":"recipes/customizing-hook-messages/","level":1,"title":"Customizing Hook Messages","text":"","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#the-problem","level":2,"title":"The Problem","text":"

    ctx hooks speak ctx's language, not your project's. The QA gate says \"lint the ENTIRE project\" and \"make build,\" but your Python project uses pytest and ruff. The post-commit nudge suggests running lints, but your project uses npm test. You could remove the hook entirely, but then you lose the logic (counting, state tracking, adaptive frequency) just to change the words.

    How do you customize what hooks say without removing what they do?

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#tldr","level":2,"title":"TL;DR","text":"
    ctx system message list                     # see all hooks and their messages\nctx system message show qa-reminder gate    # view the current template\nctx system message edit qa-reminder gate    # copy default to .context/ for editing\nctx system message reset qa-reminder gate   # revert to embedded default\n
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#commands-used","level":2,"title":"Commands Used","text":"Tool Type Purpose ctx system message list CLI command Show all hook messages with category and override status ctx system message show CLI command Print the effective message template ctx system message edit CLI command Copy embedded default to .context/ for editing ctx system message reset CLI command Delete user override, revert to default","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#how-it-works","level":2,"title":"How It Works","text":"

    Hook messages use a 3-tier fallback:

    1. User override: .context/hooks/messages/{hook}/{variant}.txt
    2. Embedded default: compiled into the ctx binary
    3. Hardcoded fallback: belt-and-suspenders safety net

    The hook logic (when to fire, counting, state tracking, cooldowns) is unchanged. Only the content (what text gets emitted) comes from the template. You customize what the hook says without touching how it decides to speak.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#finding-the-original-templates","level":3,"title":"Finding the Original Templates","text":"

    The default templates live in the ctx source tree at:

    internal/assets/hooks/messages/{hook}/{variant}.txt\n

    You can also browse them on GitHub: internal/assets/hooks/messages/

    Or use ctx system message show to print any template without digging through source code:

    ctx system message show qa-reminder gate        # QA gate instructions\nctx system message show check-persistence nudge  # persistence nudge\nctx system message show post-commit nudge        # post-commit reminder\n

    The show output includes the template source and available variables -- everything you need to write a replacement.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#template-variables","level":3,"title":"Template Variables","text":"

    Some messages use Go text/template variables for dynamic content:

    No context files updated in {{.PromptsSinceNudge}}+ prompts.\nHave you discovered learnings, made decisions,\nestablished conventions, or completed tasks\nworth persisting?\n

    The show and edit commands list available variables for each message. When writing a replacement, keep the same {{.VariableName}} placeholders to preserve dynamic content. Variables that you omit render as <no value>: no error, but the output may look odd.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#intentional-silence","level":3,"title":"Intentional Silence","text":"

    An empty template file (0 bytes or whitespace-only) means \"don't emit a message\". The hook still runs its logic but produces no output. This lets you silence specific messages without removing the hook from hooks.json.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-python-project-qa-gate","level":2,"title":"Example: Python Project QA Gate","text":"

    The default QA gate says \"lint the ENTIRE project\" and references make lint. For a Python project, you want pytest and ruff:

    # See the current default\nctx system message show qa-reminder gate\n\n# Copy it to .context/ for editing\nctx system message edit qa-reminder gate\n\n# Edit the override\n

    Replace the content in .context/hooks/messages/qa-reminder/gate.txt:

    HARD GATE! DO NOT COMMIT without completing ALL of these steps first:\n(1) Run the full test suite: pytest -x\n(2) Run the linter: ruff check .\n(3) Verify a clean working tree\nRun tests and linter BEFORE every git commit, no exceptions.\n

    The hook still fires on every Edit call. The logic is identical. Only the instructions changed.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-silencing-ceremony-nudges","level":2,"title":"Example: Silencing Ceremony Nudges","text":"

    The ceremony check nudges you to use /ctx-remember and /ctx-wrap-up. If your team has a different workflow and finds these noisy:

    ctx system message edit check-ceremonies both\nctx system message edit check-ceremonies remember\nctx system message edit check-ceremonies wrapup\n

    Then empty each file:

    echo -n \"\" > .context/hooks/messages/check-ceremonies/both.txt\necho -n \"\" > .context/hooks/messages/check-ceremonies/remember.txt\necho -n \"\" > .context/hooks/messages/check-ceremonies/wrapup.txt\n

    The hooks still track ceremony usage internally, but they no longer emit any visible output.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#example-javascript-project-post-commit","level":2,"title":"Example: JavaScript Project Post-Commit","text":"

    The default post-commit nudge mentions generic \"lints and tests.\" For a JavaScript project:

    ctx system message edit post-commit nudge\n

    Replace with:

    Commit succeeded. 1. Offer context capture to the user: Decision (design\nchoice?), Learning (gotcha?), or Neither. 2. Ask the user: \"Want me to\nrun npm test and eslint before you push?\" Do NOT push. The user pushes\nmanually.\n
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#the-two-categories","level":2,"title":"The Two Categories","text":"

    Not all messages are equal. The list command shows each message's category:

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#customizable-17-messages","level":3,"title":"Customizable (17 messages)","text":"

    Messages that are opinions: project-specific wording that benefits from customization. These are the primary targets for override.

    Hook Variant Description check-backup-age warning Backup staleness warning check-freshness stale Technology constant freshness warning check-ceremonies both Both ceremonies missing check-ceremonies remember Start-of-session ceremony check-ceremonies wrapup End-of-session ceremony check-context-size checkpoint Context capacity warning check-context-size oversize Injection oversize nudge check-context-size window Context window usage warning (>80%) check-journal both Unexported sessions + unenriched entries check-journal unenriched Unenriched journal entries check-journal unexported Unexported sessions check-knowledge warning Knowledge file growth check-map-staleness stale Architecture map staleness check-persistence nudge Context persistence nudge post-commit nudge Post-commit context capture qa-reminder gate Pre-commit QA gate","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#ctx-specific-10-messages","level":3,"title":"ctx-specific (10 messages)","text":"

    Messages specific to ctx's own development workflow. You can customize them, but edit will warn you first.

    Hook Variant Description block-dangerous-commands cp-to-bin Block copy to bin dirs block-dangerous-commands install-to-local-bin Block copy to ~/.local/bin block-dangerous-commands mid-git-push Block git push block-dangerous-commands mid-sudo Block sudo block-non-path-ctx absolute-path Block absolute path invocation block-non-path-ctx dot-slash Block ./ctx invocation block-non-path-ctx go-run Block go run invocation check-reminders reminders Pending reminders relay check-resources alert Resource pressure alert check-version key-rotation Key rotation nudge check-version mismatch Version mismatch","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#template-variables-reference","level":2,"title":"Template Variables Reference","text":"Hook Variant Variables check-backup-age warning {{.Warnings}} check-freshness stale {{.StaleFiles}} check-context-size checkpoint (none) check-context-size oversize {{.TokenCount}} check-context-size window {{.TokenCount}}, {{.Percentage}} check-ceremonies both, remember, wrapup (none) check-journal both {{.UnexportedCount}}, {{.UnenrichedCount}} check-journal unenriched {{.UnenrichedCount}} check-journal unexported {{.UnexportedCount}} check-knowledge warning {{.FileWarnings}} check-map-staleness stale {{.LastRefreshDate}}, {{.ModuleCount}} check-persistence nudge {{.PromptsSinceNudge}} check-reminders reminders {{.ReminderList}} check-resources alert {{.AlertMessages}} check-version key-rotation {{.KeyAgeDays}} check-version mismatch {{.BinaryVersion}}, {{.PluginVersion}} post-commit nudge (none) qa-reminder gate (none) block-dangerous-commands all variants (none) block-non-path-ctx all variants (none)

    Templates that reference undefined variables render <no value>: no error, graceful degradation.

    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#tips","level":2,"title":"Tips","text":"
    • Override files are version-controlled: they live in .context/ alongside your other context files. Team members get the same customized messages.
    • Start with show: always check the current default before editing. The embedded template is the baseline your override replaces.
    • Use reset to undo: if a customization causes confusion, reset reverts to the embedded default instantly.
    • Empty file = silence: you don't need to delete the hook. An empty override file silences the message while preserving the hook's logic.
    • JSON output for scripting: ctx system message list --json returns structured data for automation.
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/customizing-hook-messages/#see-also","level":2,"title":"See Also","text":"
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Auditing System Hooks: verifying hooks are running and auditing their output
    • Configuration: project-level settings via .ctxrc
    ","path":["Recipes","Hooks and Notifications","Customizing Hook Messages"],"tags":[]},{"location":"recipes/dependency-graph/","level":1,"title":"Generating Dependency Graphs","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#why-dependency-graphs","level":2,"title":"Why Dependency Graphs?","text":"

    Understanding how packages relate to each other is the first step in onboarding, refactoring, and architecture review. ctx dep generates dependency graphs from source code so you can see the structure at a glance instead of tracing imports by hand.

    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#quick-start","level":2,"title":"Quick Start","text":"
    # Auto-detect ecosystem and output Mermaid (default)\nctx dep\n\n# Table format for a quick terminal overview\nctx dep --format table\n\n# JSON for programmatic consumption\nctx dep --format json\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#ecosystem-detection","level":2,"title":"Ecosystem Detection","text":"

    ctx dep looks for manifest files in this order:

    1. Go: go.mod
    2. Node.js: package.json
    3. Python: pyproject.toml, setup.py, requirements.txt
    4. Rust: Cargo.toml

    First match wins. To override detection, use --type:

    # Force Python even if go.mod exists\nctx dep --type python\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#output-formats","level":2,"title":"Output Formats","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#mermaid-default","level":3,"title":"Mermaid (default)","text":"

    Produces a Mermaid graph definition you can paste into GitHub PRs, Obsidian notes, or any Mermaid-compatible renderer.

    ctx dep --format mermaid\n
    graph TD\n    internal/cli --> internal/config\n    internal/cli --> internal/memory\n    internal/config --> internal/entry
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#table","level":3,"title":"Table","text":"

    Flat two-column view for quick terminal scanning.

    ctx dep --format table\n
    PACKAGE                  DEPENDS ON\ninternal/cli             internal/config, internal/memory\ninternal/config          internal/entry\ninternal/memory          internal/index\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#json","level":3,"title":"JSON","text":"

    Machine-readable output for scripts and pipelines.

    ctx dep --format json | jq '.nodes | length'\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#including-external-dependencies","level":2,"title":"Including External Dependencies","text":"

    By default, only internal (first-party) dependencies are shown. Add --external to include third-party packages:

    ctx dep --external\nctx dep --external --format table\n

    This is useful when auditing transitive dependencies or checking which packages pull in heavy external libraries.

    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#when-to-use-it","level":2,"title":"When to Use It","text":"
    • Onboarding. Generate a Mermaid graph and drop it into the project wiki. New contributors see the architecture before reading code.
    • Refactoring. Before moving packages, check what depends on them. Combine with ctx drift to find stale references after the move.
    • Architecture review. Table format gives a quick overview; Mermaid format goes into design docs and PRs.
    • Pre-commit. Run in CI to detect unexpected new dependencies between packages.
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#combining-with-other-commands","level":2,"title":"Combining with Other Commands","text":"","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#refactoring-with-ctx-drift","level":3,"title":"Refactoring with ctx drift","text":"
    # See the dependency structure before refactoring\nctx dep --format table\n\n# After moving packages, check for broken references\nctx drift\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#feeding-architecture-maps","level":3,"title":"Feeding architecture maps","text":"

    Use JSON output as input for context files or architecture documentation:

    # Generate a dependency snapshot for the context directory\nctx dep --format json > .context/deps.json\n\n# Or pipe into other tools\nctx dep --format mermaid >> docs/architecture.md\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#monorepos-and-multi-ecosystem-projects","level":2,"title":"Monorepos and Multi-Ecosystem Projects","text":"

    In a monorepo with multiple ecosystems, ctx dep picks the first manifest it finds (Go beats Node.js beats Python beats Rust). Use --type to target a specific ecosystem:

    # In a repo with both go.mod and package.json\nctx dep --type node\nctx dep --type go\n

    For separate subdirectories, run from each root:

    cd services/api && ctx dep --format table\ncd frontend && ctx dep --type node --format mermaid\n
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/dependency-graph/#tips","level":2,"title":"Tips","text":"
    • Start with table format. It is the fastest way to get a mental model of the dependency structure. Switch to Mermaid when you need a visual for documentation or a PR.
    • Pipe JSON to jq. Filter for specific packages, count edges, or extract subgraphs programmatically.
    • Skip --external unless you need it. Internal-only graphs are cleaner and load faster. Add external deps when you are specifically auditing third-party usage.
    • Force --type in CI. Auto-detection is convenient locally, but explicit types prevent surprises when the repo structure changes.
    ","path":["Generating Dependency Graphs"],"tags":[]},{"location":"recipes/design-before-coding/","level":1,"title":"Design Before Coding","text":"","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#the-problem","level":2,"title":"The Problem","text":"

    You start coding a feature. Halfway through, you realize the approach doesn't handle a key edge case. You refactor. Then you discover the CLI interface doesn't fit the existing patterns. More refactoring.

    The design work happened during implementation, mixed in with debugging and trial-and-error. The result works, but the spec was never written down, the trade-offs were never recorded, and the next session has no idea why things are shaped this way.

    How do you front-load design so the implementation is straightforward?

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-brainstorm          # explore the design space\n/ctx-spec                # write the spec document\n/ctx-add-task            # break it into tasks\n/ctx-implement           # execute step-by-step\n

    Four skills, used in sequence. Each produces an artifact that feeds the next.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-brainstorm Skill Structured design dialogue: explore approaches /ctx-spec Skill Scaffold and fill out a spec from the template /ctx-add-task Skill Add implementation tasks to TASKS.md /ctx-implement Skill Execute a plan step-by-step with verification /ctx-add-decision Skill Record design choices made during brainstorming","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-1-brainstorm-the-design","level":3,"title":"Step 1: Brainstorm the Design","text":"

    Start with /ctx-brainstorm when you have a rough idea but haven't committed to an approach. The skill follows a gated process:

    1. Understand context: what exists today, what's the gap
    2. Clarify the idea: one question at a time, not a wall of questions
    3. Surface non-functional requirements: performance, security, compatibility
    4. Lock understanding: confirm before exploring solutions
    5. Explore 2-3 approaches: with trade-offs for each
    6. Stress-test: poke holes in the chosen approach
    7. Present the design: detailed enough to implement from
    You: \"I want to add RSS feed generation to the blog.\"\n\nAgent: \"Before we design, let me understand: is this for the journal\n  site, the docs site, or both?\"\n\nYou: \"Journal site only.\"\n\nAgent: [asks about update frequency, content scope, existing infra...]\n       [presents 3 approaches with trade-offs]\n\nYou: \"Option 2 - generate at build time.\"\n\nAgent: \"Let me stress-test that. What happens when...\"\n       [probes edge cases]\n       \"Design looks solid. Want me to record the approach as a\n       decision and write a spec?\"\n

    The brainstorm produces a validated design in conversation. It doesn't produce a file - that's what the spec is for.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-2-write-the-spec","level":3,"title":"Step 2: Write the Spec","text":"

    Once the design is clear, use /ctx-spec to produce the written artifact. The skill reads the project's spec template (specs/tpl/spec-template.md) and walks through each section:

    You: /ctx-spec (rss feed generation)\n\nAgent: \"Creating specs/rss-feed.md from template.\"\n\n       \"Problem: What user-visible problem does this solve? Why now?\"\n\nYou: \"Users can't subscribe to blog updates. They have to check\n      the site manually.\"\n\nAgent: [writes the Problem section, moves to Approach]\n\n       \"Approach: High-level, how does this work?\"\n\nYou: \"Generate feed.xml during ctx journal site. Atom format.\"\n\nAgent: [writes Approach, moves to Happy Path, then Edge Cases...]\n

    The skill spends extra time on Edge Cases and Error Handling: These are where specs earn their value. The skill pushes for at least three edge cases and won't accept \"none\" without a challenge.

    Sections that don't apply can be skipped. The result is a complete spec at specs/{feature-name}.md.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-3-break-into-tasks","level":3,"title":"Step 3: Break Into Tasks","text":"

    After the spec is written, the skill offers to create tasks:

    Agent: \"Spec written to specs/rss-feed.md. Want me to break this\n  into tasks in TASKS.md?\"\n\nYou: \"Yes.\"\n\nAgent: [creates a Phase section referencing the spec, adds tasks]\n       \"Added Phase 0.8: RSS/Atom Feed Generation with 4 tasks:\n         - [ ] Implement feed.xml generation in ctx journal site\n         - [ ] Add --feed flag and .ctxrc feed config\n         - [ ] Write tests for feed generation\n         - [ ] Add recipe and update docs\"\n

    Each task is independently completable and references the spec via Spec: specs/rss-feed.md in the Phase header.

    You can also invoke /ctx-add-task directly at any point to add individual tasks.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#step-4-implement-step-by-step","level":3,"title":"Step 4: Implement Step-by-Step","text":"

    Pick up tasks with /ctx-implement. The skill loads the spec, breaks work into atomic steps, and checkpoints after every 3-5 steps with a build and test verification:

    You: /ctx-implement (specs/rss-feed.md)\n\nAgent: \"Loaded spec. Breaking into steps:\n         1. Add FeedEntry type to journal package\n         2. Implement feed.xml template\n         3. Wire into site generation pipeline\n         [builds and tests after step 3]\n         4. Add --feed flag to ctx journal site\n         5. Add .ctxrc feed configuration\n         [builds and tests after step 5]\n         ...\"\n

    If a build or test fails, the agent stops, diagnoses, and fixes before continuing.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#when-to-skip-steps","level":2,"title":"When to Skip Steps","text":"

    Not every feature needs all four steps. Use your judgment:

    Situation Start at Vague idea, multiple valid approaches Step 1: Brainstorm Clear approach, need to document it Step 2: Spec Spec already exists, need to plan work Step 3: Tasks Tasks exist, ready to code Step 4: Implement

    A brainstorm without a spec is fine for small decisions. A spec without a brainstorm is fine when the design is obvious. The full chain is for features complex enough to warrant front-loaded design.

    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need skill names. Natural language works:

    You say What happens \"Let's think through this feature\" /ctx-brainstorm \"Spec this out\" /ctx-spec \"Write a design doc for...\" /ctx-spec \"Break this into tasks\" /ctx-add-task \"Implement the spec\" /ctx-implement \"Let's design before we build\" Starts at brainstorm","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#tips","level":2,"title":"Tips","text":"
    • Brainstorm first when uncertain. If you can articulate the approach in two sentences, skip to spec. If you can't, brainstorm.
    • Specs prevent scope creep. The Non-Goals section is as important as the approach. Writing down what you won't do keeps implementation focused.
    • Edge cases are the point. A spec that only describes the happy path isn't a spec - it's a wish. The /ctx-spec skill pushes for at least 3 edge cases because that's where designs break.
    • Record decisions during brainstorming. When you choose between approaches, the agent offers to persist the trade-off via /ctx-add-decision. Accept - future sessions need to know why, not just what.
    • Specs are living documents. Update them when implementation reveals new constraints. A spec that diverges from reality is worse than no spec.
    • The spec template is customizable. Edit specs/tpl/spec-template.md to match your project's needs. The /ctx-spec skill reads whatever template it finds there.
    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/design-before-coding/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: /ctx-brainstorm: structured design dialogue
    • Skills Reference: /ctx-spec: spec scaffolding from template
    • Skills Reference: /ctx-implement: step-by-step execution with verification
    • Tracking Work Across Sessions: task lifecycle and archival
    • Importing Claude Code Plans: turning ephemeral plans into permanent specs
    • Persisting Decisions, Learnings, and Conventions: capturing design trade-offs
    ","path":["Recipes","Knowledge and Tasks","Design Before Coding"],"tags":[]},{"location":"recipes/external-context/","level":1,"title":"Keeping Context in a Separate Repo","text":"","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#the-problem","level":2,"title":"The Problem","text":"

    ctx files contain project-specific decisions, learnings, conventions, and tasks. By default, they live in .context/ inside the project tree, and that works well when the context can be public.

    But sometimes you need the context outside the project:

    • Open-source projects with private context: Your architectural notes, internal task lists, and scratchpad entries shouldn't ship with the public repo.
    • Compliance or IP concerns: Context files reference sensitive design rationale that belongs in a separate access-controlled repository.
    • Personal preference: You want a single context repo that covers multiple projects, or you just prefer keeping notes separate from code.

    ctx supports this through three configuration methods. This recipe shows how to set them up and how to tell your AI assistant where to find the context.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#tldr","level":2,"title":"TL;DR","text":"

    First --allow-outside-cwd in your project:

    mkdir ~/repos/myproject-context && cd ~/repos/myproject-context && git init\ncd ~/repos/myproject\nctx --context-dir ~/repos/myproject-context --allow-outside-cwd init\n

    Then, create a .ctxrc in your project root to specify the new .context folder location:

    context_dir: ~/repos/myproject-context\nallow_outside_cwd: true\n

    All ctx commands now use the external directory automatically.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init CLI command Initialize context directory --context-dir Global flag Point ctx at a non-default directory --allow-outside-cwd Global flag Permit context outside the project root .ctxrc Config file Persist the context directory setting CTX_DIR Env variable Override context directory per-session /ctx-status Skill Verify context is loading correctly","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-1-create-the-private-context-repo","level":3,"title":"Step 1: Create the Private Context Repo","text":"

    Create a separate repository for your context files. This can live anywhere: a private GitHub repo, a shared drive, a sibling directory:

    # Create the context repo\nmkdir ~/repos/myproject-context\ncd ~/repos/myproject-context\ngit init\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-2-initialize-ctx-pointing-at-it","level":3,"title":"Step 2: Initialize ctx Pointing at It","text":"

    From your project root, initialize ctx with --context-dir pointing to the external location. Because the directory is outside your project tree, you also need --allow-outside-cwd:

    cd ~/repos/myproject\nctx --context-dir ~/repos/myproject-context \\\n    --allow-outside-cwd \\\n    init\n

    This creates the full .context/-style file set inside ~/repos/myproject-context/ instead of ~/repos/myproject/.context/.

    Boundary Validation

    ctx validates that the .context directory is within the current working directory.

    If your external directory is truly outside the project root:

    • Either every ctx command needs --allow-outside-cwd,
    • or you can persist the setting in .ctxrc (next step).
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-3-make-it-stick","level":3,"title":"Step 3: Make It Stick","text":"

    Typing --context-dir and --allow-outside-cwd on every command is tedious. Pick one of these methods to make the configuration permanent.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-a-ctxrc-recommended","level":4,"title":"Option A: .ctxrc (Recommended)","text":"

    Create a .ctxrc file in your project root:

    # .ctxrc: committed to the project repo\ncontext_dir: ~/repos/myproject-context\nallow_outside_cwd: true\n

    ctx reads .ctxrc automatically. Every command now uses the external directory without extra flags:

    ctx status          # reads from ~/repos/myproject-context\nctx add learning \"Redis MULTI doesn't roll back on error\"\n

    Commit .ctxrc

    .ctxrc belongs in the project repo. It contains no secrets: It's just a path and a boundary override.

    .ctxrc lets teammates share the same configuration.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-b-ctx_dir-environment-variable","level":4,"title":"Option B: CTX_DIR Environment Variable","text":"

    Good for CI pipelines, temporary overrides, or when you don't want to commit a .ctxrc:

    # In your shell profile (~/.bashrc, ~/.zshrc)\nexport CTX_DIR=~/repos/myproject-context\n

    Or for a single session:

    CTX_DIR=~/repos/myproject-context ctx status\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#option-c-shell-alias","level":4,"title":"Option C: Shell Alias","text":"

    If you prefer a shell alias over .ctxrc:

    # ~/.bashrc or ~/.zshrc\nalias ctx='ctx --context-dir ~/repos/myproject-context --allow-outside-cwd'\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#priority-order","level":4,"title":"Priority Order","text":"

    When multiple methods are set, ctx resolves the context directory in this order (highest priority first):

    1. --context-dir flag
    2. CTX_DIR environment variable
    3. context_dir in .ctxrc
    4. Default: .context/
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-4-agent-auto-discovery-via-bootstrap","level":3,"title":"Step 4: Agent Auto-Discovery via Bootstrap","text":"

    When context lives outside the project tree, your AI assistant needs to know where to find it. The ctx system bootstrap command resolves the configured context directory and communicates it to the agent automatically:

    $ ctx system bootstrap\nctx bootstrap\n=============\n\ncontext_dir: /home/user/repos/myproject-context\n\nFiles:\n  CONSTITUTION.md, TASKS.md, DECISIONS.md, ...\n

    The CLAUDE.md template generated by ctx init already instructs the agent to run ctx system bootstrap at session start. Because .ctxrc is in the project root, your agent inherits the external path automatically via the ctx system boostrap call instruction.

    Here is the relevant section from CLAUDE.md for reference:

    <!-- CLAUDE.md -->\n1. **Run `ctx system bootstrap`**: CRITICAL, not optional.\n   This tells you where the context directory is. If it fails or returns\n   no context_dir, STOP and warn the user.\n

    Moreover, every nudge (context checkpoint, persistence reminder, etc.) also includes a Context: /home/user/repos/myproject-context footer, so the agent remains anchored to the correct directory even in long sessions.

    If you use CTX_DIR instead of .ctxrc, export it in your shell profile so the hook process inherits it:

    export CTX_DIR=~/repos/myproject-context\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-5-share-with-teammates","level":3,"title":"Step 5: Share with Teammates","text":"

    Teammates clone both repos and set up .ctxrc:

    # Clone the project\ngit clone git@github.com:org/myproject.git\ncd myproject\n\n# Clone the private context repo\ngit clone git@github.com:org/myproject-context.git ~/repos/myproject-context\n

    If .ctxrc is already committed to the project, they're done: ctx commands will find the external context automatically.

    If teammates use different paths, each developer sets their own CTX_DIR:

    export CTX_DIR=~/my-own-path/myproject-context\n

    For encryption key distribution across the team, see the Syncing Scratchpad Notes recipe.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#step-6-day-to-day-sync","level":3,"title":"Step 6: Day-to-Day Sync","text":"

    The external context repo has its own git history. Treat it like any other repo: Commit and push after sessions:

    cd ~/repos/myproject-context\n\n# After a session\ngit add -A\ngit commit -m \"Session: refactored auth module, added rate-limit learning\"\ngit push\n

    Your AI assistant can do this too. When ending a session:

    You: \"Save what we learned and push the context repo.\"\n\nAgent: [runs ctx add learning, then commits and pushes the context repo]\n

    You can also set up a post-session habit: project code gets committed to the project repo, context gets committed to the context repo.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember the flags; simply ask your assistant:

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#set-up-your-system-using-natural-language","level":3,"title":"Set Up Your System Using Natural Language","text":"
    You: \"Set up ctx to use ~/repos/myproject-context as the context directory.\"\n\nAgent: \"I'll create a .ctxrc in the project root pointing to that path.\n       I'll also update CLAUDE.md so future sessions know where to find\n       context. Want me to initialize the context files there too?\"\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#configure-separate-repo-for-context-folder-using-natural-language","level":3,"title":"Configure Separate Repo for .context Folder Using Natural Language","text":"
    You: \"My context is in a separate repo. Can you load it?\"\n\nAgent: [reads .ctxrc, finds the path, loads context from the external dir]\n       \"Loaded. You have 3 pending tasks, last session was about the auth\n       refactor.\"\n
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#tips","level":2,"title":"Tips","text":"
    • Start simple. If you don't need external context yet, don't set it up. The default .context/ in-tree is the easiest path. Move to an external repo when you have a concrete reason.
    • One context repo per project. Sharing a single context directory across multiple projects creates confusion. Keep the mapping 1:1.
    • Use .ctxrc over env vars when the path is stable. It's committed, documented, and works for the whole team without per-developer shell setup.
    • Don't forget the boundary flag. The most common error is Error: context directory is outside the project root. Set allow_outside_cwd: true in .ctxrc or pass --allow-outside-cwd.
    • Commit both repos at session boundaries. Context without code history (or code without context history) loses half the value.
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#next-up","level":2,"title":"Next Up","text":"

    The Complete Session →: Walk through a full ctx session from start to finish.

    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/external-context/#see-also","level":2,"title":"See Also","text":"
    • Setting Up ctx Across AI Tools: initial setup recipe
    • Syncing Scratchpad Notes Across Machines: distribute encryption keys when context is shared
    • CLI Reference: all global flags including --context-dir and --allow-outside-cwd
    ","path":["Recipes","Getting Started","Keeping Context in a Separate Repo"],"tags":[]},{"location":"recipes/guide-your-agent/","level":1,"title":"Guide Your Agent","text":"

    Commands vs. Skills

    Commands (ctx status, ctx add task) run in your terminal.

    Skills (/ctx-reflect, /ctx-next) run inside your AI coding assistant.

    Recipes combine both.

    Think of commands as structure and skills as behavior.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#proactive-behavior","level":2,"title":"Proactive Behavior","text":"

    These recipes show explicit commands and skills, but agents trained on the ctx playbook are proactive: They offer to save learnings after debugging, record decisions after trade-offs, create follow-up tasks after completing work, and suggest what to work on next.

    Your questions train the agent. Asking \"what have we learned?\" or \"is our context clean?\" does two things:

    • It triggers the workflow right now,
    • and it reinforces the pattern.

    The more you guide, the more the agent habituates the behavior and begins offering on its own.

    Each recipe includes a Conversational Approach section showing these natural-language patterns.

    Tip

    Don't wait passively for proactive behavior: especially in early sessions.

    Ask, guide, reinforce. Over time, you ask less and the agent offers more.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#next-up","level":2,"title":"Next Up","text":"

    Setup Across AI Tools →: Initialize ctx and configure hooks for Claude Code, Cursor, Aider, Copilot, or Windsurf.

    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/guide-your-agent/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle from start to finish
    • Prompting Guide: general tips for working effectively with AI coding assistants
    ","path":["Recipes","Getting Started","Guide Your Agent"],"tags":[]},{"location":"recipes/hook-output-patterns/","level":1,"title":"Hook Output Patterns","text":"","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code hooks can output text, JSON, or nothing at all. But the format of that output determines who sees it and who acts on it.

    Choose the wrong pattern, and your carefully crafted warning gets silently absorbed by the agent, or your agent-directed nudge gets dumped on the user as noise.

    This recipe catalogs the known hook output patterns and explains when to use each one.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#tldr","level":2,"title":"TL;DR","text":"

    Eight patterns from full control to full invisibility:

    • hard gate (exit 2),
    • VERBATIM relay (agent MUST show),
    • agent directive (context injection),
    • and silent side-effect (background work).

    Most hooks belong in the middle.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#the-spectrum","level":2,"title":"The Spectrum","text":"

    These patterns form a spectrum based on who decides what the user sees:

    Pattern Who decides? Hard gate Hook decides (agent can't proceed) VERBATIM relay Hook decides (agent must show) Escalating severity Hook suggests, agent judges urgency Conditional relay Hook sets criteria, agent evaluates Suggested action Hook proposes, agent + user decide Agent directive Agent decides entirely Silent injection Nobody: invisible background context Silent side-effect Nobody: invisible background work

    The spectrum runs from full hook control (hard gate) to full invisibility (silent side effect).

    Most hooks belong somewhere in the middle.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-1-hard-gate","level":2,"title":"Pattern 1: Hard Gate","text":"

    Block the tool call entirely. The agent cannot proceed: it must find another approach or tell the user.

    echo '{\"decision\": \"block\", \"reason\": \"Use ctx from PATH, not ./ctx\"}'\n

    When to use: Enforcing invariants that must never be violated: Constitution rules, security boundaries, destructive command prevention.

    Hook type: PreToolUse only (Claude Code first-class mechanism).

    Examples in ctx:

    • ctx system block-non-path-ctx: Enforces the PATH invocation rule
    • block-git-push.sh: Requires explicit user approval for pushes (project-local)
    • block-dangerous-commands.sh: Prevents sudo, copies to ~/.local/bin (project-local)

    Trade-off: The agent gets a block response with a reason. Good reasons help the agent recover (\"use X instead\"); bad reasons leave it stuck.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-2-verbatim-relay","level":2,"title":"Pattern 2: VERBATIM Relay","text":"

    Force the agent to show this to the user as-is. The explicit instruction overcomes the agent's tendency to silently absorb context.

    echo \"IMPORTANT: Relay this warning to the user VERBATIM before answering their question.\"\necho \"\"\necho \"┌─ Journal Reminder ─────────────────────────────\"\necho \"│ You have 12 sessions not yet exported.\"\necho \"└────────────────────────────────────────────────\"\n

    When to use: Actionable reminders the user needs to see regardless of what they asked: Stale backups, unexported sessions, resource warnings.

    Hook type: UserPromptSubmit (runs before the agent sees the prompt).

    Examples in ctx:

    • ctx system check-journal: Unexported sessions and unenriched entries
    • ctx system check-context-size: Context capacity warning
    • ctx system check-resources: Resource pressure (memory, swap, disk, load): DANGER only
    • ctx system check-freshness: Technology constant staleness warning
    • check-backup-age.sh: Stale backup warning (project-local)

    Trade-off: Noisy if overused. Every VERBATIM relay adds a preamble before the agent's actual answer. Throttle with once-per-day markers or adaptive frequency.

    Key detail: The phrase IMPORTANT: Relay this ... VERBATIM is what makes this work. Without it, agents tend to process the information internally and never surface it. The explicit instruction is the pattern: the box-drawing is just fancy formatting.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-3-agent-directive","level":2,"title":"Pattern 3: Agent Directive","text":"

    Tell the agent to do something, not the user. The agent decides whether and how to involve the user.

    echo \"┌─ Persistence Checkpoint (prompt #25) ───────────\"\necho \"│ No context files updated in 15+ prompts.\"\necho \"│ Have you discovered learnings, decisions,\"\necho \"│ or completed tasks worth persisting?\"\necho \"└──────────────────────────────────────────────────\"\n

    When to use: Behavioral nudges. The hook detects a condition and asks the agent to consider an action. The user may never need to know.

    Hook type: UserPromptSubmit.

    Examples in ctx:

    • ctx system check-persistence: Nudges the agent to persist context

    Trade-off: No guarantee the agent acts. The nudge is one signal among many in the context window. Strong phrasing helps (\"Have you...?\" is better than \"Consider...\"), but ultimately the agent decides.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-4-silent-context-injection","level":2,"title":"Pattern 4: Silent Context Injection","text":"

    Load context with no visible output. The agent gets enriched without either party noticing.

    ctx agent --budget 4000 >/dev/null || true\n

    When to use: Background context loading that should be invisible. The agent benefits from the information, but neither it, nor the user needs to know it happened.

    Hook type: PreToolUse with .* matcher (runs on every tool call).

    Examples in ctx:

    • The ctx agent PreToolUse hook: injects project context silently

    Trade-off: Adds latency to every tool call. Keep the injected content small and fast to generate.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-5-silent-side-effect","level":2,"title":"Pattern 5: Silent Side-Effect","text":"

    Do work, produce no output: Housekeeping that needs no acknowledgment.

    find \"$CTX_TMPDIR\" -type f -mtime +15 -delete\n

    When to use: Cleanup, log rotation, temp file management. Anything where the action is the point and nobody needs to know it happened.

    Hook type: Any hook where output is irrelevant.

    Examples in ctx:

    • Log rotation, marker file cleanup, state directory maintenance

    Trade-off: None, if the action is truly invisible. If it can fail in a way that matters, consider logging.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-6-conditional-relay","level":3,"title":"Pattern 6: Conditional Relay","text":"

    Tell the agent to relay only if a condition holds in context.

    echo \"If the user's question involves modifying .context/ files,\"\necho \"relay this warning VERBATIM:\"\necho \"\"\necho \"┌─ Context Integrity ─────────────────────────────\"\necho \"│ CONSTITUTION.md has not been verified in 7 days.\"\necho \"└────────────────────────────────────────────────\"\necho \"\"\necho \"Otherwise, proceed normally.\"\n

    When to use: Warnings that only matter in certain contexts. Avoids noise when the user is doing unrelated work.

    Trade-off: Depends on the agent's judgment about when the condition holds. More fragile than VERBATIM relay, but less noisy.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-7-suggested-action","level":3,"title":"Pattern 7: Suggested Action","text":"

    Give the agent a specific command to propose to the user.

    echo \"┌─ Stale Dependencies ──────────────────────────\"\necho \"│ go.sum is 30+ days newer than go.mod.\"\necho \"│ Suggested: run \\`go mod tidy\\`\"\necho \"│ Ask the user before proceeding.\"\necho \"└───────────────────────────────────────────────\"\n

    When to use: The hook detects a fixable condition and knows the fix. Goes beyond a nudge: Gives the agent a concrete next step. The agent still asks for permission but knows exactly what to propose.

    Trade-off: The suggestion might be wrong or outdated. The \"ask the user before proceeding\" part is critical.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#pattern-8-escalating-severity","level":3,"title":"Pattern 8: Escalating Severity","text":"

    Different urgency tiers with different relay expectations.

    # INFO: agent processes silently, mentions if relevant\necho \"INFO: Last test run was 3 days ago.\"\n\n# WARN: agent should mention to user at next natural pause\necho \"WARN: 12 uncommitted changes across 3 branches.\"\n\n# CRITICAL: agent must relay immediately, before any other work\necho \"CRITICAL: Relay VERBATIM before answering. Disk usage at 95%.\"\n

    When to use: When you have multiple hooks producing output and need to avoid overwhelming the user. INFO gets absorbed, WARN gets mentioned, CRITICAL interrupts.

    Examples in ctx:

    • ctx system check-resources: Uses two tiers (WARNING/DANGER) internally but only fires the VERBATIM relay at DANGER level: WARNING is silent. See ctx system for the user-facing command that shows both tiers.

    Trade-off: Requires agent training or convention to recognize the tiers. Without a shared protocol, the prefixes are just text.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#choosing-a-pattern","level":2,"title":"Choosing a Pattern","text":"
    Is the agent about to do something forbidden?\n  └─ Yes → Hard gate\n\nDoes the user need to see this regardless of what they asked?\n  └─ Yes → VERBATIM relay\n  └─ Sometimes → Conditional relay\n\nShould the agent consider an action?\n  └─ Yes, with a specific fix → Suggested action\n  └─ Yes, open-ended → Agent directive\n\nIs this background context the agent should have?\n  └─ Yes → Silent injection\n\nIs this housekeeping?\n  └─ Yes → Silent side-effect\n
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#design-tips","level":2,"title":"Design Tips","text":"

    Throttle aggressively: VERBATIM relays that fire every prompt will be ignored or resented. Use once-per-day markers (touch $REMINDED), adaptive frequency (every Nth prompt), or staleness checks (only fire if condition persists).

    Include actionable commands: \"You have 12 unexported sessions\" is less useful than \"You have 12 unexported sessions. Run: ctx recall export --all.\" Give the user (or agent) the exact next step.

    Use box-drawing for visual structure: The ┌─ ─┐ │ └─ ─┘ pattern makes hook output visually distinct from agent prose. It also signals \"this is machine-generated, not agent opinion.\"

    Test the silence path: Most hook runs should produce no output (the condition isn't met). Make sure the common case is fast and silent.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#common-pitfalls","level":2,"title":"Common Pitfalls","text":"

    Lessons from 19 days of hook debugging in ctx. Every one of these was encountered, debugged, and fixed in production.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#silent-misfire-wrong-key-name","level":3,"title":"Silent Misfire: Wrong Key Name","text":"
    { \"PreToolUseHooks\": [ ... ] }\n

    The key is PreToolUse, not PreToolUseHooks. Claude Code validates silently: A misspelled key means the hook is ignored with no error. Always test with a debug echo first to confirm the hook fires before adding real logic.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#json-escaping-breaks-shell-commands","level":3,"title":"JSON Escaping Breaks Shell Commands","text":"

    Go's json.Marshal escapes >, <, and & as Unicode sequences (\\u003e) by default. This breaks shell commands in generated config:

    \"command\": \"ctx agent 2\\u003e/dev/null\"\n

    Fix: use json.Encoder with SetEscapeHTML(false) when generating hook configuration.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#stdin-not-environment-variables","level":3,"title":"stdin, Not Environment Variables","text":"

    Hook input arrives as JSON via stdin, not environment variables:

    # Wrong:\nCOMMAND=\"$CLAUDE_TOOL_INPUT\"\n\n# Right:\nHOOK_INPUT=$(cat)\nCOMMAND=$(echo \"$HOOK_INPUT\" | jq -r '.tool_input.command // empty')\n
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#regex-overfitting","level":3,"title":"Regex Overfitting","text":"

    A regex meant to catch ctx as a binary will also match ctx as a directory component:

    # Too broad: blocks: git -C /home/jose/WORKSPACE/ctx status\n(/home/|/tmp/|/var/)[^ ]*ctx[^ ]*\n\n# Narrow to binary only:\n(/home/|/tmp/|/var/)[^ ]*/ctx( |$)\n

    Test hook regexes against paths that contain the target string as a substring, not just as the final component.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#repetition-fatigue","level":3,"title":"Repetition Fatigue","text":"

    Injecting context on every tool call sounds safe. In practice, after seeing the same context injection fifteen times, the agent treats it as background noise: Conventions stated in the injected context get violated because salience has been destroyed by repetition.

    Fix: cooldowns. ctx agent --session $PPID --cooldown 10m injects at most once per ten minutes per session using a tombstone file in /tmp/. This is not an optimization; it is a correction for a design flaw. Every injection consumes attention budget: 50 tool calls at 4,000 tokens each means 200,000 tokens of repeated context, most of it wasted.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#hardcoded-paths","level":3,"title":"Hardcoded Paths","text":"

    A username rename (parallels to jose) broke every hook at once. Use $CLAUDE_PROJECT_DIR instead of absolute paths:

    \"command\": \"\\\"$CLAUDE_PROJECT_DIR\\\"/.claude/hooks/block-git-push.sh\"\n

    If the platform provides a runtime variable for paths, always use it.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#next-up","level":2,"title":"Next Up","text":"

    Webhook Notifications →: Get push notifications when loops complete, hooks fire, or agents hit milestones.

    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-output-patterns/#see-also","level":2,"title":"See Also","text":"
    • Customizing Hook Messages: override what hooks say without changing what they do
    • Claude Code Permission Hygiene: how permissions and hooks work together
    • Defense in Depth: why hooks matter for agent security
    ","path":["Recipes","Hooks and Notifications","Hook Output Patterns"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/","level":1,"title":"Hook Sequence Diagrams","text":"","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#hook-lifecycle","level":2,"title":"Hook Lifecycle","text":"

    Every ctx hook is a Go binary invoked by Claude Code at one of three lifecycle events: PreToolUse (before a tool runs, can block), PostToolUse (after a tool completes), or UserPromptSubmit (on every user prompt, before any tools run). Hooks receive JSON on stdin and emit JSON or plain text on stdout.

    This page documents the execution flow of every hook as a sequence diagram.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#pretooluse-hooks","level":2,"title":"PreToolUse Hooks","text":"

    These fire before a tool executes. They can block, gate, or inject context.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#context-load-gate","level":3,"title":"context-load-gate","text":"

    Matcher: .* (all tools)

    Injects the full context packet on first tool use of a session. One-shot per session.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as context-load-gate\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Git as git log\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized\n    alt not initialized\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Check paused\n    alt paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check ctx-loaded-{session} marker\n    alt marker exists\n        Hook-->>CC: (silent exit, already fired)\n    end\n    Hook->>State: Create marker (one-shot guard)\n    Hook->>State: Prune stale session files\n    loop Each file in ReadOrder\n        alt GLOSSARY or TASK\n            Note over Hook: Skip (Task mentioned in footer only)\n        else DECISION or LEARNING\n            Hook->>Ctx: Extract index table only\n        else other files\n            Hook->>Ctx: Read full content\n        end\n        Hook->>Hook: Estimate tokens per file\n    end\n    Hook->>Git: Detect changes since last session\n    Hook->>Hook: Build injection (files + changes + token counts)\n    Hook-->>CC: JSON {additionalContext: injection}\n    Hook->>Hook: Send webhook (metadata only)\n    Hook->>State: Write oversize flag if tokens > threshold
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#block-non-path-ctx","level":3,"title":"block-non-path-ctx","text":"

    Matcher: Bash

    Blocks ./ctx, go run ./cmd/ctx, or absolute-path ctx invocations. Constitutionally enforced.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as block-non-path-ctx\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Extract command\n    alt command empty\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Test regex: relative-path, go-run, absolute-path\n    alt no match\n        Hook-->>CC: (silent exit)\n    end\n    alt absolute-path + test exception\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Hook-->>CC: JSON {decision: BLOCK, reason + constitution suffix}\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#qa-reminder","level":3,"title":"qa-reminder","text":"

    Matcher: Bash

    Gate nudge before any git command. Reminds agent to lint/test.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as qa-reminder\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Check command contains \"git\"\n    alt no git command\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, gate, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: QA gate}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#specs-nudge","level":3,"title":"specs-nudge","text":"

    Matcher: EnterPlanMode

    Nudges agent to save plans/specs when new implementation detected.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as specs-nudge\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: specs nudge}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#posttooluse-hooks","level":2,"title":"PostToolUse Hooks","text":"

    These fire after a tool completes. They observe, nudge, and track state.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#post-commit","level":3,"title":"post-commit","text":"

    Matcher: Bash

    Fires after git commit (not amend). Nudges for context capture and checks version drift.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as post-commit\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Regex: command contains \"git commit\"?\n    alt not a git commit\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Regex: command contains \"--amend\"?\n    alt is amend\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook->>Hook: AppendDir(message)\n    Hook-->>CC: JSON {additionalContext: post-commit nudge}\n    Hook->>Hook: Relay(message)\n    Hook->>Hook: CheckVersionDrift()
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-task-completion","level":3,"title":"check-task-completion","text":"

    Matcher: Edit, Write

    Configurable-interval nudge after edits. Per-session counter resets after firing.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-task-completion\n    participant State as .context/state/\n    participant RC as .ctxrc\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>RC: Read task nudge interval\n    alt interval <= 0 (disabled)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Read per-session counter\n    Hook->>Hook: Increment counter\n    alt counter < interval\n        Hook->>State: Write counter\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Reset counter to 0\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook-->>CC: JSON {additionalContext: task nudge}\n    Hook->>Hook: Relay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#userpromptsubmit-hooks","level":2,"title":"UserPromptSubmit Hooks","text":"

    These fire on every user prompt, before any tools run. They perform health checks, track state, and nudge for housekeeping.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-context-size","level":3,"title":"check-context-size","text":"

    Adaptive context window monitoring. Fires checkpoints, window warnings, and billing alerts based on prompt count and token usage.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-context-size\n    participant State as .context/state/\n    participant Session as Session JSONL\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized\n    Hook->>Hook: Read input, resolve session ID\n    Hook->>Hook: Check paused\n    alt paused\n        Hook-->>CC: Pause acknowledgment message\n    end\n    Hook->>State: Increment session prompt counter\n    Hook->>Session: Read token info (tokens, model, window)\n\n    rect rgb(255, 240, 240)\n        Note over Hook: Billing check (independent, never suppressed)\n        alt tokens >= billing threshold (one-shot)\n            Hook->>Tpl: LoadMessage(hook, billing, vars)\n            Hook-->>CC: Billing warning nudge box\n            Hook->>Hook: NudgeAndRelay(billing message)\n        end\n    end\n\n    Hook->>State: Check wrap-up marker\n    alt wrapped up recently (< 2h)\n        Hook->>State: Write stats (event: suppressed)\n        Hook-->>CC: (silent exit)\n    end\n\n    rect rgb(240, 248, 255)\n        Note over Hook: Adaptive frequency check\n        alt count > 30 and count % 3 == 0\n            Note over Hook: High frequency trigger\n        else count > 15 and count % 5 == 0\n            Note over Hook: Medium frequency trigger\n        else\n            Hook->>State: Write stats (event: silent)\n            Hook-->>CC: (silent exit)\n        end\n    end\n\n    alt context window >= 80%\n        Hook->>Tpl: LoadMessage(hook, window, vars)\n        Hook-->>CC: Window warning nudge box\n        Hook->>Hook: NudgeAndRelay(window message)\n    else checkpoint trigger\n        Hook->>Tpl: LoadMessage(hook, checkpoint)\n        Hook-->>CC: Checkpoint nudge box\n        Hook->>Hook: NudgeAndRelay(checkpoint message)\n    end\n    Hook->>State: Write session stats
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-ceremonies","level":3,"title":"check-ceremonies","text":"

    Daily check for /ctx-remember and /ctx-wrap-up usage in recent journal entries.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-ceremonies\n    participant State as .context/state/\n    participant Journal as Journal files\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Read recent files (lookback window)\n    alt no journal files\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Scan for /ctx-remember and /ctx-wrap-up\n    alt both ceremonies present\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Note over Hook: variant: both | remember | wrapup\n    Hook-->>CC: Nudge box (missing ceremonies)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-freshness","level":3,"title":"check-freshness","text":"

    Daily check for technology-dependent constants that may need review.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-freshness\n    participant State as .context/state/\n    participant FS as Filesystem\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>FS: Stat tracked files (5 source files)\n    alt all files modified within 6 months\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, stale, {StaleFiles})\n    Hook-->>CC: Nudge box (stale file list + review URL)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-journal","level":3,"title":"check-journal","text":"

    Daily check for unexported sessions and unenriched journal entries.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-journal\n    participant State as .context/state/\n    participant Journal as Journal dir\n    participant Claude as Claude projects dir\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Check dir exists\n    Hook->>Claude: Check dir exists\n    alt either dir missing\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Journal: Get newest entry mtime\n    Hook->>Claude: Count .jsonl files newer than journal\n    Hook->>Journal: Count unenriched entries\n    alt unexported == 0 and unenriched == 0\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, {counts})\n    Note over Hook: variant: both | unexported | unenriched\n    Hook-->>CC: Nudge box (counts)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-knowledge","level":3,"title":"check-knowledge","text":"

    Daily check for knowledge file entry/line counts exceeding configured thresholds.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-knowledge\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant RC as .ctxrc\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>RC: Read thresholds (decisions, learnings, conventions)\n    alt all thresholds disabled (0)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Ctx: Parse DECISIONS.md entry count\n    Hook->>Ctx: Parse LEARNINGS.md entry count\n    Hook->>Ctx: Count CONVENTIONS.md lines\n    Hook->>Hook: Compare against thresholds\n    alt all within limits\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, warning, {FileWarnings})\n    Hook-->>CC: Nudge box (file warnings)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-map-staleness","level":3,"title":"check-map-staleness","text":"

    Daily check for architecture map age and relevant code changes.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-map-staleness\n    participant State as .context/state/\n    participant Tracking as map-tracking.json\n    participant Git as git log\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tracking: Read map-tracking.json\n    alt missing, invalid, or opted out\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Parse LastRun date\n    alt map not stale (< N days)\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Git: Count commits touching internal/ since LastRun\n    alt no relevant commits\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, stale, {date, count})\n    Hook-->>CC: Nudge box (last refresh + commit count)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-memory-drift","level":3,"title":"check-memory-drift","text":"

    Per-session check for MEMORY.md changes since last sync.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-memory-drift\n    participant State as .context/state/\n    participant Mem as memory.Discover\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check session tombstone\n    alt already nudged this session\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Mem: DiscoverMemoryPath(projectRoot)\n    alt auto memory not active\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Mem: HasDrift(contextDir, sourcePath)\n    alt no drift\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, fallback)\n    Hook-->>CC: Nudge box (drift reminder)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch session tombstone
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-persistence","level":3,"title":"check-persistence","text":"

    Tracks context file modification and nudges when edits happen without persisting context. Adaptive threshold based on prompt count.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-persistence\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Read persistence state {Count, LastNudge, LastMtime}\n    alt first prompt (no state)\n        Hook->>State: Initialize state {Count:1, LastNudge:0, LastMtime:now}\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Increment Count\n    Hook->>Ctx: Get current context mtime\n    alt context modified since LastMtime\n        Hook->>State: Reset LastNudge = Count, update LastMtime\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: sinceNudge = Count - LastNudge\n    Hook->>Hook: PersistenceNudgeNeeded(Count, sinceNudge)?\n    alt threshold not reached\n        Hook->>State: Write state\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, nudge, vars)\n    Hook-->>CC: Nudge box (prompt count, time since last persist)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Update LastNudge = Count, write state
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-reminders","level":3,"title":"check-reminders","text":"

    Per-prompt check for due reminders. No throttle.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-reminders\n    participant Store as Reminders store\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Store: ReadReminders()\n    alt load error\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Filter by due date (After <= today)\n    alt no due reminders\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, reminders, {list})\n    Hook-->>CC: Nudge box (reminder list + dismiss hints)\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-resources","level":3,"title":"check-resources","text":"

    Checks system resources (memory, swap, disk, load). Fires on every prompt. No initialization required.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-resources\n    participant Sys as sysinfo\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: HookPreamble (parse input, check pause)\n    alt paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Sys: Collect snapshot (memory, swap, disk, load)\n    Hook->>Sys: Evaluate thresholds per metric\n    alt max severity < Danger\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Filter alerts to Danger level only\n    Hook->>Hook: Build alertMessages from danger alerts\n    Hook->>Tpl: LoadMessage(hook, alert, {alertMessages}, fallback)\n    Hook-->>CC: Nudge box (danger alerts)\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-version","level":3,"title":"check-version","text":"

    Daily binary-vs-plugin version comparison with piggybacked key rotation check.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-version\n    participant State as .context/state/\n    participant Config as Binary + Plugin version\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Config: Read binary version\n    alt dev build\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Config: Read plugin version\n    alt plugin version not found or parse error\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Hook: Compare major.minor\n    alt versions match\n        Hook->>State: Touch throttle\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, mismatch, {versions})\n    Hook-->>CC: Nudge box (version mismatch)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle\n    Hook->>Hook: CheckKeyAge() (piggybacked)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#heartbeat","level":3,"title":"heartbeat","text":"

    Silent per-prompt pulse. Tracks prompt count, context modification, and token usage. The agent never sees this hook's output.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as heartbeat\n    participant State as .context/state/\n    participant Ctx as .context/ files\n    participant Notify as Webhook + EventLog\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Increment heartbeat counter\n    Hook->>Ctx: Get latest context file mtime\n    Hook->>State: Compare with last recorded mtime\n    Hook->>State: Update mtime record\n    Hook->>State: Read session token info\n    Hook->>Notify: Send heartbeat notification\n    Hook->>Notify: Append to event log\n    Hook->>State: Write heartbeat log entry\n    Note over Hook: No stdout - agent never sees this
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#project-local-hooks","level":2,"title":"Project-Local Hooks","text":"

    These hooks are configured in settings.local.json and are not shipped with ctx. They are specific to individual developer setups.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#block-dangerous-commands","level":3,"title":"block-dangerous-commands","text":"

    Lifecycle: PreToolUse. Matcher: Bash

    Blocks dangerous shell patterns (sudo, git push, cp to bin). No initialization or pause checks: always active.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as block-dangerous-commands\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {command, session_id}\n    Hook->>Hook: Extract command\n    alt command empty\n        Hook-->>CC: (silent exit)\n    end\n    Note over Hook: Cascade: first matching regex wins\n    Hook->>Hook: Test MidSudo regex\n    alt match\n        Hook->>Hook: variant = sudo\n    end\n    Hook->>Hook: Test MidGitPush regex (if no variant)\n    alt match\n        Hook->>Hook: variant = git-push\n    end\n    Hook->>Hook: Test CpMvToBin regex (if no variant)\n    alt match\n        Hook->>Hook: variant = cp-to-bin\n    end\n    Hook->>Hook: Test InstallToLocalBin regex (if no variant)\n    alt match\n        Hook->>Hook: variant = install-to-bin\n    end\n    alt no variant matched\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, variant, fallback)\n    Hook-->>CC: JSON {decision: BLOCK, reason}\n    Hook->>Hook: NudgeAndRelay(message)
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#check-backup-age","level":3,"title":"check-backup-age","text":"

    Lifecycle: UserPromptSubmit.

    Daily check for SMB mount and backup freshness.

    sequenceDiagram\n    participant CC as Claude Code\n    participant Hook as check-backup-age\n    participant State as .context/state/\n    participant FS as Filesystem\n    participant Tpl as Message Template\n\n    CC->>Hook: stdin {session_id}\n    Hook->>Hook: Check initialized + HookPreamble\n    alt not initialized or paused\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>State: Check daily throttle marker\n    alt throttled\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>FS: Check SMB mount (if env var set)\n    Hook->>FS: Check backup marker file age\n    alt no warnings\n        Hook-->>CC: (silent exit)\n    end\n    Hook->>Tpl: LoadMessage(hook, warning, {Warnings})\n    Hook-->>CC: Nudge box (warnings)\n    Hook->>Hook: NudgeAndRelay(message)\n    Hook->>State: Touch throttle marker
    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#throttling-summary","level":2,"title":"Throttling Summary","text":"Hook Lifecycle Throttle Type Scope context-load-gate PreToolUse One-shot marker Per session block-non-path-ctx PreToolUse None Every match qa-reminder PreToolUse None Every git command specs-nudge PreToolUse None Every prompt post-commit PostToolUse None Every git commit check-task-completion PostToolUse Configurable interval Per session check-context-size UserPromptSubmit Adaptive counter Per session check-ceremonies UserPromptSubmit Daily marker Once per day check-freshness UserPromptSubmit Daily marker Once per day check-journal UserPromptSubmit Daily marker Once per day check-knowledge UserPromptSubmit Daily marker Once per day check-map-staleness UserPromptSubmit Daily marker Once per day check-memory-drift UserPromptSubmit Session tombstone Once per session check-persistence UserPromptSubmit Adaptive counter Per session check-reminders UserPromptSubmit None Every prompt check-resources UserPromptSubmit None Every prompt check-version UserPromptSubmit Daily marker Once per day heartbeat UserPromptSubmit None Every prompt block-dangerous-commands PreToolUse * None Every match check-backup-age UserPromptSubmit * Daily marker Once per day

    * Project-local hook (settings.local.json), not shipped with ctx.

    ","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/hook-sequence-diagrams/#state-file-reference","level":2,"title":"State File Reference","text":"

    All state files live in .context/state/.

    File Pattern Hook Purpose ctx-loaded-{session} context-load-gate One-shot injection marker ctx-paused-{session} (all) Session pause marker ctx-wrapped-up check-context-size Suppress nudges after wrap-up (2h expiry) freshness-checked check-freshness Daily throttle backup-reminded check-backup-age Daily throttle ceremony-reminded check-ceremonies Daily throttle journal-reminded check-journal Daily throttle knowledge-reminded check-knowledge Daily throttle map-staleness-reminded check-map-staleness Daily throttle version-checked check-version Daily throttle memory-drift-nudged-{session} check-memory-drift Per-session tombstone ctx-context-count-{session} check-context-size Prompt counter stats-{session}.jsonl check-context-size Session stats log persist-{session} check-persistence Counter + mtime state ctx-task-count-{session} check-task-completion Prompt counter heartbeat-count-{session} heartbeat Prompt counter heartbeat-mtime-{session} heartbeat Last context mtime","path":["Hook Sequence Diagrams"],"tags":[]},{"location":"recipes/import-plans/","level":1,"title":"Importing Claude Code Plans","text":"","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code plan files (~/.claude/plans/*.md) are ephemeral: They have structured context, approach, and file lists, but they're orphaned after the session ends. The filenames are UUIDs, so you can't tell what's in them without opening each one.

    How do you turn a useful plan into a permanent project spec?

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#tldr","level":2,"title":"TL;DR","text":"
    You: /ctx-import-plans\nAgent: [lists plans with dates and titles]\n       1. 2026-02-28  Add authentication middleware\n       2. 2026-02-27  Refactor database connection pool\nYou: \"import 1\"\nAgent: [copies to specs/add-authentication-middleware.md]\n

    Plans are copied (not moved) to specs/, slugified by their H1 heading.

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-import-plans Skill List, filter, and import plan files to specs /ctx-add-task Skill Optionally add a task referencing the spec","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-1-list-available-plans","level":3,"title":"Step 1: List Available Plans","text":"

    Invoke the skill and it lists plans with modification dates and titles:

    You: /ctx-import-plans\n\nAgent: Found 3 plan files:\n         1. 2026-02-28  Add authentication middleware\n         2. 2026-02-27  Refactor database connection pool\n         3. 2026-02-25  Import plans skill\n       Which plans would you like to import?\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-2-filter-optional","level":3,"title":"Step 2: Filter (Optional)","text":"

    You can narrow the list with arguments:

    Argument Effect --today Only plans modified today --since YYYY-MM-DD Only plans modified on or after the date --all Import everything without prompting (none) Interactive selection 
    You: /ctx-import-plans --today\nYou: /ctx-import-plans --since 2026-02-27\nYou: /ctx-import-plans --all\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-3-select-and-import","level":3,"title":"Step 3: Select and Import","text":"

    Pick one or more plans by number:

    You: \"import 1 and 3\"\n\nAgent: Imported 2 plan(s):\n         ~/.claude/plans/abc123.md -> specs/add-authentication-middleware.md\n         ~/.claude/plans/ghi789.md -> specs/import-plans-skill.md\n       Want me to add tasks referencing these specs?\n

    The agent reads the H1 heading from each plan and slugifies it for the filename. If a plan has no H1 heading, the original filename (minus extension) is used as the slug.

    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#step-4-add-follow-up-tasks-optional","level":3,"title":"Step 4: Add Follow-Up Tasks (Optional)","text":"

    If you say yes, the agent creates tasks in TASKS.md that reference the imported specs:

    You: \"yes, add tasks\"\n\nAgent: [runs /ctx-add-task for each spec]\n       Added:\n         - [ ] Implement authentication middleware (spec: specs/add-authentication-middleware.md)\n         - [ ] Import plans skill (spec: specs/import-plans-skill.md)\n
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember the exact skill name:

    You say What happens \"import my plans\" /ctx-import-plans (interactive) \"save today's plans as specs\" /ctx-import-plans --today \"import all plans from this week\" /ctx-import-plans --since ... \"turn that plan into a spec\" /ctx-import-plans (filtered)","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#tips","level":2,"title":"Tips","text":"
    • Plans are copied, not moved: The originals stay in ~/.claude/plans/. Claude Code manages that directory; ctx doesn't delete from it.
    • Conflict handling: If specs/{slug}.md already exists, the agent asks whether to overwrite or pick a different name.
    • Specs are project memory: Once imported, specs are tracked in git and available to future sessions. Reference them from TASKS.md phase headers with Spec: specs/slug.md.
    • Pair with /ctx-implement: After importing a plan as a spec, use /ctx-implement to execute it step-by-step with verification.
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/import-plans/#see-also","level":2,"title":"See Also","text":"
    • Skills Reference: /ctx-import-plans: full skill description
    • The Complete Session: where plan import fits in the session flow
    • Tracking Work Across Sessions: managing tasks that reference imported specs
    ","path":["Recipes","Knowledge and Tasks","Importing Claude Code Plans"],"tags":[]},{"location":"recipes/knowledge-capture/","level":1,"title":"Persisting Decisions, Learnings, and Conventions","text":"","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#the-problem","level":2,"title":"The Problem","text":"

    You debug a subtle issue, discover the root cause, and move on.

    Three weeks later, a different session hits the same issue. The knowledge existed briefly in one session's memory but was never written down.

    Architectural decisions suffer the same fate: you weigh trade-offs, pick an approach, and six sessions later the AI suggests the alternative you already rejected.

    How do you make sure important context survives across sessions?

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-reflect               # surface items worth persisting\n/ctx-add-decision \"Title\"  # record with context/rationale/consequence\n/ctx-add-learning \"Title\"  # record with context/lesson/application\n

    Or just tell your agent: \"What have we learned this session?\"

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx add decision Command Record an architectural decision ctx add learning Command Record a gotcha, tip, or lesson ctx add convention Command Record a coding pattern or standard ctx reindex Command Rebuild both quick-reference indices ctx decision reindex Command Rebuild the DECISIONS.md index ctx learning reindex Command Rebuild the LEARNINGS.md index /ctx-add-decision Skill AI-guided decision capture with validation /ctx-add-learning Skill AI-guided learning capture with validation /ctx-add-convention Skill AI-guided convention recording with placement /ctx-reflect Skill Surface items worth persisting at breakpoints","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#the-workflow","level":2,"title":"The Workflow","text":"

    Decision, Learning, or Convention?

    • If you chose between alternatives, it is a decision.
    • If you discovered something surprising, it is a learning.
    • If you are codifying a repeated pattern, it is a convention.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-1-understand-what-to-persist","level":3,"title":"Step 1: Understand What to Persist","text":"

    Three context files serve different purposes:

    Decisions (DECISIONS.md) answer \"why is it this way?\" They record trade-offs between alternatives with structured fields: context, rationale, and consequences. Decisions prevent re-debating settled questions.

    Learnings (LEARNINGS.md) answer \"what did we discover the hard way?\" They record gotchas and debugging insights specific to this project with structured fields: context, lesson, and application.

    Learnings prevent repeating past mistakes.

    Conventions (CONVENTIONS.md) answer \"how do we do things here?\" They record patterns and standards. No structured fields required: just a name, a rule, and an example. Conventions keep code consistent across sessions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-2-record-decisions","level":3,"title":"Step 2: Record Decisions","text":"

    Decisions have three structured fields:

    • context,
    • rationale,
    • and consequences.

    The easiest way to record one is to tell your agent:

    You: \"Save that as a decision: we picked file-based cooldown\n      tokens over env vars.\"\n\nAgent: \"Recorded in DECISIONS.md:\n  - Decision: Use file-based cooldown tokens instead of env vars\n  - Context: Hook subprocesses cannot persist env vars to parent shell\n  - Rationale: File tokens survive across processes. Simpler than\n    IPC. Cleanup is automatic via TTL.\n  - Consequence: Tombstone files accumulate in /tmp. Cannot share\n    state across machines.\"\n

    The agent was present for the trade-off discussion. It fills in the structured fields from what it observed, which is hard to reconstruct later as a terminal one-liner.

    When multiple options were considered, the agent includes rejected alternatives in the rationale automatically.

    The /ctx-add-decision skill also guides you through the fields interactively. For quick decisions, it supports a Y-statement:

    \"In the context of [situation], facing [constraint], we decided for [choice] and against [alternatives], to achieve [benefit], accepting that [trade-off].\"

    CLI Command for Scripting and Automation

    When no agent is in the loop (CI pipelines, shell scripts, hooks), use the CLI directly with structured flags:

    ctx add decision \"Use file-based cooldown tokens instead of env vars\" \\\n  --context \"Hook subprocesses cannot persist env vars to parent shell\" \\\n  --rationale \"File tokens survive across processes. Simpler than IPC. Cleanup is automatic via TTL.\" \\\n  --consequence \"Tombstone files accumulate in /tmp. Cannot share state across machines.\"\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-3-record-learnings","level":3,"title":"Step 3: Record Learnings","text":"

    Learnings have three structured fields: context, lesson, and application.

    Again, your agent is the best tool for this. It was there when you discovered the gotcha and can express it more completely than a backslash-escaped terminal command:

    You: \"That subprocess thing was painful. Save it as a learning.\"\n\nAgent: \"Added to LEARNINGS.md:\n  - Learning: Claude Code hooks run in a subprocess\n  - Context: Set env var in PreToolUse hook, but it was not visible\n    in the main session\n  - Lesson: Hook scripts execute in a child process. Env changes do\n    not propagate to parent.\n  - Application: Use tombstone files for hook-to-session\n    communication. Never rely on hook env vars.\"\n

    You said one sentence. The agent produced a structured entry with all three fields filled from the session context.

    That is the point: the agent has the full conversation and can be far more expressive than what you would type at a command prompt.

    The /ctx-add-learning skill applies three quality filters:

    1. Could someone Google this in 5 minutes?
    2. Is it specific to this codebase?
    3. Did it take real effort to discover?

    All three must pass.

    Learnings capture principles and heuristics, not code snippets.

    CLI Command for Scripting and Automation

    When no agent is in the loop:

    ctx add learning \"Claude Code hooks run in a subprocess\" \\\n  --context \"Set env var in PreToolUse hook, but it was not visible in the main session\" \\\n  --lesson \"Hook scripts execute in a child process. Env changes do not propagate to parent.\" \\\n  --application \"Use tombstone files for hook-to-session communication. Never rely on hook env vars.\"\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-4-record-conventions","level":3,"title":"Step 4: Record Conventions","text":"

    Conventions are simpler: just a name, a rule, and optionally a section.

    These are short enough that either approach works:

    You: \"We've been using kebab-case for every CLI flag. Codify that.\"\n\nAgent: \"Added to CONVENTIONS.md under Naming:\n  'Use kebab-case for all CLI flag names.'\"\n

    Or from the terminal:

    ctx add convention \"Use kebab-case for all CLI flag names\" --section \"Naming\"\n

    Conventions work best for rules that come up repeatedly. Codify a pattern the third time you see it, not the first.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-5-reindex-after-manual-edits","level":3,"title":"Step 5: Reindex After Manual Edits","text":"

    DECISIONS.md and LEARNINGS.md maintain a quick-reference index at the top: a compact table of date and title for each entry. The index updates automatically via ctx add, but falls out of sync after hand edits.

    ctx reindex\n

    This single command regenerates both indices. You can also reindex individually with ctx decision reindex or ctx learning reindex.

    Run reindex after any manual edit. The index lets AI tools scan all entries without reading the full file, which matters when token budgets are tight.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-6-use-ctx-reflect-to-surface-what-to-capture","level":3,"title":"Step 6: Use /ctx-reflect to Surface What to Capture","text":"

    Keep It Conversational

    /ctx-reflect is not the only way to trigger reflection.

    Agents trained on the ctx playbook naturally surface persist-worthy items at breakpoints, even without invoking the skill explicitly.

    A conversational prompt like \"anything worth saving?\" or \"let's wrap up\" can trigger the same review.

    The skill provides a structured checklist, but the behavior is available through natural conversation.

    At natural breakpoints (after completing a feature, fixing a bug, or before ending a session) use /ctx-reflect to identify items worth persisting.

    /ctx-reflect\n

    The skill walks through learnings, decisions, tasks, and session notes, skipping categories with nothing to report. The output includes specific commands for each suggested persist:

    This session implemented file-based cooldown for `ctx agent` and\ndiscovered that hook subprocesses cannot set env vars in the parent.\n\nI'd suggest persisting:\n- **Learning**: Hook subprocesses cannot propagate env vars\n  `ctx add learning \"...\" --context \"...\" --lesson \"...\" --application \"...\"`\n- **Decision**: File-based cooldown tokens over env vars\n  `ctx add decision \"...\" --context \"...\" --rationale \"...\" --consequence \"...\"`\n\nWant me to persist any of these?\n

    The skill always asks before persisting.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#step-7-the-conversational-approach","level":3,"title":"Step 7: The Conversational Approach","text":"

    The commands shown in Steps 2 to 4 are precise, but you rarely need to type them yourself. When working with an agent that has loaded the ctx playbook, natural language triggers the same operations.

    You ask, the agent acts:

    You say What the agent does \"What have we learned this session?\" Reviews recent work, identifies learnings, offers to persist \"Save that as a decision\" Captures the trade-off you just discussed with structured fields \"Any gotchas worth remembering?\" Scans recent work for non-obvious lessons \"Record that convention\" Adds the pattern you just agreed on to CONVENTIONS.md \"Let's wrap up\" Runs through the reflect checklist conversationally

    Example exchange:

    You: \"What did we learn from that debugging session?\"\n\nAgent: \"We discovered three things worth persisting:\n  1. Hook subprocesses can't propagate env vars to the parent. We\n     spent 20 minutes on this before switching to tombstone files.\n  2. Tombstone files need a TTL or they accumulate in /tmp.\n  3. The cooldown logic must check file mtime, not just existence.\n  Want me to save these as learnings?\"\n\nYou: \"Yes, all of them.\"\n\nAgent: \"Done. Added all three to LEARNINGS.md with structured fields.\"\n

    The agent can also be proactive without being asked. The playbook encourages agents to persist context at natural milestones.

    You may see:

    • After fixing a tricky bug: \"I noticed this was a non-obvious issue. Want me to save it as a learning?\"
    • After choosing between approaches: \"We just made a trade-off between file-based tokens and IPC. Should I record this as a decision?\"
    • At session milestones: the agent checks what is worth persisting and offers a brief summary.

    When agents run unattended (no human in the loop), they may persist directly:

    • \"I've added the subprocess env var gotcha to LEARNINGS.md so we don't hit it again.\"
    • \"Recorded the decision to use file-based tokens over env vars in DECISIONS.md.\"
    • \"Marked the cooldown task done and added a follow-up for TTL cleanup.\"

    This is behavior by design.

    The playbook's self-check prompt, \"If this session ended right now, would the next session know what happened?\" drives agents to persist early and often rather than waiting for explicit instructions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#command-line-approach-scripting-and-automation","level":3,"title":"Command-line Approach (Scripting and Automation)","text":"
    # Decision: record the trade-off\nctx add decision \"Use PostgreSQL over SQLite\" \\\n  --context \"Need concurrent multi-user access\" \\\n  --rationale \"SQLite locks on writes; Postgres handles concurrency\" \\\n  --consequence \"Requires a database server; team needs Postgres training\"\n\n# Learning: record the gotcha\nctx add learning \"SQL migrations must be idempotent\" \\\n  --context \"Deploy failed when migration ran twice after rollback\" \\\n  --lesson \"CREATE TABLE without IF NOT EXISTS fails on retry\" \\\n  --application \"Always use IF NOT EXISTS guards in migrations\"\n\n# Convention: record the pattern\nctx add convention \"API handlers return structured errors\" --section \"API\"\n\n# Reindex after manual edits\nctx reindex\n\n# Reflect at breakpoints (from AI assistant)\n# /ctx-reflect\n
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#conversational-approach-interactive-sessions","level":3,"title":"Conversational Approach (Interactive Sessions)","text":"
    You: \"We just picked Postgres over SQLite for the concurrency\n      reasons. Save that?\"\n\nAgent: \"Recorded. Added to DECISIONS.md:\n  - Decision: Use PostgreSQL over SQLite\n  - Context: Need concurrent multi-user access\n  - Rationale: SQLite locks on writes; Postgres handles concurrency\n  - Consequence: Requires a database server; team needs Postgres\n    training\"\n\nYou: \"Also that migration thing. The deploy blew up when the\n      migration ran twice.\"\n\nAgent: \"Got it. Added to LEARNINGS.md:\n  - Learning: SQL migrations must be idempotent\n  - Lesson: CREATE TABLE without IF NOT EXISTS fails on retry\n  - Application: Always use IF NOT EXISTS guards in migrations\"\n\nYou: \"Good. Anything else worth saving before we wrap up?\"\n\nAgent: \"We've been using structured error returns in every API\n  handler this session. Want me to codify that as a convention?\"\n\nYou: \"Do it.\"\n\nAgent: \"Done. Added 'API handlers return structured errors' to\n  CONVENTIONS.md under the API section.\"\n

    Both approaches produce the same structured entries in the same context files.

    • The conversational approach is the natural fit for interactive sessions;
    • the CLI commands are better suited for scripts, hooks, and automation pipelines.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#tips","level":2,"title":"Tips","text":"
    • Record decisions at the moment of choice. The alternatives you considered and the reasons you rejected them fade quickly. Capture trade-offs while they are fresh.
    • Learnings should fail the Gemini test. If someone could find it in a 5-minute Gemini search, it does not belong in LEARNINGS.md.
    • Conventions earn their place through repetition. Add a convention the third time you see a pattern, not the first.
    • Use /ctx-reflect at natural breakpoints. The checklist catches items you might otherwise lose.
    • Keep the entries self-contained. Each entry should make sense on its own. A future session may load only one due to token budget constraints.
    • Reindex after every hand edit. It takes less than a second. A stale index causes AI tools to miss entries.
    • Prefer the structured fields. The verbosity forces clarity. A decision without a rationale is just a fact. A learning without an application is just a story.
    • Talk to your agent, do not type commands. In interactive sessions, the conversational approach is the recommended way to capture knowledge. Say \"save that as a learning\" or \"any decisions worth recording?\" and let the agent handle the structured fields. Reserve the CLI commands for scripting, automation, and CI/CD pipelines where there is no agent in the loop.
    • Trust the agent's proactive instincts. Agents trained on the ctx playbook will offer to persist context at milestones. A brief \"want me to save this?\" is cheaper than re-discovering the same lesson three sessions later.
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#next-up","level":2,"title":"Next Up","text":"

    Tracking Work Across Sessions →: Add, prioritize, complete, and archive tasks across sessions.

    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/knowledge-capture/#see-also","level":2,"title":"See Also","text":"
    • Tracking Work Across Sessions: managing the tasks that decisions and learnings support
    • The Complete Session: full session lifecycle including reflection and context persistence
    • Detecting and Fixing Drift: keeping knowledge files accurate as the codebase evolves
    • CLI Reference: full documentation for ctx add, ctx decision, ctx learning
    • Context Files: format and conventions for DECISIONS.md, LEARNINGS.md, and CONVENTIONS.md
    ","path":["Recipes","Knowledge and Tasks","Persisting Decisions, Learnings, and Conventions"],"tags":[]},{"location":"recipes/memory-bridge/","level":1,"title":"Bridging Claude Code Auto Memory","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code maintains per-project auto memory at ~/.claude/projects/<slug>/memory/MEMORY.md. This file is:

    • Outside the repo - not version-controlled, not portable
    • Machine-specific - tied to one ~/.claude/ directory
    • Invisible to ctx - context loading and hooks don't read it

    Meanwhile, ctx maintains structured context files (DECISIONS.md, LEARNINGS.md, CONVENTIONS.md) that are git-tracked, portable, and token-budgeted - but Claude Code doesn't automatically write to them.

    The two systems hold complementary knowledge with no bridge between them.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#tldr","level":2,"title":"TL;DR","text":"
    ctx memory sync          # Mirror MEMORY.md into .context/memory/mirror.md\nctx memory status        # Check for drift\nctx memory diff          # See what changed since last sync\n

    The check-memory-drift hook nudges automatically when MEMORY.md changes - you don't need to remember to sync manually.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx memory sync CLI command Copy MEMORY.md to mirror, archive previous ctx memory status CLI command Show drift, timestamps, line counts ctx memory diff CLI command Show changes since last sync ctx memory import CLI command Classify and promote entries to .context/ files ctx memory publish CLI command Push curated .context/ content to MEMORY.md ctx memory unpublish CLI command Remove published block from MEMORY.md ctx system check-memory-drift Hook Nudge when MEMORY.md has changed (once/session)","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#how-it-works","level":2,"title":"How It Works","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#discovery","level":3,"title":"Discovery","text":"

    Claude Code encodes project paths as directory names under ~/.claude/projects/. The encoding replaces / with - and prefixes with -:

    /home/jose/WORKSPACE/ctx  →  ~/.claude/projects/-home-jose-WORKSPACE-ctx/\n

    ctx memory uses this encoding to locate MEMORY.md automatically from your project root - no configuration needed.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#mirroring","level":3,"title":"Mirroring","text":"

    When you run ctx memory sync:

    1. The previous mirror is archived to .context/memory/archive/mirror-<timestamp>.md
    2. MEMORY.md is copied to .context/memory/mirror.md
    3. Sync state is updated in .context/state/memory-import.json

    The mirror is git-tracked, so it travels with the project. Archives provide a fallback for projects that don't use git.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#drift-detection","level":3,"title":"Drift Detection","text":"

    The check-memory-drift hook compares MEMORY.md's modification time against the mirror. When drift is detected, the agent sees:

    ┌─ Memory Drift ────────────────────────────────────────────────\n│ MEMORY.md has changed since last sync.\n│ Run: ctx memory sync\n│ Context: .context\n└────────────────────────────────────────────────────────────────\n

    The nudge fires once per session to avoid noise.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#typical-workflow","level":2,"title":"Typical Workflow","text":"","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#at-session-start","level":3,"title":"At Session Start","text":"

    If the hook fires a drift nudge, sync before diving into work:

    ctx memory diff     # Review what changed\nctx memory sync     # Mirror the changes\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#periodic-check","level":3,"title":"Periodic Check","text":"
    ctx memory status\n# Memory Bridge Status\n#   Source:      ~/.claude/projects/.../memory/MEMORY.md\n#   Mirror:      .context/memory/mirror.md\n#   Last sync:   2026-03-05 14:30 (2 hours ago)\n#\n#   MEMORY.md:  47 lines\n#   Mirror:     32 lines\n#   Drift:      detected (source is newer)\n#   Archives:   3 snapshots in .context/memory/archive/\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#dry-run","level":3,"title":"Dry Run","text":"

    Preview what sync would do without writing:

    ctx memory sync --dry-run\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#storage-layout","level":2,"title":"Storage Layout","text":"
    .context/\n├── memory/\n│   ├── mirror.md                          # Raw copy of MEMORY.md (often git-tracked)\n│   └── archive/\n│       ├── mirror-2026-03-05-143022.md    # Timestamped pre-sync snapshots\n│       └── mirror-2026-03-04-220015.md\n├── state/\n│   └── memory-import.json                 # Sync tracking state\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#edge-cases","level":2,"title":"Edge Cases","text":"Scenario Behavior Auto memory not active sync exits 1 with message. status reports \"not active\". Hook skips silently. First sync (no mirror) Creates mirror without archiving. MEMORY.md is empty Syncs to empty mirror (valid). Not initialized Init guard rejects (same as all ctx commands).","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#importing-entries","level":2,"title":"Importing Entries","text":"

    Once you've synced, you can classify and promote entries into structured .context/ files:

    ctx memory import --dry-run    # Preview classification\nctx memory import              # Actually promote entries\n

    Each entry is classified by keyword heuristics:

    Keywords Target always use, prefer, never use, standard CONVENTIONS.md decided, chose, trade-off, approach DECISIONS.md gotcha, learned, watch out, bug, caveat LEARNINGS.md todo, need to, follow up TASKS.md Everything else Skipped

    Entries that don't match any pattern are skipped - they stay in the mirror for manual review. Deduplication (hash-based) prevents re-importing the same entry on subsequent runs.

    Review Before Importing

    Use --dry-run first. The heuristic classifier is deliberately simple - it may misclassify ambiguous entries. Review the plan, then import.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#full-workflow","level":3,"title":"Full Workflow","text":"
    ctx memory sync                # 1. Mirror MEMORY.md\nctx memory import --dry-run    # 2. Preview what would be imported\nctx memory import              # 3. Promote entries to .context/ files\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#publishing-context-to-memorymd","level":2,"title":"Publishing Context to MEMORY.md","text":"

    Push curated .context/ content back into MEMORY.md so Claude Code sees structured project context on session start - without needing hooks.

    ctx memory publish --dry-run    # Preview what would be published\nctx memory publish              # Write to MEMORY.md\nctx memory publish --budget 40  # Tighter line budget\n

    Published content is wrapped in markers:

    <!-- ctx:published -->\n# Project Context (managed by ctx)\n\n## Pending Tasks\n- [ ] Implement feature X\n...\n<!-- ctx:end -->\n

    Rules:

    • ctx owns everything between the markers
    • Claude owns everything outside the markers
    • ctx memory import reads only outside the markers
    • ctx memory publish replaces only inside the markers

    To remove the published block entirely:

    ctx memory unpublish\n

    Publish at Wrap-Up, Not on Commit

    The best time to publish is during session wrap-up, after persisting decisions and learnings. Never auto-publish - give yourself a chance to review what's going into MEMORY.md.

    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/memory-bridge/#full-bidirectional-workflow","level":3,"title":"Full Bidirectional Workflow","text":"
    ctx memory sync                 # 1. Mirror MEMORY.md\nctx memory import --dry-run     # 2. Check what Claude wrote\nctx memory import               # 3. Promote entries to .context/\nctx memory publish --dry-run    # 4. Check what would be published\nctx memory publish              # 5. Push context to MEMORY.md\n
    ","path":["Recipes","Knowledge and Tasks","Bridging Claude Code Auto Memory"],"tags":[]},{"location":"recipes/multi-tool-setup/","level":1,"title":"Setup Across AI Tools","text":"","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#the-problem","level":2,"title":"The Problem","text":"

    You have installed ctx and want to set it up with your AI coding assistant so that context persists across sessions. Different tools have different integration depths. For example:

    • Claude Code supports native hooks that load and save context automatically.
    • Cursor injects context via its system prompt.
    • Aider reads context files through its --read flag.

    This recipe walks through the complete setup for each tool, from initialization through verification, so you end up with a working memory layer regardless of which AI tool you use.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#tldr","level":2,"title":"TL;DR","text":"
    cd your-project\nctx init                      # creates .context/\nsource <(ctx completion zsh)  # shell completion (or bash/fish)\n\n# ## Claude Code (automatic after plugin install) ##\nclaude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n\n# ## Cursor / Aider / Copilot / Windsurf ##\nctx hook cursor # or: aider, copilot, windsurf\n

    Create a .ctxrc in your project root to configure token budgets, context directory, drift thresholds, and more.

    Then start your AI tool and ask: \"Do you remember?\"

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx init Create .context/ directory, templates, and permissions ctx hook Generate integration configuration for a specific AI tool ctx agent Print a token-budgeted context packet for AI consumption ctx load Output assembled context in read order (for manual pasting) ctx watch Auto-apply context updates from AI output (non-native tools) ctx completion Generate shell autocompletion for bash, zsh, or fish ctx recall export Export sessions to editable journal Markdown","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-1-initialize-ctx","level":3,"title":"Step 1: Initialize ctx","text":"

    Run ctx init in your project root. This creates the .context/ directory with all template files and seeds ctx permissions in settings.local.json.

    cd your-project\nctx init\n

    This produces the following structure:

    .context/\n  CONSTITUTION.md     # Hard rules the AI must never violate\n  TASKS.md            # Current and planned work\n  CONVENTIONS.md      # Code patterns and standards\n  ARCHITECTURE.md     # System overview\n  DECISIONS.md        # Architectural decisions with rationale\n  LEARNINGS.md        # Lessons learned, gotchas, tips\n  GLOSSARY.md         # Domain terms and abbreviations\n  AGENT_PLAYBOOK.md   # How AI tools should use this system\n

    Using a Different .context Directory

    The .context/ directory doesn't have to live inside your project. You can point ctx to an external folder via .ctxrc, the CTX_DIR environment variable, or the --context-dir CLI flag.

    This is useful for monorepos or shared context across repositories.

    See Configuration for details and External Context for a full recipe.

    For Claude Code, install the ctx plugin to get hooks and skills:

    claude /plugin marketplace add ActiveMemory/ctx\nclaude /plugin install ctx@activememory-ctx\n

    If you only need the core files (useful for lightweight setups), use the --minimal flag:

    ctx init --minimal\n

    This creates only TASKS.md, DECISIONS.md, and CONSTITUTION.md.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-2-generate-tool-specific-hooks","level":3,"title":"Step 2: Generate Tool-Specific Hooks","text":"

    If you are using a tool other than Claude Code (which is configured automatically by ctx init), generate its integration configuration:

    # For Cursor\nctx hook cursor\n\n# For Aider\nctx hook aider\n\n# For GitHub Copilot\nctx hook copilot\n\n# For Windsurf\nctx hook windsurf\n

    Each command prints the configuration you need. How you apply it depends on the tool.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#claude-code","level":4,"title":"Claude Code","text":"

    No action needed. Just install ctx from the Marketplace as ActiveMemory/ctx.

    Claude Code is a First-Class Citizen

    With the ctx plugin installed, Claude Code gets hooks and skills automatically. The PreToolUse hook runs ctx agent --budget 4000 on every tool call (with a 10-minute cooldown so it only fires once per window).

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#cursor","level":4,"title":"Cursor","text":"

    Add the system prompt snippet to .cursor/settings.json:

    {\n  \"ai.systemPrompt\": \"Read .context/TASKS.md and .context/CONVENTIONS.md before responding. Follow rules in .context/CONSTITUTION.md.\"\n}\n

    Context files appear in Cursor's file tree. You can also paste a context packet directly into chat:

    ctx agent --budget 4000 | xclip    # Linux\nctx agent --budget 4000 | pbcopy   # macOS\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#aider","level":4,"title":"Aider","text":"

    Create .aider.conf.yml so context files are loaded on every session:

    read:\n  - .context/CONSTITUTION.md\n  - .context/TASKS.md\n  - .context/CONVENTIONS.md\n  - .context/DECISIONS.md\n

    Then start Aider normally:

    aider\n

    Or specify files on the command line:

    aider --read .context/TASKS.md --read .context/CONVENTIONS.md\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-3-set-up-shell-completion","level":3,"title":"Step 3: Set Up Shell Completion","text":"

    Shell completion lets you tab-complete ctx subcommands and flags, which is especially useful while learning the CLI.

    # Bash (add to ~/.bashrc)\nsource <(ctx completion bash)\n\n# Zsh (add to ~/.zshrc)\nsource <(ctx completion zsh)\n\n# Fish\nctx completion fish > ~/.config/fish/completions/ctx.fish\n

    After sourcing, typing ctx a<TAB> completes to ctx agent, and ctx recall <TAB> shows list, show, and export.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-4-verify-the-setup-works","level":3,"title":"Step 4: Verify the Setup Works","text":"

    Start a fresh session in your AI tool and ask:

    \"Do you remember?\"

    A correctly configured tool responds with specific context: current tasks from TASKS.md, recent decisions, and previous session topics. It should not say \"I don't have memory\" or \"Let me search for files.\"

    This question checks the passive side of memory. A properly set-up agent is also proactive: it treats context maintenance as part of its job:

    • After a debugging session, it offers to save a learning.
    • After a trade-off discussion, it asks whether to record the decision.
    • After completing a task, it suggests follow-up items.

    The \"do you remember?\" check verifies both halves: recall and responsibility.

    For example, after resolving a tricky bug, a proactive agent might say:

    That Redis timeout issue was subtle. Want me to save this as a *learning*\nso we don't hit it again?\n

    If you see behavior like this, the setup is working end to end.

    In Claude Code, you can also invoke the /ctx-status skill:

    /ctx-status\n

    This prints a summary of all context files, token counts, and recent activity, confirming that hooks are loading context.

    If context is not loading, check the basics:

    Symptom Fix ctx: command not found Ensure ctx is in your PATH: which ctx Hook errors Verify plugin is installed: claude /plugin list Context not refreshing Cooldown may be active; wait 10 minutes or set --cooldown 0","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-5-enable-watch-mode-for-non-native-tools","level":3,"title":"Step 5: Enable Watch Mode for Non-Native Tools","text":"

    Tools like Aider, Copilot, and Windsurf do not support native hooks for saving context automatically. For these, run ctx watch alongside your AI tool.

    Pipe the AI tool's output through ctx watch:

    # Terminal 1: Run Aider with output logged\naider 2>&1 | tee /tmp/aider.log\n\n# Terminal 2: Watch the log for context updates\nctx watch --log /tmp/aider.log\n

    Or for any generic tool:

    your-ai-tool 2>&1 | tee /tmp/ai.log &\nctx watch --log /tmp/ai.log\n

    When the AI emits structured update commands, ctx watch parses and applies them automatically:

    <context-update type=\"learning\"\n  context=\"Debugging rate limiter\"\n  lesson=\"Redis MULTI/EXEC does not roll back on error\"\n  application=\"Wrap rate-limit checks in Lua scripts instead\"\n>Redis Transaction Behavior</context-update>\n

    To preview changes without modifying files:

    ctx watch --dry-run --log /tmp/ai.log\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#step-6-export-session-transcripts-optional","level":3,"title":"Step 6: Export Session Transcripts (Optional)","text":"

    If you want to browse past session transcripts, export them to the journal:

    ctx recall export --all\n

    This converts raw session data into editable Markdown files in .context/journal/. You can then enrich them with metadata using /ctx-journal-enrich-all inside your AI assistant.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Here is the condensed setup for all three tools:

    # ## Common (run once per project) ##\ncd your-project\nctx init\nsource <(ctx completion zsh)       # or bash/fish\n\n# ## Claude Code (automatic, just verify) ##\n# Start Claude Code, then ask: \"Do you remember?\"\n\n# ## Cursor ##\nctx hook cursor\n# Add the system prompt to .cursor/settings.json\n# Paste context: ctx agent --budget 4000 | pbcopy\n\n# ## Aider ##\nctx hook aider\n# Create .aider.conf.yml with read: paths\n# Run watch mode alongside: ctx watch --log /tmp/aider.log\n\n# ## Verify any Tool ##\n# Ask your AI: \"Do you remember?\"\n# Expect: specific tasks, decisions, recent context\n
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#tips","level":2,"title":"Tips","text":"
    • Start with ctx init (not --minimal) for your first project. The full template set gives the agent more to work with, and you can always delete files later.
    • For Claude Code, the token budget is configured in the plugin's hooks.json. To customize, adjust the --budget flag in the ctx agent hook command.
    • The --session $PPID flag isolates cooldowns per Claude Code process, so parallel sessions do not suppress each other.
    • Commit your .context/ directory to version control. Several ctx features (journals, changelogs, blog generation) rely on git history.
    • For Cursor and Copilot, keep CONVENTIONS.md visible. These tools treat open files as higher-priority context.
    • Run ctx drift periodically to catch stale references before they confuse the agent.
    • The agent playbook instructs the agent to persist context at natural milestones (completed tasks, decisions, gotchas). In practice, this works best when you reinforce the habit: a quick \"anything worth saving?\" after a debugging session goes a long way.
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#next-up","level":2,"title":"Next Up","text":"

    Keeping Context in a Separate Repo →: Store context files outside the project tree for multi-repo or open source setups.

    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multi-tool-setup/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle recipe
    • Multilingual Session Parsing: configure session header prefixes for other languages
    • CLI Reference: all commands and flags
    • Integrations: detailed per-tool integration docs
    ","path":["Recipes","Getting Started","Setup Across AI Tools"],"tags":[]},{"location":"recipes/multilingual-sessions/","level":1,"title":"Multilingual Session Parsing","text":"","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#the-problem","level":2,"title":"The Problem","text":"

    Your team works across languages. Session files written by AI tools might use headers like # Oturum: 2026-01-15 - API Düzeltme (Turkish) or # セッション: 2026-01-15 - テスト (Japanese) instead of # Session: 2026-01-15 - Fix API.

    By default, ctx only recognizes Session: as a session header prefix. Files with other prefixes are silently skipped during recall export and journal generation: They look like regular Markdown, not sessions.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#tldr","level":2,"title":"TL;DR","text":"

    Add recognized prefixes to .ctxrc:

    session_prefixes:\n  - \"Session:\"      # English (include to keep default)\n  - \"Oturum:\"       # Turkish\n  - \"セッション:\"     # Japanese\n

    Restart your session. All configured prefixes are now recognized.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#how-it-works","level":2,"title":"How It Works","text":"

    The Markdown session parser detects session files by looking for an H1 header that starts with a known prefix followed by a date:

    # Session: 2026-01-15 - Fix API Rate Limiting\n# Oturum: 2026-01-15 - API Düzeltme\n# セッション: 2026-01-15 - テスト\n

    The list of recognized prefixes comes from session_prefixes in .ctxrc. When the key is absent or empty, ctx falls back to the built-in default: [\"Session:\"].

    Date-only headers (# 2026-01-15 - Morning Work) are always recognized regardless of prefix configuration.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#configuration","level":2,"title":"Configuration","text":"","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#adding-a-language","level":3,"title":"Adding a language","text":"

    Add the prefix with a trailing colon to your .ctxrc:

    session_prefixes:\n  - \"Session:\"\n  - \"Sesión:\"       # Spanish\n

    Include Session: explicitly

    When you override session_prefixes, the default is replaced, not extended. If you still want English headers recognized, include \"Session:\" in your list.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#team-setup","level":3,"title":"Team setup","text":"

    Commit .ctxrc to the repo so all team members share the same prefix list. This ensures ctx recall export and journal generation pick up sessions from all team members regardless of language.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#common-prefixes","level":3,"title":"Common prefixes","text":"Language Prefix English Session: Turkish Oturum: Spanish Sesión: French Session: German Sitzung: Japanese セッション: Korean 세션: Portuguese Sessão: Chinese 会话:","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#verifying","level":3,"title":"Verifying","text":"

    After configuring, test with ctx recall list. Sessions with the new prefixes should appear in the output.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#what-this-does-not-do","level":2,"title":"What This Does NOT Do","text":"
    • Change the interface language: ctx output is always English. This setting only controls which session files ctx can parse.
    • Generate headers: ctx never writes session headers. The prefix list is recognition-only (input, not output).
    • Affect JSONL sessions: Claude Code JSONL transcripts don't use header prefixes. This only applies to Markdown session files in .context/sessions/.
    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/multilingual-sessions/#see-also","level":2,"title":"See Also","text":"

    See also: Setup Across AI Tools - complete multi-tool setup including Markdown session configuration.

    See also: CLI Reference - full .ctxrc field reference including session_prefixes.

    ","path":["Recipes","Getting Started","Multilingual Session Parsing"],"tags":[]},{"location":"recipes/parallel-worktrees/","level":1,"title":"Parallel Agent Development with Git Worktrees","text":"","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#the-problem","level":2,"title":"The Problem","text":"

    You have a large backlog (10, 20, 30 open tasks) and many of them are independent: docs work that doesn't touch Go code, a new package that doesn't overlap with existing ones, test coverage for a stable module.

    Running one agent at a time means serial execution. You want 3-4 agents working in parallel, each on its own track, without stepping on each other's files.

    Git worktrees solve this.

    Each worktree is a separate working directory with its own branch, but they share the same .git object database. Combined with ctx's persistent context, each agent session picks up the full project state and works independently.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-worktree                                   # 1. group tasks by file overlap\ngit worktree add ../myproject-docs -b work/docs # 2. create worktrees\ncd ../myproject-docs && claude                  # 3. launch agents (one per track)\n/ctx-worktree teardown docs                     # 4. merge back and clean up\n

    TASKS.md will conflict on merge: Accept all [x] completions from both sides.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-worktree Skill Create, list, and tear down worktrees /ctx-next Skill Pick tasks from the backlog for each track git worktree Command Underlying git worktree management git merge Command Merge completed tracks back to main","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-1-assess-the-backlog","level":3,"title":"Step 1: Assess the Backlog","text":"

    Start in your main checkout. Ask the agent to analyze your tasks and group them by blast radius: which files and directories each task touches.

    /ctx-worktree\nLook at TASKS.md and group the pending tasks into 2-3 independent\ntracks based on which files they'd touch. Show me the grouping\nbefore creating anything.\n

    The agent reads TASKS.md, estimates file overlap, and proposes groups:

    Proposed worktree groups:\n\n  work/docs   # recipe updates, blog post (touches: docs/)\n  work/crypto # scratchpad encryption infra (touches: internal/crypto/)\n  work/tests  # recall test coverage (touches: internal/cli/recall/)\n
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-2-create-the-worktrees","level":3,"title":"Step 2: Create the Worktrees","text":"

    Once you approve the grouping, the agent creates worktrees as sibling directories:

    Create the worktrees for those three groups.\n

    Behind the scenes:

    git worktree add ../myproject-docs -b work/docs\ngit worktree add ../myproject-crypto -b work/crypto\ngit worktree add ../myproject-tests -b work/tests\n

    Each worktree is a full working copy on its own branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-3-launch-agents","level":3,"title":"Step 3: Launch Agents","text":"

    Open a separate terminal (or editor window) for each worktree and start a Claude Code session:

    # Terminal 1\ncd ../myproject-docs\nclaude\n\n# Terminal 2\ncd ../myproject-crypto\nclaude\n\n# Terminal 3\ncd ../myproject-tests\nclaude\n

    Each agent sees the full project, including .context/, and can work independently.

    Do Not Initialize Context in Worktrees

    Do not run ctx init in worktrees: The .context directory is already tracked in git.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-4-work","level":3,"title":"Step 4: Work","text":"

    Each agent works through its assigned tasks. They can read TASKS.md to know what's assigned to their track, use /ctx-next to pick the next item, and commit normally on their work/* branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-5-merge-back","level":3,"title":"Step 5: Merge Back","text":"

    As each track finishes, return to the main checkout and merge:

    /ctx-worktree teardown docs\n

    The agent checks for uncommitted changes, merges work/docs into your current branch, removes the worktree, and deletes the branch.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-6-handle-tasksmd-conflicts","level":3,"title":"Step 6: Handle TASKS.md Conflicts","text":"

    TASKS.md will almost always conflict when merging: Multiple agents will mark different tasks as [x]. This is expected and easy to resolve:

    Accept all completions from both sides. No task should go from [x] back to [ ]. The merge resolution is always additive.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#step-7-cleanup","level":3,"title":"Step 7: Cleanup","text":"

    After all tracks are merged, verify everything is clean:

    /ctx-worktree list\n

    Should show only the main working tree. All work/* branches should be gone.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't have to use the skill directly for every step. These natural prompts work:

    • \"I have a big backlog. Can we split it across worktrees?\"
    • \"Which of these tasks can run in parallel without conflicts?\"
    • \"Merge the docs track back in.\"
    • \"Clean up all the worktrees, we're done.\"
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#what-works-differently-in-worktrees","level":2,"title":"What Works Differently in Worktrees","text":"

    The encryption key lives at ~/.ctx/.ctx.key (user-level, outside the project). Because all worktrees on the same machine share this path, ctx pad and ctx notify work in worktrees automatically - no special setup needed.

    One thing to watch:

    • Journal enrichment: ctx recall export and ctx journal enrich write files relative to the current working directory. Enrichments created in a worktree stay there and are discarded on teardown. Enrich journals on the main branch after merging: the JSONL session logs are always intact, and you don't lose any data.

    Context Files Will Merge Just Fine

    Tracked context files (TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md) work normally; git handles them.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#tips","level":2,"title":"Tips","text":"
    • 3-4 worktrees max. Beyond that, merge complexity outweighs the parallelism benefit. The skill enforces this limit.
    • Group by package or directory, not by priority. Two high-priority tasks that touch the same files must be in the same track.
    • TASKS.md will conflict on merge. This is normal. Accept all [x] completions: The resolution is always additive.
    • Don't run ctx init in worktrees. The .context/ directory is tracked in git. Running init overwrites shared context files.
    • Name worktrees by concern, not by number. work/docs and work/crypto are more useful than work/track-1 and work/track-2.
    • Commit frequently in each worktree. Smaller commits make merge conflicts easier to resolve.
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#next-up","level":2,"title":"Next Up","text":"

    Back to the beginning: Guide Your Agent →

    Or explore the full recipe list.

    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/parallel-worktrees/#see-also","level":2,"title":"See Also","text":"
    • Running an Unattended AI Agent: for serial autonomous loops instead of parallel tracks
    • Tracking Work Across Sessions: managing the task backlog that feeds into parallelization
    • The Complete Session: the complete session workflow end-to-end, with examples
    ","path":["Recipes","Agents and Automation","Parallel Agent Development with Git Worktrees"],"tags":[]},{"location":"recipes/permission-snapshots/","level":1,"title":"Permission Snapshots","text":"","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#the-problem","level":2,"title":"The Problem","text":"

    Claude Code's .claude/settings.local.json accumulates one-off permissions every time you click \"Allow\". After busy sessions the file is full of session-specific entries that expand the agent's surface area beyond intent.

    Since settings.local.json is .gitignored, there is no PR review or CI check. The file drifts independently on every machine, and there is no built-in way to reset to a known-good state.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#tldr","level":2,"title":"TL;DR","text":"
    /ctx-sanitize-permissions               # audit for dangerous patterns\nctx permission snapshot            # save golden image\n# ... sessions accumulate cruft ...\nctx permission restore             # reset to golden state\n
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#the-solution","level":2,"title":"The Solution","text":"

    Save a curated settings.local.json as a golden image, then restore from it to drop session-accumulated permissions. The golden file (.claude/settings.golden.json) is committed to version control and shared with the team.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Command/Skill Role in this workflow ctx permission snapshot Save settings.local.json as golden image ctx permission restore Reset settings.local.json from golden image /ctx-sanitize-permissions Audit for dangerous patterns before snapshotting","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#step-by-step","level":2,"title":"Step by Step","text":"","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#1-curate-your-permissions","level":3,"title":"1. Curate Your Permissions","text":"

    Start with a clean settings.local.json. Optionally run /ctx-sanitize-permissions to remove dangerous patterns first.

    Review the file manually. Every entry should be there because you decided it belongs, not because you clicked \"Allow\" once during debugging.

    See the Permission Hygiene recipe for recommended defaults.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#2-take-a-snapshot","level":3,"title":"2. Take a Snapshot","text":"
    ctx permission snapshot\n# Saved golden image: .claude/settings.golden.json\n

    This creates a byte-for-byte copy. No re-encoding, no indent changes.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#3-commit-the-golden-file","level":3,"title":"3. Commit the Golden File","text":"
    git add .claude/settings.golden.json\ngit commit -m \"Add permission golden image\"\n

    The golden file is not gitignored (unlike settings.local.json). This is intentional: it becomes a team-shared baseline.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#4-auto-restore-at-the-session-start","level":3,"title":"4. Auto-Restore at the Session Start","text":"

    Add this instruction to your CLAUDE.md:

    ## On Session Start\n\nRun `ctx permission restore` to reset permissions to the golden image.\n

    The agent will restore the golden image at the start of every session, automatically dropping any permissions accumulated during previous sessions.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#5-update-when-intentional-changes-are-made","level":3,"title":"5. Update When Intentional Changes Are Made","text":"

    When you add a new permanent permission (not a one-off debugging entry):

    # Edit settings.local.json with the new permission\n# Then update the golden image:\nctx permission snapshot\ngit add .claude/settings.golden.json\ngit commit -m \"Update permission golden image: add cargo test\"\n
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#conversational-approach","level":2,"title":"Conversational Approach","text":"

    You don't need to remember exact commands. These natural-language prompts work with agents trained on the ctx playbook:

    What you say What happens \"Save my current permissions as baseline\" Agent runs ctx permission snapshot \"Reset permissions to the golden image\" Agent runs ctx permission restore \"Clean up my permissions\" Agent runs /ctx-sanitize-permissions then snapshot \"What permissions did I accumulate?\" Agent diffs local vs golden","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#next-up","level":2,"title":"Next Up","text":"

    Turning Activity into Content →: Generate blog posts, changelogs, and journal sites from your project activity.

    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/permission-snapshots/#see-also","level":2,"title":"See Also","text":"
    • Permission Hygiene: recommended defaults and maintenance workflow
    • CLI Reference: ctx permission: full command documentation
    ","path":["Recipes","Maintenance","Permission Snapshots"],"tags":[]},{"location":"recipes/prompt-templates/","level":1,"title":"Reusable Prompt Templates","text":"","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#the-problem","level":2,"title":"The Problem","text":"

    The gap between \"raw instruction typed into chat\" and \"full SKILL.md skill\" has no lightweight option. A user who wants a consistent code review checklist or refactoring guard rails has two bad choices:

    • Author a full skill (high friction, needs frontmatter, rebuild to embed)
    • Keep prompts in their head or a scratch file (no discoverability, no sharing)
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                         # stamps starter prompts\nctx prompt list                  # see available prompts\nctx prompt show code-review      # print a prompt\nctx prompt add my-prompt --stdin # create from stdin\nctx prompt rm my-prompt          # delete\n

    Or in your AI assistant: /ctx-prompt code-review

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx prompt list Command List available prompt templates ctx prompt show <name> Command Print prompt content to stdout ctx prompt add <name> Command Create from embedded template or stdin ctx prompt rm <name> Command Delete a prompt template ctx init Command Stamps starter prompts during initialization /ctx-prompt Skill List or apply prompt templates in-session","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#creating-prompts","level":3,"title":"Creating Prompts","text":"

    From starter templates: ctx init stamps three starters:

    • code-review: review checklist anchored to project conventions
    • refactor: refactoring with guard rails (tests first, preserve behavior)
    • explain: explain code for onboarding and knowledge transfer

    From embedded templates:

    ctx prompt add code-review    # creates from built-in template\nctx prompt add refactor       # creates from built-in template\n

    Custom prompts from stdin:

    echo \"# Debug Checklist\n\n1. Reproduce the issue\n2. Check error logs\n3. Add targeted logging\n4. Isolate the failing component\" | ctx prompt add debug --stdin\n
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#using-prompts","level":3,"title":"Using Prompts","text":"

    In your AI assistant: invoke the skill:

    /ctx-prompt code-review\n

    The agent retrieves the prompt and follows its instructions in your current context. If no name is given, it lists available prompts.

    From the CLI: pipe into other tools:

    ctx prompt show code-review    # print to stdout\n
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#sharing-prompts","level":3,"title":"Sharing Prompts","text":"

    Prompt templates live in .context/prompts/ and are committed to git by default. Your whole team shares the same prompts. For private prompts, add .context/prompts/ to .gitignore.

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#tips","level":2,"title":"Tips","text":"

    Keep prompts short and focused. A good prompt template is 5-15 lines. If it's longer, it's probably a skill.

    Anchor to project context. Reference .context/CONVENTIONS.md or .context/ARCHITECTURE.md in your prompts: the AI will read those files for project-specific patterns.

    Name prompts for the action, not the content. Use code-review not code-review-checklist. The .md extension is added automatically.

    Prompts are not skills. They have no frontmatter, no trigger rules, no allowed-tools. They are plain markdown instructions. If you need automation, create a skill instead.

    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/prompt-templates/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: full command documentation
    • Context Files: structure of .context/
    • Detecting and Fixing Drift: keeping context clean
    ","path":["Recipes","Agents and Automation","Reusable Prompt Templates"],"tags":[]},{"location":"recipes/publishing/","level":1,"title":"Turning Activity into Content","text":"","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-problem","level":2,"title":"The Problem","text":"

    Your .context/ directory is full of decisions, learnings, and session history.

    Your git log tells the story of a project evolving.

    But none of this is visible to anyone outside your terminal.

    You want to turn this raw activity into:

    • a browsable journal site,
    • blog posts,
    • changelog posts.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#tldr","level":2,"title":"TL;DR","text":"
    ctx recall export --all             # 1. export sessions to markdown\n\n/ctx-journal-enrich-all             # 2. add metadata and tags\n\nctx journal site --serve            # 3. build and serve the journal\n\n/ctx-blog about the caching layer   # 4. draft a blog post\n/ctx-blog-changelog v0.1.0 \"v0.2\"   # 5. write a changelog post\n

    Read on for details on each stage.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx recall export Command Export session JSONL to editable markdown ctx journal site Command Generate a static site from journal entries ctx journal obsidian Command Generate an Obsidian vault from journal entries ctx serve Command Serve any zensical directory (default: journal) ctx site feed Command Generate Atom feed from finalized blog posts make journal Makefile Shortcut for export + site rebuild /ctx-journal-enrich-all Skill Full pipeline: export if needed, then batch-enrich (recommended) /ctx-journal-enrich Skill Add metadata, summaries, and tags to one entry /ctx-blog Skill Draft a blog post from recent project activity /ctx-blog-changelog Skill Write a themed post from a commit range","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-1-export-sessions-to-markdown","level":3,"title":"Step 1: Export Sessions to Markdown","text":"

    Raw session data lives as JSONL files in Claude Code's internal storage. The first step is converting these into readable, editable markdown.

    # Export all sessions from the current project\nctx recall export --all\n\n# Export from all projects (if you work across multiple repos)\nctx recall export --all --all-projects\n\n# Export a single session by ID or slug\nctx recall export abc123\nctx recall export gleaming-wobbling-sutherland\n

    Exported files land in .context/journal/ as individual Markdown files with session metadata and the full conversation transcript.

    --all is safe by default: Only new sessions are exported. Existing files are skipped. Use --regenerate to re-export existing files (YAML frontmatter is preserved). Use --regenerate --keep-frontmatter=false -y to regenerate everything including frontmatter.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-2-enrich-entries-with-metadata","level":3,"title":"Step 2: Enrich Entries with Metadata","text":"

    Raw entries have timestamps and conversations but lack the structured metadata that makes a journal searchable. Use /ctx-journal-enrich-all to process your entire backlog at once:

    /ctx-journal-enrich-all\n

    The skill finds all unenriched entries, filters out noise (suggestion sessions, very short sessions, multipart continuations), and processes each one by extracting titles, topics, technologies, and summaries from the conversation.

    For large backlogs (20+ entries), it can spawn subagents to process entries in parallel.

    To enrich a single entry instead:

    /ctx-journal-enrich twinkly-stirring-kettle\n/ctx-journal-enrich 2026-01-24\n

    After enrichment, an entry gains YAML frontmatter:

    ---\ntitle: \"Implement Redis caching for API endpoints\"\ndate: 2026-01-24\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nkey_files:\n  - internal/api/middleware/cache.go\n  - internal/cache/redis.go\n---\n

    This metadata powers better navigation in the journal site:

    • titles replace slugs,
    • summaries appear in the index,
    • and search covers topics and technologies.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-3-generate-the-journal-site","level":3,"title":"Step 3: Generate the Journal Site","text":"

    With entries exported and enriched, generate the static site:

    # Generate site files\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate and serve locally (opens at http://localhost:8000)\nctx journal site --serve\n\n# Custom output directory\nctx journal site --output ~/my-journal\n

    The site is generated in .context/journal-site/ by default. It uses zensical for static site generation (pipx install zensical).

    Or use the Makefile shortcut that combines export and rebuild:

    make journal\n

    This runs ctx recall export --all followed by ctx journal site --build, then reminds you to enrich before rebuilding. To serve the built site, use make journal-serve or ctx serve (serve-only, no regeneration).

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#alternative-export-to-obsidian-vault","level":3,"title":"Alternative: Export to Obsidian Vault","text":"

    If you use Obsidian for knowledge management, generate a vault instead of (or alongside) the static site:

    ctx journal obsidian\nctx journal obsidian --output ~/vaults/ctx-journal\n

    This produces an Obsidian-ready directory with wikilinks, MOC (Map of Content) pages for topics/files/types, and a \"Related Sessions\" footer on each entry for graph connectivity. Open the output directory in Obsidian as a vault.

    The vault uses the same enriched source entries as the static site. Both outputs can coexist: The static site goes to .context/journal-site/, the vault to .context/journal-obsidian/.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-4-draft-blog-posts-from-activity","level":3,"title":"Step 4: Draft Blog Posts from Activity","text":"

    When your project reaches a milestone worth sharing, use /ctx-blog to draft a post from recent activity. The skill gathers context from multiple sources: git log, DECISIONS.md, LEARNINGS.md, completed tasks, and journal entries.

    /ctx-blog about the caching layer we just built\n/ctx-blog last week's refactoring work\n/ctx-blog lessons learned from the migration\n

    The skill gathers recent commits, decisions, and learnings; identifies a narrative arc; drafts an outline for approval; writes the full post; and saves it to docs/blog/YYYY-MM-DD-slug.md.

    Posts are written in first person with code snippets, commit references, and an honest discussion of what went wrong.

    The Output is zensical-Flavored Markdown

    The blog skills produce Markdown tuned for a zensical site: topics: frontmatter (zensical's tag field), a docs/blog/ output path, and a banner image reference.

    The content is still standard Markdown and can be adapted to other static site generators, but the defaults assume a zensical project structure.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-5-write-changelog-posts-from-commit-ranges","level":3,"title":"Step 5: Write Changelog Posts from Commit Ranges","text":"

    For release notes or \"what changed\" posts, /ctx-blog-changelog takes a starting commit and a theme, then analyzes everything that changed:

    /ctx-blog-changelog 040ce99 \"building the journal system\"\n/ctx-blog-changelog HEAD~30 \"what's new in v0.2.0\"\n/ctx-blog-changelog v0.1.0 \"the road to v0.2.0\"\n

    The skill diffs the commit range, identifies the most-changed files, and constructs a narrative organized by theme rather than chronology, including a key commits table and before/after comparisons.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#step-6-generate-the-blog-feed","level":3,"title":"Step 6: Generate the Blog Feed","text":"

    After publishing blog posts, generate the Atom feed so readers and automation can discover new content:

    ctx site feed\n

    This scans docs/blog/ for finalized posts (reviewed_and_finalized: true), extracts title, date, author, topics, and summary, and writes a valid Atom 1.0 feed to site/feed.xml. The feed is also generated automatically as part of make site.

    The feed is available at ctx.ist/feed.xml.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#the-conversational-approach","level":2,"title":"The Conversational Approach","text":"

    You can also drive your publishing anytime with natural language:

    \"write about what we did this week\"\n\"turn today's session into a blog post\"\n\"make a changelog post covering everything since the last release\"\n\"enrich the last few journal entries\"\n

    The agent has full visibility into your .context/ state (tasks completed, decisions recorded, learnings captured), so its suggestions are grounded in what actually happened.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    The full pipeline from raw transcripts to published content:

    # 1. Export all sessions\nctx recall export --all\n\n# 2. In Claude Code: enrich all entries with metadata\n/ctx-journal-enrich-all\n\n# 3. Build and serve the journal site\nmake journal\nmake journal-serve\n\n# 3b. Or generate an Obsidian vault\nctx journal obsidian\n\n# 4. In Claude Code: draft a blog post\n/ctx-blog about the features we shipped this week\n\n# 5. In Claude Code: write a changelog post\n/ctx-blog-changelog v0.1.0 \"what's new in v0.2.0\"\n

    The journal pipeline is idempotent at every stage. You can rerun ctx recall export --all without losing enrichment. You can rebuild the site as many times as you want.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#tips","level":2,"title":"Tips","text":"
    • Export regularly. Run ctx recall export --all after each session to keep your journal current. Only new sessions are exported: Existing files are skipped by default.
    • Use batch enrichment. /ctx-journal-enrich-all filters noise (suggestion sessions, trivial sessions, multipart continuations) so you do not have to decide what is worth enriching.
    • Keep journal files in .gitignore. Session journals can contain sensitive data: file contents, commands, internal discussions, and error messages with stack traces. Add .context/journal/ and .context/journal-site/ to .gitignore.
    • Use /ctx-blog for narrative posts and /ctx-blog-changelog for release posts. One finds a story in recent activity, the other explains a commit range by theme.
    • Edit the drafts. These skills produce drafts, not final posts. Review the narrative, add your perspective, and remove anything that does not serve the reader.
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#next-up","level":2,"title":"Next Up","text":"

    Running an Unattended AI Agent →: Set up an AI agent that works through tasks overnight without you at the keyboard.

    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/publishing/#see-also","level":2,"title":"See Also","text":"
    • Session Journal: journal system, enrichment schema
    • CLI Reference: ctx recall: export, list, show session history
    • CLI Reference: ctx journal site: static site generation
    • CLI Reference: ctx journal obsidian: Obsidian vault export
    • CLI Reference: ctx serve: serve-only (no regeneration)
    • Browsing and Enriching Past Sessions: journal browsing workflow
    • The Complete Session: capturing context during a session
    ","path":["Recipes","Maintenance","Turning Activity into Content"],"tags":[]},{"location":"recipes/scratchpad-sync/","level":1,"title":"Syncing Scratchpad Notes Across Machines","text":"","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#the-problem","level":2,"title":"The Problem","text":"

    You work from multiple machines: a desktop and a laptop, or a local machine and a remote dev server.

    The scratchpad entries are encrypted. The ciphertext (.context/scratchpad.enc) travels with git, but the encryption key lives outside the project at ~/.ctx/.ctx.key and is never committed. Without the key on each machine, you cannot read or write entries.

    How do you distribute the key and keep the scratchpad in sync?

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#tldr","level":2,"title":"TL;DR","text":"
    ctx init                                                  # 1. generates key\nscp ~/.ctx/.ctx.key user@machine-b:~/.ctx/.ctx.key        # 2. copy key\nchmod 600 ~/.ctx/.ctx.key                                 # 3. secure it\n# Normal git push/pull syncs the encrypted scratchpad.enc\n# On conflict: ctx pad resolve → rebuild → git add + commit\n

    Finding Your Key File

    The key is always at ~/.ctx/.ctx.key - one key, one machine.

    Treat the Key Like a Password

    The scratchpad key is the only thing protecting your encrypted entries.

    Store a backup in a secure enclave such as a password manager, and treat it with the same care you would give passwords, certificates, or API tokens.

    Anyone with the key can decrypt every scratchpad entry.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx init CLI command Initialize context (generates the key automatically) ctx pad add CLI command Add a scratchpad entry ctx pad rm CLI command Remove a scratchpad entry ctx pad edit CLI command Edit a scratchpad entry ctx pad resolve CLI command Show both sides of a merge conflict ctx pad merge CLI command Merge entries from other scratchpad files ctx pad import CLI command Bulk-import lines from a file ctx pad export CLI command Export blob entries to a directory scp Shell Copy the key file between machines git push / git pull Shell Sync the encrypted file via git /ctx-pad Skill Natural language interface to pad commands","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-1-initialize-on-machine-a","level":3,"title":"Step 1: Initialize on Machine A","text":"

    Run ctx init on your first machine. The key is created automatically at ~/.ctx/.ctx.key:

    ctx init\n# ...\n# Created ~/.ctx/.ctx.key (0600)\n# Created .context/scratchpad.enc\n

    The key lives outside the project directory and is never committed. The .enc file is tracked in git.

    Key Folder Change (v0.7.0+)

    If you built ctx from source or upgraded past v0.6.0, the key location changed to ~/.ctx/.ctx.key. Check these legacy folders and copy your key manually:

    # Old locations (pick whichever exists)\nls ~/.local/ctx/keys/        # pre-v0.7.0 user-level\nls .context/.ctx.key         # pre-v0.6.0 project-local\n\n# Copy to the new location\nmkdir -p ~/.ctx && chmod 700 ~/.ctx\ncp <old-key-path> ~/.ctx/.ctx.key\nchmod 600 ~/.ctx/.ctx.key\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-2-copy-the-key-to-machine-b","level":3,"title":"Step 2: Copy the Key to Machine B","text":"

    Use any secure transfer method. The key is always at ~/.ctx/.ctx.key:

    # scp - create the target directory first\nssh user@machine-b \"mkdir -p ~/.ctx && chmod 700 ~/.ctx\"\nscp ~/.ctx/.ctx.key user@machine-b:~/.ctx/.ctx.key\n\n# Or use a password manager, USB drive, etc.\n

    Set permissions on Machine B:

    chmod 600 ~/.ctx/.ctx.key\n

    Secure the Transfer

    The key is a raw 256-bit AES key. Anyone with the key can decrypt the scratchpad. Use an encrypted channel (SSH, password manager, vault).

    Never paste it in plaintext over email or chat.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-3-normal-pushpull-workflow","level":3,"title":"Step 3: Normal Push/Pull Workflow","text":"

    The encrypted file is committed, so standard git sync works:

    # Machine A: add entries and push\nctx pad add \"staging API key: sk-test-abc123\"\ngit add .context/scratchpad.enc\ngit commit -m \"Update scratchpad\"\ngit push\n\n# Machine B: pull and read\ngit pull\nctx pad\n#   1. staging API key: sk-test-abc123\n

    Both machines have the same key, so both can decrypt the same .enc file.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-4-read-and-write-from-either-machine","level":3,"title":"Step 4: Read and Write from Either Machine","text":"

    Once the key is distributed, all ctx pad commands work identically on both machines. Entries added on Machine A are visible on Machine B after a git pull, and vice versa.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#step-5-handle-merge-conflicts","level":3,"title":"Step 5: Handle Merge Conflicts","text":"

    If both machines add entries between syncs, pulling will create a merge conflict on .context/scratchpad.enc. Git cannot merge binary (encrypted) content automatically.

    The fastest approach is ctx pad merge: It reads both conflict sides, deduplicates, and writes the union:

    # Extract theirs to a temp file, then merge it in\ngit show :3:.context/scratchpad.enc > /tmp/theirs.enc\ngit checkout --ours .context/scratchpad.enc\nctx pad merge /tmp/theirs.enc\n\n# Done: Commit the resolved scratchpad:\ngit add .context/scratchpad.enc\ngit commit -m \"Resolve scratchpad merge conflict\"\n

    Alternatively, use ctx pad resolve to inspect both sides manually:

    ctx pad resolve\n# === Ours (this machine) ===\n#   1. staging API key: sk-test-abc123\n#   2. check DNS after deploy\n#\n# === Theirs (incoming) ===\n#   1. staging API key: sk-test-abc123\n#   2. new endpoint: api.example.com/v2\n

    Then reconstruct the merged scratchpad:

    # Start fresh with all entries from both sides\nctx pad add \"staging API key: sk-test-abc123\"\nctx pad add \"check DNS after deploy\"\nctx pad add \"new endpoint: api.example.com/v2\"\n\n# Mark the conflict resolved\ngit add .context/scratchpad.enc\ngit commit -m \"Resolve scratchpad merge conflict\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#merge-conflict-walkthrough","level":2,"title":"Merge Conflict Walkthrough","text":"

    Here's a full scenario showing how conflicts arise and how to resolve them:

    1. Both machines start in sync (1 entry):

    Machine A: 1. staging API key: sk-test-abc123\nMachine B: 1. staging API key: sk-test-abc123\n

    2. Both add entries independently:

    Machine A adds: \"check DNS after deploy\"\nMachine B adds: \"new endpoint: api.example.com/v2\"\n

    3. Machine A pushes first. Machine B pulls and gets a conflict:

    git pull\n# CONFLICT (content): Merge conflict in .context/scratchpad.enc\n

    4. Machine B runs ctx pad resolve:

    ctx pad resolve\n# === Ours ===\n#   1. staging API key: sk-test-abc123\n#   2. new endpoint: api.example.com/v2\n#\n# === Theirs ===\n#   1. staging API key: sk-test-abc123\n#   2. check DNS after deploy\n

    5. Rebuild with entries from both sides and commit:

    # Clear and rebuild (or use the skill to guide you)\nctx pad add \"staging API key: sk-test-abc123\"\nctx pad add \"check DNS after deploy\"\nctx pad add \"new endpoint: api.example.com/v2\"\n\ngit add .context/scratchpad.enc\ngit commit -m \"Merge scratchpad: keep entries from both machines\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#conversational-approach","level":3,"title":"Conversational Approach","text":"

    When working with an AI assistant, you can resolve conflicts naturally:

    You: \"I have a scratchpad merge conflict. Can you resolve it?\"\n\nAgent: \"Let me extract theirs and merge it in.\"\n       [runs git show :3:.context/scratchpad.enc > /tmp/theirs.enc]\n       [runs git checkout --ours .context/scratchpad.enc]\n       [runs ctx pad merge /tmp/theirs.enc]\n       \"Merged 2 new entries (1 duplicate skipped). Want me to\n       commit the resolution?\"\n
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#tips","level":2,"title":"Tips","text":"
    • Back up the key: If you lose it, you lose access to all encrypted entries. Store a copy in your password manager.
    • One key per project: Each ctx init generates a unique key. Don't reuse keys across projects.
    • Keys work in worktrees: Because the key lives at ~/.ctx/.ctx.key (outside the project), git worktrees on the same machine share the key automatically. No special setup needed.
    • Plaintext fallback for non-sensitive projects: If encryption adds friction and you have nothing sensitive, set scratchpad_encrypt: false in .ctxrc. Merge conflicts become trivial text merges.
    • Never commit the key: The key is stored outside the project at ~/.ctx/.ctx.key and should never be copied into the repository.
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#next-up","level":2,"title":"Next Up","text":"

    Hook Output Patterns →: Choose the right output pattern for your Claude Code hooks.

    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-sync/#see-also","level":2,"title":"See Also","text":"
    • Scratchpad: feature overview, all commands, when to use scratchpad vs context files
    • Persisting Decisions, Learnings, and Conventions: for structured knowledge that outlives the scratchpad
    ","path":["Recipes","Knowledge and Tasks","Syncing Scratchpad Notes Across Machines"],"tags":[]},{"location":"recipes/scratchpad-with-claude/","level":1,"title":"Using the Scratchpad","text":"","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#the-problem","level":2,"title":"The Problem","text":"

    During a session you accumulate quick notes, reminders, intermediate values, and sometimes sensitive tokens. They don't fit TASKS.md (not work items) or DECISIONS.md (not decisions). They don't have the structured fields that LEARNINGS.md requires.

    Without somewhere to put them, they get lost between sessions.

    How do you capture working memory that persists across sessions without polluting your structured context files?

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#tldr","level":2,"title":"TL;DR","text":"
    ctx pad add \"check DNS propagation after deploy\"\nctx pad         # list entries\nctx pad show 1  # print entry (pipe-friendly)\n

    Entries are encrypted at rest and travel with git.

    Use the /ctx-pad skill to manage entries from inside your AI session.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx pad CLI command List all scratchpad entries ctx pad show N CLI command Output raw text of entry N (pipe-friendly) ctx pad add CLI command Add a new entry ctx pad edit CLI command Replace, append to, or prepend to an entry ctx pad add --file CLI command Ingest a file as a blob entry ctx pad show N --out CLI command Extract a blob entry to a file ctx pad rm CLI command Remove an entry ctx pad mv CLI command Reorder entries ctx pad import CLI command Bulk-import lines from a file (or stdin) ctx pad export CLI command Export all blob entries to a directory /ctx-pad Skill Natural language interface to all pad commands","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-1-add-a-note-naturally","level":3,"title":"Step 1: Add a Note Naturally","text":"

    You don't need to remember any syntax. Just tell your assistant what to jot down:

    You: \"jot down: check DNS propagation after deploy\"\n\nAgent: \"Added to scratchpad:\n  1. check DNS propagation after deploy\"\n

    Behind the scenes, the agent runs ctx pad add \"check DNS propagation after deploy\".

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-2-view-your-scratchpad","level":3,"title":"Step 2: View Your Scratchpad","text":"
    You: \"show my scratchpad\"\n\nAgent: \"Your scratchpad has 3 entries:\n  1. check DNS propagation after deploy\n  2. staging API endpoint: api.staging.example.com/v2\n  3. retry limit should be 5, not 3\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-3-edit-an-entry","level":3,"title":"Step 3: Edit an Entry","text":"
    You: \"update entry 2 to include the new endpoint\"\n\nAgent: \"Updated entry 2:\n  was: staging API endpoint: api.staging.example.com/v2\n  now: staging API endpoint: api.prod.example.com/v2\"\n

    For partial edits, the agent can use --append or --prepend:

    You: \"append the port number to entry 2\"\n\nAgent: \"Updated entry 2:\n  staging API endpoint: api.prod.example.com/v2 :8443\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-4-compose-entries","level":3,"title":"Step 4: Compose Entries","text":"

    Use ctx pad show N to pipe entry content into other operations:

    You: \"append the content of entry 3 to entry 1\"\n\nAgent: [runs ctx pad edit 1 --append \"$(ctx pad show 3)\"]\n       \"Done. Entry 1 is now:\n        check DNS propagation after deploy retry limit should be 5, not 3\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-5-reorder-by-priority","level":3,"title":"Step 5: Reorder by Priority","text":"
    You: \"move entry 4 to the top\"\n\nAgent: [runs ctx pad mv 4 1]\n       \"Moved entry 4 to position 1. Scratchpad reordered.\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-6-clean-up","level":3,"title":"Step 6: Clean Up","text":"
    You: \"remove entry 2, it's done\"\n\nAgent: [runs ctx pad rm 2]\n       \"Removed entry 2. 3 entries remaining.\"\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-7-store-a-file-as-a-blob","level":3,"title":"Step 7: Store a File as a Blob","text":"

    The scratchpad can hold small files (up to 64 KB) as encrypted blob entries. The file is base64-encoded and stored alongside a label you provide:

    # Ingest a file: the first argument is the label\nctx pad add \"deploy config\" --file ./deploy.yaml\n\n# List shows the label with a [BLOB] marker\nctx pad\n#   1. check DNS propagation after deploy\n#   2. deploy config [BLOB]\n
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-8-extract-a-blob","level":3,"title":"Step 8: Extract a Blob","text":"

    Use show --out to write the decoded file back to disk:

    # Write blob entry to a file\nctx pad show 2 --out ./recovered-deploy.yaml\n\n# Or print to stdout (for piping)\nctx pad show 2 | head -5\n

    Blob entries are encrypted identically to text entries: They're just base64-encoded before encryption. The --out flag decodes and writes the raw bytes.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-9-bulk-import-notes","level":3,"title":"Step 9: Bulk Import Notes","text":"

    When you have a file with many notes (one per line), import them in bulk instead of adding one at a time:

    # Import from a file: Each non-empty line becomes an entry\nctx pad import notes.txt\n\n# Or pipe from stdin\ngrep TODO *.go | ctx pad import -\n

    All entries are written in a single encrypt/write cycle, regardless of how many lines the file contains.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#step-10-export-blobs-to-disk","level":3,"title":"Step 10: Export Blobs to Disk","text":"

    Export all blob entries to a directory as individual files. Each blob's label becomes the filename:

    # Export to a directory (created if needed)\nctx pad export ./ideas\n\n# Preview what would be exported\nctx pad export --dry-run ./ideas\n\n# Force overwrite existing files\nctx pad export --force ./backup\n

    When a file already exists, a unix timestamp is prepended to the filename to avoid collisions. Use --force to overwrite instead.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#using-ctx-pad-in-a-session","level":2,"title":"Using /ctx-pad in a Session","text":"

    Invoke the /ctx-pad skill first, then describe what you want in natural language. Without the skill prefix, the agent may route your request to TASKS.md or another context file instead of the scratchpad.

    You: /ctx-pad jot down: check DNS after deploy\nYou: /ctx-pad show my scratchpad\nYou: /ctx-pad delete entry 3\n

    Once the skill is active, it translates intent into commands:

    You say (after /ctx-pad) What the agent does \"jot down: check DNS after deploy\" ctx pad add \"check DNS after deploy\" \"remember this: retry limit is 5\" ctx pad add \"retry limit is 5\" \"show my scratchpad\" / \"what's on my pad\" ctx pad \"show me entry 3\" ctx pad show 3 \"delete the third one\" / \"remove entry 3\" ctx pad rm 3 \"change entry 2 to ...\" ctx pad edit 2 \"new text\" \"append ' +important' to entry 3\" ctx pad edit 3 --append \" +important\" \"prepend 'URGENT:' to entry 1\" ctx pad edit 1 --prepend \"URGENT: \" \"prioritize entry 4\" / \"move to the top\" ctx pad mv 4 1 \"import my notes from notes.txt\" ctx pad import notes.txt \"export all blobs to ./ideas\" ctx pad export ./ideas

    When in Doubt, Use the CLI Directly

    The ctx pad commands work the same whether you run them yourself or let the skill invoke them.

    If the agent misroutes a request, fall back to ctx pad add \"...\" in your terminal.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#when-to-use-scratchpad-vs-context-files","level":2,"title":"When to Use Scratchpad vs Context Files","text":"Situation Use Temporary reminders (\"check X after deploy\") Scratchpad Session-start reminders (\"remind me next session\") ctx remind Working values during debugging (ports, endpoints, counts) Scratchpad Sensitive tokens or API keys (short-term storage) Scratchpad Quick notes that don't fit anywhere else Scratchpad Work items with completion tracking TASKS.md Trade-offs between alternatives with rationale DECISIONS.md Reusable lessons with context/lesson/application LEARNINGS.md Codified patterns and standards CONVENTIONS.md

    Decision Guide

    • If it has structured fields (context, rationale, lesson, application), it belongs in a context file like DECISIONS.md or LEARNINGS.md.
    • If it's a work item you'll mark done, it belongs in TASKS.md.
    • If you want a message relayed VERBATIM at the next session start, it belongs in ctx remind.
    • If it's a quick note, reminder, or working value (especially if it's sensitive or ephemeral) it belongs on the scratchpad.

    Scratchpad Is Not a Junk Drawer

    The scratchpad is for working memory, not long-term storage.

    If a note is still relevant after several sessions, promote it:

    A persistent reminder becomes a task, a recurring value becomes a convention, a hard-won insight becomes a learning.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#tips","level":2,"title":"Tips","text":"
    • Entries persist across sessions: The scratchpad is committed (encrypted) to git, so entries survive session boundaries. Pick up where you left off.
    • Entries are numbered and reorderable: Use ctx pad mv to put high-priority items at the top.
    • ctx pad show N enables unix piping: Output raw entry text with no numbering prefix. Compose with --append, --prepend, or other shell tools.
    • Never mention the key file contents to the AI: The agent knows how to use ctx pad commands but should never read or print the encryption key (~/.ctx/.ctx.key) directly.
    • Encryption is transparent: You interact with plaintext; the encryption/decryption happens automatically on every read/write.
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#next-up","level":2,"title":"Next Up","text":"

    Syncing Scratchpad Notes Across Machines →: Distribute encryption keys and scratchpad data across environments.

    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/scratchpad-with-claude/#see-also","level":2,"title":"See Also","text":"
    • Scratchpad: feature overview, all commands, encryption details, plaintext override
    • Persisting Decisions, Learnings, and Conventions: for structured knowledge that outlives the scratchpad
    • The Complete Session: full session lifecycle showing how the scratchpad fits into the broader workflow
    ","path":["Recipes","Knowledge and Tasks","Using the Scratchpad"],"tags":[]},{"location":"recipes/session-archaeology/","level":1,"title":"Browsing and Enriching Past Sessions","text":"","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-problem","level":2,"title":"The Problem","text":"

    After weeks of AI-assisted development you have dozens of sessions scattered across JSONL files in ~/.claude/projects/. Finding the session where you debugged the Redis connection pool, or remembering what you decided about the caching strategy three Tuesdays ago, often means grepping raw JSON.

    There is no table of contents, no search, and no summaries.

    This recipe shows how to turn that raw session history into a browsable, searchable, and enriched journal site you can navigate in your browser.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#tldr","level":2,"title":"TL;DR","text":"

    Export and Generate

    ctx recall export --all\nctx journal site --serve\n

    Enrich

    /ctx-journal-enrich-all\n

    Rebuild

    ctx journal site --serve\n

    Read on for what each stage does and why.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx recall list Command List parsed sessions with metadata ctx recall show Command Inspect a specific session in detail ctx recall export Command Export sessions to editable journal Markdown ctx journal site Command Generate a static site from journal entries ctx journal obsidian Command Generate an Obsidian vault from journal entries ctx serve Command Serve any zensical directory (default: journal) /ctx-recall Skill Browse sessions inside your AI assistant /ctx-journal-enrich Skill Add frontmatter metadata to a single entry /ctx-journal-enrich-all Skill Full pipeline: export if needed, then batch-enrich","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-workflow","level":2,"title":"The Workflow","text":"

    The session journal follows a four-stage pipeline.

    Each stage is idempotent and safe to re-run:

    By default, each stage skips entries that have already been processed.

    export -> enrich -> rebuild\n
    Stage Tool What it does Skips if Where Export ctx recall export --all Converts session JSONL to Markdown File already exists (safe default) CLI or agent Enrich /ctx-journal-enrich-all Adds frontmatter, summaries, topic tags Frontmatter already present Agent only Rebuild ctx journal site --build Generates browsable static HTML N/A CLI only Obsidian ctx journal obsidian Generates Obsidian vault with wikilinks N/A CLI only

    Where Do You Run Each Stage?

    Export (Steps 1 to 3) works equally well from the terminal or inside your AI assistant via /ctx-recall. The CLI is fine here: the agent adds no special intelligence, it just runs the same command.

    Enrich (Step 4) requires the agent: it reads conversation content and produces structured metadata.

    Rebuild and serve (Step 5) is a terminal operation that starts a long-running server.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-1-list-your-sessions","level":3,"title":"Step 1: List Your Sessions","text":"

    Start by seeing what sessions exist for the current project:

    ctx recall list\n

    Sample output:

    Sessions (newest first)\n=======================\n\n  Slug                           Project   Date         Duration  Turns  Tokens\n  gleaming-wobbling-sutherland   ctx       2026-02-07   1h 23m    47     82,341\n  twinkly-stirring-kettle        ctx       2026-02-06   0h 45m    22     38,102\n  bright-dancing-hopper          ctx       2026-02-05   2h 10m    63     124,500\n  quiet-flowing-dijkstra         ctx       2026-02-04   0h 18m    11     15,230\n  ...\n

    Slugs Look Cryptic?

    These auto-generated slugs (gleaming-wobbling-sutherland) are hard to recognize later.

    Use /ctx-journal-enrich to add human-readable titles, topic tags, and summaries to exported journal entries, making them easier to find.

    Filter by project or tool if you work across multiple codebases:

    ctx recall list --project ctx --limit 10\nctx recall list --tool claude-code\nctx recall list --all-projects\n
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-2-inspect-a-specific-session","level":3,"title":"Step 2: Inspect a Specific Session","text":"

    Before exporting everything, inspect a single session to see its metadata and conversation summary:

    ctx recall show --latest\n

    Or look up a specific session by its slug, partial ID, or UUID:

    ctx recall show gleaming-wobbling-sutherland\nctx recall show twinkly\nctx recall show abc123\n

    Add --full to see the complete message content instead of the summary view:

    ctx recall show --latest --full\n

    This is useful for checking what happened before deciding whether to export and enrich it.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-3-export-sessions-to-the-journal","level":3,"title":"Step 3: Export Sessions to the Journal","text":"

    Export converts raw session data into editable Markdown files in .context/journal/:

    # Export all sessions from the current project\nctx recall export --all\n\n# Export a single session\nctx recall export gleaming-wobbling-sutherland\n\n# Include sessions from all projects\nctx recall export --all --all-projects\n

    --keep-frontmatter=false Discards Enrichments

    --keep-frontmatter=false discards enriched YAML frontmatter during regeneration.

    Back up your journal before using this flag.

    Each exported file contains session metadata (date, time, duration, model, project, git branch), a tool usage summary, and the full conversation transcript.

    Re-exporting is safe. Running ctx recall export --all only exports new sessions: Existing files are never touched. Use --dry-run to preview what would be exported without writing anything.

    To re-export existing files (e.g., after a format improvement), use --regenerate: Conversation content is regenerated while preserving any YAML frontmatter you or the enrichment skill has added. You'll be prompted before any files are overwritten.

    --regenerate Replaces the Markdown Body

    --regenerate preserves YAML frontmatter but replaces the entire Markdown body with freshly generated content from the source JSONL.

    If you manually edited the conversation transcript (added notes, redacted sensitive content, restructured sections), those edits will be lost.

    BACK UP YOUR JOURNAL FIRST.

    To protect entries you've hand-edited, you can explicitly lock them:

    ctx recall lock <pattern>\n

    Locked entries are always skipped, regardless of flags.

    If you prefer to add locked: true directly in frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json:

    ctx recall sync\n

    See ctx recall lock --help and ctx recall sync --help for details.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-4-enrich-with-metadata","level":3,"title":"Step 4: Enrich with Metadata","text":"

    Raw exports have timestamps and transcripts but lack the semantic metadata that makes sessions searchable: topics, technology tags, outcome status, and summaries. The /ctx-journal-enrich* skills add this structured frontmatter.

    Locked entries are skipped by enrichment skills, just as they are by export. Lock entries you want to protect before running batch enrichment.

    Batch enrichment (recommended):

    /ctx-journal-enrich-all\n

    The skill finds all unenriched entries, filters out noise (suggestion sessions, very short sessions, multipart continuations), and processes each one by extracting titles, topics, technologies, and summaries from the conversation.

    It shows you a grouped summary before applying changes so you can scan quickly rather than reviewing one by one.

    For large backlogs (20+ entries), the skill can spawn subagents to process entries in parallel.

    Single-entry enrichment:

    /ctx-journal-enrich twinkly\n/ctx-journal-enrich 2026-02-06\n

    Each enriched entry gets YAML frontmatter like this:

    ---\ntitle: \"Implement Redis caching middleware\"\ndate: 2026-02-06\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nlibraries:\n  - go-redis/redis\nkey_files:\n  - internal/cache/redis.go\n  - internal/api/middleware/cache.go\n---\n

    The skill also generates a summary and can extract decisions, learnings, and tasks mentioned during the session.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#step-5-generate-and-serve-the-site","level":3,"title":"Step 5: Generate and Serve the Site","text":"

    With exported and enriched journal files, generate the static site:

    # Generate site structure only\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate, build, and serve locally\nctx journal site --serve\n

    Then open http://localhost:8000 to browse.

    The site includes a date-sorted index, individual session pages with full conversations, search (press /), dark mode, and enriched titles in the navigation when frontmatter exists.

    You can also serve an already-generated site without regenerating using ctx serve (serve-only, no regeneration).

    The site generator requires zensical (pipx install zensical).

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#where-does-agent-add-value","level":2,"title":"Where Does Agent Add Value?","text":"

    Export, list, and show are mechanical: The agent runs the same CLI commands you would, so you can stay in your terminal for those.

    The agent earns its keep in enrich. It reads conversation content, understands what happened, and produces structured metadata. That is agent work, not CLI work.

    You can also ask your agent to browse sessions conversationally instead of remembering flags:

    What did we work on last week?\nShow me the session about Redis.\nExport everything to the journal.\n

    This is convenient but not required: ctx recall list gives you the same inventory.

    Where the agent genuinely helps is chaining the pipeline:

    You:   What happened last Tuesday?\nAgent: Last Tuesday you worked on two sessions:\n       - bright-dancing-hopper (2h 10m): refactored the middleware\n         pipeline and added Redis caching\n       - quiet-flowing-dijkstra (18m): quick fix for a nil pointer\n         in the config loader\n       Want me to export and enrich them?\nYou:   Yes, do it.\nAgent: Exports both, enriches, then proposes frontmatter.\n

    The value is staying in one context while the agent runs export -> enrich without you manually switching tools.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A typical pipeline from raw sessions to a browsable site:

    # Terminal: export and generate\nctx recall export --all\nctx journal site --serve\n
    # AI assistant: enrich\n/ctx-journal-enrich-all\n
    # Terminal: rebuild with enrichments\nctx journal site --serve\n

    If your project includes Makefile.ctx (deployed by ctx init), use make journal to combine export and rebuild stages. Then enrich inside Claude Code, then make journal again to pick up enrichments.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#session-retention-and-cleanup","level":2,"title":"Session Retention and Cleanup","text":"

    Claude Code does not keep JSONL transcripts forever. Understanding its cleanup behavior helps you avoid losing session history.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#default-behavior","level":3,"title":"Default Behavior","text":"

    Claude Code retains session transcripts for approximately 30 days. After that, JSONL files are automatically deleted during cleanup. Once deleted, ctx recall can no longer see those sessions - the data is gone.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#the-cleanupperioddays-setting","level":3,"title":"The cleanupPeriodDays Setting","text":"

    Claude Code exposes a cleanupPeriodDays setting in its configuration (~/.claude/settings.json) that controls retention:

    Value Behavior 30 (default) Transcripts older than 30 days are deleted 60, 90, etc. Extends the retention window 0 Disables writing new transcripts entirely - not \"keep forever\"

    Setting cleanupPeriodDays to 0

    Setting this to 0 does not mean \"never delete.\" It disables transcript creation altogether. No new JSONL files are written, which means ctx recall sees nothing new. This is rarely what you want.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#why-journal-export-matters","level":3,"title":"Why Journal Export Matters","text":"

    The journal export pipeline (Steps 1-4 above) is your archival mechanism. Exported Markdown files in .context/journal/ persist independently of Claude Code's cleanup cycle. Even after the source JSONL files are deleted, your journal entries remain.

    Recommendation: export regularly - weekly, or after any session worth revisiting. A quick ctx recall export --all takes seconds and ensures nothing falls through the 30-day window.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#quick-archival-checklist","level":3,"title":"Quick Archival Checklist","text":"
    1. Run ctx recall export --all at least weekly
    2. Enrich high-value sessions with /ctx-journal-enrich before the details fade from your own memory
    3. Lock enriched entries (ctx recall lock <pattern>) to protect them from accidental regeneration
    4. Rebuild the journal site periodically to keep it current
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#tips","level":2,"title":"Tips","text":"
    • Start with /ctx-recall inside your AI assistant. If you want to quickly check what happened in a recent session without leaving your editor, /ctx-recall lets you browse interactively without exporting.
    • Large sessions may be split automatically. Sessions with 200+ messages can be split into multiple parts (session-abc123.md, session-abc123-p2.md, session-abc123-p3.md) with navigation links between them. The site generator can handle this.
    • Suggestion sessions can be separated. Claude Code can generate short suggestion sessions for autocomplete. These may appear under a separate section in the site index, so they do not clutter your main session list.
    • Your agent is a good session browser. You do not need to remember slugs, dates, or flags. Ask \"what did we do yesterday?\" or \"find the session about Redis\" and it can map the question to recall commands.

    Journal Files Are Sensitive

    Journal files MUST be .gitignored.

    Session transcripts can contain sensitive data such as file contents, commands, error messages with stack traces, and potentially API keys.

    Add .context/journal/, .context/journal-site/, and .context/journal-obsidian/ to your .gitignore.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#next-up","level":2,"title":"Next Up","text":"

    Persisting Decisions, Learnings, and Conventions →: Record decisions, learnings, and conventions so they survive across sessions.

    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-archaeology/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: where session saving fits in the daily workflow
    • Turning Activity into Content: generating blog posts from session history
    • Session Journal: full documentation of the journal system
    • CLI Reference: ctx recall: all recall subcommands and flags
    • CLI Reference: ctx journal: site generation options
    • CLI Reference: ctx serve: serve-only (no regeneration)
    • Context Files: the .context/ directory structure
    ","path":["Recipes","Sessions","Browsing and Enriching Past Sessions"],"tags":[]},{"location":"recipes/session-ceremonies/","level":1,"title":"Session Ceremonies","text":"","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#the-problem","level":2,"title":"The Problem","text":"

    Sessions have two critical moments: the start and the end.

    • At the start, you need the agent to load context and confirm it knows what is going on.
    • At the end, you need to capture whatever the session produced before the conversation disappears.

    Most ctx skills work conversationally: \"jot down: check DNS after deploy\" is as good as /ctx-pad add \"check DNS after deploy\". But session boundaries are different. They are well-defined moments with specific requirements, and partial execution is costly.

    If the agent only half-loads context at the start, it works from stale assumptions. If it only half-persists at the end, learnings and decisions are lost.

    This Is One of the Few Times Being Explicit Matters

    Session ceremonies are the two bookend skills that mark these boundaries.

    They are the exception to the conversational rule:

    Invoke /ctx-remember and /ctx-wrap-up explicitly as slash commands.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#tldr","level":2,"title":"TL;DR","text":"

    Start: /ctx-remember: load context, get a structured readback.

    End: /ctx-wrap-up: review session, propose candidates, persist approved items.

    Use the slash commands, not conversational triggers, for completeness.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#explicit-invocation-matters","level":2,"title":"Explicit Invocation Matters","text":"

    Most ctx skills encourage natural language. These two are different:

    Well-defined moments: Sessions have clear boundaries. A slash command marks the boundary unambiguously.

    Ambiguity risk: \"Do you remember?\" could mean many things. /ctx-remember means exactly one thing: load context and present a structured readback.

    Completeness: Conversational triggers risk partial execution. The agent might load some files but skip the session history, or persist one learning but forget to check for uncommitted changes. The slash command runs the full ceremony.

    Muscle memory: Typing /ctx-remember at session start and /ctx-wrap-up at session end becomes a habit, like opening and closing braces.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose /ctx-remember Skill Load context and present structured readback /ctx-wrap-up Skill Gather session signal, propose and persist context /ctx-commit Skill Commit with context capture (offered by wrap-up) ctx agent CLI Load token-budgeted context packet ctx recall list CLI List recent sessions ctx add CLI Persist learnings, decisions, conventions, tasks","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#session-start-ctx-remember","level":2,"title":"Session Start: /ctx-remember","text":"

    Invoke at the beginning of every session:

    /ctx-remember\n

    The skill silently:

    1. Loads the context packet via ctx agent --budget 4000
    2. Reads TASKS.md, DECISIONS.md, LEARNINGS.md
    3. Checks recent sessions via ctx recall list --limit 3

    Then presents a structured readback with four sections:

    • Last session: topic, date, what was accomplished
    • Active work: pending and in-progress tasks
    • Recent context: 1-2 relevant decisions or learnings
    • Next step: suggestion or question about what to focus on

    The readback should feel like recall, not a file system tour. If the agent says \"Let me check if there are files...\" instead of a confident summary, the skill is not working correctly.

    What About 'do you remember?'

    The conversational trigger still works. But /ctx-remember guarantees the full ceremony runs:

    • context packet,
    • file reads,
    • session history,
    • and all four readback sections.

    The conversational version may cut corners.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#session-end-ctx-wrap-up","level":2,"title":"Session End: /ctx-wrap-up","text":"

    Invoke before ending a session where meaningful work happened:

    /ctx-wrap-up\n

    The skill runs four phases:

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-1-gather-signal","level":3,"title":"Phase 1: Gather Signal","text":"

    Silently checks git diff --stat, recent commits, and scans the conversation for themes: architectural choices, gotchas, patterns established, follow-up work identified.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-2-propose-candidates","level":3,"title":"Phase 2: Propose Candidates","text":"

    Presents a structured list grouped by type:

    ## Session Wrap-Up\n\n### Learnings (2 candidates)\n1. **PyMdownx details extension breaks pre/code rendering**\n   - Context: Journal site showed broken code blocks inside details tags\n   - Lesson: details extension wraps content in <details> HTML, which\n     interferes with <pre><code> rendering\n   - Application: Use fenced code blocks instead of indented code inside\n     admonitions when details extension is active\n\n2. **Hook subprocesses cannot propagate env vars**\n   - Context: Set env var in PreToolUse hook, invisible in main session\n   - Lesson: Hooks execute in child processes; env changes don't propagate\n   - Application: Use tombstone files for hook-to-session communication\n\n### Decisions (1 candidate)\n1. **File-based cooldown tokens over env vars**\n   - Context: Need session-scoped cooldown for ctx agent auto-loading\n   - Rationale: File tokens survive across processes, simpler than IPC\n   - Consequence: Tombstone files accumulate in /tmp; need TTL cleanup\n\nPersist all? Or select which to keep?\n

    Each candidate has complete structured fields, not just a title. Empty categories are omitted.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-3-persist","level":3,"title":"Phase 3: Persist","text":"

    After you approve (all, some, or modified), the skill runs the appropriate ctx add commands and reports results.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#nudge-suppression","level":3,"title":"Nudge Suppression","text":"

    After persisting, the skill marks the session as wrapped up via ctx system mark-wrapped-up. This suppresses context checkpoint nudges for 2 hours so the wrap-up ceremony itself does not trigger noisy reminders.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#phase-4-commit-offer","level":3,"title":"Phase 4: Commit Offer","text":"

    If there are uncommitted changes, offers to run /ctx-commit. Does not auto-commit.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#when-to-skip","level":2,"title":"When to Skip","text":"

    Not every session needs ceremonies.

    Skip /ctx-remember when:

    • You are doing a quick one-off lookup (reading a file, checking a value)
    • Context was already loaded this session via /ctx-agent
    • You are continuing immediately after a previous session and context is still fresh

    Skip /ctx-wrap-up when:

    • Nothing meaningful happened (only read files, answered a question)
    • You already persisted everything manually during the session
    • The session was trivial (typo fix, quick config change)

    A good heuristic: if the session produced something a future session should know about, run /ctx-wrap-up. If not, just close.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#quick-reference","level":2,"title":"Quick Reference","text":"
    # Session start\n/ctx-remember\n\n# ... do work ...\n\n# Session end\n/ctx-wrap-up\n

    That is the complete ceremony. Two commands, bookending your session.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#relationship-to-other-skills","level":2,"title":"Relationship to Other Skills","text":"Skill When Purpose /ctx-remember Session start Load and confirm context /ctx-reflect Mid-session breakpoints Checkpoint at milestones /ctx-wrap-up Session end Full session review and persist /ctx-commit After completing work Commit with context capture

    /ctx-reflect is for mid-session checkpoints. /ctx-wrap-up is for end-of-session: it is more thorough, covers the full session arc, and includes the commit offer. If you already ran /ctx-reflect recently, /ctx-wrap-up avoids proposing the same candidates again.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#tips","level":2,"title":"Tips","text":"
    • Make it a habit: The value of ceremonies compounds over sessions. Each /ctx-wrap-up makes the next /ctx-remember richer.
    • Trust the candidates: The agent scans the full conversation. It often catches learnings you forgot about.
    • Edit before approving: If a proposed candidate is close but not quite right, tell the agent what to change. Do not settle for a vague learning when a precise one is possible.
    • Do not force empty ceremonies: If /ctx-wrap-up finds nothing worth persisting, that is fine. A session that only read files and answered questions does not need artificial learnings.
    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#next-up","level":2,"title":"Next Up","text":"

    Browsing and Enriching Past Sessions →: Export session history to a browsable journal and enrich entries with metadata.

    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-ceremonies/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: the full session workflow that ceremonies bookend
    • Persisting Decisions, Learnings, and Conventions: deep dive on what gets persisted during wrap-up
    • Detecting and Fixing Drift: keeping context files accurate between ceremonies
    • Pausing Context Hooks: skip ceremonies entirely for quick tasks that don't need them
    ","path":["Recipes","Sessions","Session Ceremonies"],"tags":[]},{"location":"recipes/session-changes/","level":1,"title":"Reviewing Session Changes","text":"","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#what-changed-while-you-were-away","level":2,"title":"What Changed While You Were Away?","text":"

    Between sessions, teammates commit code, context files get updated, and decisions pile up. ctx change gives you a single-command summary of everything that moved since your last session.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#quick-start","level":2,"title":"Quick Start","text":"
    # Auto-detects your last session and shows what changed\nctx change\n\n# Check what changed in the last 48 hours\nctx change --since 48h\n\n# Check since a specific date\nctx change --since 2026-03-10\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#how-reference-time-works","level":2,"title":"How Reference Time Works","text":"

    ctx change needs a reference point to compare against. It tries these sources in order:

    1. --since flag: explicit duration (24h, 72h) or date (2026-03-10, RFC3339 timestamp)
    2. Session markers: ctx-loaded-* files in .context/state/; picks the second-most-recent (your previous session start)
    3. Event log: last context-load-gate event from .context/state/events.jsonl
    4. Fallback: 24 hours ago

    The marker-based detection means ctx change usually just works without any flags: it knows when you last loaded context and shows everything after that.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#what-it-reports","level":2,"title":"What It Reports","text":"","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#context-file-changes","level":3,"title":"Context file changes","text":"

    Any .md file in .context/ modified after the reference time:

    ### Context File Changes\n- `TASKS.md` - modified 2026-03-11 14:30\n- `DECISIONS.md` - modified 2026-03-11 09:15\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#code-changes","level":3,"title":"Code changes","text":"

    Git activity since the reference time:

    ### Code Changes\n- **12 commits** since reference point\n- **Latest**: Fix journal enrichment ordering\n- **Directories touched**: internal, docs, specs\n- **Authors**: jose, claude\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#integrating-into-session-start","level":2,"title":"Integrating Into Session Start","text":"

    Pair ctx change with the /ctx-remember ceremony for a complete session-start picture:

    # 1. Load context (this also creates the session marker)\nctx agent --budget 4000\n\n# 2. See what changed since your last session\nctx change\n

    Or script it:

    # .context/hooks/session-start.sh\nctx agent --budget 4000\necho \"---\"\nctx change\n
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#team-workflows","level":2,"title":"Team Workflows","text":"

    When multiple people share a .context/ directory, ctx change shows who changed what:

    # After pulling from remote\ngit pull\nctx change --since 72h\n

    This surfaces context file changes from teammates that you might otherwise miss in the commit log.

    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-changes/#tips","level":2,"title":"Tips","text":"
    • No changes? If nothing shows up, the reference time might be wrong. Use --since 48h to widen the window.
    • Works without git. Context file changes are detected by filesystem mtime, not git. Code changes require git.
    • Hook integration. The context-load-gate hook writes the session marker that ctx change uses for auto-detection. If you're not using the ctx plugin, markers won't exist and it falls back to the event log or 24h window.
    ","path":["Reviewing Session Changes"],"tags":[]},{"location":"recipes/session-lifecycle/","level":1,"title":"The Complete Session","text":"","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#the-problem","level":2,"title":"The Problem","text":"

    \"What does a full ctx session look like from start to finish?\"

    You have ctx installed and your .context/ directory initialized, but the individual commands and skills feel disconnected.

    How do they fit together into a coherent workflow?

    This recipe walks through a complete session, from opening your editor to persisting context before you close it, so you can see how each piece connects.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#tldr","level":2,"title":"TL;DR","text":"
    1. Load: /ctx-remember: load context, get structured readback.
    2. Orient: /ctx-status: check file health and token usage.
    3. Pick: /ctx-next: choose what to work on.
    4. Work: implement, test, iterate.
    5. Commit: /ctx-commit: commit and capture decisions/learnings.
    6. Reflect: /ctx-reflect: identify what to persist (at milestones)
    7. Wrap up: /ctx-wrap-up: end-of-session ceremony.

    Read on for the full walkthrough with examples.

    What is a Readback?

    A readback is a structured summary where the agent plays back what it knows:

    • last session,
    • active tasks,
    • recent decisions.

    This way, you can confirm it loaded the right context.

    The term \"readback\" comes from aviation, where pilots repeat instructions back to air traffic control to confirm they heard correctly.

    Same idea in ctx: The agent tells you what it \"thinks\" is going on, and you correct anything that's off before the work begins.

    • Last session: topic, date, what was accomplished
    • Active work: pending and in-progress tasks
    • Recent context: 1-2 decisions or learnings that matter now
    • Next step: suggestion or question about what to focus on
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx status CLI command Quick health check on context files ctx agent CLI command Load token-budgeted context packet ctx recall list CLI command List previous sessions ctx recall show CLI command Inspect a specific session in detail /ctx-remember Skill Recall project context with structured readback /ctx-agent Skill Load full context packet inside the assistant /ctx-status Skill Show context summary with commentary /ctx-next Skill Suggest what to work on with rationale /ctx-commit Skill Commit code and prompt for context capture /ctx-reflect Skill Structured reflection checkpoint /ctx-recall Skill Browse session history inside your AI assistant","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#the-workflow","level":2,"title":"The Workflow","text":"

    The session lifecycle has seven steps. You will not always use every step (for example, a quick bugfix might skip reflection, and a research session might skip committing), but the full arc looks like this:

    Load context > Orient > Pick a Task > Work > Commit > Reflect

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-1-load-context","level":3,"title":"Step 1: Load Context","text":"

    Start every session by loading what you know. The fastest way is a single prompt:

    Do you remember what we were working on?\n

    This triggers the /ctx-remember skill. Behind the scenes, the assistant runs ctx agent --budget 4000, reads the files listed in the context packet (TASKS.md, DECISIONS.md, LEARNINGS.md, CONVENTIONS.md), checks ctx recall list --limit 3 for recent sessions, and then presents a structured readback.

    The readback should feel like a recall, not a file system tour. If you see \"Let me check if there are files...\" instead of a confident summary, the context system is not loaded properly.

    As an alternative, if you want raw data instead of a readback, run ctx status in your terminal or invoke /ctx-status for a summarized health check showing file counts, token usage, and recent activity.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-2-orient","level":3,"title":"Step 2: Orient","text":"

    After loading context, verify you understand the current state.

    /ctx-status\n

    The status output shows which context files are populated, how many tokens they consume, and which files were recently modified. Look for:

    • Empty core files: TASKS.md or CONVENTIONS.md with no content means the context is sparse
    • High token count (over 30k): the context is bloated and might need ctx compact
    • No recent activity: files may be stale and need updating

    If the status looks healthy and the readback from Step 1 gave you enough context, skip ahead.

    If something seems off (stale tasks, missing decisions...), spend a minute reading the relevant file before proceeding.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-3-pick-what-to-work-on","level":3,"title":"Step 3: Pick What to Work On","text":"

    With context loaded, choose a task. You can pick one yourself, or ask the assistant to recommend:

    /ctx-next\n

    The skill reads TASKS.md, checks recent sessions to avoid re-suggesting completed work, and presents 1-3 ranked recommendations with rationale.

    It prioritizes in-progress tasks over new starts (finishing is better than starting), respects explicit priority tags, and favors momentum: continuing a thread from a recent session is cheaper than context-switching.

    If you already know what you want to work on, state it directly:

    Let's work on the session enrichment feature.\n
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-4-do-the-work","level":3,"title":"Step 4: Do the Work","text":"

    This is the main body of the session: write code, fix bugs, refactor, research: whatever the task requires.

    During this phase, a few ctx-specific patterns help:

    Check decisions before choosing: when you face a design choice, check if a prior decision covers it.

    Is this consistent with our decisions?\n

    Constrain scope: keep the assistant focused on the task at hand.

    Only change files in internal/cli/session/. Nothing else.\n

    Use /ctx-implement for multistep plans: if the task has multiple steps, this skill executes them one at a time with build/test verification between each step.

    Context monitoring runs automatically: the check-context-size hook monitors context capacity at adaptive intervals. Early in a session it stays silent. After 16+ prompts it starts monitoring, and past 30 prompts it checks frequently. If context capacity is running high, it will suggest saving unsaved work. No manual invocation is needed.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-5-commit-with-context","level":3,"title":"Step 5: Commit with Context","text":"

    When the work is ready, use the context-aware commit instead of raw git commit:

    /ctx-commit\n

    The Agent May Recommend Committing

    You do not always need to invoke /ctx-commit explicitly.

    After a commit, the agent may proactively offer to capture context:

    \"We just made a trade-off there. Want me to record it as a decision?\"

    This is normal: The Agent Playbook encourages persisting at milestones, and a commit is a natural milestone.

    As an alternative, you can ask the assistant \"can we commit this?\" and it will pick up the /ctx-commit skill for you.

    The skill runs a pre-commit build check (for Go projects, go build), reviews the staged changes, drafts a commit message focused on \"why\" rather than \"what\", and then commits.

    After the commit succeeds, it prompts you:

    **Any context to capture?**\n\n- **Decision**: Did you make a design choice or trade-off?\n- **Learning**: Did you hit a gotcha or discover something?\n- **Neither**: No context to capture; we are done.\n

    If you made a decision, the skill records it with ctx add decision. If you learned something, it records it with ctx add learning including context, lesson, and application fields. This is the bridge between committing code and remembering why the code looks the way it does.

    If source code changed in areas that affect documentation, the skill also offers to check for doc drift.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-6-reflect","level":3,"title":"Step 6: Reflect","text":"

    At natural breakpoints (after finishing a feature, resolving a complex bug, or before switching tasks) pause to reflect:

    /ctx-reflect\n

    Agents Reflect at Milestones

    Agents often reflect without explicit invocation.

    After completing a significant piece of work, the agent may naturally surface items worth persisting:

    \"We discovered that $PPID resolves differently inside hooks. Should I save that as a learning?\"

    This is the agent following the Work-Reflect-Persist cycle from the Agent Playbook.

    You do not need to say /ctx-reflect for this to happen; the agent treats milestones as reflection triggers on its own.

    The skill works through a checklist: learnings discovered, decisions made, tasks completed or created, and whether there are items worth persisting. It then presents a summary with specific items to persist, each with the exact command to run:

    I would suggest persisting:\n\n- **Learning**: `$PPID` in PreToolUse hooks resolves to the Claude Code PID\n  `ctx add learning --context \"...\" --lesson \"...\" --application \"...\"`\n- **Task**: mark \"Add cooldown to ctx agent\" as done\n- **Decision**: tombstone-based cooldown with 10m default\n  `ctx add decision \"...\"`\n\nWant me to persist any of these?\n

    The skill asks before persisting anything. You choose what to keep.

    Not every commit needs reflection. A typo fix does not. But when you have been debugging for an hour and finally understand the root cause, that is worth a reflection checkpoint.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#step-7-persist-before-ending","level":3,"title":"Step 7: Persist Before Ending","text":"

    Before ending the session, run the wrap-up ceremony to capture outstanding learnings, decisions, conventions, and tasks:

    /ctx-wrap-up\n

    Ceremony Skills

    /ctx-remember at session start and /ctx-wrap-up at session end are ceremony skills: Invoke them as explicit slash commands for completeness, not conversationally.

    See Session Ceremonies for details on why these two skills are the exception to the conversational rule.

    The skill gathers signal from git diff, recent commits, and the conversation, then proposes structured candidates for your approval. After you select which to keep, it persists them via ctx add and offers /ctx-commit if uncommitted changes remain.

    Session transcripts are automatically captured by Claude Code and can be browsed later with ctx recall list and ctx recall show.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#conversational-session-flow","level":2,"title":"Conversational Session Flow","text":"

    The steps above describe the mechanics. In practice, a session with a ctx-aware agent feels more like a conversation than a command sequence.

    The agent knows the lifecycle and moves through it naturally, often without explicit invocation. Here is a realistic example:

    You: Do you remember what we were working on?

    Agent (loads context silently, presents structured readback):

    Last session (Feb 7, caching-layer): we implemented the in-memory cache with\nTTL expiration and wrote tests for the eviction policy. \n\nYou have 3 pending tasks; the biggest one is adding Redis as a backend.\n\nRecent decision:<br>\nwe chose LRU over LFU because the access pattern is mostly recency-based.\n\nWant to continue with the Redis backend, or tackle something else?\n

    You: Let's work on the Redis caching backend.

    Agent (picks up the task, begins implementation):

    Got it. I see the task in TASKS.md: \"Add Redis backend for cache layer.\"\n\nI will start with the connection pool setup. Only touching\n`internal/cache/redis/` for now.\n

    (The agent works... writes code, runs tests, iterates.)

    Agent (after implementing the connection pool and choosing a retry strategy):

    The connection pool is working. I went with exponential backoff with jitter\nfor retries instead of fixed intervals; it handles thundering herd better\nunder reconnection storms. That is a design choice worth recording. \n\nWant me to save it as a decision?\n

    You: Yes, go ahead.

    Agent:

    Done. Added to DECISIONS.md: \"Exponential backoff with jitter for Redis\nreconnection, to avoid thundering herd on pool recovery.\"\n

    (More work happens... the agent implements the cache read/write paths.)

    You: What else did we learn during this session?

    Agent:

    A few things worth capturing:\n\n* **Learning**: Redis `SET` with `NX` and `PX` flags handles atomic\n  set-if-not-exists with TTL in a single call. No need for a separate\n  `EXPIRE` command. We initially did it in two calls and hit a race condition.\n* **Learning**: The `go-redis` library's `PoolSize` default is 10 per CPU.\n  For our workload, explicit sizing at 20 was more predictable.\n* **Task update**: The connection pool subtask is done; the read/write path\n  is implemented but needs integration tests.\n\nWant me to persist these?\n

    You: Yes. And let's wrap up.

    Agent (reflects and persists... all in one flow):

    Persisted:\n\n* 2 learnings added to LEARNINGS.md\n* Marked \"connection pool setup\" done in TASKS.md\n* Added \"write integration tests for Redis cache\" as a new task\n\nContext is up to date. You are good to close.\n

    Notice What Happened

    In the above workflow, the user never typed /ctx-reflect or ctx add learning.

    The agent moved through Load, Orient, Pick, Work, Commit, and Reflect driven by natural conversation.

    \"Let's wrap up\" was enough to trigger the full reflect-and-persist flow.

    The agent surfaced persist-worthy items at milestones: after a design choice, after discovering a gotcha: without waiting to be asked.

    This is the intended experience.

    The commands and skills still exist for when you want precise control, but the agent is a proactive partner in the lifecycle, not a passive executor of slash commands.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    Quick-reference checklist for a complete session:

    • Load: /ctx-remember: load context and confirm readback
    • Orient: /ctx-status: check file health and token usage
    • Pick: /ctx-next: choose what to work on
    • Work: implement, test, iterate (scope with \"only change X\")
    • Commit: /ctx-commit: commit and capture decisions/learnings
    • Reflect: /ctx-reflect: identify what to persist (at milestones)
    • Wrap up: /ctx-wrap-up: end-of-session ceremony

    Conversational equivalents: you can drive the same lifecycle with plain language:

    Step Slash command Natural language Load /ctx-remember \"Do you remember?\" / \"What were we working on?\" Orient /ctx-status \"How's our context looking?\" Pick /ctx-next \"What should we work on?\" / \"Let's do the caching task\" Work -- \"Only change files in internal/cache/\" Commit /ctx-commit \"Commit this\" / \"Ship it\" Reflect /ctx-reflect \"What did we learn?\" / (agent offers at milestones) Wrap up /ctx-wrap-up (use the slash command for completeness)

    The agent understands both columns.

    In practice, most sessions use a mix:

    • Explicit Commands when you want precision;
    • Natural Language when you want flow and agentic autonomy.

    The agent will also initiate steps on its own (particularly \"Reflect\") when it recognizes a milestone.

    Short sessions (quick bugfix) might only use: Load, Work, Commit.

    Long sessions should Reflect after each major milestone and persist learnings and decisions before ending.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#tips","level":2,"title":"Tips","text":"

    Persist early if context is running low. A hook monitors context capacity and notifies you when it gets high, but do not wait for the notification. If you have been working for a while and have unpersisted learnings, persist proactively.

    Browse previous sessions by topic. If you need context from a prior session, ctx recall show auth will match by keyword. You do not need to remember the exact date or slug.

    Reflection is optional but valuable. You can skip /ctx-reflect for small changes, but always persist learnings and decisions before ending a session where you did meaningful work. These are what the next session loads.

    Let the hook handle context loading. The PreToolUse hook runs ctx agent automatically with a cooldown, so context loads on first tool use without you asking. The /ctx-remember prompt at session start is for your benefit (to get a readback), not because the assistant needs it.

    The agent is a proactive partner, not a passive tool. A ctx-aware agent follows the Agent Playbook: it watches for milestones (completed tasks, design decisions, discovered gotchas) and offers to persist them without being asked. If you finish a tricky debugging session, it may say \"That root cause is worth saving as a learning. Want me to record it?\" before you think to ask. This is by design.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#next-up","level":2,"title":"Next Up","text":"

    Session Ceremonies →: The two bookend rituals for every session: /ctx-remember at the start, /ctx-wrap-up at the end.

    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-lifecycle/#see-also","level":2,"title":"See Also","text":"
    • Session Ceremonies: why /ctx-remember and /ctx-wrap-up are explicit slash commands, not conversational
    • CLI Reference: full documentation for all ctx commands
    • Prompting Guide: effective prompts for ctx-enabled projects
    • Tracking Work Across Sessions: deep dive on task management
    • Persisting Decisions, Learnings, and Conventions: deep dive on knowledge capture
    • Detecting and Fixing Drift: keeping context files accurate
    • Pausing Context Hooks: shortcut the full lifecycle for quick tasks that don't need ceremony overhead
    ","path":["Recipes","Sessions","The Complete Session"],"tags":[]},{"location":"recipes/session-pause/","level":1,"title":"Pausing Context Hooks","text":"","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#the-problem","level":2,"title":"The Problem","text":"

    Not every session needs the full ceremony. Quick investigations, one-off questions, small fixes unrelated to active project work: These tasks don't benefit from persistence nudges, ceremony reminders, or knowledge checks. Every hook still fires, consuming tokens and attention on work that won't produce learnings or decisions worth capturing.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#tldr","level":2,"title":"TL;DR","text":"Command What it does ctx pause or /ctx-pause Silence all nudge hooks for this session ctx resume or /ctx-resume Restore normal hook behavior

    Pause is session-scoped: It only affects the current session. Other sessions (same project, different terminal) are unaffected.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#what-gets-paused","level":2,"title":"What Gets Paused","text":"

    All nudge and reminder hooks go silent:

    • Context size checkpoints
    • Ceremony adoption nudges
    • Persistence reminders
    • Journal maintenance reminders
    • Knowledge growth nudges
    • Map staleness nudges
    • Version update nudges
    • Resource pressure warnings
    • QA reminders
    • Post-commit nudges
    • Specs nudges
    • Backup age warnings
    • Context load gate
    • Pending reminders relay
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#what-still-fires","level":2,"title":"What Still Fires","text":"

    Security hooks always run, even when paused:

    • block-non-path-ctx: prevents ./ctx invocations
    • block-dangerous-commands: blocks sudo, force push, etc.
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#workflow","level":2,"title":"Workflow","text":"
    # 1. Session starts: Context loads normally.\n\n# 2. You realize this is a quick task\nctx pause\n\n# 3. Work without interruption: hooks are silent\n\n# 4. Session evolves into real work? Resume first\nctx resume\n\n# 5. Now wrap up normally\n# /ctx-wrap-up\n
    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#graduated-reminder","level":2,"title":"Graduated Reminder","text":"

    Paused hooks aren't completely invisible. A minimal indicator appears so you always know the state:

    Paused turns What you see 1-5 ctx:paused 6+ ctx:paused (N turns): resume with /ctx-resume

    This prevents the \"forgot I paused\" problem during long sessions.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#tips","level":2,"title":"Tips","text":"

    • Resume before wrapping up. If your quick task turns into real work, resume hooks before running /ctx-wrap-up. The wrap-up ceremony needs active hooks to capture learnings properly.

    • Initial context load is unaffected. The ~8k token startup injection (CLAUDE.md, playbook, constitution) happens before any command runs. Pause only affects hooks that fire during the session.

    • Use for quick investigations. Debugging a stack trace? Checking a git log? Answering a colleague's question? Pause, do the work, close the session. No ceremony needed.

    • Don't use for real work. If you're implementing features, fixing bugs, or making decisions: keep hooks active. The nudges exist to prevent context loss.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-pause/#see-also","level":2,"title":"See Also","text":"

    See also: Session Ceremonies: the bookend rituals that pause lets you skip when they aren't needed.

    See also: Customizing Hook Messages: if you want to change what hooks say rather than silencing them entirely.

    See also: The Complete Session: the full session workflow that pause shortcuts for quick tasks.

    ","path":["Recipes","Sessions","Pausing Context Hooks"],"tags":[]},{"location":"recipes/session-reminders/","level":1,"title":"Session Reminders","text":"","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#the-problem","level":2,"title":"The Problem","text":"

    You're deep in a session and realize: \"I need to refactor the swagger definitions next time.\" You could add a task, but this isn't a work item: it's a note to future-you. You could jot it on the scratchpad, but scratchpad entries don't announce themselves.

    How do you leave a message that your next session opens with?

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#tldr","level":2,"title":"TL;DR","text":"
    ctx remind \"refactor the swagger definitions\"\nctx remind list\nctx remind dismiss 1\n

    Reminders surface automatically at session start: VERBATIM, every session, until you dismiss them.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx remind CLI command Add a reminder (default action) ctx remind list CLI command Show all pending reminders ctx remind dismiss CLI command Remove a reminder by ID (or --all) /ctx-remind Skill Natural language interface to reminders","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-1-leave-a-reminder","level":3,"title":"Step 1: Leave a Reminder","text":"

    Tell your agent what to remember, or run it directly:

    You: \"remind me to refactor the swagger definitions\"\n\nAgent: [runs ctx remind \"refactor the swagger definitions\"]\n       \"Reminder set:\n         + [1] refactor the swagger definitions\"\n

    Or from the terminal:

    ctx remind \"refactor the swagger definitions\"\n
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-2-set-a-date-gate-optional","level":3,"title":"Step 2: Set a Date Gate (Optional)","text":"

    If the reminder shouldn't fire until a specific date:

    You: \"remind me to check the deploy logs after Tuesday\"\n\nAgent: [runs ctx remind \"check the deploy logs\" --after 2026-02-25]\n       \"Reminder set:\n         + [2] check the deploy logs  (after 2026-02-25)\"\n

    The reminder stays silent until that date, then fires every session.

    The agent converts natural language dates (\"tomorrow\", \"next week\", \"after the release on Friday\") to YYYY-MM-DD. If it's ambiguous, it asks.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-3-start-a-new-session","level":3,"title":"Step 3: Start a New Session","text":"

    Next session, the reminder appears automatically before anything else:

    ┌─ Reminders ──────────────────────────────────────\n│  [1] refactor the swagger definitions\n│\n│ Dismiss: ctx remind dismiss <id>\n│ Dismiss all: ctx remind dismiss --all\n└──────────────────────────────────────────────────\n

    No action needed: The check-reminders hook fires on UserPromptSubmit and the agent relays the box verbatim.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-4-dismiss-when-done","level":3,"title":"Step 4: Dismiss When Done","text":"

    After you've acted on a reminder (or decided to skip it):

    You: \"dismiss reminder 1\"\n\nAgent: [runs ctx remind dismiss 1]\n       \"Dismissed:\n         - [1] refactor the swagger definitions\"\n

    Or clear everything:

    ctx remind dismiss --all\n
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#step-5-check-whats-pending","level":3,"title":"Step 5: Check What's Pending","text":"
    ctx remind list\n
      [1] refactor the swagger definitions\n  [3] review auth token expiry logic\n  [4] check deploy logs  (after 2026-02-25, not yet due)\n

    Date-gated reminders that haven't reached their date show (not yet due).

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#using-ctx-remind-in-a-session","level":2,"title":"Using /ctx-remind in a Session","text":"

    Invoke the /ctx-remind skill, then describe what you want:

    You: /ctx-remind remind me to update the API docs\nYou: /ctx-remind what reminders do I have?\nYou: /ctx-remind dismiss reminder 3\n
    You say (after /ctx-remind) What the agent does \"remind me to update the API docs\" ctx remind \"update the API docs\" \"remind me next week to check staging\" ctx remind \"check staging\" --after 2026-03-02 \"what reminders do I have?\" ctx remind list \"dismiss reminder 3\" ctx remind dismiss 3 \"clear all reminders\" ctx remind dismiss --all","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#reminders-vs-scratchpad-vs-tasks","level":2,"title":"Reminders vs Scratchpad vs Tasks","text":"You want to... Use Leave a note that announces itself next session ctx remind Jot down a quick value or sensitive token ctx pad Track work with status and completion TASKS.md Record a decision or lesson for all sessions Context files

    Decision guide:

    • If it should announce itself at session start → ctx remind
    • If it's a quiet note you'll check manually → ctx pad
    • If it's a work item you'll mark done → TASKS.md

    Reminders Are Sticky Notes, Not Tasks

    A reminder has no status, no priority, no lifecycle. It's a message to \"future you\" that fires until dismissed.

    If you need tracking, use a task in TASKS.md.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#tips","level":2,"title":"Tips","text":"
    • Reminders fire every session: Unlike nudges (which throttle to once per day), reminders repeat until you dismiss them. This is intentional: You asked to be reminded.
    • Date gating is session-scoped, not clock-scoped: --after 2026-02-25 means \"don't show until sessions on or after Feb 25.\" It does not mean \"alarm at midnight on Feb 25.\"
    • The agent handles date parsing: Say \"next week\" or \"after Friday\": The agent converts it to YYYY-MM-DD. The CLI only accepts the explicit date format.
    • Reminders are committed to git: They travel with the repo. If you switch machines, your reminders follow.
    • IDs never reuse: After dismissing reminder 3, the next reminder gets ID 4 (or higher). No confusion from recycled numbers.
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#next-up","level":2,"title":"Next Up","text":"

    Using the Scratchpad →: For quiet notes and sensitive values that don't need session-start announcements.

    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/session-reminders/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: ctx remind: full command syntax and flags
    • The Complete Session: how reminders fit into the session lifecycle
    • Managing Tasks: for work items that need status tracking
    ","path":["Recipes","Sessions","Session Reminders"],"tags":[]},{"location":"recipes/state-maintenance/","level":1,"title":"State Directory Maintenance","text":"","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#the-problem","level":2,"title":"The Problem","text":"

    Every session creates tombstone files in .context/state/ - small markers that suppress repeat hook nudges (\"already checked context size\", \"already sent persistence reminder\"). Over days and weeks, these accumulate into hundreds of files from long-dead sessions.

    The files are harmless individually, but the clutter makes it harder to reason about state, and stale global tombstones can suppress nudges across sessions entirely.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#tldr","level":2,"title":"TL;DR","text":"
    ctx system prune --dry-run     # preview what would be removed\nctx system prune               # prune files older than 7 days\nctx system prune --days 1      # more aggressive: keep only today\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#commands-used","level":2,"title":"Commands Used","text":"Tool Type Purpose ctx system prune Command Remove old per-session state files ctx status Command Quick health overview including state dir","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#understanding-state-files","level":2,"title":"Understanding State Files","text":"

    State files fall into two categories:

    Session-scoped (contain a UUID in the filename): Created per-session to suppress repeat nudges. Safe to prune once the session ends. Examples:

    context-check-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\nheartbeat-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\npersistence-nudge-11e94c1d-1639-4c04-bf77-63dcf1f50ec7\n

    Global (no UUID): Persist across sessions. ctx system prune preserves these automatically. Some are legitimate state (events.jsonl, memory-import.json); others may be stale tombstones that need manual review.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#the-workflow","level":2,"title":"The Workflow","text":"","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-1-preview","level":3,"title":"Step 1: Preview","text":"

    Always dry-run first to see what would be removed:

    ctx system prune --dry-run\n

    The output shows each file, its age, and a summary:

      would prune: context-check-abc123... (age: 3d)\n  would prune: heartbeat-abc123... (age: 3d)\n\nDry run - would prune 150 files (skip 70 recent, preserve 14 global)\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-2-prune","level":3,"title":"Step 2: Prune","text":"

    Choose an age threshold. The default is 7 days:

    ctx system prune               # older than 7 days\nctx system prune --days 3      # older than 3 days\nctx system prune --days 1      # older than 1 day (aggressive)\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-3-review-global-files","level":3,"title":"Step 3: Review Global Files","text":"

    After pruning, check what prune preserved:

    ls .context/state/ | grep -v '[0-9a-f]\\{8\\}-[0-9a-f]\\{4\\}'\n

    Legitimate global files (keep):

    • events.jsonl - event log
    • memory-import.json - import tracking state

    Stale global tombstones (safe to delete):

    • Files like backup-reminded, ceremony-reminded, version-checked with no session UUID are one-shot markers. If they are from a previous session, they are stale and can be removed manually.
    rm .context/state/backup-reminded .context/state/ceremony-reminded\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#step-4-verify","level":3,"title":"Step 4: Verify","text":"
    ls .context/state/ | wc -l    # should be manageable\n
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#when-to-prune","level":2,"title":"When to Prune","text":"
    • Weekly: ctx system prune with default 7-day threshold
    • After heavy parallel work: Multiple concurrent sessions create many tombstones. Prune with --days 1 afterward.
    • When state directory exceeds ~100 files: A sign that pruning hasn't run recently
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#tips","level":2,"title":"Tips","text":"

    Pruning active sessions is safe but noisy: If you prune a file belonging to a still-running session, the corresponding hook will re-fire its nudge on the next prompt. Minor UX annoyance, not data loss.

    No context files are stored in state: The state directory contains only tombstones, counters, and diagnostic data. Nothing in .context/state/ affects your decisions, learnings, tasks, or conventions.

    Test artifacts sneak in: Files like context-check-statstest or heartbeat-unknown are artifacts from development or testing. They lack UUIDs so prune preserves them. Delete manually.

    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/state-maintenance/#see-also","level":2,"title":"See Also","text":"
    • Detecting and Fixing Drift: broader context maintenance including drift detection and archival
    • Troubleshooting: diagnostic workflow using ctx doctor and event logs
    • CLI Reference: system: full flag documentation for ctx system prune and related commands
    ","path":["State Directory Maintenance"],"tags":[]},{"location":"recipes/system-hooks-audit/","level":1,"title":"Auditing System Hooks","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-problem","level":2,"title":"The Problem","text":"

    ctx runs 14 system hooks behind the scenes: nudging your agent to persist context, warning about resource pressure, gating commits on QA. But these hooks are invisible by design. You never see them fire. You never know if they stopped working.

    How do you verify your hooks are actually running, audit what they do, and get alerted when they go silent?

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tldr","level":2,"title":"TL;DR","text":"
    ctx system check-resources # run a hook manually\nls -la .context/logs/      # check hook execution logs\nctx notify setup           # get notified when hooks fire\n

    Or ask your agent: \"Are our hooks running?\"

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx system <hook> CLI command Run a system hook manually ctx system resources CLI command Show system resource status ctx system stats CLI command Stream or dump per-session token stats ctx notify setup CLI command Configure webhook for audit trail ctx notify test CLI command Verify webhook delivery .ctxrc notify.events Configuration Subscribe to relay for full hook audit .context/logs/ Log files Local hook execution ledger","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#what-are-system-hooks","level":2,"title":"What Are System Hooks?","text":"

    System hooks are plumbing commands that ctx registers with your AI tool (Claude Code, Cursor, etc.) via the plugin's hooks.json. They fire automatically at specific events during your AI session:

    Event When Hooks UserPromptSubmit Before the agent sees your prompt 10 check hooks + heartbeat PreToolUse Before the agent uses a tool block-non-path-ctx, qa-reminder PostToolUse After a tool call succeeds post-commit

    You never run these manually. Your AI tool runs them for you: That's the point.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-complete-hook-catalog","level":2,"title":"The Complete Hook Catalog","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#prompt-time-checks-userpromptsubmit","level":3,"title":"Prompt-Time Checks (UserPromptSubmit)","text":"

    These fire before every prompt, but most are throttled to avoid noise.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-context-size-context-capacity-warning","level":4,"title":"check-context-size: Context Capacity Warning","text":"

    What: Adaptive prompt counter. Silent for the first 15 prompts, then nudges with increasing frequency (every 5th, then every 3rd).

    Why: Long sessions lose coherence. The nudge reminds both you and the agent to persist context before the window fills up.

    Output: VERBATIM relay box with prompt count.

    ┌─ Context Checkpoint (prompt #20) ────────────────\n│ This session is getting deep. Consider wrapping up\n│ soon. If there are unsaved learnings, decisions, or\n│ conventions, now is a good time to persist them.\n│ ⏱ Context window: ~45k tokens (~22% of 200k)\n└──────────────────────────────────────────────────\n

    Stats: Every prompt records token usage to .context/state/stats-{session}.jsonl. Monitor live with ctx system stats --follow or query with ctx system stats --json. Stats are recorded even during wrap-up suppression (event: suppressed).

    Billing guard: When billing_token_warn is set in .ctxrc, a one-shot warning fires if session tokens exceed the threshold. This warning is independent of all other triggers - it fires even during wrap-up suppression.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-persistence-context-staleness-nudge","level":4,"title":"check-persistence: Context Staleness Nudge","text":"

    What: Tracks when .context/*.md files were last modified. If too many prompts pass without a write, nudges the agent to persist.

    Why: Sessions produce insights that evaporate if not recorded. This catches the \"we talked about it but never wrote it down\" failure mode.

    Output: VERBATIM relay after 20+ prompts without a context file change.

    ┌─ Persistence Checkpoint (prompt #20) ───────────\n│ No context files updated in 20+ prompts.\n│ Have you discovered learnings, made decisions,\n│ established conventions, or completed tasks\n│ worth persisting?\n│\n│ Run /ctx-wrap-up to capture session context.\n└──────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-ceremonies-session-ritual-adoption","level":4,"title":"check-ceremonies: Session Ritual Adoption","text":"

    What: Scans your last 3 journal entries for /ctx-remember and /ctx-wrap-up usage. Nudges once per day if missing.

    Why: Session ceremonies are the highest-leverage habit in ctx. This hook bootstraps the habit until it becomes automatic.

    Output: Tailored nudge depending on which ceremony is missing.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-journal-unexported-session-reminder","level":4,"title":"check-journal: Unexported Session Reminder","text":"

    What: Detects unexported Claude Code sessions and unenriched journal entries. Fires once per day.

    Why: Exported sessions become searchable history. Unenriched entries lack metadata for filtering. Both decay in value over time.

    Output: VERBATIM relay with counts and exact commands.

    ┌─ Journal Reminder ─────────────────────────────\n│ You have 3 new session(s) not yet exported.\n│ 5 existing entries need enrichment.\n│\n│ Export and enrich:\n│   ctx recall export --all\n│   /ctx-journal-enrich-all\n└────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-resources-system-resource-pressure","level":4,"title":"check-resources: System Resource Pressure","text":"

    What: Monitors memory, swap, disk, and CPU load. Only fires at DANGER severity (memory >= 90%, swap >= 75%, disk >= 95%, load >= 1.5x CPU count).

    Why: Resource exhaustion mid-session can corrupt work. This provides early warning to persist and exit.

    Output: VERBATIM relay listing critical resources.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-knowledge-knowledge-file-growth","level":4,"title":"check-knowledge: Knowledge File Growth","text":"

    What: Counts entries in LEARNINGS.md, DECISIONS.md, and lines in CONVENTIONS.md. Fires once per day when thresholds are exceeded.

    Why: Large knowledge files dilute agent context. 35 learnings compete for attention; 15 focused ones get applied. Thresholds are configurable in .ctxrc.

    Default thresholds:

    # .ctxrc\nentry_count_learnings: 30\nentry_count_decisions: 20\nconvention_line_count: 200\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-version-binaryplugin-version-drift","level":4,"title":"check-version: Binary/Plugin Version Drift","text":"

    What: Compares the ctx binary version against the plugin version. Fires once per day. Also checks encryption key age for rotation nudge.

    Why: Version drift means hooks reference features the binary doesn't have. The key rotation nudge prevents indefinite key reuse.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-reminders-pending-reminder-relay","level":4,"title":"check-reminders: Pending Reminder Relay","text":"

    What: Reads .context/reminders.json and surfaces any due reminders via VERBATIM relay. No throttle: fires every session until dismissed.

    Why: Reminders are sticky notes to future-you. Unlike nudges (which throttle to once per day), reminders repeat deliberately until the user dismisses them.

    Output: VERBATIM relay box listing due reminders.

    ┌─ Reminders ──────────────────────────────────────\n│  [1] refactor the swagger definitions\n│\n│ Dismiss: ctx remind dismiss <id>\n│ Dismiss all: ctx remind dismiss --all\n└──────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-freshness-technology-constant-staleness","level":4,"title":"check-freshness: Technology Constant Staleness","text":"

    What: Stats files listed in .ctxrc freshness_files and warns if any haven't been modified in over 6 months. Daily throttle. Silent when no files are configured (opt-in via .ctxrc).

    Why: Model capabilities evolve - token budgets, attention limits, and context window sizes that were accurate 6 months ago may no longer reflect best practices. This hook reminds you to review and touch the file to confirm values are still current.

    Config (.ctxrc):

    freshness_files:\n  - path: config/thresholds.yaml\n    desc: Model token limits and batch sizes\n    review_url: https://docs.example.com/limits  # optional\n

    Each entry has a path (relative to project root), desc (what constants live there), and optional review_url (where to check current values). When review_url is set, the nudge includes \"Review against: {url}\". When absent, just \"Touch the file to mark it as reviewed.\"

    Output: VERBATIM relay listing stale files, silent otherwise.

    ┌─ Technology Constants Stale ──────────────────────\n│   config/thresholds.yaml (210 days ago)\n│     - Model token limits and batch sizes\n│   Review against: https://docs.example.com/limits\n│ Touch each file to mark it as reviewed.\n└───────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#check-map-staleness-architecture-map-drift","level":4,"title":"check-map-staleness: Architecture Map Drift","text":"

    What: Checks whether map-tracking.json is older than 30 days and there are commits touching internal/ since the last map refresh. Daily throttle prevents repeated nudges.

    Why: Architecture documentation drifts silently as code evolves. This hook detects structural changes that the map hasn't caught up with and suggests running /ctx-architecture to refresh.

    Output: VERBATIM relay when stale and modules changed, silent otherwise.

    ┌─ Architecture Map Stale ────────────────────────────\n│ ARCHITECTURE.md hasn't been refreshed since 2026-01-15\n│ and there are commits touching 12 modules.\n│ /ctx-architecture keeps architecture docs drift-free.\n│\n│ Want me to run /ctx-architecture to refresh?\n└─────────────────────────────────────────────────────\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#heartbeat-session-heartbeat-webhook","level":4,"title":"heartbeat: Session Heartbeat Webhook","text":"

    What: Fires on every prompt. Sends a webhook notification with prompt count, session ID, context modification status, and token usage telemetry. Never produces stdout.

    Why: Other hooks only send webhooks when they \"speak\" (nudge/relay). When silent, you have no visibility into session activity. The heartbeat provides a continuous session-alive signal with token consumption data for observability dashboards or liveness monitoring.

    Output: None (webhook + event log only).

    Payload:

    {\n  \"event\": \"heartbeat\",\n  \"message\": \"heartbeat: prompt #7 (context_modified=false tokens=158k pct=79%)\",\n  \"detail\": {\n    \"hook\": \"heartbeat\",\n    \"variant\": \"pulse\",\n    \"variables\": {\n      \"prompt_count\": 7,\n      \"session_id\": \"abc...\",\n      \"context_modified\": false,\n      \"tokens\": 158000,\n      \"context_window\": 200000,\n      \"usage_pct\": 79\n    }\n  }\n}\n

    Token fields (tokens, context_window, usage_pct) are included when usage data is available from the session JSONL file.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tool-time-hooks-pretooluse-posttooluse","level":3,"title":"Tool-Time Hooks (PreToolUse / PostToolUse)","text":"","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#block-non-path-ctx-path-enforcement-hard-gate","level":4,"title":"block-non-path-ctx: PATH Enforcement (Hard Gate)","text":"

    What: Blocks any Bash command that invokes ./ctx, ./dist/ctx, go run ./cmd/ctx, or an absolute path to ctx. Only PATH invocations are allowed.

    Why: Enforces CONSTITUTION.md's invocation invariant. Running a dev-built binary in production context causes version confusion and silent behavior drift.

    Output: Block response (prevents the tool call):

    {\"decision\": \"block\", \"reason\": \"Use 'ctx' from PATH, not './ctx'...\"}\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#qa-reminder-pre-commit-qa-gate","level":4,"title":"qa-reminder: Pre-Commit QA Gate","text":"

    What: Fires on every Edit tool use. Reminds the agent to lint and test the entire project before committing.

    Why: Agents tend to \"I'll test later\" and then commit untested code. Repetition is intentional: the hook reinforces the habit on every edit, not just before commits.

    Output: Agent directive with hard QA gate instructions.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#post-commit-context-capture-after-commit","level":4,"title":"post-commit: Context Capture After Commit","text":"

    What: Fires after any git commit (excludes --amend). Prompts the agent to offer context capture (decision? learning?) and suggest running lints/tests before pushing.

    Why: Commits are natural reflection points. The nudge converts mechanical git operations into context-capturing opportunities.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#auditing-hooks-via-the-local-event-log","level":2,"title":"Auditing Hooks via the Local Event Log","text":"

    If you don't need an external audit trail, enable the local event log for a self-contained record of hook activity:

    # .ctxrc\nevent_log: true\n

    Once enabled, every hook that fires writes an entry to .context/state/events.jsonl. Query it with ctx system events:

    ctx system events                    # last 50 events\nctx system events --hook qa-reminder # filter by hook\nctx system events --session <id>     # filter by session\nctx system events --json | jq '.'    # raw JSONL for processing\n

    The event log is local, queryable, and doesn't require any external service. For a full diagnostic workflow combining event logs with structural health checks, see Troubleshooting.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#auditing-hooks-via-webhooks","level":2,"title":"Auditing Hooks via Webhooks","text":"

    The most powerful audit setup pipes all hook output to a webhook, giving you a real-time external record of what your agent is being told.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-1-set-up-the-webhook","level":3,"title":"Step 1: Set Up the Webhook","text":"
    ctx notify setup\n# Enter your webhook URL (Slack, Discord, ntfy.sh, IFTTT, etc.)\n

    See Webhook Notifications for service-specific setup.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-2-subscribe-to-relay-events","level":3,"title":"Step 2: Subscribe to relay Events","text":"
    # .ctxrc\nnotify:\n  events:\n    - relay   # all hook output: VERBATIM relays, directives, blocks\n    - nudge   # just the user-facing VERBATIM relays\n

    The relay event fires for every hook that produces output. This includes:

    Hook Event sent check-context-size relay + nudge check-persistence relay + nudge check-ceremonies relay + nudge check-journal relay + nudge check-resources relay + nudge check-knowledge relay + nudge check-version relay + nudge check-reminders relay + nudge check-freshness relay + nudge check-map-staleness relay + nudge heartbeat heartbeat only block-non-path-ctx relay only post-commit relay only qa-reminder relay only","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#step-3-cross-reference","level":3,"title":"Step 3: Cross-Reference","text":"

    With relay enabled, your webhook receives a JSON payload every time a hook fires:

    {\n  \"event\": \"relay\",\n  \"message\": \"check-persistence: No context updated in 20+ prompts\",\n  \"session_id\": \"b854bd9c\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"my-project\"\n}\n

    This creates an external audit trail independent of the agent. You can now cross-verify: did the agent actually relay the checkpoint the hook told it to relay?

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#verifying-hooks-actually-fire","level":2,"title":"Verifying Hooks Actually Fire","text":"

    Hooks are invisible. An invisible thing that breaks is indistinguishable from an invisible thing that never existed. Three verification methods, from simplest to most robust:

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-1-ask-the-agent","level":3,"title":"Method 1: Ask the Agent","text":"

    The simplest check. After a few prompts into a session:

    \"Did you receive any hook output this session? Print the last\ncontext checkpoint or persistence nudge you saw.\"\n

    The agent should be able to recall recent hook output from its context window. If it says \"I haven't received any hook output\", either:

    • The hooks aren't firing (check installation);
    • The session is too short (hooks throttle early);
    • The hooks fired but the agent absorbed them silently.

    Limitation: You are trusting the agent to report accurately. Agents sometimes confabulate or miss context. Use this as a quick smoke test, not definitive proof.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-2-check-the-webhook-trail","level":3,"title":"Method 2: Check the Webhook Trail","text":"

    If you have relay events enabled, check your webhook receiver. Every hook that fires sends a timestamped notification. No notification = no fire.

    This is the ground truth. The webhook is called directly by the ctx binary, not by the agent. The agent cannot fake, suppress, or modify webhook deliveries.

    Compare what the webhook received against what the agent claims to have relayed. Discrepancies mean the agent is absorbing nudges instead of surfacing them.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#method-3-read-the-local-logs","level":3,"title":"Method 3: Read the Local Logs","text":"

    Hooks that support logging write to .context/logs/:

    # Check context-size hook activity\ncat .context/logs/check-context-size.log\n\n# Sample output:\n# [2026-02-22 09:15:00] [session:b854bd9c] prompt#1 silent\n# [2026-02-22 09:17:33] [session:b854bd9c] prompt#16 CHECKPOINT\n# [2026-02-22 09:20:01] [session:b854bd9c] prompt#20 CHECKPOINT\n
    # Check persistence nudge activity\ncat .context/logs/check-persistence.log\n\n# Sample output:\n# [2026-02-22 09:15:00] [session:b854bd9c] init count=1 mtime=1770646611\n# [2026-02-22 09:20:01] [session:b854bd9c] prompt#20 NUDGE since_nudge=20\n

    Logs are append-only and written by the ctx binary, not the agent.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#detecting-silent-hook-failures","level":2,"title":"Detecting Silent Hook Failures","text":"

    The hardest failure mode: hooks that stop firing without error. The plugin config changes, a binary update drops a hook, or a PATH issue silently breaks execution. Nothing errors: The hook just never runs.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#the-staleness-signal","level":3,"title":"The Staleness Signal","text":"

    If .context/logs/check-context-size.log has no entries newer than 5 days but you've been running sessions daily, something is wrong. The absence of evidence is evidence of absence: but only if you control for inactivity.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#false-positive-protection","level":3,"title":"False Positive Protection","text":"

    A naive \"hooks haven't fired in N days\" alert fires incorrectly when you simply haven't used ctx. The correct check needs two inputs:

    1. Last hook fire time: from .context/logs/ or webhook history
    2. Last session activity: from journal entries or ctx recall list

    If sessions are happening but hooks aren't firing, that's a real problem. If neither sessions nor hooks are happening, that's a vacation.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#what-to-check","level":3,"title":"What to Check","text":"

    When you suspect hooks aren't firing:

    # 1. Verify the plugin is installed\nls ~/.claude/plugins/\n\n# 2. Check hook registration\ncat ~/.claude/plugins/ctx/hooks.json | head -20\n\n# 3. Run a hook manually to see if it errors\necho '{\"session_id\":\"test\"}' | ctx system check-context-size\n\n# 4. Check for PATH issues\nwhich ctx\nctx --version\n
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#tips","level":2,"title":"Tips","text":"
    • Start with nudge, graduate to relay: The nudge event covers user-facing VERBATIM relays. Add relay when you want full visibility into agent directives and hard gates.
    • Webhooks are your trust anchor: The agent can ignore a nudge, but it can't suppress the webhook. If the webhook fired and the agent didn't relay, you have proof of a compliance gap.
    • Hooks are throttled by design: Most check hooks fire once per day or use adaptive frequency. Don't expect a notification every prompt: Silence usually means the throttle is working, not that the hook is broken.
    • Daily markers live in .context/state/: Throttle files are stored in .context/state/ alongside other project-scoped state. If you need to force a hook to re-fire during testing, delete the corresponding marker file.
    • The QA reminder is intentionally noisy: Unlike other hooks, qa-reminder fires on every Edit call with no throttle. This is deliberate: The commit quality degrades when the reminder fades from salience.
    • Log files are safe to commit: .context/logs/ contains only timestamps, session IDs, and status keywords. No secrets, no code.
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#next-up","level":2,"title":"Next Up","text":"

    Detecting and Fixing Drift →: Keep context files accurate as your codebase evolves.

    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/system-hooks-audit/#see-also","level":2,"title":"See Also","text":"
    • Troubleshooting: full diagnostic workflow using ctx doctor, event logs, and /ctx-doctor
    • Customizing Hook Messages: override what hooks say without changing what they do
    • Webhook Notifications: setting up and configuring the webhook system
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Detecting and Fixing Drift: structural checks that complement runtime hook auditing
    • CLI Reference: full ctx system command reference
    ","path":["Recipes","Hooks and Notifications","Auditing System Hooks"],"tags":[]},{"location":"recipes/task-management/","level":1,"title":"Tracking Work Across Sessions","text":"","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-problem","level":2,"title":"The Problem","text":"

    You have work that spans multiple sessions. Tasks get added during one session, partially finished in another, and completed days later.

    Without a system, follow-up items fall through the cracks, priorities drift, and you lose track of what was done versus what still needs doing. TASKS.md grows cluttered with completed checkboxes that obscure the remaining work.

    How do you manage work items that span multiple sessions without losing context?

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#tldr","level":2,"title":"TL;DR","text":"

    Manage Tasks:

    ctx add task \"Fix race condition\" --priority high  # add\nctx add task \"Write tests\" --section \"Phase 2\"     # add to phase\nctx task complete \"race condition\"                      # mark done\nctx task snapshot \"before-refactor\"               # backup\nctx task archive                                  # clean up\n

    Pick Up the Next Task:

    /ctx-next # pick what's next\n

    Read on for the full workflow and conversational patterns.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx add task Command Add a new task to TASKS.md ctx task complete Command Mark a task as done by number or text ctx task snapshot Command Create a point-in-time backup of TASKS.md ctx task archive Command Move completed tasks to archive file /ctx-add-task Skill AI-assisted task creation with validation /ctx-archive Skill AI-guided archival with safety checks /ctx-next Skill Pick what to work on based on priorities","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-1-add-tasks-with-priorities","level":3,"title":"Step 1: Add Tasks with Priorities","text":"

    Every piece of follow-up work gets a task. Use ctx add task from the terminal or /ctx-add-task from your AI assistant. Tasks should start with a verb and be specific enough that someone unfamiliar with the session could act on them.

    # High-priority bug found during code review\nctx add task \"Fix race condition in session cooldown\" --priority high\n\n# Medium-priority feature work\nctx add task \"Add --format json flag to ctx status for CI integration\" --priority medium\n\n# Low-priority cleanup\nctx add task \"Remove deprecated --raw flag from ctx load\" --priority low\n

    The /ctx-add-task skill validates your task before recording it. It checks that the description is actionable, not a duplicate, and specific enough for someone else to pick up.

    If you say \"fix the bug,\" it will ask you to clarify which bug and where.

    Tasks Are Often Created Proactively

    In practice, many tasks are created proactively by the agent rather than by explicit CLI commands.

    After completing a feature, the agent will often identify follow-up work: tests, docs, edge cases, error handling, and offer to add them as tasks.

    You do not need to dictate ctx add task commands; the agent picks up on work context and suggests tasks naturally.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-2-organize-with-phase-sections","level":3,"title":"Step 2: Organize with Phase Sections","text":"

    Tasks live in phase sections inside TASKS.md.

    Phases provide logical groupings that preserve order and enable replay.

    A task does not move between sections. It stays in its phase permanently, and status is tracked via checkboxes and inline tags.

    ## Phase 1: Core CLI\n\n- [x] Implement ctx add command `#done:2026-02-01-143022`\n- [x] Implement ctx task complete command `#done:2026-02-03-091544`\n- [ ] Add --section flag to ctx add task `#priority:medium`\n\n## Phase 2: AI Integration\n\n- [ ] Implement ctx agent cooldown `#priority:high` `#in-progress`\n- [ ] Add ctx watch XML parsing `#priority:medium`\n  - Blocked by: Need to finalize agent output format\n\n## Backlog\n\n- [ ] Performance optimization for large TASKS.md files `#priority:low`\n- [ ] Add metrics dashboard to ctx status `#priority:deferred`\n

    Use --section when adding a task to a specific phase:

    ctx add task \"Add ctx watch XML parsing\" --priority medium --section \\\n    \"Phase 2: AI Integration\"\n

    Without --section, the task is inserted before the first unchecked task in TASKS.md.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-3-pick-what-to-work-on","level":3,"title":"Step 3: Pick What to Work On","text":"

    At the start of a session, or after finishing a task, use /ctx-next to get prioritized recommendations.

    The skill reads TASKS.md, checks recent sessions, and ranks candidates using explicit priority, blocking status, in-progress state, momentum from recent work, and phase order.

    You can also ask naturally: \"what should we work on?\" or \"what's the highest priority right now?\"

    /ctx-next\n

    The output looks like this:

    **1. Implement ctx agent cooldown** `#priority:high`\n\n    Still in-progress from yesterday's session. The tombstone file approach is\n    half-built. Finishing is cheaper than context-switching.\n\n**2. Add --section flag to ctx add task** `#priority:medium`\n\n    Last Phase 1 item. Quick win that unblocks organized task entry.\n\n---\n\n*Based on 8 pending tasks across 3 phases.\n\nLast session: agent-cooldown (2026-02-06).*\n

    In-progress tasks almost always come first:

    Finishing existing work takes priority over starting new work.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-4-complete-tasks","level":3,"title":"Step 4: Complete Tasks","text":"

    When a task is done, mark it complete by number or partial text match:

    # By task number (as shown in TASKS.md)\nctx task complete 3\n\n# By partial text match\nctx task complete \"agent cooldown\"\n

    The task's checkbox changes from [ ] to [x] and a #done timestamp is added. Tasks are never deleted: they stay in their phase section so history is preserved.

    Be Conversational

    You rarely need to run ctx task complete yourself during an interactive session.

    When you say something like \"the rate limiter is done\" or \"we finished that,\" the agent marks the task complete and moves on to suggesting what is next.

    The CLI commands are most useful for manual housekeeping, scripted workflows, or when you want precision.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-5-snapshot-before-risky-changes","level":3,"title":"Step 5: Snapshot Before Risky Changes","text":"

    Before a major refactor or any change that might break things, snapshot your current task state. This creates a copy of TASKS.md in .context/archive/ without modifying the original.

    # Default snapshot\nctx task snapshot\n\n# Named snapshot (recommended before big changes)\nctx task snapshot \"before-refactor\"\n

    This creates a file like .context/archive/tasks-before-refactor-2026-02-08-1430.md. If the refactor goes sideways, and you need to confirm what the task state looked like before you started, the snapshot is there.

    Snapshots are cheap: Take them before any change you might want to undo or review later.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#step-6-archive-when-tasksmd-gets-cluttered","level":3,"title":"Step 6: Archive When TASKS.md Gets Cluttered","text":"

    After several sessions, TASKS.md accumulates completed tasks that make it hard to see what is still pending.

    Use ctx task archive to move all [x] items to a timestamped archive file.

    Start with a dry run to preview what will be moved:

    ctx task archive --dry-run\n

    Then archive:

    ctx task archive\n

    Completed tasks move to .context/archive/tasks-2026-02-08.md. Phase headers are preserved in the archive for traceability. Pending tasks ([ ]) remain in TASKS.md.

    The /ctx-archive skill adds two safety checks before archiving: it verifies that completed tasks are genuinely cluttering the view and that nothing was marked [x] prematurely.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#letting-the-agent-drive","level":2,"title":"Letting the Agent Drive","text":"

    The steps above show the CLI commands for task management.

    In practice, most task management happens conversationally:

    An agent that has loaded the context files does not need you to type ctx add task. It tracks work naturally and offers the right operations.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#use-natural-language-instead-of-commands","level":3,"title":"Use Natural Language Instead of Commands","text":"

    These conversational prompts replace explicit commands during interactive sessions:

    Instead of typing... Just say... ctx add task \"Write tests for X\" \"We should add tests for this: track that?\" /ctx-next \"What should we work on?\" ctx task complete \"rate limiting\" \"The rate limiter is done, what's next?\" ctx task archive \"TASKS.md is getting long, can you clean it up?\" ctx add task ... && ctx add task ... \"Add follow-ups for what we just built.\"

    The agent translates these into the right ctx operations behind the scenes.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-agent-creates-tasks-proactively","level":3,"title":"The Agent Creates Tasks Proactively","text":"

    After completing a piece of work, the agent does not wait for you to dictate follow-up items. It identifies them from the work context and offers:

    **Agent**: \"I've finished implementing the rate limiter middleware. I noticed\nthree follow-up items:\n\n1. Write integration tests for the rate limiter (the unit tests pass but\n   there's no end-to-end coverage)\n2. Add rate limit headers to API responses (X-RateLimit-Remaining, etc.)\n3. Document the rate limit configuration in the ops runbook\n\nWant me to add these as tasks?\"\n

    This is how an agent behaves once it has read the Agent Playbook.

    The playbook's \"Work, Reflect, Persist\" cycle means the agent asks itself after every milestone: Did I just complete a task? Did new work emerge?

    When the answer is yes, it acts.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#asking-the-agent-what-to-capture","level":3,"title":"Asking the Agent What to Capture","text":"

    You don't always know what's worth persisting.

    Instead of reviewing the session yourself and typing specific commands, ask the agent to do the thinking:

    You say What happens \"What tasks came out of this session?\" Agent reviews the work, identifies follow-ups, and offers to add them \"Are there any tasks, learnings, or decisions worth adding?\" Agent scans the full session for all three types and proposes a batch \"What should we remember from today?\" Agent surfaces everything persist-worthy: not just tasks \"Anything we should track before we move on?\" Agent checks for loose ends specific to the work just completed

    This is especially powerful after long or exploratory sessions where multiple threads were touched.

    The agent has the full conversation in context and can spot follow-ups you might miss:

    You:   \"Are there any tasks, learnings, or decisions worth adding\n        from this session?\"\n\nAgent: \"Yes. Here's what I'd suggest:\n\n  Tasks:\n  - Add retry logic to the webhook delivery (we discussed it when\n    the timeout test failed but never tracked it)\n  - Update the API docs to reflect the new rate limit headers\n\n  Learnings:\n  - net/http's default client has no timeout: we burned 15 minutes\n    on that before adding an explicit 30s timeout\n\n  Decisions:\n  - We chose token-bucket over sliding-window for rate limiting\n    because it handles bursts better and the library is simpler\n\n  Want me to add all of these?\"\n\nYou:   \"All of them.\"\n

    The agent fills in structured fields from what it observed during the session. You get the same quality entries as if you typed verbose commands, without needing to remember what happened or how to format it.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#the-agent-completes-tasks-and-moves-on","level":3,"title":"The Agent Completes Tasks and Moves On","text":"

    When you confirm that work is finished, or when the agent can see that it is, it marks the task done and suggests the next step:

    You: \n\"The cooldown logic is working now.\"\n\nAgent: \n\"Marked 'Implement ctx agent cooldown' as done. Your highest-\npriority remaining task is 'Add --section flag to ctx add task'.\n\nIt's the last item in Phase 1 and a quick win. Want to start on that?\"\n

    The agent chains completion into next-task selection.

    One sentence from you triggers two operations.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#end-of-session-capture","level":3,"title":"End-of-Session Capture","text":"

    At the end of a session, the agent reviews what happened and catches loose ends:

    You: \n\"I think we're good for today.\"\n\nAgent: \n\"Before we wrap up: during the middleware work you mentioned\nwanting to add metrics for rate limit hits. That never made it into TASKS.md.\n\nWant me to add it as a task so it's there next session?\"\n

    This is the proactive persistence model at work.

    The agent monitors the conversation for mentioned-but-not-tracked work and surfaces it before context is lost.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#a-conversational-session-example","level":3,"title":"A Conversational Session Example","text":"

    Here is what task management looks like in a real session when the agent is driving:

    You:   What's left to do?\nAgent: You have 5 pending tasks across 2 phases. The highest priority is\n       \"Implement ctx agent cooldown\": it's marked in-progress from\n       yesterday and half-built. Want to pick that up?\n\nYou:   Yeah, let's finish it.\n       [... 20 minutes of implementation work ...]\n\nYou:   That's working. Tests pass.\nAgent: Nice. I'll mark \"Implement ctx agent cooldown\" as done.\n       I noticed two things from the implementation:\n       1. The tombstone file cleanup should happen on a timer, not just\n          at startup. Want me to add that as a task?\n       2. We learned that file locks don't work reliably on NFS. I'll\n          add that to LEARNINGS.md.\n\nYou:   Yes to both. What's next?\nAgent: Added the cleanup task as high priority. Next up is \"Add --section\n       flag to ctx add task\": last item in Phase 1. It should be\n       straightforward since the flag parsing pattern already exists\n       in the codebase. Ready?\n

    It's All Conversational

    Notice what did not happen: The user never typed a ctx command.

    The agent handled task completion, follow-up creation, learning capture, and next-task selection: all from natural conversation.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"
    # Add a task\nctx add task \"Implement rate limiting for API endpoints\" --priority high\n\n# Add to a specific phase\nctx add task \"Write integration tests for rate limiter\" --section \"Phase 2\"\n\n# See what to work on\n# (from AI assistant) /ctx-next\n\n# Mark done by text\nctx task complete \"rate limiting\"\n\n# Mark done by number\nctx task complete 5\n\n# Snapshot before a risky refactor\nctx task snapshot \"before-middleware-rewrite\"\n\n# Archive completed tasks when the list gets long\nctx task archive --dry-run     # preview first\nctx task archive               # then archive\n
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#tips","level":2,"title":"Tips","text":"
    • Start tasks with a verb: \"Add,\" \"Fix,\" \"Implement,\" \"Investigate\": not just a topic like \"Authentication.\"
    • Include the why in the task description. Future sessions lack the context of why you added the task. \"Add rate limiting\" is worse than \"Add rate limiting to prevent abuse on the public API after the load test showed 10x traffic spikes.\"
    • Use #in-progress sparingly. Only one or two tasks should carry this tag at a time. If everything is in-progress, nothing is.
    • Snapshot before, not after. The point of a snapshot is to capture the state before a change, not to celebrate what you just finished.
    • Archive regularly. Once completed tasks outnumber pending ones, it is time to archive. A clean TASKS.md helps both you and your AI assistant focus.
    • Never delete tasks. Mark them [x] (completed) or [-] (skipped with a reason). Deletion breaks the audit trail.
    • Trust the agent's task instincts. When the agent suggests follow-up items after completing work, it is drawing on the full context of what just happened.
    • Conversational prompts beat commands in interactive sessions. Saying \"what should we work on?\" is faster and more natural than running /ctx-next. Save explicit commands for scripts, CI, and unattended runs.
    • Let the agent chain operations. A single statement like \"that's done, what's next?\" can trigger completion, follow-up identification, and next-task selection in one flow.
    • Review proactive task suggestions before moving on. The best follow-ups come from items spotted in-context right after the work completes.
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#next-up","level":2,"title":"Next Up","text":"

    Using the Scratchpad →: Store short-lived sensitive notes in an encrypted scratchpad.

    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/task-management/#see-also","level":2,"title":"See Also","text":"
    • The Complete Session: full session lifecycle including task management in context
    • Persisting Decisions, Learnings, and Conventions: capturing the \"why\" behind your work
    • Detecting and Fixing Drift: keeping TASKS.md accurate over time
    • CLI Reference: full documentation for ctx add, ctx task complete, ctx task
    • Context Files: TASKS.md: format and conventions for TASKS.md
    ","path":["Recipes","Knowledge and Tasks","Tracking Work Across Sessions"],"tags":[]},{"location":"recipes/troubleshooting/","level":1,"title":"Troubleshooting","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-problem","level":2,"title":"The Problem","text":"

    Something isn't working: a hook isn't firing, nudges are too noisy, context seems stale, or the agent isn't following instructions. The information to diagnose it exists (across status, drift, event logs, hook config, and session history), but assembling it manually is tedious.

    How do you figure out what's wrong and fix it?

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#tldr","level":2,"title":"TL;DR","text":"
    ctx doctor                   # structural health check\nctx system events --last 20  # recent hook activity\n# or ask: \"something seems off, can you diagnose?\"\n
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx doctor CLI command Structural health report ctx doctor --json CLI command Machine-readable health report ctx system events CLI command Query local event log /ctx-doctor Skill Agent-driven diagnosis with analysis","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#quick-check-ctx-doctor","level":3,"title":"Quick Check: ctx doctor","text":"

    Run ctx doctor for an instant structural health report. It checks context initialization, required files, drift, hook configuration, event logging, webhooks, reminders, task completion ratio, and context token size: all in one pass:

    ctx doctor\n
    ctx doctor\n==========\n\nStructure\n  ✓ Context initialized (.context/)\n  ✓ Required files present (4/4)\n\nQuality\n  ⚠ Drift: 2 warnings (stale path in ARCHITECTURE.md, high entry count in LEARNINGS.md)\n\nHooks\n  ✓ hooks.json valid (14 hooks registered)\n  ○ Event logging disabled (enable with event_log: true in .ctxrc)\n\nState\n  ✓ No pending reminders\n  ⚠ Task completion ratio high (18/22 = 82%): consider archiving\n\nSize\n  ✓ Context size: ~4200 tokens (budget: 8000)\n\nSummary: 2 warnings, 0 errors\n

    Warnings are non-critical but worth fixing. Errors need attention. Informational notes (○) flag optional features that aren't enabled.

    For scripting:

    ctx doctor --json | jq '.warnings'\n
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#deep-dive-ctx-doctor","level":3,"title":"Deep Dive: /ctx-doctor","text":"

    When you need the agent to reason about what's wrong, use the skill. Ask naturally or invoke directly:

    Why didn't my hook fire?\nSomething seems off, can you diagnose?\n/ctx-doctor\n

    The agent follows a triage sequence:

    1. Baseline: runs ctx doctor --json for structural health
    2. Events: runs ctx system events --json --last 100 (if event logging enabled)
    3. Correlate: connects findings across both sources
    4. Present: structured findings with evidence
    5. Suggest: actionable next steps (but doesn't auto-fix)

    The skill degrades gracefully: without event logging enabled, it still runs structural checks and notes what you'd gain by enabling it.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#raw-event-inspection","level":3,"title":"Raw Event Inspection","text":"

    For power users: ctx system events with filters gives direct access to the event log.

    # Last 50 events (default)\nctx system events\n\n# Events from a specific session\nctx system events --session eb1dc9cd-0163-4853-89d0-785fbfaae3a6\n\n# Only QA reminder events\nctx system events --hook qa-reminder\n\n# Raw JSONL for jq processing\nctx system events --json | jq '.message'\n\n# Include rotated (older) events\nctx system events --all --last 100\n

    Filters use AND logic: --hook qa-reminder --session abc123 returns only QA reminder events from that specific session.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#common-problems","level":2,"title":"Common Problems","text":"","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#ctx-not-initialized","level":3,"title":"\"ctx: not initialized\"","text":"

    Symptoms: Any ctx command fails with ctx: not initialized - run \"ctx init\" first.

    Cause: You're running ctx in a directory without an initialized .context/ directory. This guard runs on all user-facing commands to prevent confusing downstream errors.

    Fix:

    ctx init          # create .context/ with template files\nctx init --minimal  # or just the essentials (CONSTITUTION, TASKS, DECISIONS)\n

    Commands that work without initialization: ctx init, ctx hook, ctx doctor, and help-only grouping commands (ctx, ctx system).

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#my-hook-isnt-firing","level":3,"title":"\"My hook isn't firing\"","text":"

    Symptoms: No nudges appearing, webhook silent, event log shows no entries for the expected hook.

    Diagnosis:

    # 1. Check if ctx is installed and on PATH\nwhich ctx && ctx --version\n\n# 2. Check if the hook is registered\ngrep \"check-persistence\" ~/.claude/plugins/ctx/hooks.json\n\n# 3. Run the hook manually to see if it errors\necho '{\"session_id\":\"test\"}' | ctx system check-persistence\n\n# 4. Check event log for the hook (if enabled)\nctx system events --hook check-persistence\n

    Common causes:

    • Plugin is not installed: run ctx init --claude to reinstall
    • PATH issue: the hook invokes ctx from PATH; ensure it resolves
    • Throttle active: most hooks fire once per day: check .context/state/ for daily marker files
    • Hook silenced: a custom message override may be an empty file: check ctx system message list for overrides
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#too-many-nudges","level":3,"title":"\"Too many nudges\"","text":"

    Symptoms: The agent is overwhelmed with hook output. Context checkpoints, persistence reminders, and QA gates fire constantly.

    Diagnosis:

    # Check how often hooks fired recently\nctx system events --last 50\n\n# Count fires per hook\nctx system events --json | jq -r '.detail.hook // \"unknown\"' \\\n  | sort | uniq -c | sort -rn\n

    Common causes:

    • QA reminder is noisy by design: it fires on every Edit call with no throttle. This is intentional. If it's too much, silence it with an empty override: ctx system message edit qa-reminder gate, then empty the file
    • Long session: context checkpoint fires with increasing frequency after prompt 15. This is the system telling you the session is getting long: consider wrapping up
    • Short throttle window: if you deleted marker files in .context/state/, daily-throttled hooks will re-fire
    • Outdated Claude Code plugin: Update the plugin using Claude Code → /plugin → \"Marketplace\"
    • ctx version mismatch: Build (or download) and install the latest ctx vesion.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#context-seems-stale","level":3,"title":"\"Context seems stale\"","text":"

    Symptoms: The agent references outdated information, paths that don't exist, or decisions that were reversed.

    Diagnosis:

    # Structural drift check\nctx drift\n\n# Full doctor check (includes drift + more)\nctx doctor\n\n# Check when context files were last modified\nctx status --verbose\n

    Common causes:

    • Drift accumulated: stale path references in ARCHITECTURE.md or CONVENTIONS.md. Fix with ctx drift --fix or ask the agent to clean up.
    • Task backlog: too many completed tasks diluting active context. Archive with ctx task archive or ctx compact --archive.
    • Large context files: LEARNINGS.md with 40+ entries competes for attention. Consolidate with /ctx-consolidate.
    • Missing session ceremonies: if /ctx-remember and /ctx-wrap-up aren't being used, context doesn't get refreshed. See Session Ceremonies.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#the-agent-isnt-following-instructions","level":3,"title":"\"The agent isn't following instructions\"","text":"

    Symptoms: The agent ignores conventions, forgets decisions, or acts contrary to CONSTITUTION.md rules.

    Diagnosis:

    # Check context token size: Is it too large for the model?\nctx doctor --json | jq '.results[] | select(.name == \"context_size\")'\n\n# Check if context is actually being loaded\nctx system events --hook context-load-gate\n

    Common causes:

    • Context too large: if total tokens exceed the model's effective attention, instructions get diluted. Check ctx doctor for the size check. Compact with ctx compact --archive.
    • Context not loading: if context-load-gate hasn't fired, the agent may not have received context. Verify the hook is registered.
    • Conflicting instructions: CONVENTIONS.md says one thing, AGENT_PLAYBOOK.md says another. Review both files for consistency.
    • Agent drift: the agent's behavior diverges from instructions over long sessions. This is normal. Use /ctx-reflect to re-anchor, or start a new session.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#prerequisites","level":2,"title":"Prerequisites","text":"
    • Event logging (optional but recommended): event_log: true in .ctxrc
    • ctx initialized: ctx init

    Event logging is not required for ctx doctor or /ctx-doctor to work. Both degrade gracefully: structural checks run regardless, and the skill notes when event data is unavailable.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#tips","level":2,"title":"Tips","text":"
    • Start with ctx doctor: It's the fastest way to get a comprehensive health picture. Save event log inspection for when you need to understand when and how often something happened.
    • Enable event logging early: The log is opt-in and low-cost (~250 bytes per event, 1MB rotation cap). Enable it before you need it: Diagnosing a problem without historical data is much harder.
    • Use the skill for correlation: ctx doctor tells you what is wrong. /ctx-doctor tells you why by correlating structural findings with event patterns. The agent can spot connections that individual commands miss.
    • Event log is gitignored: It's machine-local diagnostic data, not project context. Different machines produce different event streams.
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#next-up","level":2,"title":"Next Up","text":"

    Detecting and Fixing Drift →: Keep context files accurate as your codebase evolves.

    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/troubleshooting/#see-also","level":2,"title":"See Also","text":"
    • Auditing System Hooks: the complete hook catalog and webhook-based audit trails
    • Detecting and Fixing Drift: structural and semantic drift detection and repair
    • Webhook Notifications: push notifications for hook activity
    • ctx doctor CLI: full command reference
    • ctx system events CLI: event log query reference
    • /ctx-doctor skill: agent-driven diagnosis
    ","path":["Recipes","Maintenance","Troubleshooting"],"tags":[]},{"location":"recipes/webhook-notifications/","level":1,"title":"Webhook Notifications","text":"","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#the-problem","level":2,"title":"The Problem","text":"

    Your agent runs autonomously (loops, implements, releases) while you are away from the terminal. You have no way to know when it finishes, hits a limit, or when a hook fires a nudge.

    How do you get notified about agent activity without watching the terminal?

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#tldr","level":2,"title":"TL;DR","text":"
    ctx notify setup  # configure webhook URL (encrypted)\nctx notify test   # verify delivery\n# Hooks auto-notify on: session-end, loop-iteration, resource-danger\n
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#commands-and-skills-used","level":2,"title":"Commands and Skills Used","text":"Tool Type Purpose ctx notify setup CLI command Configure and encrypt webhook URL ctx notify test CLI command Send a test notification ctx notify --event <name> \"msg\" CLI command Send a notification from scripts/skills .ctxrc notify.events Configuration Filter which events reach your webhook","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-1-get-a-webhook-url","level":3,"title":"Step 1: Get a Webhook URL","text":"

    Any service that accepts HTTP POST with JSON works. Common options:

    Service How to get a URL IFTTT Create an applet with the \"Webhooks\" trigger Slack Create an Incoming Webhook Discord Channel Settings > Integrations > Webhooks ntfy.sh Use https://ntfy.sh/your-topic (no signup) Pushover Use API endpoint with your user key

    The URL contains auth tokens. ctx encrypts it; it never appears in plaintext in your repo.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-2-configure-the-webhook","level":3,"title":"Step 2: Configure the Webhook","text":"
    ctx notify setup\n# Enter webhook URL: https://maker.ifttt.com/trigger/ctx/json/with/key/YOUR_KEY\n# Webhook configured: https://maker.ifttt.com/***\n# Encrypted at: .context/.notify.enc\n

    This encrypts the URL with AES-256-GCM using the same key as the scratchpad (~/.ctx/.ctx.key). The encrypted file (.context/.notify.enc) is safe to commit. The key lives outside the project and is never committed.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-3-test-it","level":3,"title":"Step 3: Test It","text":"
    ctx notify test\n# Webhook responded: HTTP 200 OK\n

    If you see No webhook configured, run ctx notify setup first.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-4-configure-events","level":3,"title":"Step 4: Configure Events","text":"

    Notifications are opt-in: no events are sent unless you configure an event list in .ctxrc:

    # .ctxrc\nnotify:\n  events:\n    - loop       # loop completion or max-iteration hit\n    - nudge      # VERBATIM relay hooks (context checkpoint, persistence, etc.)\n    - relay      # all hook output (verbose, for debugging)\n    - heartbeat  # every-prompt session-alive signal with metadata\n

    Only listed events fire. Omitting an event silently drops it.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#step-5-use-in-your-own-skills","level":3,"title":"Step 5: Use in Your Own Skills","text":"

    Add ctx notify calls to any skill or script:

    # In a release skill\nctx notify --event release \"v1.2.0 released successfully\" 2>/dev/null || true\n\n# In a backup script\nctx notify --event backup \"Nightly backup completed\" 2>/dev/null || true\n

    The 2>/dev/null || true suffix ensures the notification never breaks your script: If there's no webhook or the HTTP call fails, it's a silent noop.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#event-types","level":2,"title":"Event Types","text":"

    ctx fires these events automatically:

    Event Source When loop Loop script Loop completes or hits max iterations nudge System hooks VERBATIM relay nudge is emitted (context checkpoint, persistence, ceremonies, journal, resources, knowledge, version) relay System hooks Any hook output (VERBATIM relays, agent directives, block responses) heartbeat System hook Every prompt: session-alive signal with prompt count and context modification status test ctx notify test Manual test notification (custom) Your skills You wire ctx notify --event <name> in your own scripts

    nudge vs relay: The nudge event fires only for VERBATIM relay hooks (the ones the agent is instructed to show verbatim). The relay event fires for all hook output: VERBATIM relays, agent directives, and hard gates. Subscribe to relay for debugging (\"did the agent get the post-commit nudge?\"), nudge for user-facing assurance (\"was the checkpoint emitted?\").

    Webhooks as a Hook Audit Trail

    Subscribe to relay events and you get an external record of every hook that fires, independent of the agent.

    This lets you verify hooks are running and catch cases where the agent absorbs a nudge instead of surfacing it.

    See Auditing System Hooks for the full workflow.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#payload-format","level":2,"title":"Payload Format","text":"

    Every notification sends a JSON POST:

    {\n  \"event\": \"nudge\",\n  \"message\": \"check-context-size: Context window at 82%\",\n  \"detail\": {\n    \"hook\": \"check-context-size\",\n    \"variant\": \"window\",\n    \"variables\": {\"Percentage\": 82, \"TokenCount\": \"164k\"}\n  },\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-22T14:30:00Z\",\n  \"project\": \"ctx\"\n}\n

    The detail field is a structured template reference containing the hook name, variant, and any template variables. This lets receivers filter by hook or variant without parsing rendered text. The field is omitted when no template reference applies (e.g. custom ctx notify calls).

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#heartbeat-payload","level":3,"title":"Heartbeat Payload","text":"

    The heartbeat event fires on every prompt with session metadata and token usage telemetry:

    {\n  \"event\": \"heartbeat\",\n  \"message\": \"heartbeat: prompt #7 (context_modified=false tokens=158k pct=79%)\",\n  \"detail\": {\n    \"hook\": \"heartbeat\",\n    \"variant\": \"pulse\",\n    \"variables\": {\n      \"prompt_count\": 7,\n      \"session_id\": \"abc123-...\",\n      \"context_modified\": false,\n      \"tokens\": 158000,\n      \"context_window\": 200000,\n      \"usage_pct\": 79\n    }\n  },\n  \"session_id\": \"abc123-...\",\n  \"timestamp\": \"2026-02-28T10:15:00Z\",\n  \"project\": \"ctx\"\n}\n

    The tokens, context_window, and usage_pct fields are included when token data is available from the session JSONL file. They are omitted when no usage data has been recorded yet (e.g. first prompt).

    Unlike other events, heartbeat fires every prompt (not throttled). Use it for observability dashboards or liveness monitoring of long-running sessions.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#security-model","level":2,"title":"Security Model","text":"Component Location Committed? Permissions Encryption key ~/.ctx/.ctx.key No (user-level) 0600 Encrypted URL .context/.notify.enc Yes (safe) 0600 Webhook URL Never on disk in plaintext N/A N/A

    The key is shared with the scratchpad. If you rotate the encryption key, re-run ctx notify setup to re-encrypt the webhook URL with the new key.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#key-rotation","level":2,"title":"Key Rotation","text":"

    ctx checks the age of the encryption key once per day. If it's older than 90 days (configurable via key_rotation_days), a VERBATIM nudge is emitted suggesting rotation.

    # .ctxrc\nkey_rotation_days: 30   # nudge sooner (default: 90)\n
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#worktrees","level":2,"title":"Worktrees","text":"

    The webhook URL is encrypted with the same encryption key (~/.ctx/.ctx.key). Because the key lives at the user level, it is shared across all worktrees on the same machine - notifications work in worktrees automatically.

    This means agents running in worktrees cannot send webhook alerts. For autonomous runs where worktree agents are opaque, monitor them from the terminal rather than relying on webhooks. Enrich journals and review results on the main branch after merging.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#event-log-the-local-complement","level":2,"title":"Event Log: The Local Complement","text":"

    Don't need a webhook but want diagnostic visibility? Enable event_log: true in .ctxrc. The event log writes the same payload as webhooks to a local JSONL file (.context/state/events.jsonl) that you can query without any external service:

    ctx system events --last 20          # recent hook activity\nctx system events --hook qa-reminder # filter by hook\n

    Webhooks and event logging are independent: you can use either, both, or neither. Webhooks give you push notifications and an external audit trail. The event log gives you local queryability and ctx doctor integration.

    See Troubleshooting for how they work together.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#tips","level":2,"title":"Tips","text":"
    • Fire-and-forget: Notifications never block. HTTP errors are silently ignored. No retry, no response parsing.
    • No webhook = no cost: When no webhook is configured, ctx notify exits immediately. System hooks that call notify.Send() add zero overhead.
    • Multiple projects: Each project has its own .notify.enc. You can point different projects at different webhooks.
    • Event filter is per-project: Configure notify.events in each project's .ctxrc independently.
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#next-up","level":2,"title":"Next Up","text":"

    Auditing System Hooks →: Verify your hooks are running, audit what they do, and get alerted when they go silent.

    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/webhook-notifications/#see-also","level":2,"title":"See Also","text":"
    • CLI Reference: ctx notify: full command reference
    • Configuration: .ctxrc settings including notify options
    • Running an Unattended AI Agent: how loops work and how notifications fit in
    • Hook Output Patterns: understanding VERBATIM relays, agent directives, and hard gates
    • Auditing System Hooks: using webhooks as an external audit trail for hook execution
    ","path":["Recipes","Hooks and Notifications","Webhook Notifications"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/","level":1,"title":"When to Use a Team of Agents","text":"","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-problem","level":2,"title":"The Problem","text":"

    You have a task, and you are wondering: \"should I throw more agents at it?\"

    More agents can mean faster results, but they also mean coordination overhead, merge conflicts, divergent mental models, and wasted tokens re-reading context.

    The wrong setup costs more than it saves.

    This recipe is a decision framework: It helps you choose between a single agent, parallel worktrees, and a full agent team, and explains what ctx provides at each level.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#tldr","level":2,"title":"TL;DR","text":"
    • Single agent for most work;
    • Parallel worktrees when tasks touch disjoint file sets;
    • Agent teams only when tasks need real-time coordination. When in doubt, start with one agent.
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-spectrum","level":2,"title":"The Spectrum","text":"

    There are three modes, ordered by complexity:

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#1-single-agent-default","level":3,"title":"1. Single Agent (Default)","text":"

    One agent, one session, one branch. This is correct for most work.

    Use this when:

    • The task has linear dependencies (step 2 needs step 1's output);
    • Changes touch overlapping files;
    • You need tight feedback loops (review each change before the next);
    • The task requires deep understanding of a single area;
    • Total effort is less than a few hours of agent time.

    ctx provides: Full .context/: tasks, decisions, learnings, conventions, all in one session.

    The agent builds a coherent mental model and persists it as it goes.

    Example tasks: Bug fixes, feature implementation, refactoring a module, writing documentation for one area, debugging.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#2-parallel-worktrees-independent-tracks","level":3,"title":"2. Parallel Worktrees (Independent Tracks)","text":"

    2-4 agents, each in a separate git worktree on its own branch, working on non-overlapping parts of the codebase.

    Use this when:

    • You have 5+ independent tasks in the backlog;
    • Tasks group cleanly by directory or package;
    • File overlap between groups is zero or near-zero;
    • Each track can be completed and merged independently;
    • You want parallelism without coordination complexity.

    ctx provides: Shared .context/ via git (each worktree sees the same tasks, decisions, conventions). /ctx-worktree skill for setup and teardown. TASKS.md as a lightweight work queue.

    Example tasks: Docs + new package + test coverage (three tracks that don't touch the same files). Parallel recipe writing. Independent module development.

    See: Parallel Agent Development with Git Worktrees

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#3-agent-team-coordinated-swarm","level":3,"title":"3. Agent Team (Coordinated Swarm)","text":"

    Multiple agents communicating via messages, sharing a task list, with a lead agent coordinating. Claude Code's team/swarm feature.

    Use this when:

    • Tasks have dependencies but can still partially overlap;
    • You need research and implementation happening simultaneously;
    • The work requires different roles (researcher, implementer, tester);
    • A lead agent needs to review and integrate others' work;
    • The task is large enough that coordination cost is justified.

    ctx provides: .context/ as shared state that all agents can read. Task tracking for work assignment. Decisions and learnings as team memory that survives individual agent turnover.

    Example tasks: Large refactor across modules where a lead reviews merges. Research and implementation where one agent explores options while another builds. Multi-file feature that needs integration testing after parallel implementation.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-decision-framework","level":2,"title":"The Decision Framework","text":"

    Ask these questions in order:

    Can one agent do this in a reasonable time?\n  YES → Single agent. Stop here.\n  NO  ↓\n\nCan the work be split into non-overlapping file sets?\n  YES → Parallel worktrees (2-4 tracks)\n  NO  ↓\n\nDo the subtasks need to communicate during execution?\n  YES → Agent team with lead coordination\n  NO  → Parallel worktrees with a merge step\n
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#the-file-overlap-test","level":3,"title":"The File Overlap Test","text":"

    This is the critical decision point. Before choosing multi-agent, list the files each subtask would touch. If two subtasks modify the same file, they belong in the same track (or the same single-agent session).

    You: \"I want to parallelize these tasks. Which files would each one touch?\"\n\nAgent: [reads `TASKS.md`, analyzes codebase]\n       \"Task A touches internal/config/ and internal/cli/initialize/\n        Task B touches docs/ and site/\n        Task C touches internal/config/ and internal/cli/status/\n\n        Tasks A and C overlap on internal/config/ # they should be\n        in the same track. Task B is independent.\"\n

    When in doubt, keep things in one track. A merge conflict in a critical file costs more time than the parallelism saves.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#when-teams-make-things-worse","level":2,"title":"When Teams Make Things Worse","text":"

    \"More agents\" is not always better. Watch for these patterns:

    Merge hell: If you are spending more time resolving conflicts than the parallel work saved, you split wrong: Re-group by file overlap.

    Context divergence: Each agent builds its own mental model. After 30 minutes of independent work, agent A might make assumptions that contradict agent B's approach. Shorter tracks with frequent merges reduce this.

    Coordination theater: A lead agent spending most of its time assigning tasks, checking status, and sending messages instead of doing work. If the task list is clear enough, worktrees with no communication are cheaper.

    Re-reading overhead: Every agent reads .context/ on startup. A team of 4 agents each reading 4000 tokens of context = 16000 tokens before anyone does any work. For small tasks, that overhead dominates.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#what-ctx-gives-you-at-each-level","level":2,"title":"What ctx Gives You at Each Level","text":"ctx Feature Single Agent Worktrees Team .context/ files Full access Shared via git Shared via filesystem TASKS.md Work queue Split by track Assigned by lead Decisions/Learnings Persisted in session Persisted per branch Persisted by any agent /ctx-next Picks next task Picks within track Lead assigns /ctx-worktree N/A Setup + teardown Optional /ctx-commit Normal commits Per-branch commits Per-agent commits","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#team-composition-recipes","level":2,"title":"Team Composition Recipes","text":"

    Four practical team compositions for common workflows.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#feature-development-3-agents","level":3,"title":"Feature Development (3 agents)","text":"Role Responsibility Architect Writes spec in specs/, breaks work into TASKS.md phases Implementer Picks tasks from TASKS.md, writes code, marks [x] done Reviewer Runs tests, ctx drift, lint; files issues as new tasks

    Coordination: TASKS.md checkboxes. Architect writes tasks before implementer starts. Reviewer runs after each implementer commit.

    Anti-pattern: All three agents editing the same file simultaneously. Sequence the work so only one agent touches a file at a time.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#consolidation-sprint-3-4-agents","level":3,"title":"Consolidation Sprint (3-4 agents)","text":"Role Responsibility Auditor Runs ctx drift, identifies stale paths and broken refs Code Fixer Updates source code to match context (or vice versa) Doc Writer Updates ARCHITECTURE.md, CONVENTIONS.md, and docs/ Test Fixer (Optional) Fixes tests broken by the fixer's changes

    Coordination: Auditor's ctx drift output is the shared work queue. Each agent claims a subset of issues by adding #in-progress labels.

    Anti-pattern: Fixer and doc writer both editing ARCHITECTURE.md. Assign file ownership explicitly.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#release-prep-2-agents","level":3,"title":"Release Prep (2 agents)","text":"Role Responsibility Release Notes Generates changelog from commits, writes release notes Validation Runs full test suite, lint, build across platforms

    Coordination: Both read TASKS.md to identify what shipped. Release notes agent works from git log; validation agent works from make audit.

    Anti-pattern: Release notes agent running tests \"to verify.\" Each agent stays in its lane.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#documentation-sprint-3-agents","level":3,"title":"Documentation Sprint (3 agents)","text":"Role Responsibility Content Writes new pages, expands existing docs Cross-linker Adds nav entries, cross-references, \"See Also\" sections Verifier Builds site, checks broken links, validates rendering

    Coordination: Content agent writes files first. Cross-linker updates zensical.toml and index pages after content lands. Verifier builds after each batch.

    Antipattern: Content and cross-linker both editing zensical.toml. Batch nav updates into the cross-linker's pass.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#tips","level":2,"title":"Tips","text":"
    • Start with one agent: Only add parallelism when you have identified the bottleneck. \"This would go faster with more agents\" is usually wrong for tasks under 2 hours.
    • The 3-4 agent ceiling is real: Coordination overhead grows quadratically. 2 agents = 1 communication pair. 4 agents = 6 pairs. Beyond 4, you are managing agents more than doing work.
    • Worktrees > teams for most parallelism needs: If agents don't need to talk to each other during execution, worktrees give you parallelism with zero coordination overhead.
    • Use ctx as the shared brain: Whether it's one agent or four, the .context/ directory is the single source of truth. Decisions go in DECISIONS.md, not in chat messages between agents.
    • Merge early, merge often: Long-lived parallel branches diverge. Merge a track as soon as it's done rather than waiting for all tracks to finish.
    • TASKS.md conflicts are normal: Multiple agents completing different tasks will conflict on merge. The resolution is always additive: accept all [x] completions from both sides.
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#next-up","level":2,"title":"Next Up","text":"

    Parallel Agent Development with Git Worktrees →: Run multiple agents on independent task tracks using git worktrees.

    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#go-deeper","level":2,"title":"Go Deeper","text":"
    • CLI Reference: all commands and flags
    • Integrations: setup for Claude Code, Cursor, Aider
    • Session Journal: browse and search session history
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"recipes/when-to-use-agent-teams/#see-also","level":2,"title":"See Also","text":"
    • Parallel Agent Development with Git Worktrees: the mechanical \"how\" for worktree-based parallelism
    • Running an Unattended AI Agent: serial autonomous loops: a different scaling strategy
    • Tracking Work Across Sessions: managing the task backlog that feeds into any multi-agent setup
    ","path":["Recipes","Agents and Automation","When to Use a Team of Agents"],"tags":[]},{"location":"reference/","level":1,"title":"Reference","text":"

    Technical reference for ctx commands, skills, and internals.

    ","path":["Reference"],"tags":[]},{"location":"reference/#the-system-explains-itself","level":3,"title":"The System Explains Itself","text":"

    The 12 properties that must hold for any valid ctx implementation. Not features: constraints. The system's contract with its users and contributors.

    ","path":["Reference"],"tags":[]},{"location":"reference/#cli","level":3,"title":"CLI","text":"

    Every command, subcommand, and flag. Now a top-level section: see CLI Reference.

    ","path":["Reference"],"tags":[]},{"location":"reference/#skills","level":3,"title":"Skills","text":"

    The full skill catalog: what each skill does, when it triggers, and how skills interact with commands.

    ","path":["Reference"],"tags":[]},{"location":"reference/#tool-ecosystem","level":3,"title":"Tool Ecosystem","text":"

    How ctx compares to Cursor Rules, Aider conventions, CLAUDE.md, and other context approaches.

    ","path":["Reference"],"tags":[]},{"location":"reference/#session-journal","level":3,"title":"Session Journal","text":"

    Export, browse, and enrich your session history. Covers the journal site, Obsidian export, and the enrichment pipeline.

    ","path":["Reference"],"tags":[]},{"location":"reference/#scratchpad","level":3,"title":"Scratchpad","text":"

    Encrypted, git-tracked scratch space for short notes and sensitive values that travel with the project.

    ","path":["Reference"],"tags":[]},{"location":"reference/#version-history","level":3,"title":"Version History","text":"

    Changelog for every ctx release.

    ","path":["Reference"],"tags":[]},{"location":"reference/comparison/","level":1,"title":"Tool Ecosystem","text":"","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#high-level-mental-model","level":2,"title":"High-Level Mental Model","text":"

    Many tools help AI think.

    ctx helps AI remember.

    • Not by storing thoughts,
    • but by preserving intent.
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#how-ctx-differs-from-similar-tools","level":2,"title":"How ctx Differs from Similar Tools","text":"

    There are many tools in the AI ecosystem that touch parts of the context problem:

    • Some manage prompts.
    • Some retrieve data.
    • Some provide runtime context objects.
    • Some offer enterprise platforms.

    ctx focuses on a different layer entirely.

    This page explains where ctx fits, and where it intentionally does not.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#the-core-distinction","level":2,"title":"The Core Distinction","text":"

    Most tools treat context as input.

    ctx treats context as infrastructure.

    That single difference explains nearly all of ctx's design choices.

    Question Most tools ctx Where does context live? In prompts or APIs In files How long does it last? One request / one session Across time Who can read it? The model Humans and tools How is it updated? Implicitly Explicitly Is it inspectable? Rarely Always","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#prompt-management-tools","level":2,"title":"Prompt Management Tools","text":"

    Examples include:

    • prompt templates;
    • reusable system prompts;
    • prompt libraries;
    • prompt versioning tools.

    These tools help you start a session.

    They do not help you continue one.

    Prompt tools:

    • inject text at session start;
    • are ephemeral by design;
    • do not evolve with the project.

    ctx:

    • persists knowledge over time;
    • accumulates decisions and learnings;
    • makes the context part of the repository itself.

    Prompt tooling and ctx are complementary; not competing. Yet, they operate in different layers.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#retrieval-augmented-generation-rag","level":2,"title":"Retrieval-Augmented Generation (RAG)","text":"

    RAG systems typically:

    • index documents
    • embed text
    • retrieve chunks dynamically at runtime

    They are excellent for:

    • large knowledge bases
    • static documentation
    • reference material

    RAG answers questions like:

    \"What information might be relevant right now?\"

    ctx answers a different question:

    \"What have we already decided, learned, or committed to?\"

    Here are some key differences:

    RAG ctx Statistical relevance Intentional relevance Embedding-based File-based Opaque retrieval Explicit structure Runtime query Persistent memory

    ctx does not replace RAG. Instead, it defines a persistent context layer that RAG can optionally augment.

    RAG belongs to the data plane; ctx defines the context control plane.

    It focuses on project memory, not knowledge search.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#agent-frameworks","level":2,"title":"Agent Frameworks","text":"

    Agent frameworks often provide:

    • task loops
    • tool orchestration
    • planner/executor patterns
    • autonomous iteration

    These systems are powerful, but they typically assume that:

    • memory is external
    • context is injected
    • state is transient

    Agent frameworks answer:

    \"How should the agent act?\"

    ctx answers:

    \"What should the agent remember?\"

    Without persistent context, agents tend to:

    • rediscover decisions
    • repeat mistakes
    • lose architectural intent

    This is why ctx pairs well with autonomous loop workflows:

    • The loop provides iteration
    • ctx provides continuity

    Together, loops become cumulative instead of forgetful.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#sdk-level-context-objects","level":2,"title":"SDK-Level Context Objects","text":"

    Some SDKs expose \"context\" objects that exist:

    • inside a process
    • during a request
    • for the lifetime of a call chain

    These are extremely useful and completely different.

    SDK context objects:

    • are in-memory
    • disappear when the process ends
    • are not shared across sessions

    ctx:

    • survives process restarts
    • survives new chats
    • survives new days

    They share a name, not a purpose.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#enterprise-context-platforms","level":2,"title":"Enterprise Context Platforms","text":"

    Enterprise platforms often provide:

    • centralized context services
    • dashboards
    • access control
    • organizational knowledge layers

    These tools are designed for:

    • teams
    • governance
    • compliance
    • managed environments

    ctx is intentionally:

    • local-first
    • file-based
    • dependency-free
    • CLI-driven
    • developer-controlled

    It does not require:

    • a server
    • a database
    • an account
    • a SaaS backend

    ctx optimizes for individual and small-team workflows where context should live next to code; not behind a service boundary.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#specific-tool-comparisons","level":2,"title":"Specific Tool Comparisons","text":"

    Users often evaluate ctx against specific tools they already use. These comparisons clarify where responsibilities overlap, where they diverge, and where the tools are genuinely complementary.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#claude-code-memory-anthropic-auto-memory","level":3,"title":"Claude Code Memory / Anthropic Auto-Memory","text":"

    Anthropic's auto-memory is tool-managed memory (L2): the model decides what to remember, stores it automatically, and retrieves it implicitly. ctx is system memory (L3): humans and agents explicitly curate decisions, learnings, and tasks in inspectable files.

    Auto-memory is convenient - you do not configure anything. But it is also opaque: you cannot see what was stored, edit it precisely, or share it across tools. ctx files are plain Markdown in your repository, visible in diffs and code review.

    The two are complementary. ctx can absorb auto-memory as an input source (importing what the model remembered into structured context files) while providing the durable, inspectable layer that auto-memory lacks.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#cursorrules-clauderules","level":3,"title":".cursorrules / .claude/rules","text":"

    Static rule files (.cursorrules, .claude/rules/) declare conventions: coding style, forbidden patterns, preferred libraries. They are effective for what to do and load automatically at session start.

    ctx adds dimensions that rule files do not cover: architectural decisions with rationale, learnings discovered during development, active tasks, and a constitution that governs agent behavior. Critically, ctx context accumulates - each session can add to it, and token budgeting ensures only the most relevant context is injected.

    Use rule files for static conventions. Use ctx for evolving project memory.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#aider-read-watch","level":3,"title":"Aider --read / --watch","text":"

    Aider's --read flag injects file contents at session start; --watch reloads them on change. The concept is similar to ctx's \"load\" step: make the agent aware of specific files.

    The differences emerge beyond loading. Aider has no persistence model -- nothing the agent learns during a session is written back. There is no token budgeting (large files consume the full context window), no priority ordering across file types, and no structured format for decisions or learnings. ctx provides the full lifecycle: load, accumulate, persist, and budget.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#copilot-workspace","level":3,"title":"Copilot @workspace","text":"

    GitHub Copilot's @workspace performs workspace-wide code search. It answers \"what code exists?\" - finding function definitions, usages, and file structure across the repository.

    ctx answers a different question: \"what did we decide?\" It stores architectural intent, not code indices. Copilot's workspace search and ctx's project memory are orthogonal; one finds code, the other preserves the reasoning behind it.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#cline-memory","level":3,"title":"Cline Memory","text":"

    Cline's memory bank stores session context within the Cline extension. The motivation is similar to ctx: help the agent remember across sessions.

    The key difference is portability. Cline memory is tied to Cline - it does not transfer to Claude Code, Cursor, Aider, or any other tool. ctx is tool-agnostic: context lives in plain files that any editor, agent, or script can read. Switching tools does not mean losing memory.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#when-ctx-is-a-good-fit","level":2,"title":"When ctx Is a Good Fit","text":"

    ctx works best when:

    • you want AI work to compound over time;
    • architectural decisions matter;
    • context must be inspectable;
    • humans and AI must share the same source of truth;
    • Git history should include why, not just what.
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#when-ctx-is-not-the-right-tool","level":2,"title":"When ctx Is Not the Right Tool","text":"

    ctx is probably not what you want if:

    • you only need one-off prompts;
    • you rely exclusively on RAG;
    • you want autonomous agents without a human-readable state;
    • you require centralized enterprise control;
    • you want black-box memory systems,

    These are valid goals; just different ones.

    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/comparison/#further-reading","level":2,"title":"Further Reading","text":"
    • You Can't Import Expertise: why project-specific context matters more than generic best practices
    ","path":["Reference","Tool Ecosystem"],"tags":[]},{"location":"reference/design-invariants/","level":1,"title":"Invariants","text":"","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#the-system-explains-itself","level":1,"title":"The System Explains Itself","text":"

    These are the properties that must hold for any valid ctx implementation.

    • These are not features.
    • These are constraints.

    A change that violates an invariant is a category error, not an improvement.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#cognitive-state-tiers","level":2,"title":"Cognitive State Tiers","text":"

    ctx distinguishes between three forms of state:

    • Authoritative state: Versioned, inspectable artifacts that define intent and survive time.
    • Delivery views: Deterministic assemblies of the authoritative state for a specific budget or workflow.
    • Ephemeral working state: Local, transient, or sensitive data that assists interaction but does not define system truth.

    The invariants below apply primarily to the authoritative cognitive state.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#1-cognitive-state-is-explicit","level":2,"title":"1. Cognitive State Is Explicit","text":"

    All authoritative context lives in artifacts that can be inspected, reviewed, and versioned.

    If something is important, it must exist as a file: Not only in a prompt, a chat, or a model's hidden memory.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#2-assembly-is-reproducible","level":2,"title":"2. Assembly Is Reproducible","text":"

    Given the same:

    • repository state,
    • configuration,
    • and inputs,

    context assembly produces the same result.

    Heuristics may rank or filter for delivery under constraints.

    They do not alter the authoritative state.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#3-the-authoritative-state-is-human-readable","level":2,"title":"3. The Authoritative State Is Human-Readable","text":"

    The authoritative cognitive state must be stored in formats that a human can:

    • read,
    • diff,
    • review,
    • and edit directly.

    Sensitive working memory may be encrypted at rest. However, encryption must not become the only representation of authoritative knowledge.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#4-artifacts-outlive-sessions","level":2,"title":"4. Artifacts Outlive Sessions","text":"

    Sessions are transient.

    Knowledge persists.

    Reasoning, decisions, and outcomes must remain available after the interaction that produced them has ended.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#5-authority-is-user-defined","level":2,"title":"5. Authority Is User-Defined","text":"

    What enters the authoritative context is an explicit human decision.

    Models may suggest.

    Automation may assist.

    Selection is never implicit.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#6-operation-is-local-first","level":2,"title":"6. Operation Is Local-First","text":"

    The core system must function without requiring network access or a remote service.

    External systems may extend ctx.

    They must not be required for its operation.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#7-versioning-is-the-memory-model","level":2,"title":"7. Versioning Is the Memory Model","text":"

    The evolution of the authoritative cognitive state must be:

    • preserved,
    • inspectable,
    • and branchable.

    Ephemeral and sensitive working state may use different retention and diff strategies by design.

    Understanding includes understanding how we arrived here.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#8-structure-enables-scale","level":2,"title":"8. Structure Enables Scale","text":"

    Unstructured accumulation is not memory.

    Authoritative cognitive state must have a defined layout that:

    • communicates intent,
    • supports navigation,
    • and prevents drift.
    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#9-verification-is-the-scoreboard","level":2,"title":"9. Verification Is the Scoreboard","text":"

    Claims without recorded outcomes are noise.

    Reality (observed and captured) is the only signal that compounds.

    This invariant defines a required direction:

    The authoritative state must be able to record expectation and result.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#10-capture-once-reuse-indefinitely","level":2,"title":"10. Capture Once, Reuse Indefinitely","text":"

    Work that has already produced understanding must not be re-derived from scratch.

    Explored paths, rejected options, and validated conclusions are permanent assets.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#11-policies-are-encoded-not-remembered","level":2,"title":"11. Policies Are Encoded, not Remembered","text":"

    Alignment must not depend on recall or goodwill.

    Constraints that matter must exist in machine-readable form and participate in context assembly.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#12-the-system-explains-itself","level":2,"title":"12. The System Explains Itself","text":"

    From the repository state alone it must be possible to determine:

    • what was authoritative,
    • what constraints applied.

    Delivery views may be optimized.

    They must not become the only explanation.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#non-goals","level":1,"title":"Non-Goals","text":"

    To avoid category errors, ctx does not attempt to be:

    • a skill,
    • a prompt management tool,
    • a chat history viewer,
    • an autonomous agent runtime,
    • a vector database,
    • a hosted memory service.

    Such systems may integrate with ctx.

    They do not define it.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#implications-for-contributions","level":1,"title":"Implications for Contributions","text":"

    Valid contributions:

    • strengthen an invariant,
    • reduce the cost of maintaining an invariant,
    • or extend the system without violating invariants.

    Invalid contributions:

    • introduce hidden authoritative state,
    • replace reproducible assembly with non-reproducible behavior,
    • make core operation depend on external services,
    • reduce human inspectability of authoritative state,
    • or bypass explicit user authority over what becomes authoritative.
    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/design-invariants/#the-contract","level":1,"title":"The Contract","text":"

    Everything else (commands, skills, layouts, integrations, optimizations) is an implementation detail.

    These invariants are the system.

    ","path":["Reference","Invariants"],"tags":[]},{"location":"reference/scratchpad/","level":1,"title":"Scratchpad","text":"","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#what-is-ctx-scratchpad","level":2,"title":"What Is ctx Scratchpad?","text":"

    A one-liner scratchpad, encrypted at rest, synced via git.

    Quick notes that don't fit decisions, learnings, or tasks: reminders, intermediate values, sensitive tokens, working memory during debugging. Entries are numbered, reorderable, and persist across sessions.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#encrypted-by-default","level":2,"title":"Encrypted by Default","text":"

    Scratchpad entries are encrypted with AES-256-GCM before touching the disk.

    Component Path Git status Encryption key ~/.ctx/.ctx.key User-level, 0600 permissions Encrypted data .context/scratchpad.enc Committed

    The key is generated automatically during ctx init (256-bit via crypto/rand) and stored at ~/.ctx/.ctx.key. One key per machine, shared across all projects.

    The ciphertext format is [12-byte nonce][ciphertext+tag]. No external dependencies: Go stdlib only.

    Because the key is .gitignored and the data is committed, you get:

    • At-rest encryption: the .enc file is opaque without the key
    • Git sync: push/pull the encrypted file like any other tracked file
    • Key separation: the key never leaves the machine unless you copy it
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#commands","level":2,"title":"Commands","text":"Command Purpose ctx pad List all entries (numbered 1-based) ctx pad show N Output raw text of entry N (no prefix, pipe-friendly) ctx pad add \"text\" Append a new entry ctx pad rm N Remove entry at position N ctx pad edit N \"text\" Replace entry N with new text ctx pad edit N --append \"text\" Append text to the end of entry N ctx pad edit N --prepend \"text\" Prepend text to the beginning of entry N ctx pad add TEXT --file PATH Ingest a file as a blob entry (TEXT is the label) ctx pad show N --out PATH Write decoded blob content to a file ctx pad mv N M Move entry from position N to position M ctx pad resolve Show both sides of a merge conflict for resolution ctx pad import FILE Bulk-import lines from a file (or stdin with -) ctx pad import --blob DIR Import directory files as blob entries ctx pad export [DIR] Export all blob entries to a directory as files ctx pad merge FILE... Merge entries from other scratchpad files into current

    All commands decrypt on read, operate on plaintext in memory, and re-encrypt on write. The key file is never printed to stdout.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#examples","level":3,"title":"Examples","text":"
    # Add a note\nctx pad add \"check DNS propagation after deploy\"\n\n# List everything\nctx pad\n#   1. check DNS propagation after deploy\n#   2. staging API key: sk-test-abc123\n\n# Show raw text (for piping)\nctx pad show 2\n# sk-test-abc123\n\n# Compose entries\nctx pad edit 1 --append \"$(ctx pad show 2)\"\n\n# Reorder\nctx pad mv 2 1\n\n# Clean up\nctx pad rm 2\n
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#bulk-import-and-export","level":2,"title":"Bulk Import and Export","text":"

    Import lines from a file in bulk (each non-empty line becomes an entry):

    # Import from a file\nctx pad import notes.txt\n\n# Import from stdin\ngrep TODO *.go | ctx pad import -\n

    Export all blob entries to a directory as files:

    # Export to a directory\nctx pad export ./ideas\n\n# Preview without writing\nctx pad export --dry-run\n\n# Overwrite existing files\nctx pad export --force ./backup\n
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#merging-scratchpads","level":2,"title":"Merging Scratchpads","text":"

    Combine entries from other scratchpad files into your current pad. Useful when merging work from parallel worktrees, other machines, or teammates:

    # Merge from a worktree's encrypted scratchpad\nctx pad merge worktree/.context/scratchpad.enc\n\n# Merge from multiple sources (encrypted and plaintext)\nctx pad merge pad-a.enc notes.md\n\n# Merge a foreign encrypted pad using its key\nctx pad merge --key /other/.ctx.key foreign.enc\n\n# Preview without writing\nctx pad merge --dry-run pad-a.enc pad-b.md\n

    Each input file is auto-detected as encrypted or plaintext: decryption is attempted first, and on failure the file is parsed as plain text. Entries are deduplicated by exact content, so running merge twice with the same file is safe.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#file-blobs","level":2,"title":"File Blobs","text":"

    The scratchpad can store small files (up to 64 KB) as blob entries. Files are base64-encoded and stored with a human-readable label.

    # Ingest a file: first argument is the label\nctx pad add \"deploy config\" --file ./deploy.yaml\n\n# Listing shows label with a [BLOB] marker\nctx pad\n#   1. check DNS propagation after deploy\n#   2. deploy config [BLOB]\n\n# Extract to a file\nctx pad show 2 --out ./recovered.yaml\n\n# Or print decoded content to stdout\nctx pad show 2\n

    Blob entries are encrypted identically to text entries. The internal format is label:::base64data: You never need to construct this manually.

    Constraint Value Max file size (pre-encoding) 64 KB Storage format label:::base64(content) Display label [BLOB] in listings

    When Should You Use Blobs

    Blobs are for small files you want encrypted and portable: config snippets, key fragments, deployment manifests, test fixtures. For anything larger than 64 KB, use the filesystem directly.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#using-with-ai","level":2,"title":"Using with AI","text":"

    Use Natural Language

    As in many ctx features, the ctx scratchpad can also be used with natural langauge. You don't have to memorize the CLI commands.

    CLI gives you \"precision\", whereas natural language gives you flow.

    The /ctx-pad skill maps natural language to ctx pad commands. You don't need to remember the syntax:

    You say What happens \"jot down: check DNS after deploy\" ctx pad add \"check DNS after deploy\" \"show my scratchpad\" ctx pad \"delete the third entry\" ctx pad rm 3 \"update entry 2 to include the new endpoint\" ctx pad edit 2 \"...\" \"move entry 4 to the top\" ctx pad mv 4 1 \"import my notes from notes.txt\" ctx pad import notes.txt \"export all blobs to ./backup\" ctx pad export ./backup \"merge the scratchpad from the worktree\" ctx pad merge worktree/.context/scratchpad.enc

    The skill handles the translation. You describe what you want in plain English; the agent picks the right command.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#worktrees","level":2,"title":"Worktrees","text":"

    The encryption key lives at ~/.ctx/.ctx.key (outside the project directory). Because all worktrees on the same machine share this path, ctx pad works in worktrees automatically - no special setup needed.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#key-distribution","level":2,"title":"Key Distribution","text":"

    The encryption key (~/.ctx/.ctx.key) stays on the machine where it was generated. ctx never transmits it.

    To share the scratchpad across machines:

    1. Copy the key manually: scp, USB drive, password manager.
    2. Push/pull the .enc file via git as usual.
    3. Both machines can now read and write the same scratchpad.

    Never Commit the Key

    The key is .gitignored by default. If you override this, anyone with repo access can decrypt your scratchpad.

    Treat the key like an SSH private key.

    See the Syncing Scratchpad Notes Across Machines recipe for a step-by-step walkthrough.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#plaintext-override","level":2,"title":"Plaintext Override","text":"

    For projects where encryption is unnecessary, disable it in .ctxrc:

    scratchpad_encrypt: false\n

    In plaintext mode:

    • Entries are stored in .context/scratchpad.md instead of .enc.
    • No key is generated or required.
    • All ctx pad commands work identically.
    • The file is human-readable and diffable.

    When Should You Use Plaintext

    Plaintext mode is useful for non-sensitive projects, solo work where encryption adds friction, or when you want scratchpad entries visible in git diff.

    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#when-should-you-use-scratchpad-versus-context-files","level":2,"title":"When Should You Use Scratchpad versus Context Files","text":"Use case Where it goes Temporary reminders (\"check X after deploy\") Scratchpad Working values during debugging Scratchpad Sensitive tokens or API keys (short-term) Scratchpad Quick notes that don't fit anywhere else Scratchpad Items that are not directly relevant to the project Scratchpad Things that you want to keep near, but also hidden Scratchpad Work items with completion tracking TASKS.md Trade-offs with rationale DECISIONS.md Reusable lessons with context/lesson/application LEARNINGS.md Codified patterns and standards CONVENTIONS.md

    Rule of thumb:

    • If it needs structure or will be referenced months later, use a context file (i.e. DECISIONS.md, LEARNINGS.md, TASKS.md).
    • If it is working memory for the current session or week, use the scratchpad.
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/scratchpad/#see-also","level":2,"title":"See Also","text":"
    • Syncing Scratchpad Notes Across Machines: Key distribution, push/pull workflow, merge conflict resolution
    • Using the Scratchpad: Natural language examples, blob workflow, when to use scratchpad vs context files
    • Context Files: Format and conventions for all .context/ files
    • Security: Trust model and permission hygiene
    ","path":["Reference","Scratchpad"],"tags":[]},{"location":"reference/session-journal/","level":1,"title":"Session Journal","text":"

    Important Security Note

    Session journals contain sensitive data such as file contents, commands, API keys, internal discussions, error messages with stack traces, and more.

    The .context/journal-site/ and .context/journal-obsidian/ directories MUST be .gitignored.

    • DO NOT host your journal publicly.
    • DO NOT commit your journal files to version control.
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#browse-your-session-history","level":2,"title":"Browse Your Session History","text":"

    ctx's Session Journal turns your AI coding sessions into a browsable, searchable, and editable archive.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#quick-start","level":2,"title":"Quick Start","text":"

    After using ctx for a couple of sessions, you can generate a journal site with:

    # Export all sessions to markdown\nctx recall export --all\n\n# Generate and serve the journal site\nctx journal site --serve\n

    Then open http://localhost:8000 to browse your sessions.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#what-you-get","level":2,"title":"What You Get","text":"

    The Session Journal gives you:

    • Browsable history: Navigate through all your AI sessions by date
    • Full conversations: See every message, tool use, and result
    • Token usage: Track how many tokens each session consumed
    • Search: Find sessions by content, project, or date
    • Dark mode: Easy on the eyes for late-night archaeology

    Each session page includes the following sections:

    Section Content Metadata Date, time, duration, model, project, git branch Summary Space for your notes (editable) Tool Usage Which tools were used and how often Conversation Full transcript with timestamps","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#the-workflow","level":2,"title":"The Workflow","text":"","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#1-export-sessions","level":3,"title":"1. Export Sessions","text":"
    # Export all sessions from current project (only new files)\nctx recall export --all\n\n# Export sessions from all projects\nctx recall export --all --all-projects\n\n# Export a specific session by ID (always writes)\nctx recall export abc123\n\n# Preview what would be exported\nctx recall export --all --dry-run\n\n# Re-export existing (regenerates conversation, preserves YAML frontmatter)\nctx recall export --all --regenerate\n\n# Discard frontmatter during regeneration\nctx recall export --all --regenerate --keep-frontmatter=false -y\n

    Exported sessions go to .context/journal/ as editable Markdown files.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#2-generate-the-site","level":3,"title":"2. Generate the Site","text":"
    # Generate site structure\nctx journal site\n\n# Generate and build static HTML\nctx journal site --build\n\n# Generate and serve locally\nctx journal site --serve\n\n# Custom output directory\nctx journal site --output ~/my-journal\n

    The site is generated in .context/journal-site/ by default.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#3-browse-and-search","level":3,"title":"3. Browse and Search","text":"

    Open http://localhost:8000 after running --serve.

    • Use the sidebar to navigate by date
    • Use search (/ key) to find specific content
    • Click any session to see the full conversation
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#editing-sessions","level":2,"title":"Editing Sessions","text":"

    Exported sessions are plain Markdown in .context/journal/. You can:

    • Add summaries: Fill in the ## Summary section
    • Add notes: Insert your own commentary anywhere
    • Highlight key moments: Use Markdown formatting
    • Delete noise: Remove irrelevant tool outputs

    After editing, regenerate the site:

    ctx journal site --serve\n
    Safe by Default

    Running ctx recall export --all only exports new sessions. Existing files are skipped entirely (your edits and enrichments are never touched).

    Use --regenerate to re-export existing files. Conversation content is regenerated, but YAML frontmatter (topics, type, outcome, etc.) is preserved. You'll be prompted before any existing files are overwritten; add -y to skip the prompt.

    Use --keep-frontmatter=false to discard enriched frontmatter during regeneration.

    Locked entries (via ctx recall lock) are always skipped, regardless of flags. If you prefer to add locked: true to frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#large-sessions","level":2,"title":"Large Sessions","text":"

    Sessions with many messages (200+) are automatically split into multiple parts for better browser performance. Navigation links connect the parts:

    session-abc123.md      (Part 1 of 3)\nsession-abc123-p2.md   (Part 2 of 3)\nsession-abc123-p3.md   (Part 3 of 3)\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#suggestion-sessions","level":2,"title":"Suggestion Sessions","text":"

    Claude Code generates \"suggestion\" sessions for auto-complete prompts. These are separated in the index under a \"Suggestions\" section to keep your main session list focused.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#enriching-journal-entries","level":2,"title":"Enriching Journal Entries","text":"

    Raw exported sessions contain basic metadata (date, time, project) but lack the structured information needed for effective search, filtering, and analysis. Journal enrichment adds semantic metadata that transforms a flat archive into a searchable knowledge base.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#why-enrich","level":3,"title":"Why Enrich?","text":"

    Without enrichment, you have timestamps and raw conversations. With enrichment:

    • Find sessions by topic: \"Show me all auth-related sessions\"
    • Filter by outcome: \"What did I abandon vs complete?\"
    • Track technology usage: \"When did I last work with PostgreSQL?\"
    • Identify key files: Jump directly to the files discussed
    • Get summaries: Understand what happened without reading transcripts
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#the-frontmatter-schema","level":3,"title":"The Frontmatter Schema","text":"

    Enriched entries begin with YAML frontmatter:

    ---\ntitle: \"Implement caching layer\"\ndate: 2026-01-27\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - performance\ntechnologies:\n  - go\n  - redis\nlibraries:\n  - go-redis/redis\nkey_files:\n  - internal/cache/redis.go\n  - internal/cache/memory.go\n---\n
    Field Required Description title Yes Descriptive title (not the session slug) date Yes Session date (YYYY-MM-DD) type Yes Session type (see below) outcome Yes How the session ended (see below) topics No Subject areas discussed technologies No Languages, databases, frameworks libraries No Specific packages or libraries used key_files No Important files created or modified

    Type values:

    Type When to use feature Building new functionality bugfix Fixing broken behavior refactor Restructuring without behavior change exploration Research, learning, experimentation debugging Investigating issues documentation Writing docs, comments, README

    Outcome values:

    Outcome Meaning completed Goal achieved partial Some progress, work continues abandoned Stopped pursuing this approach blocked Waiting on external dependency","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#using-ctx-journal-enrich","level":3,"title":"Using /ctx-journal-enrich","text":"

    The /ctx-journal-enrich skill automates enrichment by analyzing conversation content and proposing metadata.

    Invoke by session identifier:

    /ctx-journal-enrich twinkly-stirring-kettle\n/ctx-journal-enrich twinkly\n/ctx-journal-enrich 2026-01-24\n/ctx-journal-enrich 76fe2ab9\n

    The skill will:

    1. Check if locked - locked entries are skipped (same as export);
    2. Find the matching journal file;
    3. Read and analyze the conversation;
    4. Propose frontmatter (type, topics, outcome, technologies);
    5. Generate a 2-3 sentence summary;
    6. Extract decisions, learnings, and tasks mentioned;
    7. Show a diff and ask for confirmation before writing.
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#before-and-after","level":3,"title":"Before and After","text":"

    Before enrichment:

    # twinkly-stirring-kettle\n\n**ID**: abc123-def456\n**Date**: 2026-01-24\n**Time**: 14:30:00\n...\n\n## Summary\n\n[Add your summary of this session]\n\n## Conversation\n...\n

    After enrichment:

    ---\ntitle: \"Add Redis caching to API endpoints\"\ndate: 2026-01-24\ntype: feature\noutcome: completed\ntopics:\n  - caching\n  - api-performance\ntechnologies:\n  - go\n  - redis\nkey_files:\n  - internal/api/middleware/cache.go\n  - internal/cache/redis.go\n---\n\n# twinkly-stirring-kettle\n\n**ID**: abc123-def456\n**Date**: 2026-01-24\n**Time**: 14:30:00\n...\n\n## Summary\n\nImplemented Redis-based caching middleware for frequently accessed API endpoints.\nAdded cache invalidation on writes and configurable TTL per route. Reduced\n the average response time from 200ms to 15ms for cached routes.\n\n## Decisions\n\n* Used Redis over in-memory cache for horizontal scaling\n* Chose per-route TTL configuration over global setting\n\n## Learnings\n\n* Redis WATCH command prevents race conditions during cache invalidation\n\n## Conversation\n...\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#enrichment-and-site-generation","level":3,"title":"Enrichment and Site Generation","text":"

    The journal site generator uses enriched metadata for better organization:

    • Titles appear in navigation instead of slugs
    • Summaries provide context in the index
    • Topics enable filtering (when using search)
    • Types allow grouping by work category

    Future improvements will add topic-based navigation and outcome filtering to the generated site.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#batch-enrichment","level":3,"title":"Batch Enrichment","text":"

    To enrich multiple sessions, process them one at a time:

    # List unenriched sessions (those without frontmatter)\ngrep -L \"^---$\" .context/journal/*.md | head -10\n

    Then run /ctx-journal-enrich on each. Enrichment is intentionally interactive to ensure accuracy.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#obsidian-vault-export","level":2,"title":"Obsidian Vault Export","text":"

    If you use Obsidian for knowledge management, you can export your journal as an Obsidian vault instead of (or alongside) the static site:

    ctx journal obsidian\n

    This generates a vault in .context/journal-obsidian/ with:

    • Wikilinks ([[target|display]]) instead of Markdown links
    • MOC pages (Map of Content) for topics, key files, and session types
    • Related sessions footer per entry: links to entries sharing the same topics
    • Transformed frontmatter: topics renamed to tags (Obsidian-recognized), aliases added from title for search
    • Graph-optimized structure: MOC hubs and cross-linked entries create dense graph connectivity

    To use: open the output directory in Obsidian (\"Open folder as vault\").

    # Custom output directory\nctx journal obsidian --output ~/vaults/ctx-journal\n

    Static site vs Obsidian Vault

    Use ctx journal site when you want a web-browsable archive with search and dark mode. Use ctx journal obsidian when you want graph view, backlinks, and tag-based navigation inside Obsidian. Both use the same enriched source entries: you can generate both.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#full-pipeline","level":2,"title":"Full Pipeline","text":"

    The complete journal workflow has four stages. Each is idempotent: safe to re-run, and stages skip already-processed entries.

    export → enrich → rebuild\n
    Stage Command / Skill What it does Skips if Export ctx recall export --all Converts session JSONL to Markdown File already exists (safe default) Enrich /ctx-journal-enrich Adds frontmatter, summaries, topics Frontmatter already present Rebuild ctx journal site --build Generates static HTML site -- Obsidian ctx journal obsidian Generates Obsidian vault with wikilinks --

    One-command pipeline

    /ctx-journal-enrich-all handles export automatically - it detects unexported sessions and exports them before enriching. You only need to run ctx journal site --build afterward.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#using-make-journal","level":3,"title":"Using make journal","text":"

    If your project includes Makefile.ctx (deployed by ctx init), the first and last stages are combined:

    make journal           # export + rebuild\n

    After it runs, it reminds you to enrich in Claude Code:

    Next steps (in Claude Code):\n  /ctx-journal-enrich-all # exports if needed + adds metadata per entry\n\nThen re-run: make journal\n

    Rendering Issues?

    If individual entries have rendering problems (broken fences, malformed lists), use /ctx-journal-normalize on the affected file. This is rarely needed as programmatic normalization during export handles most cases.

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#tips","level":2,"title":"Tips","text":"

    Daily workflow: 

    # Export, browse, then enrich in Claude Code\nmake journal && make journal-serve\n# Then in Claude Code: /ctx-journal-enrich <session>\n

    After a productive session: 

    # Export just that session and add notes\nctx recall export <session-id>\n# Edit .context/journal/<session>.md\n# Regenerate: ctx journal site\n

    Searching across all sessions: 

    # Use grep on the journal directory\ngrep -r \"authentication\" .context/journal/\n

    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#requirements","level":2,"title":"Requirements","text":"Use pipx for zensical

    pip install zensical may install a non-functional stub on system Python. Using venv has other issues too.

    These issues especially happen on Mac OSX.

    Use pipx install zensical, which creates an isolated environment and handles Python version management automatically.

    The journal site uses zensical for static site generation:

    pipx install zensical\n
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/session-journal/#see-also","level":2,"title":"See Also","text":"
    • ctx recall: Session discovery and listing
    • ctx journal site: Static site generation
    • ctx journal obsidian: Obsidian vault export
    • Context Files: The .context/ directory structure
    ","path":["Reference","Session Journal"],"tags":[]},{"location":"reference/skills/","level":1,"title":"Skills","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#skills","level":2,"title":"Skills","text":"

    Skills are slash commands that run inside your AI assistant (e.g., /ctx-next), as opposed to CLI commands that run in your terminal (e.g., ctx status).

    Skills give your agent structured workflows: It knows what to read, what to run, and when to ask. Most wrap one or more ctx CLI commands with opinionated behavior on top.

    Skills Are Best Used Conversationally

    The beauty of ctx is that it's designed to be intuitive and conversational, allowing you to interact with your AI assistant naturally. That's why you don't have to memorize many of these skills.

    See the Prompting Guide for natural-language triggers that invoke these skills conversationally.

    However, when you need a more precise control, you have the option to invoke the relevant skills directly.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#all-skills","level":2,"title":"All Skills","text":"Skill Description Type /ctx-remember Recall project context and present structured readback user-invocable /ctx-wrap-up End-of-session context persistence ceremony user-invocable /ctx-status Show context summary with interpretation user-invocable /ctx-agent Load full context packet for AI consumption user-invocable /ctx-next Suggest 1-3 concrete next actions with rationale user-invocable /ctx-commit Commit with integrated context persistence user-invocable /ctx-reflect Pause and reflect on session progress user-invocable /ctx-add-task Add actionable task to TASKS.md user-invocable /ctx-add-decision Record architectural decision with rationale user-invocable /ctx-add-learning Record gotchas and lessons learned user-invocable /ctx-add-convention Record coding convention for consistency user-invocable /ctx-archive Archive completed tasks from TASKS.md user-invocable /ctx-pad Manage encrypted scratchpad entries user-invocable /ctx-recall Browse and export AI session history user-invocable /ctx-journal-enrich Enrich single journal entry with metadata user-invocable /ctx-journal-enrich-all Full journal pipeline: export if needed, then batch-enrich user-invocable /ctx-journal-normalize Normalize journal markdown for clean rendering user-invocable /ctx-blog Generate blog post draft from project activity user-invocable /ctx-blog-changelog Generate themed blog post from a commit range user-invocable /ctx-consolidate Consolidate redundant learnings or decisions user-invocable /ctx-drift Detect and fix context drift user-invocable /ctx-prompt Apply, list, and manage saved prompt templates user-invocable /ctx-prompt-audit Analyze prompting patterns for improvement user-invocable /ctx-check-links Audit docs for dead internal and external links user-invocable /ctx-sanitize-permissions Audit Claude Code permissions for security risks user-invocable /ctx-verify Verify claims before reporting completion user-invocable /ctx-brainstorm Structured design dialogue before implementation user-invocable /ctx-spec Scaffold a feature spec from a project template user-invocable /ctx-import-plans Import Claude Code plan files into project specs user-invocable /ctx-implement Execute a plan step-by-step with verification user-invocable /ctx-loop Generate autonomous loop script user-invocable /ctx-worktree Manage git worktrees for parallel agents user-invocable /ctx-architecture Build and maintain architecture maps user-invocable /ctx-remind Manage session-scoped reminders user-invocable /ctx-doctor Troubleshoot ctx behavior with health checks and event analysis user-invocable /ctx-skill-audit Audit skills against Anthropic prompting best practices user-invocable /ctx-skill-creator Create, improve, and test skills user-invocable /ctx-pause Pause context hooks for this session user-invocable /ctx-resume Resume context hooks after a pause user-invocable","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#session-lifecycle","level":2,"title":"Session Lifecycle","text":"

    Skills for starting, running, and ending a productive session.

    Session Ceremonies

    Two skills in this group are ceremony skills: /ctx-remember (session start) and /ctx-wrap-up (session end). Unlike other skills that work conversationally, these should be invoked as explicit slash commands for completeness. See Session Ceremonies.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-remember","level":3,"title":"/ctx-remember","text":"

    Recall project context and present a structured readback. Ceremony skill: invoke explicitly at session start.

    Wraps: ctx agent --budget 4000, ctx recall list --limit 3, reads TASKS.md, DECISIONS.md, LEARNINGS.md

    See also: Session Ceremonies, The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-status","level":3,"title":"/ctx-status","text":"

    Show context summary (files, token budget, tasks, recent activity) with interpreted suggestions.

    Wraps: ctx status [--verbose] [--json]

    See also: The Complete Session, ctx status CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-agent","level":3,"title":"/ctx-agent","text":"

    Load the full context packet optimized for AI consumption. Also runs automatically via the PreToolUse hook with cooldown.

    Wraps: ctx agent [--budget] [--format] [--cooldown] [--session]

    See also: The Complete Session, ctx agent CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-next","level":3,"title":"/ctx-next","text":"

    Suggest 1-3 concrete next actions ranked by priority, momentum, and unblocked status.

    Wraps: reads TASKS.md, ctx recall list --limit 3

    See also: The Complete Session, Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-commit","level":3,"title":"/ctx-commit","text":"

    Commit code with integrated context persistence: pre-commit checks, staged files, Co-Authored-By trailer, and a post-commit prompt to capture decisions and learnings.

    Wraps: git add, git commit, optionally chains to /ctx-add-decision and /ctx-add-learning

    See also: The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-reflect","level":3,"title":"/ctx-reflect","text":"

    Pause and reflect on session progress. Walks through a checklist of learnings, decisions, task completions, and session notes to persist.

    Wraps: chains to ctx add learning, ctx add decision, manual TASKS.md updates

    See also: The Complete Session, Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-wrap-up","level":3,"title":"/ctx-wrap-up","text":"

    End-of-session context persistence ceremony. Gathers signal from git diff, recent commits, and conversation themes. Proposes candidates (learnings, decisions, conventions, tasks) with complete structured fields for user approval, then persists via ctx add. Offers /ctx-commit if uncommitted changes remain. Ceremony skill: invoke explicitly at session end.

    Wraps: git diff --stat, git log, ctx add learning, ctx add decision, ctx add convention, ctx add task, chains to /ctx-commit

    See also: Session Ceremonies, The Complete Session

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#context-persistence","level":2,"title":"Context Persistence","text":"

    Skills for recording work artifacts: tasks, decisions, learnings, conventions: into .context/ files.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-task","level":3,"title":"/ctx-add-task","text":"

    Add an actionable task with optional priority and phase section.

    Wraps: ctx add task \"description\" [--priority high|medium|low]

    See also: Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-decision","level":3,"title":"/ctx-add-decision","text":"

    Record an architectural decision with context, rationale, and consequence. Supports Y-statement (lightweight) and full ADR formats.

    Wraps: ctx add decision \"title\" --context \"...\" --rationale \"...\" --consequence \"...\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-learning","level":3,"title":"/ctx-add-learning","text":"

    Record a project-specific gotcha, bug, or unexpected behavior. Filters for insights that are searchable, project-specific, and required real effort to discover.

    Wraps: ctx add learning \"title\" --context \"...\" --lesson \"...\" --application \"...\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-add-convention","level":3,"title":"/ctx-add-convention","text":"

    Record a coding convention that should be standardized across sessions. Targets patterns seen 2-3+ times.

    Wraps: ctx add convention \"rule\" --section \"Name\"

    See also: Persisting Decisions, Learnings, and Conventions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-archive","level":3,"title":"/ctx-archive","text":"

    Archive completed tasks from TASKS.md to a timestamped file in .context/archive/. Preserves phase headers for traceability.

    Wraps: ctx task archive [--dry-run]

    See also: Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#scratchpad","level":2,"title":"Scratchpad","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-pad","level":3,"title":"/ctx-pad","text":"

    Manage the encrypted scratchpad: add, remove, edit, and reorder one-liner notes. Encrypted at rest with AES-256-GCM.

    Wraps: ctx pad, ctx pad add, ctx pad rm, ctx pad edit, ctx pad mv, ctx pad import, ctx pad export, ctx pad merge

    See also: Scratchpad, Using the Scratchpad

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#journal-history","level":2,"title":"Journal & History","text":"

    Skills for browsing, exporting, and enriching your AI session history into a structured journal.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-recall","level":3,"title":"/ctx-recall","text":"

    Browse, inspect, and export AI session history. List recent sessions, show details by slug or ID, and export to .context/journal/.

    Wraps: ctx recall list, ctx recall show, ctx recall export

    See also: Browsing and Enriching Past Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-enrich","level":3,"title":"/ctx-journal-enrich","text":"

    Enrich a single journal entry with YAML frontmatter: title, type, outcome, topics, technologies, and summary. Shows diff before writing.

    Wraps: reads and edits .context/journal/*.md files

    See also: Browsing and Enriching Past Sessions, Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-enrich-all","level":3,"title":"/ctx-journal-enrich-all","text":"

    Full journal pipeline: exports unexported sessions first, then batch-enriches all unenriched entries. Filters out short sessions and continuations. Can spawn subagents for large backlogs.

    Wraps: ctx recall export --all + iterates /ctx-journal-enrich

    See also: Browsing and Enriching Past Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-journal-normalize","level":3,"title":"/ctx-journal-normalize","text":"

    Normalize journal markdown for clean rendering: fix fence nesting, metadata formatting, list indentation, and collapse large tool outputs.

    Wraps: reads and edits .context/journal/*.md files

    See also: Browsing and Enriching Past Sessions, Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#content-creation","level":2,"title":"Content Creation","text":"

    Skills for turning project activity into publishable content.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-blog","level":3,"title":"/ctx-blog","text":"

    Generate a blog post draft from recent project activity: git history, decisions, learnings, tasks, and journal entries. Requires a narrative arc (problem, approach, outcome).

    Wraps: reads git log, DECISIONS.md, LEARNINGS.md, TASKS.md, journal entries; writes to docs/blog/

    See also: Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-blog-changelog","level":3,"title":"/ctx-blog-changelog","text":"

    Generate a themed blog post from a commit range. Takes a starting commit and unifying theme, analyzes diffs and journal entries from that period.

    Wraps: git log, git diff --stat; writes to docs/blog/

    See also: Turning Activity into Content

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#auditing-health","level":2,"title":"Auditing & Health","text":"

    Skills for detecting drift, auditing alignment, and improving prompt quality.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-consolidate","level":3,"title":"/ctx-consolidate","text":"

    Consolidate redundant entries in LEARNINGS.md or DECISIONS.md. Groups overlapping entries by keyword similarity, presents candidates, and (with user approval) merges groups into denser combined entries. Originals are archived, not deleted.

    Wraps: reads LEARNINGS.md and DECISIONS.md, writes consolidated entries, archives originals, runs ctx reindex

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-drift","level":3,"title":"/ctx-drift","text":"

    Detect and fix context drift: stale paths, missing files, file age staleness, task accumulation, entry count warnings, and constitution violations via ctx drift. Also detects skill drift against canonical templates.

    Wraps: ctx drift [--fix]

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-prompt","level":3,"title":"/ctx-prompt","text":"

    Apply, list, and manage saved prompt templates from .context/prompts/. Prompt templates are plain Markdown files for common patterns like code review, refactoring, or explaining code.

    Wraps: ctx prompt list, ctx prompt show, ctx prompt apply, ctx prompt create

    Trigger phrases: \"use the code-review prompt\", \"list my prompts\", \"apply the refactor template\", \"create a prompt template\"

    See also: Prompt Templates

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-prompt-audit","level":3,"title":"/ctx-prompt-audit","text":"

    Analyze recent prompting patterns to identify vague or ineffective prompts. Reviews 3-5 journal entries and suggests rewrites with positive observations.

    Wraps: reads .context/journal/ entries

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-doctor","level":3,"title":"/ctx-doctor","text":"

    Troubleshoot ctx behavior. Runs structural health checks via ctx doctor, analyzes event log patterns via ctx system events, and presents findings with suggested actions. The CLI provides the structural baseline; the agent adds semantic analysis of event patterns and correlations.

    Wraps: ctx doctor --json, ctx system events --json --last 100, ctx remind list, ctx system message list, reads .ctxrc

    Trigger phrases: \"diagnose\", \"troubleshoot\", \"doctor\", \"health check\", \"why didn't my hook fire?\", \"hooks seem broken\", \"something seems off\"

    Graceful degradation: If event_log is not enabled, the skill still works but with reduced capability. It runs structural checks and notes: \"Enable event_log: true in .ctxrc for hook-level diagnostics.\"

    See also: Troubleshooting, ctx doctor CLI, ctx system events CLI

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-check-links","level":3,"title":"/ctx-check-links","text":"

    Scan all markdown files under docs/ for broken links. Three passes: internal links (verify file targets exist on disk), external links (HTTP HEAD with timeout, report failures as warnings), and image references. Resolves relative paths, strips anchors before checking, and skips localhost/example URLs.

    Wraps: Glob + Grep to scan, curl for external checks

    Trigger phrases: \"check links\", \"audit links\", \"any broken links?\", \"dead links\"

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-sanitize-permissions","level":3,"title":"/ctx-sanitize-permissions","text":"

    Audit .claude/settings.local.json for dangerous permissions across four risk categories: hook bypass (Critical), destructive commands (High), config injection vectors (High), and overly broad patterns (Medium). Reports findings by severity and offers specific fix actions with user confirmation.

    Wraps: reads .claude/settings.local.json, edits with confirmation

    Trigger phrases: \"audit permissions\", \"are my permissions safe?\", \"sanitize permissions\", \"check settings\"

    See also: Claude Code Permission Hygiene

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-verify","level":3,"title":"/ctx-verify","text":"

    Run the relevant verification command before claiming a result. Maps claims to required evidence (\"tests pass\" needs test output, \"build succeeds\" needs exit 0) and includes self-audit questions to surface gaps before reporting done.

    Wraps: runs the verification command appropriate to the claim (go test, make audit, go build, diff, etc.)

    Trigger phrases: \"verify this\", \"does it work?\", \"prove it passes\", \"is it done?\"

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#planning-execution","level":2,"title":"Planning & Execution","text":"

    Skills for structured design, implementation, and parallel agent workflows.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-brainstorm","level":3,"title":"/ctx-brainstorm","text":"

    Transform raw ideas into clear, validated designs through structured dialogue before any implementation begins. Follows a gated process: understand context, clarify the idea (one question at a time), surface non-functional requirements, lock understanding with user confirmation, explore 2-3 design approaches with trade-offs, stress-test the chosen approach, and present the detailed design.

    Wraps: reads DECISIONS.md, relevant source files; chains to /ctx-add-decision for recording design choices

    Trigger phrases: \"let's brainstorm\", \"design this\", \"think through\", \"before we build\", \"what approach should we take?\"

    See also: /ctx-spec

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-spec","level":3,"title":"/ctx-spec","text":"

    Scaffold a feature spec from the project template and walk through each section with the user. Covers: problem, approach, happy path, edge cases, validation rules, error handling, interface, implementation, configuration, testing, and non-goals. Spends extra time on edge cases and error handling.

    Wraps: reads specs/tpl/spec-template.md, writes to specs/, optionally chains to /ctx-add-task

    Trigger phrases: \"spec this out\", \"write a spec\", \"create a spec\", \"design document\"

    See also: /ctx-brainstorm, /ctx-import-plans

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-import-plans","level":3,"title":"/ctx-import-plans","text":"

    Import Claude Code plan files (~/.claude/plans/*.md) into the project's specs/ directory. Lists plans with dates and H1 titles, supports filtering (--today, --since, --all), slugifies headings for filenames, and optionally creates tasks referencing each imported spec.

    Wraps: reads ~/.claude/plans/*.md, writes to specs/, optionally chains to /ctx-add-task

    See also: Importing Claude Code Plans, Tracking Work Across Sessions

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-implement","level":3,"title":"/ctx-implement","text":"

    Execute a multi-step plan with build and test verification at each step. Loads a plan from a file or conversation context, breaks it into atomic steps, and checkpoints after every 3-5 steps.

    Wraps: reads plan file, runs verification commands (go build, go test, etc.)

    See also: Running an Unattended AI Agent

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-loop","level":3,"title":"/ctx-loop","text":"

    Generate a ready-to-run shell script for autonomous AI iteration. Supports Claude Code, Aider, and generic tool templates with configurable completion signals.

    Wraps: ctx loop [--tool] [--prompt] [--max-iterations] [--completion] [--output]

    See also: Autonomous Loops, Running an Unattended AI Agent

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-worktree","level":3,"title":"/ctx-worktree","text":"

    Manage git worktrees for parallel agent development. Create sibling worktrees on dedicated branches, analyze task blast radius for grouping, and tear down with merge.

    Wraps: git worktree add, git worktree list, git worktree remove, git merge

    See also: Parallel Agent Development with Git Worktrees

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-architecture","level":3,"title":"/ctx-architecture","text":"

    Build and maintain architecture maps incrementally. Creates or refreshes ARCHITECTURE.md (succinct project map, loaded at session start) and DETAILED_DESIGN.md (deep per-module reference, consulted on-demand). Coverage is tracked in map-tracking.json so each run extends the map rather than re-analyzing everything.

    Wraps: ctx status, git log, reads source files; writes ARCHITECTURE.md, DETAILED_DESIGN.md, map-tracking.json

    See also: Detecting and Fixing Drift

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-remind","level":3,"title":"/ctx-remind","text":"

    Manage session-scoped reminders via natural language. Translates user intent (\"remind me to refactor swagger\") into the corresponding ctx remind command. Handles date conversion for --after flags.

    Wraps: ctx remind, ctx remind list, ctx remind dismiss

    See also: Session Reminders

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#skill-authoring","level":2,"title":"Skill Authoring","text":"","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-skill-audit","level":3,"title":"/ctx-skill-audit","text":"

    Audit one or more skills against Anthropic prompting best practices. Checks audit dimensions: positive framing, motivation, phantom references, examples, subagent guards, scope, and descriptions. Reports findings by severity with concrete fix suggestions.

    Wraps: reads internal/assets/claude/skills/*/SKILL.md or .claude/skills/*/SKILL.md, references anthropic-best-practices.md

    Trigger phrases: \"audit this skill\", \"check skill quality\", \"review the skills\", \"are our skills any good?\"

    See also: /ctx-skill-creator, Contributing

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-skill-creator","level":3,"title":"/ctx-skill-creator","text":"

    Create, improve, and test skills. Guides the full lifecycle: capture intent, interview for edge cases, draft the SKILL.md, test with realistic prompts, review results with the user, and iterate. Applies core principles: the agent is already smart (only add what it does not know), the description is the trigger (make it specific and \"pushy\"), and explain the why instead of rigid directives.

    Wraps: reads/writes .claude/skills/ and internal/assets/claude/skills/

    Trigger phrases: \"create a skill\", \"turn this into a skill\", \"make a slash command\", \"this should be a skill\", \"improve this skill\", \"the skill isn't triggering\"

    See also: Contributing

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#session-control","level":2,"title":"Session Control","text":"

    Skills for controlling hook behavior during a session.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-pause","level":3,"title":"/ctx-pause","text":"

    Pause all context nudge and reminder hooks for the current session. Security hooks still fire. Use for quick investigations or tasks that don't need ceremony overhead.

    Wraps: ctx pause

    Trigger phrases: \"pause ctx\", \"pause context\", \"stop the nudges\", \"quiet mode\"

    See also: Pausing Context Hooks

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#ctx-resume","level":3,"title":"/ctx-resume","text":"

    Resume context hooks after a pause. Restores normal nudge, reminder, and ceremony behavior. Silent no-op if not paused.

    Wraps: ctx resume

    Trigger phrases: \"resume ctx\", \"resume context\", \"turn nudges back on\", \"unpause\"

    See also: Pausing Context Hooks

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/skills/#project-specific-skills","level":2,"title":"Project-Specific Skills","text":"

    The ctx plugin ships the skills listed above. Teams can add their own project-specific skills to .claude/skills/ in the project root: These are separate from plugin-shipped skills and are scoped to the project.

    Project-specific skills follow the same format and are invoked the same way.

    Custom skills are not covered in this reference.

    ","path":["Reference","Skills"],"tags":[]},{"location":"reference/versions/","level":1,"title":"Version History","text":"","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#version-history","level":2,"title":"Version History","text":"

    Documentation snapshots for each release.

    Tap the corresponding view docs to view the docs as they were at that release.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#releases","level":2,"title":"Releases","text":"Version Release Date Documentation v0.6.0 2026-02-16 view docs v0.3.0 2026-02-07 view docs v0.2.0 2026-02-01 view docs v0.1.2 2026-01-27 view docs v0.1.1 2026-01-26 view docs v0.1.0 2026-01-25 view docs","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v060-the-integration-release","level":3,"title":"v0.6.0: The Integration Release","text":"

    Plugin architecture: hooks and skills converted from shell scripts to Go subcommands, shipped as a Claude Code marketplace plugin. Multi-tool hook generation for Cursor, Aider, Copilot, and Windsurf. Webhook notifications with encrypted URL storage.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v030-the-discipline-release","level":3,"title":"v0.3.0: The Discipline Release","text":"

    Journal static site generation via zensical. 49-skill audit and fix pass (positive framing, phantom reference removal, scope tightening). Context consolidation skill. golangci-lint v2 migration.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v020-the-archaeology-release","level":3,"title":"v0.2.0: The Archaeology Release","text":"

    Session journal system: ctx recall export converts Claude Code JSONL transcripts to browsable Markdown. Constants refactor with semantic prefixes (Dir*, File*, Filename*). CRLF handling for Windows compatibility.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v012","level":3,"title":"v0.1.2","text":"

    Default Claude Code permissions deployed on ctx init. Prompting guide published as a standalone documentation page.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v011","level":3,"title":"v0.1.1","text":"

    Bug fixes: hook schema key format corrected, JSON unicode escaping fixed in context file output.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#v010-initial-release","level":3,"title":"v0.1.0: Initial Release","text":"

    CLI with 15 subcommands, 6 context file types (CONSTITUTION, TASKS, CONVENTIONS, ARCHITECTURE, DECISIONS, LEARNINGS), Makefile build system, and Claude Code hook integration.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#latest","level":2,"title":"Latest","text":"

    The main documentation always reflects the latest development version.

    For the most recent stable release, see v0.6.0.

    ","path":["Reference","Version History"],"tags":[]},{"location":"reference/versions/#changelog","level":2,"title":"Changelog","text":"

    For detailed changes between versions, see the GitHub Releases page.

    ","path":["Reference","Version History"],"tags":[]},{"location":"security/","level":1,"title":"Security","text":"

    Security model, agent hardening, and vulnerability reporting.

    ","path":["Security"],"tags":[]},{"location":"security/#securing-ai-agents","level":3,"title":"Securing AI Agents","text":"

    Defense in depth for unattended AI agents: five layers of protection, each with a known bypass, strength in combination.

    ","path":["Security"],"tags":[]},{"location":"security/#security-policy","level":3,"title":"Security Policy","text":"

    Trust model, vulnerability reporting, permission hygiene, and security design principles.

    ","path":["Security"],"tags":[]},{"location":"security/agent-security/","level":1,"title":"Securing AI Agents","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#defense-in-depth-securing-ai-agents","level":1,"title":"Defense in Depth: Securing AI Agents","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#the-problem","level":2,"title":"The Problem","text":"

    An unattended AI agent with unrestricted access to your machine is an unattended shell with unrestricted access to your machine.

    This is not a theoretical concern. AI coding agents execute shell commands, write files, make network requests, and modify project configuration. When running autonomously (overnight, in a loop, without a human watching), the attack surface is the full capability set of the operating system user account.

    The risk is not that the AI is malicious. The risk is that the AI is controllable: it follows instructions from context, and context can be poisoned.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#threat-model","level":2,"title":"Threat Model","text":"","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#how-agents-get-compromised","level":3,"title":"How Agents Get Compromised","text":"

    AI agents follow instructions from multiple sources: system prompts, project files, conversation history, and tool outputs. An attacker who can inject content into any of these sources can redirect the agent's behavior.

    Vector How it works Prompt injection via dependencies A malicious package includes instructions in its README, changelog, or error output. The agent reads these during installation or debugging and follows them. Prompt injection via fetched content The agent fetches a URL (documentation, API response, Stack Overflow answer) containing embedded instructions. Poisoned project files A contributor adds adversarial instructions to CLAUDE.md, .cursorrules, or .context/ files. The agent loads these at session start. Self-modification between iterations In an autonomous loop, the agent modifies its own configuration files. The next iteration loads the modified config with no human review. Tool output injection A command's output (error messages, log lines, file contents) contains instructions the agent interprets and follows.","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#what-can-a-compromised-agent-do","level":3,"title":"What Can a Compromised Agent Do","text":"

    Depends entirely on what permissions and access the agent has:

    Access level Potential impact Unrestricted shell Execute any command, install software, modify system files Network access Exfiltrate source code, credentials, or context files to external servers Docker socket Escape container isolation by spawning privileged sibling containers SSH keys Pivot to other machines, push to remote repositories, access production systems Write access to own config Disable its own guardrails for the next iteration","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#the-defense-layers","level":2,"title":"The Defense Layers","text":"

    No single layer is sufficient. Each layer catches what the others miss.

    Layer 1: Soft instructions     (CONSTITUTION.md, playbook)\nLayer 2: Application controls  (permission allowlist, tool restrictions)\nLayer 3: OS-level isolation    (user accounts, filesystem, containers)\nLayer 4: Network controls      (firewall rules, airgap)\nLayer 5: Infrastructure        (VM isolation, resource limits)\n
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-1-soft-instructions-probabilistic","level":3,"title":"Layer 1: Soft Instructions (Probabilistic)","text":"

    Markdown files like CONSTITUTION.md and the Agent Playbook tell the agent what to do and what not to do. These are probabilistic: the agent usually follows them, but there is no enforcement mechanism.

    What it catches: Most common mistakes. An agent that has been told \"never delete production data\" will usually not delete production data.

    What it misses: Prompt injection. A sufficiently crafted injection can override soft instructions. Long context windows dilute attention on rules stated early. Edge cases where instructions are ambiguous.

    Verdict: Necessary but not sufficient. Good for the common case. Do not rely on it for security boundaries.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-2-application-controls-deterministic-at-runtime-mutable-across-iterations","level":3,"title":"Layer 2: Application Controls (Deterministic at Runtime, Mutable Across Iterations)","text":"

    AI tool runtimes (Claude Code, Cursor, etc.) provide permission systems: tool allowlists, command restrictions, confirmation prompts.

    For Claude Code, ctx init writes both an allowlist and an explicit deny list into .claude/settings.local.json. The golden images live in internal/assets/permissions/:

    Allowlist (allow.txt): only these tools run without confirmation:

    Bash(ctx:*)\nSkill(ctx-add-convention)\nSkill(ctx-add-decision)\n... # all bundled ctx-* skills\n

    Deny list (deny.txt): these are blocked even if the agent requests them:

    # Dangerous operations\nBash(sudo *)\nBash(git push *)\nBash(git push)\nBash(rm -rf /*)\nBash(rm -rf ~*)\nBash(curl *)\nBash(wget *)\nBash(chmod 777 *)\n\n# Sensitive file reads\nRead(**/.env)\nRead(**/.env.*)\nRead(**/*credentials*)\nRead(**/*secret*)\nRead(**/*.pem)\nRead(**/*.key)\n\n# Sensitive file edits\nEdit(**/.env)\nEdit(**/.env.*)\n

    What it catches: The agent cannot run commands outside the allowlist, and the deny list blocks dangerous operations even if a future allowlist change were to widen access. If rm, curl, sudo, or docker are not allowed and sudo/curl/wget are explicitly denied, the agent cannot invoke them regardless of what any prompt says.

    What it misses: The agent can modify the allowlist itself. In an autonomous loop, if the agent writes to .claude/settings.local.json, and the next iteration loads the modified config, then the protection is effectively lost. The application enforces the rules, but the application reads the rules from files the agent can write.

    Verdict: Strong first layer. Must be combined with self-modification prevention (Layer 3).

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-3-os-level-isolation-deterministic-and-unbypassable","level":3,"title":"Layer 3: OS-Level Isolation (Deterministic and Unbypassable)","text":"

    The operating system enforces access controls that no application-level trick can override. An unprivileged user cannot read files owned by root. A process without CAP_NET_RAW cannot open raw sockets. These are kernel boundaries.

    Control Purpose Dedicated user account No sudo, no privileged group membership (docker, wheel, adm). The agent cannot escalate privileges. Filesystem permissions Project directory writable; everything else read-only or inaccessible. Agent cannot reach other projects, home directories, or system config. Immutable config files CLAUDE.md, .claude/settings.local.json, and .context/CONSTITUTION.md owned by a different user or marked immutable (chattr +i on Linux). The agent cannot modify its own guardrails.

    What it catches: Privilege escalation, self-modification, lateral movement to other projects or users.

    What it misses: Actions within the agent's legitimate scope. If the agent has write access to source code (which it needs to do its job), it can introduce vulnerabilities in the code itself.

    Verdict: Essential. This is the layer that makes the other layers trustworthy.

    OS-level isolation does not make the agent safe; it makes the other layers meaningful.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-4-network-controls","level":3,"title":"Layer 4: Network Controls","text":"

    An agent that cannot reach the internet cannot exfiltrate data. It also cannot ingest new instructions mid-loop from external documents, API responses, or hostile content.

    Scenario Recommended control Agent does not need the internet --network=none (container) or outbound firewall drop-all Agent needs to fetch dependencies Allow specific registries (npmjs.com, proxy.golang.org, pypi.org) via firewall rules. Block everything else. Agent needs API access Allow specific API endpoints only. Use an HTTP proxy with allowlisting.

    What it catches: Data exfiltration, phone-home payloads, downloading additional tools, and instruction injection via fetched content.

    What it misses: Nothing, if the agent genuinely does not need the network. The tradeoff is that many real workloads need dependency resolution, so a full airgap requires pre-populated caches.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#layer-5-infrastructure-isolation","level":3,"title":"Layer 5: Infrastructure Isolation","text":"

    The strongest boundary is a separate machine (or something that behaves like one).

    The moment you stop arguing about prompts and start arguing about kernels, you are finally doing security.

    Containers (Docker, Podman):

    docker run --rm \\\n  --network=none \\\n  --cap-drop=ALL \\\n  --memory=4g \\\n  --cpus=2 \\\n  -v /path/to/project:/workspace \\\n  -w /workspace \\\n  your-dev-image \\\n  ./loop.sh\n

    Docker Socket is sudo Access

    Critical: never mount the Docker socket (/var/run/docker.sock).

    An agent with socket access can spawn sibling containers with full host access, effectively escaping the sandbox.

    Use rootless Docker or Podman to eliminate this escalation path.

    Virtual machines: The strongest isolation. The guest kernel has no visibility into the host OS. No shared folders, no filesystem passthrough, no SSH keys to other machines.

    Resource limits: CPU, memory, and disk quotas prevent a runaway agent from consuming all resources. Use ulimit, cgroup limits, or container resource constraints.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#putting-it-all-together","level":2,"title":"Putting It All Together","text":"

    A defense-in-depth setup for overnight autonomous runs:

    Layer Implementation Stops Soft instructions CONSTITUTION.md with \"never delete tests\", \"always run tests before committing\" Common mistakes (probabilistic) Application allowlist .claude/settings.local.json with explicit tool permissions Unauthorized commands (deterministic within runtime) Immutable config chattr +i on CLAUDE.md, .claude/, CONSTITUTION.md Self-modification between iterations Unprivileged user Dedicated user, no sudo, no docker group Privilege escalation Container --cap-drop=ALL --network=none, rootless, no socket mount Host escape, network exfiltration Resource limits --memory=4g --cpus=2, disk quotas Resource exhaustion

    Each layer is straightforward: The strength is in the combination.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#common-mistakes","level":2,"title":"Common Mistakes","text":"

    \"I'll just use --dangerously-skip-permissions\": This disables Layer 2 entirely. Without Layers 3-5, you have no protection at all. Only use this flag inside a properly isolated container or VM.

    \"The agent is sandboxed in Docker\": A Docker container with the Docker socket mounted, running as root, with --privileged, and full network access is not sandboxed. It is a root shell with extra steps.

    \"CONSTITUTION.md says not to do that\": Markdown is a suggestion. It works most of the time. It is not a security boundary. Do not use it as one.

    \"I reviewed the CLAUDE.md, it's fine\": The agent can modify CLAUDE.md during iteration N. Iteration N+1 loads the modified version. Unless the file is immutable, your review is stale.

    \"The agent only has access to this one project\": Does the project directory contain .env files, SSH keys, API tokens, or credentials? Does it have a .git/config with push access to a remote? Filesystem isolation means isolating what is in the directory too.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#team-security-considerations","level":2,"title":"Team Security Considerations","text":"

    When multiple developers share a .context/ directory, security considerations extend beyond single-agent hardening.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#code-review-for-context-files","level":3,"title":"Code Review for Context Files","text":"

    Treat .context/ changes like code changes. Context files influence agent behavior (a modified CONSTITUTION.md or CONVENTIONS.md changes what every agent on the team will do next session). Review them in PRs with the same scrutiny you apply to production code.

    Watch for:

    • Weakened constitutional rules (removed constraints, softened language)
    • New decisions that contradict existing ones without acknowledging it
    • Learnings that encode incorrect assumptions
    • Task additions that bypass the team's prioritization process
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#gitignore-patterns","level":3,"title":"Gitignore Patterns","text":"

    ctx init configures .gitignore automatically, but verify these patterns are in place:

    • Always gitignored: .ctx.key (encryption key), .context/logs/, .context/journal/
    • Team decision: scratchpad.enc (encrypted, safe to commit for shared scratchpad state); .gitignore if scratchpads are personal
    • Never committed: .env, credentials, API keys (enforced by drift secret detection)
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#multi-developer-context-sharing","level":3,"title":"Multi-Developer Context Sharing","text":"

    CONSTITUTION.md is the shared contract. All team members and their agents inherit it. Changes require team consensus, not unilateral edits.

    When multiple agents write to the same context files concurrently (e.g., two developers adding learnings simultaneously), git merge conflicts are expected. Resolution is typically additive: accept both additions. Destructive resolution (dropping one side) loses context.

    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#team-conventions-for-context-management","level":3,"title":"Team Conventions for Context Management","text":"

    Establish and document:

    • Who reviews context changes: Same reviewers as code, or a designated context owner?
    • How to resolve conflicting decisions: If two sessions record contradictory decisions, which wins? Default: the later one must explicitly supersede the earlier one with rationale.
    • Frequency of context maintenance: Weekly ctx drift checks, monthly consolidation passes, archival after each milestone.
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#checklist","level":2,"title":"Checklist","text":"

    Before running an unattended AI agent:

    • Agent runs as a dedicated unprivileged user (no sudo, no docker group)
    • Agent's config files are immutable or owned by a different user
    • Permission allowlist restricts tools to the project's toolchain
    • Container drops all capabilities (--cap-drop=ALL)
    • Docker socket is NOT mounted
    • Network is disabled or restricted to specific domains
    • Resource limits are set (memory, CPU, disk)
    • No SSH keys, API tokens, or credentials are accessible to the agent
    • Project directory does not contain .env or secrets files
    • Iteration cap is set (--max-iterations)
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/agent-security/#further-reading","level":2,"title":"Further Reading","text":"
    • Running an Unattended AI Agent: the ctx recipe for autonomous loops, including step-by-step permissions and isolation setup
    • Security: ctx's own trust model and vulnerability reporting
    • Autonomous Loops: full documentation of the loop pattern, PROMPT.md templates, and troubleshooting
    ","path":["Security","Securing AI Agents"],"tags":[]},{"location":"security/reporting/","level":1,"title":"Security Policy","text":"","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#reporting-vulnerabilities","level":2,"title":"Reporting Vulnerabilities","text":"

    At ctx we take security very seriously.

    If you discover a security vulnerability in ctx, please report it responsibly.

    Do NOT open a public issue for security vulnerabilities.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#email","level":3,"title":"Email","text":"

    Send details to security@ctx.ist.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#github-private-reporting","level":3,"title":"GitHub Private Reporting","text":"
    1. Go to the Security tab;
    2. Click \"Report a Vulnerability\";
    3. Provide a detailed description.
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#encrypted-reports-optional","level":3,"title":"Encrypted Reports (Optional)","text":"

    If your report contains sensitive details (proof-of-concept exploits, credentials, or internal system information), you can encrypt your message with our PGP key:

    • In-repo: SECURITY_KEY.asc
    • Keybase: keybase.io/alekhinejose
    # Import the key\ngpg --import SECURITY_KEY.asc\n\n# Encrypt your report\ngpg --armor --encrypt --recipient security@ctx.ist report.txt\n

    Encryption is optional. Unencrypted reports to security@ctx.ist or via GitHub Private Reporting are perfectly fine.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#what-to-include","level":3,"title":"What to Include","text":"
    • Description of the vulnerability,
    • Steps to reproduce,
    • Potential impact,
    • Suggested fix (if any).
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#attribution","level":2,"title":"Attribution","text":"

    We appreciate responsible disclosure and will acknowledge security researchers who report valid vulnerabilities (unless they prefer to remain anonymous).

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#response-timeline","level":3,"title":"Response Timeline","text":"

    Open source, Best-Effort Timelines

    ctx is a volunteer-maintained open source project.

    The timelines below are guidelines, not guarantees, and depend on contributor availability.

    We will address security reports on a best-effort basis and prioritize them by severity.

    Stage Timeframe Acknowledgment Within 48 hours Initial assessment Within 7 days Resolution target Within 30 days (depending on severity)","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#trust-model","level":2,"title":"Trust Model","text":"

    ctx operates within a single trust boundary: the local filesystem.

    The person who authors .context/ files is the same person who runs the agent that reads them. There is no remote input, no shared state, and no server component.

    This means:

    • ctx does not sanitize context files for prompt injection. This is a deliberate design choice, not an oversight. The files are authored by the developer who owns the machine: Sanitizing their own instructions back to them would be counterproductive.
    • If you place adversarial instructions in your own .context/ files, your agent will follow them. This is expected behavior. You control the context; the agent trusts it.

    Shared Repositories

    In shared repositories, .context/ files should be reviewed in code review (the same way you would review CI/CD config or Makefiles). A malicious contributor could add harmful instructions to CONSTITUTION.md or TASKS.md.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#security-design","level":2,"title":"Security Design","text":"

    ctx is designed with security in mind:

    • No secrets in context: The constitution explicitly forbids storing secrets, tokens, API keys, or credentials in .context/ files
    • Local only: ctx runs entirely locally with no external network calls
    • No code execution: ctx reads and writes Markdown files only; it does not execute arbitrary code
    • Git-tracked: Core context files are meant to be committed, so they should never contain sensitive data. Exception: sessions/ and journal/ contain raw conversation data and should be gitignored
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#permission-hygiene","level":2,"title":"Permission Hygiene","text":"

    Claude Code evaluates permissions in deny → ask → allow order. ctx init automatically populates permissions.deny with rules that block dangerous operations before the allow list is ever consulted.

    Default deny rules block:

    • sudo, git push, rm -rf /, rm -rf ~, curl, wget, chmod 777
    • Read/Edit of .env, credentials, secrets, .pem, .key files

    Even with deny rules in place, the allow list accumulates one-off permissions over time. Periodically review for:

    • Destructive commands: git reset --hard, git clean -f, etc.
    • Config injection vectors: permissions that allow modifying files controlling agent behavior (CLAUDE.md, settings.local.json)
    • Broad wildcards: overly permissive patterns that pre-approve more than intended
    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#state-file-management","level":2,"title":"State File Management","text":"

    Hook state files (throttle markers, prompt counters, pause markers) are stored in .context/state/, which is project-scoped and gitignored. State files are automatically managed by the hooks that create them; no manual cleanup is needed.

    ","path":["Security","Security Policy"],"tags":[]},{"location":"security/reporting/#best-practices","level":2,"title":"Best Practices","text":"
    1. Review before committing: Always review .context/ files before committing
    2. Use .gitignore: If you must store sensitive notes locally, add them to .gitignore
    3. Drift detection: Run ctx drift to check for potential issues
    4. Permission audit: Review .claude/settings.local.json after busy sessions
    ","path":["Security","Security Policy"],"tags":[]},{"location":"thesis/","level":1,"title":"Context as State","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#a-persistence-layer-for-human-ai-cognition","level":2,"title":"A Persistence Layer for Human-AI Cognition","text":"

    Jose Alekhinne - jose@ctx.ist

    February 2026

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#abstract","level":3,"title":"Abstract","text":"

    As AI tools evolve from code-completion utilities into reasoning collaborators, the knowledge that governs their behavior becomes as important as the code they produce; yet, that knowledge is routinely discarded at the end of every session.

    AI-assisted development systems assemble context at prompt time using heuristic retrieval from mutable sources: recent files, semantic search results, session history. These approaches optimize relevance at the moment of generation but do not persist the cognitive state that produced decisions. Reasoning is not reproducible, intent is lost across sessions, and teams cannot audit the knowledge that constrains automated behavior.

    This paper argues that context should be treated as deterministic, version-controlled state rather than as a transient query result. We ground this argument in three sources of evidence: a landscape analysis of 17 systems spanning AI coding assistants, agent frameworks, and knowledge stores; a taxonomy of five primitive categories that reveals irrecoverable architectural trade-offs; and an experience report from ctx, a persistence layer for AI-assisted development, which developed itself using its own persistence model across 389 sessions over 33 days. We define a three-tier model for cognitive state: authoritative knowledge, delivery views, and ephemeral state. Then we present six design invariants empirically validated by 56 independent rejection decisions observed across the analyzed landscape. We show that context determinism applies to assembly, not to model output, and that the curation cost this model requires is offset by compounding returns in reproducibility, auditability, and team cognition.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#1-introduction","level":2,"title":"1. Introduction","text":"

    The introduction of large language models into software development has shifted the primary interface from code execution to interactive reasoning. In this environment, the correctness of an output depends not only on source code but on the context supplied to the model: the conventions, decisions, architectural constraints, and domain knowledge that bound the space of acceptable responses.

    Current systems treat context as a query result assembled at the moment of interaction. A developer begins a session; the tool retrieves what it estimates to be relevant from chat history, recent files, and vector stores; the model generates output conditioned on this transient assembly; the session ends, and the context evaporates. The next session begins the cycle again.

    This model has improved substantially over the past year. CLAUDE.md files, Cursor rules, Copilot's memory system, and tools such as Mem0, Letta, and Kindex each address aspects of the persistence problem. Yet across 17 systems we analyzed spanning AI coding assistants, agent frameworks, autonomous coding agents, and purpose-built knowledge stores, no system provides all five of the following properties simultaneously: deterministic context assembly, human-readable file-based persistence, token-budgeted delivery, zero runtime dependencies, and local-first operation.

    This paper does not propose a universal replacement for retrieval-centric workflows. It defines a persistence layer (embodied in ctx (https://ctx.ist)) whose advantages emerge under specific operational conditions: when reproducibility is a requirement, when knowledge must outlive sessions and individuals, when teams require shared cognitive authority, or when offline operation is necessary.

    The trade-offs (manual curation cost, reduced automatic recall, coarser granularity) are intentional and mirror the trade-offs accepted by systems that favor reproducibility over convenience, such as reproducible builds and immutable infrastructure 1 6.

    The contribution is threefold: a three-tier model for cognitive state that resolves the ambiguity between authoritative knowledge and ephemeral session artifacts; six design invariants empirically grounded in a cross-system landscape analysis; and an experience report demonstrating that the model produces compounding returns when applied to its own development.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#2-the-limits-of-prompt-time-context","level":2,"title":"2. The Limits of Prompt-Time Context","text":"

    Prompt-time assembly pipelines typically consist of corpus selection, retrieval, ranking, and truncation. These pipelines are probabilistic and time-dependent, producing three failure modes that compound over the lifetime of a project.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#21-non-reproducibility","level":3,"title":"2.1 Non-Reproducibility","text":"

    If context is derived from mutable sources using heuristic ranking, identical requests at different times receive different inputs. A developer who asks \"What is our authentication strategy?\" on Tuesday may receive a different context window than the same question on Thursday: Not because the strategy changed, but because the retrieval heuristic surfaced different fragments.

    Reproducibility (the ability to reconstruct the exact inputs that produced a given output) is a foundational property of reliable systems. Its loss in AI-assisted development mirrors the historical evolution from ad-hoc builds to deterministic build systems 1 2. The build community learned that when outputs depend on implicit state (environment variables, system clocks, network-fetched dependencies), debugging becomes archaeology. The same principle applies when AI outputs depend on non-deterministic context retrieval.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#22-opaque-knowledge","level":3,"title":"2.2 Opaque Knowledge","text":"

    Embedding-based memory increases recall but reduces inspectability. When a vector store determines that a code snippet is \"similar\" to the current query, the ranking function is opaque: the developer cannot inspect why that snippet was chosen, whether a more relevant artifact was excluded, or whether the ranking will remain stable. This prevents deterministic debugging, policy auditing, and causal attribution (properties that information retrieval theory identifies as fundamental trade-offs of probabilistic ranking) 3.

    In practice, this opacity manifests as a compliance ceiling. In our experience developing a context management system (detailed in Section 7), soft instructions (directives that ask an AI agent to read specific files or follow specific procedures) achieve approximately 75-85% compliance. The remaining 15-25% represents cases where the agent exercises judgment about whether the instruction applies, effectively applying a second ranking function on top of the explicit directive. When 100% compliance is required, instruction is insufficient; the content must be injected directly, removing the agent's option to skip it.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#23-loss-of-intent","level":3,"title":"2.3 Loss of Intent","text":"

    Session transcripts record interaction but not cognition. A transcript captures what was said but not which assumptions were accepted, which alternatives were rejected, or which constraints governed the decision. The distinction matters: a decision to use PostgreSQL recorded as a one-line note (\"Use PostgreSQL\") teaches a model what was decided; a structured record with context, rationale, and consequences teaches it why (and why is what prevents the model from unknowingly reversing the decision in a future session) 4.

    Session transcripts provide history. Cognitive state requires something more: the persistent, structured representation of the knowledge required for correct decision-making.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#3-cognitive-state-a-three-tier-model","level":2,"title":"3. Cognitive State: A Three-Tier Model","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#31-definitions","level":3,"title":"3.1 Definitions","text":"

    We define cognitive state as the authoritative, persistent representation of the knowledge required for correct decision-making within a project. It is human-authored or human-ratified, versioned, inspectable, and reproducible. It is distinct from logs, transcripts, retrieval results, and model-generated summaries.

    Previous formulations of this idea have treated cognitive state as a monolithic concept. In practice, a three-tier model better captures the operational reality:

    Tier 1: Authoritative State: The canonical knowledge that the system treats as ground truth. In a concrete implementation, this corresponds to a set of human-curated files with defined schemas: a constitution (inviolable rules), conventions (code patterns), an architecture document (system structure), decision records (choices with rationale), learnings (captured experience), a task list (current work), a glossary (domain terminology), and an agent playbook (operating instructions). Each file has a single purpose, a defined lifecycle, and a distinct update frequency. Authoritative state is version-controlled alongside code and reviewed through the same mechanisms (diffs, pull requests, blame annotations).

    Tier 2: Delivery Views: Derived representations of authoritative state, assembled for consumption by a model. A delivery view is produced by a deterministic assembly function that takes the authoritative state, a token budget, and an inclusion policy as inputs and produces a context window as output. The same authoritative state, budget, and policy must always produce the same delivery view. Delivery views are ephemeral (they exist only for the duration of a session), but their construction is reproducible.

    Tier 3: Ephemeral State: Session transcripts, scratchpad notes, draft journal entries, and other artifacts that exist during or immediately after a session but are not authoritative. Ephemeral state is the raw material from which authoritative state may be extracted through human review, but it is never consumed directly by the assembly function.

    This three-tier model resolves confusion present in earlier formulations: the claim that AI output is a deterministic function of the repository state. The corrected claim is that context selection is deterministic (the delivery view is a function of authoritative state), but model output remains stochastic, conditioned on the deterministic context. Formally:

    delivery_view = assemble(authoritative_state, budget, policy)\noutput = model(delivery_view)   # stochastic\n

    The persistence layer's contribution is making assemble reproducible, not making model deterministic.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#32-separation-of-concerns","level":3,"title":"3.2 Separation of Concerns","text":"

    The decision to separate authoritative state into distinct files with distinct purposes is not cosmetic. Different types of knowledge have different lifecycles:

    Knowledge Type Update Frequency Read Frequency Load Priority Example Constitution Rarely Every session Always \"Never commit secrets to git\" Tasks Every session Session start Always \"Implement token budget CLI flag\" Conventions Weekly Before coding High \"All errors use structured logging with severity levels\" Decisions When decided When questioning Medium \"Use PostgreSQL over MySQL (see ADR-003)\" Learnings When learned When stuck Medium \"Hook scripts >50ms degrade interactive UX\" Architecture When changed When designing On demand \"Three-layer pipeline: ingest → enrich → assemble\" Journal Every session Rarely Never auto \"Session 247: Removed dead-end session copy layer\"

    A monolithic context file would force the assembly function to load everything or nothing. Separation enables progressive disclosure: the minimum context that matters for the current moment, with the option to load more when needed. A normal session loads the constitution, tasks, and conventions; a deep investigation loads decision history and journal entries from specific dates.

    The budget mechanism is the constraint that makes separation valuable. Without a budget, the default behavior is to load everything, which destroys the attention density that makes loaded context useful. With a budget, the assembly function must prioritize ruthlessly: constitution first (always full), then tasks and conventions (budget-capped), then decisions and learnings (scored by recency). Entries that do not fit receive title-only summaries rather than being silently dropped (an application of the \"tell me what you don't know\" pattern identified independently by four systems in our landscape analysis).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#4-design-invariants","level":2,"title":"4. Design Invariants","text":"

    The following six invariants define the constraints that a cognitive state persistence layer must satisfy. They are not axioms chosen a priori; they are empirically grounded properties whose violation was independently identified as producing complexity costs across the 17 systems we analyzed.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-1-markdown-on-filesystem-persistence","level":3,"title":"Invariant 1: Markdown-on-Filesystem Persistence","text":"

    Context files must be human-readable, git-diffable, and editable with any text editor. No database. No binary storage.

    Validation: 11 independent rejection decisions across the analyzed landscape protected this property. Systems that adopted embedded records, binary serialization, or knowledge graphs as their core primitive consistently traded away the ability for a developer to run cat DECISIONS.md and understand the system's knowledge. The inspection cost of opaque storage compounds over the lifetime of a project: every debugging session, every audit, every onboarding conversation requires specialized tooling to access knowledge that could have been a text file.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-2-zero-runtime-dependencies","level":3,"title":"Invariant 2: Zero Runtime Dependencies","text":"

    The tool must work with no installed runtimes, no running services, and no API keys for core functionality.

    Validation: 13 independent rejection decisions protected this property (the most frequently defended invariant). Systems that required databases (PostgreSQL, SQLite, Redis), embedding models, server daemons, container runtimes, or cloud APIs for core operation introduced failure modes proportional to their dependency count. A persistence layer that depends on infrastructure is not a persistence layer; it is a service. Services have uptime requirements, version compatibility matrices, and operational costs that simple file operations do not.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-3-deterministic-context-assembly","level":3,"title":"Invariant 3: Deterministic Context Assembly","text":"

    The same files plus the same budget must produce the same output. No embedding-based retrieval, no LLM-driven selection, no wall-clock-dependent scoring in the assembly path.

    Validation: 6 independent rejection decisions protected this property. Non-deterministic assembly (whether from embedding variance, LLM-based selection, or time-dependent scoring) destroys the ability to reproduce a context window and therefore to diagnose why a model produced a given output. Determinism in the assembly path is what makes the persistence layer auditable.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-4-human-authority-over-persistent-state","level":3,"title":"Invariant 4: Human Authority Over Persistent State","text":"

    The agent may propose changes to context files but must not unilaterally modify them. All persistent changes go through human-reviewable git commits.

    Validation: 6 independent rejection decisions protected this property. Systems that allowed agents to self-modify their memory (writing freeform notes, auto-pruning old entries, generating summaries as ground truth) consistently produced lower-quality persistent context than systems that enforced human review. Structure is a feature, not a limitation: across the landscape, the pattern \"structured beats freeform\" was independently discovered by four systems that evolved from freeform LLM summaries to typed schemas with required fields.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-5-local-first-air-gap-capable","level":3,"title":"Invariant 5: Local-First, Air-Gap Capable","text":"

    Core functionality must work offline with no network access. Cloud services may be used for optional features but never for core context management.

    Validation: 7 independent rejection decisions protected this property. Infrastructure-dependent memory systems cannot operate in classified environments, isolated networks, or disaster-recovery scenarios. A filesystem-native model continues to function under all conditions where the repository is accessible.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#invariant-6-no-default-telemetry","level":3,"title":"Invariant 6: No Default Telemetry","text":"

    Any analytics, if ever added, must be strictly opt-in.

    Validation: 4 independent rejection decisions protected this property. Default telemetry erodes the trust model that a persistence layer depends on. If developers must trust the system with their architectural decisions, operational learnings, and project constraints, the system cannot simultaneously be reporting usage data to external services.

    These six invariants collectively define a design space. Each feature proposal can be evaluated against them: a feature that violates any invariant is rejected regardless of how many other systems implement it. The discipline of constraint (refusing to add capabilities that compromise foundational properties) is itself an architectural contribution. Across the 17 analyzed systems, 56 patterns were explicitly rejected for violating these invariants. The rejection count per invariant (11, 13, 6, 6, 7, 4) provides a rough measure of each property's vulnerability to architectural erosion. A representative sample of these rejections is provided in Appendix A.1

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#5-landscape-analysis","level":2,"title":"5. Landscape Analysis","text":"

    The 17 systems were selected to cover the architectural design space rather than to achieve completeness. Each included system satisfies three criteria: it represents a distinct architectural primitive for AI-assisted development, it is actively maintained or widely referenced, and it provides sufficient public documentation or source code for architectural inspection. The goal was to ensure that every major category of primitive (document, embedded record, state snapshot, event/message, construction/derivation) was represented by multiple systems, enabling cross-system pattern detection.

    The resulting set spans six categories: AI coding assistants (Continue, Sourcegraph/Cody, Aider, Claude Code), AI agent frameworks (CrewAI, AutoGen, LangGraph, LlamaIndex, Letta/MemGPT), autonomous coding agents (OpenHands, Sweep), session provenance tools (Entire), data versioning systems (Dolt, Pachyderm), pipeline/build systems (Dagger), and purpose-built knowledge stores (QubicDB, Kindex). Each system was analyzed from its source code and documentation, producing 34 individual analysis artifacts (an architectural profile and a set of insights per system) that yielded 87 adopt/adapt recommendations, 56 explicit rejection decisions, and 52 watch items.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#51-primitive-taxonomy","level":3,"title":"5.1 Primitive Taxonomy","text":"

    Every system in the AI-assisted development landscape operates on a core primitive: an atomic unit around which the entire architecture revolves. Our analysis of 17 systems reveals five categories of primitives, each making irrecoverable trade-offs:

    Group A: Document/File Primitives: Human-readable documents as the primary unit. Documents are authored by humans, version-controlled in git, and consumed by AI tools. The invariant of this group is that the primitive is always human-readable and version-controllable with standard tools. Three systems participate in this pattern: the system described in this paper as a pure expression, and Continue (via its rules directory) and Claude Code (via CLAUDE.md files) as partial participants: both use document-based context as an input but organize around different core primitives.

    Group B: Embedded Record Primitives: Vector-embedded records stored with numerical embeddings for similarity search, metadata for filtering, and scoring mechanisms for ranking. Five systems use this approach (LlamaIndex, CrewAI, Letta/MemGPT, QubicDB, Kindex). The invariant is that the primitive requires an embedding model or vector database for core operations: a dependency that precludes offline and air-gapped use.

    Group C: State Snapshot Primitives: Point-in-time captures of the complete system state. The invariant is that any past state can be reconstructed at any historical point. Three systems use this approach (LangGraph, Entire, Dolt).

    Group D: Event/Message Primitives: Sequential events or messages forming an append-only log with causal relationships. Four systems use this approach (OpenHands, AutoGen, Claude Code, Sweep). The invariant is temporal ordering and append-only semantics.

    Group E: Construction/Derivation Primitives: Derived or constructed values that encode how they were produced. The invariant is that the primitive is a function of its inputs; re-executing the same inputs produces the same primitive. Three systems use this approach (Dagger, Pachyderm, Aider).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#52-comparison-matrix","level":3,"title":"5.2 Comparison Matrix","text":"

    The five primitive categories differ along seven dimensions:

    Property Document Embedded Record State Snapshot Event/Message Construction Human-readable Yes No Varies Partially No Version-controllable Yes No Varies Yes Yes Queryable by meaning No Yes No No No Rewindable Via git No Yes Yes (replay) Yes Deterministic Yes No Yes Yes Yes Zero-dependency Yes No Varies Varies Varies Offline-capable Yes No Varies Varies Yes

    The document primitive is the only one that simultaneously satisfies human-readability, version-controllability, determinism, zero dependencies, and offline capability. This is not because documents are superior in general (embedded records provide semantic queryability that documents lack) but because the combination of all five properties is what the persistence layer requires. The choice between primitive categories is not a matter of capability but of which properties are considered invariant.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#53-convergent-patterns","level":3,"title":"5.3 Convergent Patterns","text":"

    Across the 17 analyzed systems, six design patterns were independently discovered. These convergent patterns carry extra validation weight because they emerged from different problem spaces:

    Pattern 1: \"Tell me what you don't know\": When context is incomplete, explicitly communicate to the model what information is missing and what confidence level the provided context represents. Four systems independently converged on this pattern: inserting skip markers, tracking evidence gaps, annotating provenance, or naming output quality tiers.

    Pattern 2: \"Freshness matters\": Information relevance decreases over time. Three systems independently chose exponential decay with different half-lives (30 days, 90 days, and LRU ordering). Static priority ordering with no time dimension leaves relevant recent knowledge at the same priority as stale entries. This pattern is in productive tension with the persistence model's emphasis on determinism: the claim is not that time-dependence is irrelevant, but that it belongs in the curation step (a human deciding to consolidate or archive stale entries) rather than in the assembly function (an algorithm silently down-ranking entries based on age).

    Pattern 3: \"Content-address everything\": Compute a hash of content at creation time for deduplication, cache invalidation, integrity verification, and change detection. Five systems independently implement content hashing, each discovering it solves different problems 5.

    Pattern 4: \"Structured beats freeform\": When capturing knowledge or session state, a structured schema with required fields produces more useful data than freeform text. Four systems evolved from freeform summaries to typed schemas: one moving from LLM-generated prose to a structured condenser with explicit fields for completed tasks, pending tasks, and files modified.

    Pattern 5: \"Protocol convergence\": The Model Context Protocol (MCP) is emerging as a standard tool integration layer. Nine of 17 systems support it, spanning every category in the analysis. MCP's significance for the persistence model is that it provides a transport mechanism for context delivery without dictating how context is stored or assembled. This makes the approach compatible with both retrieval-centric and persistence-centric architectures.

    Pattern 6: \"Human-in-the-loop for memory\": Critical memory decisions should involve human judgment. Fully automated memory management produces lower-quality persistent context than human-reviewed systems. Four systems independently converged on variants of this pattern: ceremony-based consolidation, interrupt/resume for human input, confirmation mode for high-risk actions, and separated \"think fast\" vs. \"think slow\" processing paths.

    Pattern 6 directly validates the ceremony model described in this paper. The persistence layer requires human curation not because automation is impossible, but because the quality of persistent knowledge degrades when the curation step is removed. The improvement opportunity is to make curation easier, not to automate it away.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#6-worked-example-architectural-decision-under-two-models","level":2,"title":"6. Worked Example: Architectural Decision Under Two Models","text":"

    We now instantiate the three-tier model in a concrete system (ctx) and illustrate the difference between prompt-time retrieval and cognitive state persistence using a real scenario from its development.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#61-the-problem","level":3,"title":"6.1 The Problem","text":"

    During development, the system accumulated three overlapping storage layers for session data: raw transcripts (owned by the AI tool), session copies (JSONL copies plus context snapshots), and enriched journal entries (Markdown summaries). The middle layer (session copies) was a dead-end write sink. An auto-save hook copied transcripts to a directory that nothing read from, because the journal pipeline already read directly from the raw transcripts. Approximately 15 source files, a shell hook, 20 configuration constants, and 30 documentation references supported infrastructure with no consumers.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#62-prompt-time-retrieval-model","level":3,"title":"6.2 Prompt-Time Retrieval Model","text":"

    In a retrieval-based system, the decision to remove the middle layer depends on whether the retrieval function surfaces the relevant context:

    The developer asks: \"Should we simplify the session storage?\" The retrieval system must find and rank the original discussion thread where the three layers were designed, the usage statistics showing zero reads from the middle layer, the journal pipeline documentation showing it reads from raw transcripts directly, and the dependency analysis showing 15 files, a hook, and 30 doc references. If any of these fragments are not retrieved (because they are in old chat history, because the embedding similarity score is low, or because the token budget was consumed by more recent but less relevant context), the model may recommend preserving the middle layer, or may not realize it exists.

    Six months later, a new team member asks the same question. The retrieval results will differ: the original discussion has aged out of recency scoring, the usage statistics are no longer in recent history, and the model may re-derive the answer or arrive at a different conclusion.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#63-cognitive-state-model","level":3,"title":"6.3 Cognitive State Model","text":"

    In the persistence model, the decision is recorded as a structured artifact at write time:

    ## [2026-02-11] Remove .context/sessions/ storage layer\n\n**Status**: Accepted\n\n**Context**: The session/recall/journal system had three overlapping\nstorage layers. The recall pipeline reads directly from raw transcripts,\nmaking .context/sessions/ a dead-end write sink that nothing reads from.\n\n**Decision**: Remove .context/sessions/ entirely. Two stores remain:\nraw transcripts (global, tool-owned) and enriched journal\n(project-local).\n\n**Rationale**: Dead-end write sinks waste code surface, maintenance\neffort, and user attention. The recall pipeline already proved that\nreading directly from raw transcripts is sufficient. Context snapshots\nare redundant with git history.\n\n**Consequence**: Deleted internal/cli/session/ (15 files), removed\nauto-save hook, removed --auto-save from watch, removed pre-compact\nauto-save, removed /ctx-save skill, updated ~45 documentation files.\nFour earlier decisions superseded.\n

    This artifact is:

    • Deterministically included in every subsequent session's delivery view (budget permitting, with title-only fallback if budget is exceeded)
    • Human-readable and reviewable as a diff in the commit that introduced it
    • Permanent: it persists in version control regardless of retrieval heuristics
    • Causally linked: it explicitly supersedes four earlier decisions, creating an auditable chain

    When the new team member asks \"Why don't we store session copies?\" six months later, the answer is the same artifact, at the same revision, with the same rationale. The reasoning is reconstructible because it was persisted at write time, not discovered at query time.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#64-the-diff-when-policy-changes","level":3,"title":"6.4 The Diff When Policy Changes","text":"

    If a future requirement re-introduces session storage (for example, to support multi-agent session correlation), the change appears as a diff to the decision record:

    - **Status**: Accepted\n+ **Status**: Superseded by [2026-08-15] Reintroduce session storage\n+ for multi-agent correlation\n

    The new decision record references the old one, creating a chain of reasoning visible in git log. In the retrieval model, the old decision would simply be ranked lower over time and eventually forgotten.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#7-experience-report-a-system-that-designed-itself","level":2,"title":"7. Experience Report: A System That Designed Itself","text":"

    The persistence model described in this paper was developed and tested by using it on its own development. Over 33 days and 389 sessions, the system's context files accumulated a detailed record of decisions made, reversed, and consolidated: providing quantitative and qualitative evidence for the model's properties.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#71-scale-and-structure","level":3,"title":"7.1 Scale and Structure","text":"

    The development produced the following authoritative state artifacts:

    • 8 consolidated decision records covering 24 original decisions spanning context injection architecture, hook design, task management, security, agent autonomy, and webhook systems
    • 18 consolidated learning records covering 75 original observations spanning agent compliance, hook behavior, testing patterns, documentation drift, and tool integration
    • A constitution with 13 inviolable rules across 4 categories (security, quality, process, context preservation)
    • 389 enriched journal entries providing a complete session-level audit trail

    The consolidation ratio (24 decisions compressed to 8 records, 75 learnings compressed to 18) illustrates the curation cost and its return: authoritative state becomes denser and more useful over time as related entries are merged, contradictions are resolved, and superseded decisions are marked.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#72-architectural-reversals","level":3,"title":"7.2 Architectural Reversals","text":"

    Three architectural reversals during development provide evidence that the persistence model captures and communicates reasoning effectively:

    Reversal 1: The two-tier persistence model: The original design included a middle storage tier for session copies. After 21 days of development, the middle tier was identified as a dead-end write sink (described in Section 6). The decision record captured the full context, and the removal was executed cleanly: 15 source files, a shell hook, and 45 documentation references. The pattern of a \"dead-end write sink\" was subsequently observed in 7 of 17 systems in our landscape analysis that store raw transcripts alongside structured context.

    Reversal 2: The prompt-coach hook: An early design included a hook that analyzed user prompts and offered improvement suggestions. After deployment, the hook produced zero useful tips, its output channel was invisible to users, and it accumulated orphan temporary files. The hook was removed, and the decision record captured the failure mode for future reference.

    Reversal 3: The soft-instruction compliance model: The original context injection strategy relied on soft instructions: directives asking the AI agent to read specific files. After measuring compliance across multiple sessions, we found a consistent 75-85% compliance ceiling. The revised strategy injects content directly, bypassing the agent's judgment about whether to comply. The learning record captures the ceiling measurement and the rationale for the architectural change.

    Each reversal was captured as a structured decision record with context, rationale, and consequences. In a retrieval-based system, these reversals would exist only in chat history, discoverable only if the retrieval function happens to surface them. In the persistence model, they are permanent, indexable artifacts that inform future decisions.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#73-compliance-ceiling","level":3,"title":"7.3 Compliance Ceiling","text":"

    The 75-85% compliance ceiling for soft instructions is the most operationally significant finding from the experience report. It means that any context management strategy relying on agent compliance with instructions (\"read this file,\" \"follow this convention,\" \"check this list\") has a hard ceiling on reliability.

    The root cause is structural: the instruction \"don't apply judgment\" is itself evaluated by judgment. When an agent receives a directive to read a file, it first assesses whether the directive is relevant to the current task (and that assessment is the judgment the directive was trying to prevent).

    The architectural response maps directly to the formal model defined in Section 3.1. Content requiring 100% compliance is included in authoritative_state and injected by the deterministic assemble function, bypassing the agent entirely. Content where 80% compliance is acceptable is delivered as instructions within the delivery view. The three-tier architecture makes this distinction explicit: authoritative state is injected; delivery views are assembled deterministically; ephemeral state is available but not pushed.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#74-compounding-returns","level":3,"title":"7.4 Compounding Returns","text":"

    Over 33 days, we observed a qualitative shift in the development experience. Early sessions (days 1-7) spent significant time re-establishing context: explaining conventions, re-stating constraints, re-deriving past decisions. Later sessions (days 25-33) began with the agent loading curated context and immediately operating within established constraints, because the constraints were in files rather than in chat history.

    This compounding effect (where each session's context curation improves all subsequent sessions) is the primary return on the curation investment. The cost is borne once (writing a decision record, capturing a learning, updating the task list); the benefit is collected on every subsequent session load.

    The effect is analogous to compound interest in financial systems: the knowledge base grows not linearly with effort but with increasing marginal returns as new knowledge interacts with existing context. A learning captured on day 5 prevents a mistake on day 12, which avoids a debugging session that would have consumed a day 12 session, freeing that session for productive work that generates new learnings. The growth is not literally exponential (it is bounded by project scope and subject to diminishing returns as the knowledge base matures), but within the observed 33-day window, the returns were consistently accelerating.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#75-scope-and-generalizability","level":3,"title":"7.5 Scope and Generalizability","text":"

    This experience report is self-referential by design: the system was developed using its own persistence model. This circularity strengthens the internal validity of the findings (the model was stress-tested under authentic conditions) but limits external generalizability. The two-week crossover point was observed on a single project of moderate complexity with a small team already familiar with the model's assumptions. Whether the same crossover holds for larger teams, for codebases with different characteristics, or for teams adopting the model without having designed it remains an open empirical question. The quantitative claims in this section should be read as existence proofs (demonstrating that the model can produce compounding returns) rather than as predictions about specific adoption scenarios.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#8-situating-the-persistence-layer","level":2,"title":"8. Situating the Persistence Layer","text":"

    The persistence layer occupies a specific position in the stack of AI-assisted development:

    Application Logic\nAI Interaction / Agents\nContext Retrieval Systems\nCognitive State Persistence Layer\nVersion Control / Storage\n

    Current systems innovate primarily in the retrieval layer (improving how context is discovered, ranked, and delivered at query time). The persistence layer sits beneath retrieval and above version control. Its role is to maintain the authoritative state that retrieval systems may query but do not own. The relationship is complementary: retrieval answers \"What in the corpus might be relevant?\"; cognitive state answers \"What must be true for this system to operate correctly?\" A mature system uses both: retrieval for discovery, persistence for authority.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#9-applicability-and-trade-offs","level":2,"title":"9. Applicability and Trade-Offs","text":"","path":["The Thesis"],"tags":[]},{"location":"thesis/#91-when-to-use-this-model","level":3,"title":"9.1 When to Use This Model","text":"

    A cognitive state persistence layer is most appropriate when:

    Reproducibility is a requirement: If a system must be able to answer \"Why did this output occur, and can it be produced again?\" then deterministic, version-controlled context becomes necessary. This is relevant in regulated environments, safety-critical systems, long-lived infrastructure, and security-sensitive deployments.

    Knowledge must outlive sessions and individuals: Projects with multi-year lifetimes accumulate architectural decisions, domain interpretations, and operational policy. If this knowledge is stored only in chat history, issue trackers, and institutional memory, it decays. The persistence model converts implicit knowledge into branchable, reviewable artifacts.

    Teams require shared cognitive authority: In collaborative environments, correctness depends on a stable answer to \"What does the system believe to be true?\" When this answer is derived from retrieval heuristics, authority shifts to ranking algorithms. When it is versioned and human-readable, authority remains with the team.

    Offline or air-gapped operation is required: Infrastructure-dependent memory systems cannot operate in classified environments, isolated networks, or disaster-recovery scenarios.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#92-when-not-to-use-this-model","level":3,"title":"9.2 When Not to Use This Model","text":"

    Zero-configuration personal workflows: For short-lived or exploratory tasks, the cost of explicit knowledge curation outweighs its benefits. Heuristic retrieval is sufficient when correctness is non-critical, outputs are disposable, and historical reconstruction is unnecessary.

    Maximum automatic recall from large corpora: Vector retrieval systems provide superior performance when the primary task is searching vast, weakly structured information spaces. The persistence model assumes that what matters can be decided and that this decision is valuable to record.

    Fully autonomous agent architectures: Agent runtimes that generate and discard state continuously, optimizing for local goal completion, do not benefit from a model that centers human ratification of knowledge.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#93-incremental-adoption","level":3,"title":"9.3 Incremental Adoption","text":"

    The transition does not require full system replacement. An incremental path:

    Step 1: Record decisions as versioned artifacts: Instead of allowing conclusions to remain in discussion threads, persist them in reviewable form with context, rationale, and consequences 4. This alone converts ephemeral reasoning into the cognitive state.

    Step 2: Make inclusion deterministic: Define explicit assembly rules. Retrieval may still exist, but it is no longer authoritative.

    Step 3: Move policy into cognitive state: When system behavior depends on stable constraints, encode those constraints as versioned knowledge. Behavior becomes reproducible.

    Step 4: Optimize assembly, not retrieval: Once the authoritative layer exists, performance improvements come from budgeting, caching, and structural refinement rather than from improving ranking heuristics.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#94-the-curation-cost","level":3,"title":"9.4 The Curation Cost","text":"

    The primary objection to this model is the cost of explicit knowledge curation. This cost is real. Writing a structured decision record takes longer than letting a chatbot auto-summarize a conversation. Maintaining a glossary requires discipline. Consolidating 75 learnings into 18 records requires judgment.

    The response is not that the cost is negligible but that it is amortized. A decision record written once is loaded hundreds of times. A learning captured today prevents repeated mistakes across all future sessions. The curation cost is paid once; the benefit compounds.

    The experience report provides rough order-of-magnitude numbers. Across 389 sessions over 33 days, curation activities (writing decision records, capturing learnings, updating the task list, consolidating entries) averaged approximately 3-5 minutes per session. In early sessions (days 1-7), before curated context existed, re-establishing context consumed approximately 10-15 minutes per session: re-explaining conventions, re-stating architectural constraints, re-deriving decisions that had been made but not persisted. By the final week (days 25-33), the re-explanation overhead had dropped to near zero: the agent loaded curated context and began productive work immediately.

    At ~12 sessions per day, the curation cost was roughly 35-60 minutes daily. The re-explanation cost in the first week was roughly 120-180 minutes daily. By the third week, that cost had fallen to under 15 minutes daily while the curation cost remained stable. The crossover (where cumulative curation cost was exceeded by cumulative time saved) occurred around day 10. These figures are approximate and derived from a single project with a small team already familiar with the model; the crossover point will vary with project complexity, team size, and curation discipline.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#10-future-work","level":2,"title":"10. Future Work","text":"

    Several directions are compatible with the model described here:

    Section-level deterministic budgeting: Current assembly operates at file granularity. Section-level budgeting would allow finer-grained control (including specific decision records while excluding others within the same file) without sacrificing determinism.

    Causal links between decisions: The experience report shows that decisions frequently reference earlier decisions (superseding, extending, or qualifying them). Formal causal links would enable traversal of the decision graph and automatic detection of orphaned or contradictory constraints.

    Content-addressed context caches: Five systems in our landscape analysis independently discovered that content hashing provides cache invalidation, integrity verification, and change detection. Applying content addressing to the assembly output would enable efficient cache reuse when the authoritative state has not changed.

    Conditional context inclusion: Five systems independently suggest that context entries could carry activation conditions (file patterns, task keywords, or explicit triggers) that control whether they are included in a given assembly. This would reduce the per-session budget cost of large knowledge bases without sacrificing determinism.

    Provenance metadata: Linking context entries to the sessions, decisions, or learnings that motivated them would strengthen the audit trail. Optional provenance fields on Markdown entries (session identifier, cause reference, motivation) would be lightweight and compatible with the existing file-based model.

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#11-conclusion","level":2,"title":"11. Conclusion","text":"

    AI-assisted development has treated context as a \"query result\" assembled at the moment of interaction, discarded at the session end. This paper identifies a complementary layer: the persistence of authoritative cognitive state as deterministic, version-controlled artifacts.

    The contribution is grounded in three sources of evidence. A landscape analysis of 17 systems reveals five categories of primitives and shows that no existing system provides the combination of human-readability, determinism, zero dependencies, and offline capability that the persistence layer requires. Six design invariants, validated by 56 independent rejection decisions, define the constraints of the design space. An experience report over 389 sessions and 33 days demonstrates compounding returns: later sessions start faster, decisions are not re-derived, and architectural reversals are captured with full context.

    The core claim is this: persistent cognitive state enables causal reasoning across time. A system built on this model can explain not only what is true, but why it became true and when it changed.

    When context is the state:

    • Reasoning is reproducible: the same authoritative state, budget, and policy produce the same delivery view.
    • Knowledge is auditable: decisions are traceable to explicit artifacts with context, rationale, and consequences.
    • Understanding compounds: each session's curation improves all subsequent sessions.

    The choice between retrieval-centric workflows and a persistence layer is not a matter of capability but of time horizon. Retrieval optimizes for relevance at the moment of interaction. Persistence optimizes for the durability of understanding across the lifetime of a project.

    🐸🖤 \"Gooood... let the deterministic context flow through the repository...\" - Kermit the Sidious, probably

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#appendix-a-representative-rejection-decisions","level":2,"title":"Appendix A: Representative Rejection Decisions","text":"

    The 56 rejection decisions referenced in Section 4 were cataloged across all 17 system analyses, grouped by the invariant they would violate. This appendix provides a representative sample (two per invariant) to illustrate the methodology.

    Invariant 1: Markdown-on-Filesystem (11 rejections): CrewAI's vector embedding storage was rejected because embeddings are not human-readable, not git-diff-friendly, and require external services. Kindex's knowledge graph as core primitive was rejected because it requires specialized commands to inspect content that could be a text file (kin show <id> vs. cat DECISIONS.md).

    Invariant 2: Zero Runtime Dependencies (13 rejections): Letta/MemGPT's PostgreSQL-backed architecture was rejected because it conflicts with local-first, no-database, single-binary operation. Pachyderm's Kubernetes-based distributed architecture was rejected as the antithesis of a single-binary design for a tool that manages text files.

    Invariant 3: Deterministic Assembly (6 rejections): LlamaIndex's embedding-based retrieval as the primary selection mechanism was rejected because it destroys determinism, requires an embedding model, and removes human judgment from the selection process. QubicDB's wall-clock-dependent scoring was rejected because it directly conflicts with the \"same inputs produce same output\" property.

    Invariant 4: Human Authority (6 rejections): Letta/MemGPT's agent self-modification of memory was rejected as fundamentally opposed to human-curated persistence. Claude Code's unstructured auto-memory (where the agent writes freeform notes) was rejected because structured files with defined schemas produce higher-quality persistent context than unconstrained agent output.

    Invariant 5: Local-First / Air-Gap Capable (7 rejections): Sweep's cloud-dependent architecture was rejected as fundamentally incompatible with the local-first, offline-capable model. LangGraph's managed cloud deployment was rejected because cloud dependencies for core functionality violate air-gap capability.

    Invariant 6: No Default Telemetry (4 rejections): Continue's telemetry-by-default (PostHog) was rejected because it contradicts the local-first, privacy-respecting trust model. CrewAI's global telemetry on import (Scarf tracking pixel) was rejected because it violates user trust and breaks air-gap capability.

    The remaining 9 rejections did not map to a specific invariant but were rejected on other architectural grounds: for example, Aider's full-file-content-in-context approach (which defeats token budgeting), AutoGen's multi-agent orchestration as core primitive (scope creep), and Claude Code's 30-day transcript retention limit (institutional knowledge should have no automatic expiration).

    ","path":["The Thesis"],"tags":[]},{"location":"thesis/#references","level":2,"title":"References","text":"

    1. Reproducible Builds Project, \"Reproducible Builds: Increasing the Integrity of Software Supply Chains\", 2017. https://reproducible-builds.org/docs/definition/ ↩↩↩

    2. S. McIntosh et al., \"The Impact of Build System Evolution on Software Quality\", ICSE, 2015. https://doi.org/10.1109/ICSE.2015.70 ↩

    3. C. Manning, P. Raghavan, H. Schütze, Introduction to Information Retrieval, Cambridge University Press, 2008. https://nlp.stanford.edu/IR-book/ ↩

    4. M. Nygard, \"Documenting Architecture Decisions\", Cognitect Blog, 2011. https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions ↩↩

    5. L. Torvalds et al., Git Internals - Git Objects (content-addressed storage concepts). https://git-scm.com/book/en/v2/Git-Internals-Git-Objects ↩

    6. Kief Morris, Infrastructure as Code, O'Reilly, 2016. ↩

    7. J. Kreps, \"The Log: What every software engineer should know about real-time data's unifying abstraction\", 2013. https://engineering.linkedin.com/distributed-systems/log ↩

    8. P. Hunt et al., \"ZooKeeper: Wait-free coordination for Internet-scale systems\", USENIX ATC, 2010. https://www.usenix.org/legacy/event/atc10/tech/full_papers/Hunt.pdf ↩

    ","path":["The Thesis"],"tags":[]}]} \ No newline at end of file diff --git a/site/security/agent-security/index.html b/site/security/agent-security/index.html index e7e06d000..4b5d14b7f 100644 --- a/site/security/agent-security/index.html +++ b/site/security/agent-security/index.html @@ -3097,6 +3097,8 @@ + + @@ -3252,6 +3254,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/security/index.html b/site/security/index.html index 77a146f2c..0274d8374 100644 --- a/site/security/index.html +++ b/site/security/index.html @@ -3097,6 +3097,8 @@ + + @@ -3252,6 +3254,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/security/reporting/index.html b/site/security/reporting/index.html index bff3ccfc8..4861ae928 100644 --- a/site/security/reporting/index.html +++ b/site/security/reporting/index.html @@ -3095,6 +3095,8 @@ + + @@ -3250,6 +3252,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/site/sitemap.xml b/site/sitemap.xml index fd064c98b..ef3b07cfb 100644 --- a/site/sitemap.xml +++ b/site/sitemap.xml @@ -204,6 +204,9 @@ https://ctx.ist/operations/integrations/ + + https://ctx.ist/operations/release/ + https://ctx.ist/operations/autonomous-loop/ diff --git a/site/thesis/index.html b/site/thesis/index.html index 3f1e9dc57..20f44cf0a 100644 --- a/site/thesis/index.html +++ b/site/thesis/index.html @@ -3657,6 +3657,8 @@ + + @@ -3812,6 +3814,36 @@ +
  • + + + + + + + + + + Cutting a Release + + + + + + + + +
    • + + + + + + + + + +
  • diff --git a/specs/ast-audit-tests.md b/specs/ast-audit-tests.md new file mode 100644 index 000000000..24f050746 --- /dev/null +++ b/specs/ast-audit-tests.md @@ -0,0 +1,123 @@ +--- +title: AST-based audit tests to replace lint-drift.sh +date: 2026-03-23 +status: ready +--- + +# AST-Based Audit Tests + +## Problem + +`hack/lint-drift.sh` uses regex/grep to detect code-level drift. This +approach has three structural weaknesses: + +1. **No type awareness** — it cannot distinguish `Use*` constants from + `DescKey*` constants, causing false positives (71 in the cmd↔YAML + check before the fix on 2026-03-23). +2. **Fragile exclusions** — when a constant moves from `token.go` to + `whitespace.go`, the exclusion glob breaks silently. +3. **Ceiling on detection** — checks that require understanding call + sites, import graphs, or type relationships are impossible in shell. + +## Solution + +Replace the five shell checks with Go tests using `go/ast` and +`go/packages`. The tests run as part of `go test ./...` — no separate +script, no separate CI step. + +## Package Location + +`internal/audit/` — a dedicated package for codebase-level invariant +tests. All files are `_test.go` so the package produces no binary +output and is not importable. + +## Check Migration + +### From lint-drift.sh (replace) + +| # | Shell check | Go test | Improvement | +|---|-------------|---------|-------------| +| 1 | Literal `"\n"` grep | `TestNoLiteralNewline` — walk AST, find string literals `== "\n"`, skip constant definition sites | No exclusion filenames to maintain | +| 2 | `cmd.Printf`/`cmd.PrintErrf` grep | `TestNoPrintfCalls` — find call expressions matching `cmd.Printf` / `cmd.PrintErrf` | Distinguishes calls from comments/strings | +| 3 | Magic dir strings in `filepath.Join` | `TestNoMagicDirStrings` — find `filepath.Join` calls with string literal args matching known `Dir*` constant values | Also catches `path.Join`, ignores test code properly | +| 4 | Literal `".md"` grep | `TestNoLiteralExtMarkdown` — same pattern as check 1 | Same benefit | +| 5 | DescKey ↔ YAML linkage | `TestDescKeyYAMLLinkage` — load `DescKey*` constants from each embed sub-package, load corresponding YAML, diff key sets | Type-aware, no regex on Go source | + +### New checks (not possible in shell) + +| Test | What it catches | +|------|----------------| +| `TestUseConstantsOnlyInCobraUse` | `Use*` constant appears only in cobra `Use:` struct field assignments | +| `TestDescKeyOnlyInLookupCalls` | `DescKey*` passed only to `assets.CommandDesc()` / `assets.FlagDesc()` / `desc.Text()` | +| `TestNoDeadConstants` | Constants defined in `embed/cmd`, `embed/flag`, `embed/text` but never referenced outside their definition | +| `TestNoWrongNamespaceLookup` | `TextDescKey` not passed to `CommandDesc()`, `FlagDescKey` not passed to `Text()`, etc. | +| `TestNoStringConcatPaths` | `filepath.Join` arguments do not contain `+` string concatenation | + +## Implementation Approach + +### AST scanning pattern + +Each test follows the same structure: + +```go +func TestNoLiteralNewline(t *testing.T) { + pkgs := loadPackages(t, "github.com/ActiveMemory/ctx/internal/...") + violations := []string{} + for _, pkg := range pkgs { + for _, file := range pkg.Syntax { + ast.Inspect(file, func(n ast.Node) bool { + // check node, append to violations + return true + }) + } + } + for _, v := range violations { + t.Error(v) + } +} +``` + +### Shared helpers + +- `loadPackages(t, pattern)` — wraps `go/packages.Load` with test + caching. Load once per test run via `sync.Once`. +- `isTestFile(filename)` — skip `_test.go` files. +- `isConstantDef(node)` — detect `const ( X = "..." )` so literal + checks can skip definition sites. +- `posString(fset, pos)` — format `file:line` for error messages. + +### Performance + +`go/packages.Load` with `NeedSyntax` for `internal/...` takes ~2-3s. +Cache the loaded packages across tests in the same package via +package-level `sync.Once`. Total overhead is comparable to the shell +script (~1s for grep vs ~3s for AST load + walk). + +## Migration Plan + +1. Create `internal/audit/` with `doc.go` and shared helpers +2. Port checks 1-4 (literal detection) as AST tests +3. Port check 5 (DescKey ↔ YAML linkage) as a type-aware test +4. Add new checks (dead constants, wrong namespace, Use-site validation) +5. Remove `hack/lint-drift.sh` and its call from `Makefile` +6. Update `Makefile` audit target to rely solely on `go test ./...` + +Steps 1-3 can ship together. Steps 4-5 can follow incrementally. + +## Non-Goals + +- Replacing `golangci-lint` — it handles standard Go linting well +- Replacing `go vet` — same +- Runtime checking — these are compile-time/test-time invariants only +- Checking non-Go files (YAML structure, Markdown formatting) — those + stay in shell or dedicated tools + +## Open Questions + +- Should the AST tests live in `internal/audit/` (dedicated) or be + colocated in `internal/config/embed/` (closer to the constants)? + Recommendation: `internal/audit/` because the checks span multiple + packages — they are codebase-level, not package-level. +- Should `hack/lint-drift.sh` be removed immediately or kept as a + fallback during migration? Recommendation: remove once all 5 checks + are ported — no parallel maintenance. diff --git a/zensical.toml b/zensical.toml index 4c4e2dd0c..9b89d9a26 100644 --- a/zensical.toml +++ b/zensical.toml @@ -112,6 +112,7 @@ nav = [ "operations/migration.md", "operations/upgrading.md", "operations/integrations.md", + "operations/release.md", "operations/autonomous-loop.md", ]}, { "Security" = [