Setup 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.
• Codex has the same hook contract, delivered as a plugin or project-local files.
• 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.

TL;DR¶

cd your-project
ctx init                      # creates .context/
source <(ctx completion zsh)  # shell completion (or bash/fish)

# ## Claude Code (automatic after plugin install) ##
claude /plugin marketplace add ActiveMemory/ctx
claude /plugin install ctx@activememory-ctx

# ## Codex (plugin route; or: ctx setup codex --write) ##
codex plugin marketplace add ActiveMemory/ctx
codex plugin add ctx@activememory-ctx
# then in codex: /hooks, trust the ctx entries

# ## OpenCode ##
ctx setup opencode --write && ctx init

# ## Pi ##
ctx setup pi --write && ctx init

# ## Cursor / Aider / Copilot / Windsurf ##
ctx setup cursor # or: aider, copilot, windsurf

# ## Companion tools (highly recommended) ##
gitnexus analyze              # code knowledge graph
# Add Gemini Search MCP server for grounded web search

Run subsequent ctx commands from the project root; ctx always reads $PWD/.context/.

Create a .ctxrc in your project root to configure token budgets, context directory, drift thresholds, and more.

Then start your AI tool and ask: "Do you remember?"

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), 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 setup cursor

# For Aider
ctx setup aider

# For GitHub Copilot
ctx setup copilot

# For Windsurf
ctx setup windsurf

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

Claude Code¶

No action needed. Just install ctx from the Marketplace as ActiveMemory/ctx.

Codex¶

Install the ctx plugin once (every project gets hooks, skills, and the MCP server):

codex plugin marketplace add ActiveMemory/ctx
codex plugin add ctx@activememory-ctx

Or keep everything inside the repository (teams, CI, codex exec):

ctx setup codex --write && ctx init

Either way, start codex, run /hooks, and trust the ctx entries; Codex does not run untrusted hooks. Project-local files also require the project to be trusted in ~/.codex/config.toml. See ctx for Codex for the full walkthrough.

OpenCode¶

Run the one-liner from the project root:

ctx setup opencode --write && ctx init

This deploys a lifecycle plugin, slash command skills, AGENTS.md, and registers the ctx MCP server globally. See ctx for OpenCode for full details.

Pi¶

Run the one-liner from the project root:

ctx setup pi --write && ctx init

This deploys a lifecycle extension (Pi has no built-in MCP by design), Agent-Skills-standard skills, and AGENTS.md. Project-local .pi/ files load only after the project is trusted. See ctx for Pi for full details.

VS Code¶

Install the ctx extension from the VS Code Marketplace (publisher: activememory). Then, from your project root:

ctx init

Open Copilot Chat and type @ctx /init to verify. The extension auto-downloads the ctx CLI if it isn't on PATH. See ctx for VS Code for full details.

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 journal <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 (in Codex, the same skill is $ctx-status):

/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: Import Session Transcripts (Optional)¶

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

ctx journal import --all

This converts raw session data into editable Markdown files in .context/journal/. Claude Code and Codex transcripts are discovered automatically (~/.claude/projects/ and $CODEX_HOME/sessions/). You can then enrich them with metadata using /ctx-journal-enrich-all inside your AI assistant.

Putting It All Together¶

Here is the condensed setup for each tool:

# ## 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?"

# ## Codex ##
codex plugin marketplace add ActiveMemory/ctx && codex plugin add ctx@activememory-ctx
# Start codex, run /hooks and trust the ctx entries, then ask: "Do you remember?"

# ## OpenCode ##
ctx setup opencode --write
# Start OpenCode, then ask: "Do you remember?"

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

# ## Aider ##
ctx setup 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.

Companion Tools (Highly Recommended)¶

ctx skills can leverage external MCP servers for web search and code intelligence. ctx works without them, but they significantly improve agent behavior across sessions. The investment is small and the benefits compound. Skills like /ctx-code-review, /ctx-explain, and /ctx-refactor all become noticeably better with these tools connected.

The two sections below name canonical implementations that ctx has tested against — Gemini Search for web-search-with-citations and GitNexus for the code knowledge graph. If your toolchain provides equivalent capabilities through different MCP servers (Firecrawl, Exa, Tavily for web search; sourcegraph-cody for code graph), use those instead. ctx skills describe capabilities, not specific tools — the agent self-routes based on what's connected.

Gemini Search¶

Provides grounded web search with citations. Used by skills and the agent playbook as the preferred search backend (faster and more accurate than built-in web search).

Setup: Add the Gemini Search MCP server to your Claude Code settings. See the Gemini Search MCP documentation for installation.

Verification:

# The agent checks this automatically during /ctx-remember
# Manual test: ask the agent to search for something

GitNexus¶

Provides a code knowledge graph with symbol resolution, blast radius analysis, and domain clustering. Used by skills like /ctx-refactor (impact analysis) and /ctx-code-review (dependency awareness).

Setup: Add the GitNexus MCP server to your Claude Code settings, then index your project:

gitnexus analyze

Verification:

# The agent checks this automatically during /ctx-remember
# If the index is stale, it will suggest rehydrating

Suppressing the Check¶

If you don't use companion tools and want to skip the availability check at session start, add to .ctxrc:

companion_check: false

Future Direction¶

The companion tool integration is evolving toward a pluggable model: bring your own search engine, bring your own code intelligence. The current integration is MCP-based and limited to Gemini Search and GitNexus. If you use a different search or code intelligence tool, skills will degrade gracefully to built-in capabilities.

See Also¶

• The Complete Session: full session lifecycle recipe
• Multilingual Session Parsing: configure session header prefixes for other languages
• CLI Reference: all commands and flags
• Integrations: detailed per-tool integration docs