Tools and Utilities

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

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>

ctx memory sync¶

Copy MEMORY.md to .context/memory/mirror.md. Archives the previous mirror before overwriting.

ctx memory sync [flags]

Flags:

Exit codes:

Example:

ctx memory sync
# Archived previous mirror to mirror-2026-03-05-143022.md
# Synced MEMORY.md -> .context/memory/mirror.md
#   Source: ~/.claude/projects/-home-user-project/memory/MEMORY.md
#   Lines: 47 (was 32)
#   New content: 15 lines since last sync

ctx memory sync --dry-run

ctx memory status¶

Show drift, timestamps, line counts, and archive count.

ctx memory status

Exit codes:

Example:

ctx memory status
# Memory Bridge Status
#   Source:      ~/.claude/projects/.../memory/MEMORY.md
#   Mirror:      .context/memory/mirror.md
#   Last sync:   2026-03-05 14:30 (2 hours ago)
#
#   MEMORY.md:  47 lines (modified since last sync)
#   Mirror:     32 lines
#   Drift:      detected (source is newer)
#   Archives:   3 snapshots in .context/memory/archive/

ctx memory diff¶

Show what changed in MEMORY.md since last sync.

ctx memory diff

Example:

ctx memory diff
# --- .context/memory/mirror.md (mirror)
# +++ ~/.claude/projects/.../memory/MEMORY.md (source)
# +- new learning: memory bridge works

No output when files are identical.

ctx memory publish¶

Push curated .context/ content into MEMORY.md so the agent sees it natively.

ctx memory publish [flags]

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:

Example:

ctx memory publish --dry-run
# Publishing .context/ -> MEMORY.md...
#   Budget: 80 lines
#   Published block:
#     5 pending tasks (from TASKS.md)
#     3 recent decisions (from DECISIONS.md)
#     5 key conventions (from CONVENTIONS.md)
#   Total: 42 lines (within 80-line budget)
# Dry run — no files written.

ctx memory publish              # Write to MEMORY.md
ctx memory publish --budget 40  # Tighter budget

ctx memory unpublish¶

Remove the ctx-managed marker block from MEMORY.md, preserving Claude-owned content.

ctx memory unpublish

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.

ctx memory import¶

Classify and promote entries from MEMORY.md into structured .context/ files.

ctx memory import [flags]

Each entry is classified by keyword heuristics:

Deduplication prevents re-importing the same entry across runs.

Flags:

Example:

ctx memory import --dry-run
# Scanning MEMORY.md for new entries...
#   Found 6 entries
#
#   -> "always use ctx from PATH"
#      Classified: CONVENTIONS.md (keywords: always use)
#
#   -> "decided to use heuristic classification over LLM-based"
#      Classified: DECISIONS.md (keywords: decided)
#
# Dry run — would import: 4 entries (1 convention, 1 decision, 1 learning, 1 task)
# Skipped: 2 entries (session notes/unclassified)

ctx memory import    # Actually write entries to .context/ files

ctx notify¶

Send fire-and-forget webhook notifications from skills, loops, and hooks.

ctx notify --event <name> [--session-id <id>] "message"

Flags:

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"
ctx notify -e nudge -s session-abc "Context checkpoint at prompt #20"

ctx notify setup¶

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

The encrypted file is safe to commit. The key (~/.ctx/.ctx.key) lives outside the project and is never committed.

ctx notify test¶

Send a test notification and report the HTTP response status.

ctx notify test

Payload format (JSON POST):

{
  "event": "loop",
  "message": "Loop completed after 5 iterations",
  "session_id": "abc123-...",
  "timestamp": "2026-02-22T14:30:00Z",
  "project": "ctx"
}

ctx deps¶

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 deps [flags]

Supported ecosystems:

Detection order: Go, Node.js, Python, Rust. First match wins.

Flags:

Examples:

# Auto-detect and show internal deps as Mermaid
ctx deps

# Include external dependencies
ctx deps --external

# Force Node.js detection (useful when multiple manifests exist)
ctx deps --type node

# Machine-readable output
ctx deps --format json

# Table format
ctx deps --format table

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.

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.

With --blobs, 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>
ctx pad import -              # read from stdin
ctx pad import --blobs <dir>  # import directory files as blobs

Arguments:

• file: Path to a text file, - for stdin, or a directory (with --blobs)

Flags:

Examples:

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

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 /path/to/other.key foreign.enc
ctx pad merge --dry-run pad-a.enc pad-b.md

ctx remind¶

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"
ctx remind <subcommand>

ctx remind add¶

Add a reminder. This is the default action: ctx remind "text" and ctx remind add "text" are equivalent.

ctx remind "refactor the swagger definitions"
ctx remind add "check CI after the deploy" --after 2026-02-25

Arguments:

• text: The reminder message (verbatim)

Flags:

Examples:

ctx remind "refactor the swagger definitions"
ctx remind "check CI after the deploy" --after 2026-02-25

ctx remind list¶

List all pending reminders. Date-gated reminders that aren't yet due are annotated with (after DATE, not yet due).

ctx remind list

Aliases: ls

ctx remind dismiss¶

Remove a reminder by ID, or remove all reminders with --all.

ctx remind dismiss <id>
ctx remind dismiss --all

Arguments:

• id: Reminder ID (shown in list output)

Flags:

Aliases: rm

Examples:

ctx remind dismiss 3
ctx remind dismiss --all

ctx pause¶

Pause all context nudge and reminder hooks for the current session. Security hooks (dangerous command blocking) and housekeeping hooks still fire.

ctx pause [flags]

Flags:

Example:

# Pause hooks for a quick investigation
ctx pause

# Resume when ready
ctx resume

See also: Pausing Context Hooks

ctx resume¶

Resume context hooks after a pause. Silent no-op if not paused.

ctx resume [flags]

Flags:

Example:

ctx resume

See also: Pausing Context Hooks

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

Site management commands for the ctx.ist static site.

ctx site <subcommand>

ctx site feed¶

Generate an Atom 1.0 feed from finalized blog posts in docs/blog/.

ctx site feed [flags]

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:

Output:

Generated site/feed.xml (21 entries)

Skipped:
  2026-02-25-the-homework-problem.md: not finalized

Warnings:
  2026-02-09-defense-in-depth.md: no summary paragraph found

Three buckets: included (count), skipped (with reason), warnings (included but degraded). exit 0 always: warnings inform but do not block.

Frontmatter requirements:

Examples:

ctx site feed                                # Generate site/feed.xml
ctx site feed --out /tmp/feed.xml            # Custom output path
ctx site feed --base-url https://example.com # Custom base URL
make site-feed                               # Makefile shortcut
make site                                    # Builds site + feed

ctx why¶

Read ctx's philosophy documents directly in the terminal.

ctx why [DOCUMENT]

Documents:

Usage:

# Interactive numbered menu
ctx why

# Show a specific document
ctx why manifesto
ctx why about
ctx why invariants

# Pipe to a pager
ctx why manifesto | less