Setting Up ctx Across AI Tools

The Problem¶

You have installed ctx and want to set it up with your AI coding assistant so that context persists across sessions. Different tools have different integration depths. For example:

• Claude Code supports native hooks that load and save context automatically
• Cursor injects context via its system prompt
• Aider reads context files through its --read flag

This recipe walks through the complete setup for each tool, from initialization through verification, so you end up with a working memory layer regardless of which AI tool you use.

cd your-project
ctx init                              # creates .context/ and seeds permissions
source <(ctx completion zsh)          # shell completion (or bash/fish)
# For other tools:
ctx hook cursor                       # or: aider, copilot, windsurf

Commands and Skills Used¶

The Workflow¶

Step 1: Initialize ctx¶

Run ctx init in your project root. This creates the .context/ directory with all template files and seeds ctx permissions in settings.local.json.

cd your-project
ctx init

This produces the following structure:

.context/
  CONSTITUTION.md     # Hard rules the AI must never violate
  TASKS.md            # Current and planned work
  CONVENTIONS.md      # Code patterns and standards
  ARCHITECTURE.md     # System overview
  DECISIONS.md        # Architectural decisions with rationale
  LEARNINGS.md        # Lessons learned, gotchas, tips
  GLOSSARY.md         # Domain terms and abbreviations
  AGENT_PLAYBOOK.md   # How AI tools should use this system

For Claude Code, install the ctx plugin to get hooks and skills:

claude /plugin marketplace add ActiveMemory/ctx
claude /plugin install ctx@activememory-ctx

If you only need the core files (useful for lightweight setups with Cursor or Copilot), use the --minimal flag:

ctx init --minimal

This creates only TASKS.md, DECISIONS.md, and CONSTITUTION.md.

Step 2: Generate Tool-Specific Hooks¶

If you are using a tool other than Claude Code (which is configured automatically by ctx init), generate its integration configuration:

# For Cursor
ctx hook cursor

# For Aider
ctx hook aider

# For GitHub Copilot
ctx hook copilot

# For Windsurf
ctx hook windsurf

Each command prints the configuration you need. How you apply it depends on the tool.

Cursor: Add the system prompt snippet to .cursor/settings.json:

{
  "ai.systemPrompt": "Read .context/TASKS.md and .context/CONVENTIONS.md before responding. Follow rules in .context/CONSTITUTION.md."
}

Context files appear in Cursor's file tree. You can also paste a context packet directly into chat:

ctx agent --budget 4000 | xclip    # Linux
ctx agent --budget 4000 | pbcopy   # macOS

Aider: Create .aider.conf.yml so context files are loaded on every session:

read:
  - .context/CONSTITUTION.md
  - .context/TASKS.md
  - .context/CONVENTIONS.md
  - .context/DECISIONS.md

Then start Aider normally:

aider

Or specify files on the command line:

aider --read .context/TASKS.md --read .context/CONVENTIONS.md

Step 3: Set Up Shell Completion¶

Shell completion lets you tab-complete ctx subcommands and flags, which is especially useful while learning the CLI.

# Bash (add to ~/.bashrc)
source <(ctx completion bash)

# Zsh (add to ~/.zshrc)
source <(ctx completion zsh)

# Fish
ctx completion fish > ~/.config/fish/completions/ctx.fish

After sourcing, typing ctx a<TAB> completes to ctx agent, and ctx recall <TAB> shows list, show, and export.

Step 4: Verify the Setup Works¶

Start a fresh session in your AI tool and ask:

"Do you remember?"

A correctly configured tool responds with specific context: current tasks from TASKS.md, recent decisions, and previous session topics. It should not say "I don't have memory" or "Let me search for files."

This question checks the passive side of memory. A properly set-up agent is also proactive: it treats context maintenance as part of its job.

• After a debugging session, it offers to save a learning
• After a trade-off discussion, it asks whether to record the decision
• After completing a task, it suggests follow-up items

The "do you remember?" check verifies both halves: recall and responsibility.

For example, after resolving a tricky bug, a proactive agent might say:

That Redis timeout issue was subtle. Want me to save this as a learning so we don't hit it again?

If you see behavior like this, the setup is working end to end.

In Claude Code, you can also invoke the /ctx-status skill:

/ctx-status

This prints a summary of all context files, token counts, and recent activity, confirming that hooks are loading context.

If context is not loading, check the basics:

Step 5: Enable Watch Mode for Non-Native Tools¶

Tools like Aider, Copilot, and Windsurf do not support native hooks for saving context automatically. For these, run ctx watch alongside your AI tool.

Pipe the AI tool's output through ctx watch:

# Terminal 1: Run Aider with output logged
aider 2>&1 | tee /tmp/aider.log

# Terminal 2: Watch the log for context updates
ctx watch --log /tmp/aider.log

Or for any generic tool:

your-ai-tool 2>&1 | tee /tmp/ai.log &
ctx watch --log /tmp/ai.log

When the AI emits structured update commands, ctx watch parses and applies them automatically:

<context-update type="learning"
  context="Debugging rate limiter"
  lesson="Redis MULTI/EXEC does not roll back on error"
  application="Wrap rate-limit checks in Lua scripts instead"
>Redis Transaction Behavior</context-update>

To preview changes without modifying files:

ctx watch --dry-run --log /tmp/ai.log

Step 6: Export Session Transcripts (Optional)¶

If you want to browse past session transcripts, export them to the journal:

ctx recall export --all

This converts raw session data into editable Markdown files in .context/journal/. You can then enrich them with metadata using /ctx-journal-enrich-all inside your AI assistant.

Putting It Together¶

Here is the condensed setup for all three tools:

# -- Common (run once per project) --
cd your-project
ctx init
source <(ctx completion zsh)       # or bash/fish

# -- Claude Code (automatic, just verify) --
# Start Claude Code, then ask: "Do you remember?"

# -- Cursor --
ctx hook cursor
# Add the system prompt to .cursor/settings.json
# Paste context: ctx agent --budget 4000 | pbcopy

# -- Aider --
ctx hook aider
# Create .aider.conf.yml with read: paths
# Run watch mode alongside: ctx watch --log /tmp/aider.log

# -- Verify any tool --
# Ask your AI: "Do you remember?"
# Expect: specific tasks, decisions, recent context

Tips¶

• Start with ctx init (not --minimal) for your first project. The full template set gives the agent more to work with, and you can always delete files later.
• For Claude Code, the token budget is configured in the plugin's hooks.json. To customize, adjust the --budget flag in the ctx agent hook command.
• The --session $PPID flag isolates cooldowns per Claude Code process, so parallel sessions do not suppress each other.
• Commit your .context/ directory to version control. Several ctx features (journals, changelogs, blog generation) rely on git history.
• For Cursor and Copilot, keep CONVENTIONS.md visible. These tools treat open files as higher-priority context.
• Run ctx drift periodically to catch stale references before they confuse the agent.
• The agent playbook instructs the agent to persist context at natural milestones (completed tasks, decisions, gotchas). In practice, this works best when you reinforce the habit: a quick "anything worth saving?" after a debugging session goes a long way.

Next Up¶

The Complete Session: Walk through a full ctx session from start to finish.

See Also¶

• The Complete Session: full session lifecycle recipe
• CLI Reference: all commands and flags
• Integrations: detailed per-tool integration docs