ctx CLI

ctx CLI¶

This is a complete reference for all ctx commands.

Global Options¶

All commands support these flags:

The NO_COLOR=1 environment variable also disables colored output.

Commands¶

ctx init¶

Initialize a new .context/ directory with template files.

ctx init [flags]

Flags:

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)
ctx init

# Autonomous mode (agent works independently)
ctx init --ralph

# Minimal setup (just core files)
ctx init --minimal

# Force overwrite existing
ctx init --force

# Merge into existing files
ctx init --merge

ctx status¶

Show the current context summary.

ctx status [flags]

Flags:

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
ctx status --json
ctx status --verbose

ctx agent¶

Print an AI-ready context packet optimized for LLM consumption.

ctx agent [flags]

Flags:

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:

Example:

# Default (8000 tokens, markdown)
ctx agent

# Smaller packet for tight context windows
ctx agent --budget 4000

# JSON format for programmatic use
ctx agent --format json

# Pipe to file
ctx agent --budget 4000 > context.md

# With cooldown (hooks/automation — requires --session)
ctx agent --session $PPID

Use case: Copy-paste into AI chat, pipe to system prompt, or use in hooks.

ctx load¶

Load and display assembled context as AI would see it.

ctx load [flags]

Flags:

Example:

ctx load
ctx load --budget 16000
ctx load --raw

ctx add¶

Add a new item to a context file.

ctx add <type> <content> [flags]

Types:

Flags:

Examples:

# Add a task
ctx add task "Implement user authentication"
ctx add task "Fix login bug" --priority high

# Record a decision (requires all ADR—Architectural Decision Record—fields)
ctx add decision "Use PostgreSQL for primary database" \
  --context "Need a reliable database for production" \
  --rationale "PostgreSQL offers ACID compliance and JSON support" \
  --consequences "Team needs PostgreSQL training"

# Note a learning (requires context, lesson, and application)
ctx add learning "Vitest mocks must be hoisted" \
  --context "Tests failed with undefined mock errors" \
  --lesson "Vitest hoists vi.mock() calls to top of file" \
  --application "Always place vi.mock() before imports in test files"

# Add to specific section
ctx add convention "Use kebab-case for filenames" --section "Naming"

ctx complete¶

Mark a task as completed.

ctx complete <task-id-or-text>

Arguments:

• task-id-or-text: Task number or partial text match

Examples:

# By text (partial match)
ctx complete "user auth"

# By task number
ctx complete 3

ctx drift¶

Detect stale or invalid context.

ctx drift [flags]

Flags:

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)
• Entry count — warns when LEARNINGS.md or DECISIONS.md exceed configurable thresholds (default: 30 learnings, 20 decisions). Configure via .contextrc:

  entry_count_learnings: 30   # warn above this (0 = disable)
  entry_count_decisions: 20   # warn above this (0 = disable)
  

Example:

ctx drift
ctx drift --json
ctx drift --fix

Exit codes:

ctx sync¶

Reconcile context with the current codebase state.

ctx sync [flags]

Flags:

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
ctx sync --dry-run

ctx compact¶

Consolidate and clean up context files.

• Moves completed tasks older than 7 days to the archive
• Archives old decisions and learnings (older than 90 days by default)
• Removes empty sections

ctx compact [flags]

Flags:

When --archive is enabled (or auto_archive: true in .contextrc), compact also archives decisions and learnings older than archive_knowledge_after_days (default 90), keeping the most recent archive_keep_recent entries (default 5).

Example:

ctx compact
ctx compact --archive

ctx completion¶

Generate shell autocompletion scripts.

ctx completion <shell>

Subcommands¶

Installation¶

# Add to ~/.bashrc
source <(ctx completion bash)

# Add to ~/.zshrc
source <(ctx completion zsh)

ctx completion fish | source
# Or save to completions directory
ctx completion fish > ~/.config/fish/completions/ctx.fish

ctx tasks¶

Manage task archival and snapshots.

ctx tasks <subcommand>

ctx tasks archive¶

Move completed tasks from TASKS.md to a timestamped archive file.

ctx tasks archive [flags]

Flags:

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 tasks archive
ctx tasks archive --dry-run

ctx tasks snapshot¶

Create a point-in-time snapshot of TASKS.md without modifying the original.

ctx tasks snapshot [name]

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 tasks snapshot
ctx tasks snapshot "before-refactor"

ctx permissions¶

Manage Claude Code permission snapshots.

ctx permissions <subcommand>

ctx permissions snapshot¶

Save .claude/settings.local.json as the golden image.

