CLI Reference

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/hooks/ with auto-save and enforcement scripts (for Claude Code)
• .claude/commands/ with ctx slash command definitions
• .claude/settings.local.json with hook configuration and pre-approved ctx permissions
• CLAUDE.md with bootstrap instructions (or merges into existing)

Example:

# Standard initialization
ctx init

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

# Force overwrite existing
ctx init --force

# Merge into existing CLAUDE.md
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:

Output:

• Read order for context files
• Constitution rules (never truncated)
• Current tasks
• Key conventions
• Recent decisions

Example:

# Default (8000 tokens, markdown)
ctx agent

# Custom budget
ctx agent --budget 4000

# JSON format
ctx agent --format json

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)

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
• Deduplicates the "learning"s with similar content
• Removes empty sections

ctx compact [flags]

Flags:

Example:

ctx compact
ctx compact --archive
ctx compact --no-auto-save

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 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 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 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 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 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. Existing files are skipped by default to preserve your edits.

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 all sessions
ctx recall export --all --force   # Overwrite existing exports

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:

pip 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 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:

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

Supported tools:

Example:

ctx hook claude-code
ctx hook cursor
ctx hook aider

ctx session¶

Manage session snapshots.

ctx session save¶

Save the current context snapshot.

ctx session save [topic] [flags]

Flags:

Example:

ctx session save
ctx session save "feature-auth"
ctx session save "bugfix" --type bugfix

ctx session list¶

List saved sessions.

ctx session list [flags]

Flags:

Output: Table of sessions with index, date, topic, and type.

Example:

ctx session list
ctx session list --limit 5

ctx session load¶

Load and display a previous session.

ctx session load <index|date|topic>

Arguments:

• index: Numeric index from session list
• date: Date pattern (e.g., 2026-01-21)
• topic: Topic keyword match

Example:

ctx session load 1           # by index
ctx session load 2026-01-21  # by date
ctx session load auth        # by topic

ctx session parse¶

Parse JSONL transcript to readable markdown.

ctx session parse <file> [flags]

Flags:

Example:

ctx session parse ~/.claude/projects/.../transcript.jsonl
ctx session parse transcript.jsonl --extract
ctx session parse transcript.jsonl -o conversation.md

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.

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

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

All settings are optional. Missing values use defaults.