CLI Reference¶

Complete reference for all ctx commands.

Global Options¶

All commands support these flags:

Commands¶

ctx init¶

Initialize a new .context/ directory with template files.

ctx init [flags]

Flags:

What it creates:

• .context/ directory with all template files
• .claude/hooks/ with auto-save script (for Claude Code)
• .claude/settings.local.json with hook configuration
• 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 current context summary.

ctx status [flags]

Flags:

Output includes:

• 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 includes:

• 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
ctx add decision "Use PostgreSQL for primary database"

# Note a learning
ctx add learning "Vitest mocks must be hoisted"

# Add to specific section
ctx add learning "Always use --no-gpg-sign" --section "Git"

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

• 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 current codebase state.

ctx sync [flags]

Flags:

What it does:

• Scans codebase for structural changes
• Compares with ARCHITECTURE.md
• Checks DEPENDENCIES.md against package.json/go.mod
• Identifies stale or outdated context

Example:

ctx sync
ctx sync --dry-run

ctx compact¶

Consolidate and clean up context files.

ctx compact [flags]

Flags:

What it does:

• Moves completed tasks older than 7 days to archive
• Deduplicates learnings with similar content
• Removes empty sections

Example:

ctx compact
ctx compact --archive

ctx watch¶

Watch for AI output and auto-apply context updates.

ctx watch [flags]

Flags:

What it does:

Parses <context-update> XML commands from AI output and applies them to context files.

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

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

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

Exit Codes¶

Environment Variables¶

Configuration File¶

Optional .contextrc or context.config.js at project root:

module.exports = {
  contextDir: '.context',      // Context directory name
  tokenBudget: 8000,           // Default token budget
  priorityOrder: [             // File loading priority
    'TASKS.md',
    'DECISIONS.md',
    'CONVENTIONS.md',
  ],
  autoArchive: true,           // Auto-archive old items
  archiveAfterDays: 7,         // Days before archiving
};