ctx permissions snapshot

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 permissions snapshot
# Saved golden image: .claude/settings.golden.json

ctx permissions restore¶

Replace settings.local.json with the golden image.

ctx permissions restore

Prints a diff of dropped (session-accumulated) and restored permissions. No-op if the files already match.

Example:

ctx permissions restore
# Dropped 3 session permission(s):
#   - Bash(cat /tmp/debug.log:*)
#   - Bash(rm /tmp/test-*:*)
#   - Bash(curl https://example.com:*)
# Restored from golden image.

ctx decisions¶

Manage the DECISIONS.md file.

ctx decisions <subcommand>

ctx decisions reindex¶

Regenerate the quick-reference index at the top of DECISIONS.md.

ctx decisions reindex

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 decisions reindex
# ✓ Index regenerated with 12 entries

ctx decisions archive¶

Archive old or superseded decisions from DECISIONS.md to .context/archive/.

ctx decisions archive [flags]

Flags:

Entries are archived if they are older than --days or marked as superseded (body contains ~~Superseded). The most recent --keep entries are always preserved regardless of age.

Example:

ctx decisions archive                # Archive old decisions (90+ days)
ctx decisions archive --dry-run      # Preview what would be archived
ctx decisions archive --days 30      # Lower the threshold
ctx decisions archive --all --keep 3 # Archive everything except 3 newest

ctx learnings¶

Manage the LEARNINGS.md file.

ctx learnings <subcommand>

ctx learnings reindex¶

Regenerate the quick-reference index at the top of LEARNINGS.md.

ctx learnings reindex

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 learnings reindex
# ✓ Index regenerated with 8 entries

ctx learnings archive¶

Archive old or superseded learnings from LEARNINGS.md to .context/archive/.

ctx learnings archive [flags]

Flags:

Entries are archived if they are older than --days or marked as superseded (body contains ~~Superseded). The most recent --keep entries are always preserved regardless of age.

Example:

ctx learnings archive                # Archive old learnings (90+ days)
ctx learnings archive --dry-run      # Preview what would be archived
ctx learnings archive --days 30      # Lower the threshold
ctx learnings archive --all --keep 3 # Archive everything except 3 newest

ctx recall¶

Browse and search AI session history from Claude Code and other tools.

ctx recall <subcommand>

ctx recall list¶

List all parsed sessions.

ctx recall list [flags]

Flags:

Sessions are sorted by date (newest first) and display slug, project, start time, duration, turn count, and token usage.

Example:

ctx recall list
ctx recall list --limit 5
ctx recall list --project ctx
ctx recall list --tool claude-code

ctx recall show¶

Show details of a specific session.

ctx recall show [session-id] [flags]

Flags:

The session ID can be a full UUID, partial match, or session slug name.

Example:

ctx recall show abc123
ctx recall show gleaming-wobbling-sutherland
ctx recall show --latest
ctx recall show --latest --full

ctx recall export¶

Export sessions to editable journal files in .context/journal/.

ctx recall export [session-id] [flags]

Flags:

Exported files include session metadata, tool usage summary, and the full conversation. When re-exporting, YAML frontmatter from enrichment (topics, type, outcome, etc.) is preserved by default; only the conversation content is regenerated.

The journal/ directory should be gitignored (like sessions/) since it contains raw conversation data.

Example:

ctx recall export abc123                # Export one session
ctx recall export --all                 # Export/update all sessions
ctx recall export --all --skip-existing # Skip files that already exist
ctx recall export --all --force         # Overwrite completely (lose frontmatter)

ctx journal¶

Analyze and synthesize exported session files.

ctx journal <subcommand>

ctx journal site¶

Generate a static site from journal entries in .context/journal/.

ctx journal site [flags]

Flags:

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

Example:

ctx journal site                    # Generate in .context/journal-site/
ctx journal site --output ~/public  # Custom output directory
ctx journal site --build            # Generate and build HTML
ctx journal site --serve            # Generate and serve locally

ctx journal obsidian¶

Generate an Obsidian vault from journal entries in .context/journal/.

ctx journal obsidian [flags]

Flags:

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/
ctx journal obsidian --output ~/vaults/ctx    # Custom output directory

ctx journal mark¶

Update processing state for a journal entry. Records the current date in .context/journal/.state.json.

ctx journal mark <filename> <stage>

Stages: exported, enriched, normalized, fences_verified

Example:

ctx journal mark 2026-01-21-session-abc12345.md enriched
ctx journal mark 2026-01-21-session-abc12345.md normalized
ctx journal mark --check 2026-01-21-session-abc12345.md fences_verified

ctx serve¶

