Skip to content

Common Workflows

ctx

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"

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.

The ctx journal command requires zensical (Python >= 3.10).

zensical is a Python-based static site generator from the Material for MkDocs team.

(why zensical?).

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

# One-time setup
pipx install zensical

Avoid pip install zensical

pip install often fails: For example, on macOS, system Python installs a non-functional stub (zensical requires Python >= 3.10), and Homebrew Python blocks system-wide installs (PEP 668).

pipx creates an isolated environment with the correct Python version automatically.

Then, export and serve:

# Export all sessions to .context/journal/
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; recall export preserves existing YAML frontmatter and only updates conversation content.

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

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.

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

See Also: