Common Workflows

The commands below cover what you'll use most often:

• recording context,
• checking health,
• browsing history,
• and running loops.

Each section is a self-contained snippet you can copy into your terminal.

For deeper, step-by-step guides, see Recipes.

Track Context¶

# Add a task
ctx add task "Implement user authentication"

# Record a decision (full ADR fields required)
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
ctx add learning "Mock functions must be hoisted in Jest" \
  --context "Tests failed with undefined mock errors" \
  --lesson "Jest hoists mock calls to top of file" \
  --application "Place jest.mock() before imports"

# Mark task complete
ctx complete "user auth"

Leave a Reminder for Next Session¶

Drop a note that surfaces automatically at the start of your next session:

# Leave a reminder
ctx remind "refactor the swagger definitions"

# Date-gated: don't surface until a specific date
ctx remind "check CI after the deploy" --after 2026-02-25

# List pending reminders
ctx remind list

# Dismiss a reminder by ID
ctx remind dismiss 1

Reminders are relayed verbatim at session start by the check-reminders hook and repeat every session until you dismiss them.

See Session Reminders for the full recipe.

Check Context Health¶

# Detect stale paths, missing files, potential secrets
ctx drift

# See full context summary
ctx status

Browse Session History¶

List and search past AI sessions from the terminal:

ctx recall list --limit 5

Journal Site¶

Export session transcripts to a browsable static site with search, navigation, and topic indices.

If you don't have it on your system, install zensical once with pipx:

# One-time setup
pipx install zensical

Export and Serve¶

Then, export and serve:

# Export all sessions to .context/journal/ (only new files)
ctx recall export --all

# Generate and serve the journal site
ctx journal site --serve

Open http://localhost:8000 to browse.

To update after new sessions, run the same two commands again.

Safe By Default¶

ctx recall export --all is safe by default:

• It only exports new sessions and skips existing files.
• Locked entries (via ctx recall lock) are always skipped by both export and enrichment skills.
• If you add locked: true to frontmatter during enrichment, run ctx recall sync to propagate the lock state to .state.json.

Re-Exporting Existing Files¶

Here is how you regenerate existing files.

Backup your .context folder before regeneration, as this is a potentially destructive action.

To re-export journal files, you need to explicitly opt-in using the --regenerate flag:

See Session Journal for the full pipeline including normalization and enrichment.

Scratchpad¶

Store short, sensitive one-liners in an encrypted scratchpad that travels with the project:

# Write a note
ctx pad set db-password "postgres://user:pass@localhost/mydb"

# Read it back
ctx pad get db-password

# List all keys
ctx pad list

The scratchpad is encrypted with a key stored at ~/.ctx/.ctx.key (outside the project, never committed).

See Scratchpad for details.

Run an Autonomous Loop¶

Generate a script that iterates an AI agent until a completion signal is detected:

ctx loop
chmod +x loop.sh
./loop.sh

See Autonomous Loops for configuration and advanced usage.

Agent Session Start¶

The first thing an AI agent should do at session start is discover where context lives:

ctx system bootstrap

This prints the resolved context directory, the files in it, and the operating rules. The CLAUDE.md template instructs the agent to run this automatically. See CLI Reference: bootstrap.

The Two Skills You Should Always Use¶

Using /ctx-remember at session start and /ctx-wrap-up at session end are the highest-value skills in the entire catalog:

# session begins:
/ctx-remember
... do work ...
# before closing the session:
/ctx-wrap-up

Let's provide some context, because this is important:

Although the agent will eventually discover your context through CLAUDE.md → AGENT_PLAYBOOK.md, /ctx-remember hydrates the full context up front (tasks, decisions, recent sessions) so the agent starts informed rather than piecing things together over several turns.

/ctx-wrap-up is the other half: A structured review that captures learnings, decisions, and tasks before you close the window.

Hooks like check-persistence remind you (the user) mid-session that context hasn't been saved in a while, but they don't trigger persistence automatically: You still have to act. Also, a CTRL+C can end things at any moment with no reliable "before session end" event.

In short, /ctx-wrap-up is the deliberate checkpoint that makes sure nothing slips through. And /ctx-remember it its mirror skill to be used at session start.

See Session Ceremonies for the full workflow.

CLI Commands vs. AI Skills¶

Most ctx operations come in two flavors: a CLI command you run in your terminal and an AI skill (slash command) you invoke inside your coding assistant.

Commands and skills are not interchangeable: Each has a distinct role.

Paired Commands¶

These have both a CLI and a skill counterpart. Use the CLI for quick, deterministic checks; use the skill when you need the agent's judgment.

AI-Only Skills¶

These have no CLI equivalent. They require the agent's reasoning.

CLI-Only Commands¶

These are infrastructure: used in scripts, CI, or one-time setup.

Next Up: Context Files →: what each .context/ file does and how to use it

See Also:

• Recipes: targeted how-to guides for specific tasks
• Knowledge Capture: patterns for recording decisions, learnings, and conventions
• Context Health: keeping your .context/ accurate and drift-free
• Session Archaeology: digging into past sessions
• Task Management: tracking and completing work items