Serve a static site locally via zensical.

ctx serve [directory]

If no directory is specified, serves the journal site (.context/journal-site).

Requires zensical to be installed:

pipx install zensical

Example:

ctx serve                           # Serve journal site
ctx serve .context/journal-site     # Serve specific directory
ctx serve ./docs                    # Serve docs folder

ctx watch¶

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]

Flags:

Example:

# Watch stdin
ai-tool | ctx watch

# Watch a log file
ctx watch --log /path/to/ai-output.log

# Preview without applying
ctx watch --dry-run

ctx hook¶

Generate AI tool integration configuration.

ctx hook <tool> [flags]

Flags:

Supported tools:

Example:

# Print hook instructions to stdout
ctx hook cursor
ctx hook aider

# Generate and write .github/copilot-instructions.md
ctx hook copilot --write

ctx loop¶

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]

Flags:

Example:

# Generate loop.sh for Claude Code
ctx loop

# Generate for Aider with custom prompt
ctx loop --tool aider --prompt TASKS.md

# Limit to 10 iterations
ctx loop --max-iterations 10

# Output to custom file
ctx loop -o my-loop.sh

Usage:

# Generate and run the loop
ctx loop
chmod +x loop.sh
./loop.sh

See Autonomous Loops for detailed workflow documentation.

ctx pad¶

Encrypted scratchpad for sensitive one-liners that travel with the project.

When invoked without a subcommand, lists all entries.

ctx pad
ctx pad <subcommand>

ctx pad add¶

Append a new entry to the scratchpad.

ctx pad add <text>
ctx pad add <label> --file <path>

Flags:

Examples:

ctx pad add "DATABASE_URL=postgres://user:pass@host/db"
ctx pad add "deploy config" --file ./deploy.yaml

ctx pad show¶

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>
ctx pad show <n> --out <path>

Arguments:

• n: 1-based entry number

Flags:

Examples:

ctx pad show 3
ctx pad show 2 --out ./recovered.yaml

ctx pad rm¶

Remove an entry by number.

ctx pad rm <n>

Arguments:

• n: 1-based entry number

ctx pad edit¶

Replace, append to, or prepend to an entry.

ctx pad edit <n> [text]

Arguments:

• n: 1-based entry number
• text: Replacement text (mutually exclusive with --append/--prepend)

Flags:

Examples:

ctx pad edit 2 "new text"
ctx pad edit 2 --append " suffix"
ctx pad edit 2 --prepend "prefix "
ctx pad edit 1 --file ./v2.yaml
ctx pad edit 1 --label "new name"

ctx pad mv¶

Move an entry from one position to another.

ctx pad mv <from> <to>

Arguments:

• from: Source position (1-based)
• to: Destination position (1-based)

ctx pad resolve¶

Show both sides of a merge conflict in the encrypted scratchpad.

ctx pad resolve

ctx pad import¶

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.

ctx pad import <file>
ctx pad import -          # read from stdin

Arguments:

• file: Path to a text file, or - for stdin

Examples:

ctx pad import notes.txt
grep TODO *.go | ctx pad import -

ctx pad export¶

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]

Arguments:

• dir: Target directory (default: current directory)

Flags:

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
ctx pad export --dry-run
ctx pad export --force ./backup

ctx pad merge¶

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...

Arguments:

• FILE...: One or more scratchpad files to merge (encrypted or plaintext)

Flags:

Examples:

ctx pad merge worktree/.context/scratchpad.enc
ctx pad merge notes.md backup.enc
ctx pad merge --key /other/.scratchpad.key foreign.enc
ctx pad merge --dry-run pad-a.enc pad-b.md

Exit Codes¶

Environment Variables¶

Configuration File¶

Optional .contextrc (YAML format) at project root:

# .contextrc
context_dir: .context                # Context directory name
token_budget: 8000                   # Default token budget
priority_order:                      # File loading priority
  - TASKS.md
  - DECISIONS.md
  - CONVENTIONS.md
auto_archive: true                   # Auto-archive old items
archive_after_days: 7                # Days before archiving tasks
archive_knowledge_after_days: 90     # Days before archiving decisions/learnings
archive_keep_recent: 5               # Recent entries to keep when archiving
scratchpad_encrypt: true             # Encrypt scratchpad (default: true)
allow_outside_cwd: false             # Skip boundary check (default: false)
entry_count_learnings: 30            # Drift warning threshold (0 = disable)
entry_count_decisions: 20            # Drift warning threshold (0 = disable)

Priority order: CLI flags > Environment variables > .contextrc > Defaults

All settings are optional. Missing values use defaults.