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 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 (.context/.context.key) is gitignored and 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 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/.context.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 why¶

Read ctx's philosophy documents directly in the terminal, stripped of MkDocs artifacts so they display cleanly without a browser.

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