AI Tools

AI Tools¶

Context works with any AI tool that can read files. This guide covers setup for popular AI coding assistants.

Claude Code (Full Integration)¶

Claude Code has the deepest integration via the ctx plugin.

Setup¶

First, install ctx and initialize your project:

ctx init

Then, install the ctx plugin in Claude Code:

# From the ctx repository
claude /plugin install ./internal/assets/claude

# Or from the marketplace
claude /plugin marketplace add ActiveMemory/ctx
claude /plugin install ctx@activememory-ctx

{ "enabledPlugins": { "ctx@activememory-ctx": true } }

This gives you:

How It Works¶

graph TD
    A[Session Start] --> B[Claude reads CLAUDE.md]
    B --> C[PreToolUse hook runs]
    C --> D[ctx agent loads context]
    D --> E[Work happens]
    E --> F[Session End]

1. Session start: Claude reads CLAUDE.md, which tells it to check .context/
2. First tool use: PreToolUse hook runs ctx agent and emits the context packet (subsequent invocations within the cooldown window are silent)
3. Next session: Claude reads context files and continues with context

Plugin Hooks¶

The ctx plugin provides lifecycle hooks implemented as Go subcommands (ctx system *):

A catch-all PreToolUse hook also runs ctx agent on every tool use (with cooldown) to autoload context.

Hook Configuration¶

The plugin's hooks.json wires everything automatically: no manual configuration in settings.local.json needed:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "ctx system context-load-gate" }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "ctx system block-non-path-ctx" }
        ]
      },
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "ctx system qa-reminder" }
        ]
      },
      {
        "matcher": "EnterPlanMode",
        "hooks": [
          { "type": "command", "command": "ctx system specs-nudge" }
        ]
      },
      {
        "matcher": ".*",
        "hooks": [
          { "type": "command", "command": "ctx agent --budget 4000 2>/dev/null || true" }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "ctx system post-commit" }
        ]
      }
    ],
    "UserPromptSubmit": [
      {
        "hooks": [
          { "type": "command", "command": "ctx system check-context-size" },
          { "type": "command", "command": "ctx system check-ceremonies" },
          { "type": "command", "command": "ctx system check-persistence" },
          { "type": "command", "command": "ctx system check-journal" },
          { "type": "command", "command": "ctx system check-reminders" },
          { "type": "command", "command": "ctx system check-version" },
          { "type": "command", "command": "ctx system check-resources" },
          { "type": "command", "command": "ctx system check-knowledge" },
          { "type": "command", "command": "ctx system check-map-staleness" },
          { "type": "command", "command": "ctx system heartbeat" }
        ]
      }
    ]
  }
}

Customizing Token Budget and Cooldown¶

Edit the PreToolUse command to change the token budget or cooldown:

"command": "ctx agent --budget 8000 --session $PPID >/dev/null || true"
"command": "ctx agent --budget 4000 --cooldown 5m --session $PPID >/dev/null || true"

The --session $PPID flag isolates the cooldown per session: $PPID resolves to the Claude Code process PID, so concurrent sessions don't interfere. The default cooldown is 10 minutes; use --cooldown 0 to disable it.

Verifying Setup¶

1. Start a new Claude Code session;
2. Ask: "Do you remember?"
3. Claude should cite specific context:
   • Current tasks from .context/TASKS.md;
   • Recent decisions or learnings;
   • Recent session history from ctx recall.

Local Plugin Development¶

When developing ctx locally (adding skills, hooks, or changing plugin behavior), Claude Code caches the plugin by version. You must bump the version in both files and update the marketplace for changes to take effect:

1. Bump version in both:

2. internal/assets/claude/.claude-plugin/plugin.json (plugin manifest), .claude-plugin/marketplace.json (marketplace listing*);

3. Update the marketplace in Claude Code:

4. Open the Plugins UI (/plugins or Esc menu),
5. Go to Marketplaces tab,
6. Select the activememory-ctx Marketplace,

7. Choose Update marketplace;

8. Start a new Claude Code session: skill changes aren't reflected in existing sessions.

Troubleshooting¶

Manual Context Load¶

If hooks aren't working, manually load context:

# Get context packet
ctx agent --budget 4000

# Or paste into conversation
cat .context/TASKS.md

Agent Skills¶

The ctx plugin ships Agent Skills following the agentskills.io specification.

These are invoked in Claude Code with /skill-name.

Session Lifecycle Skills¶

Context Persistence Skills¶

Scratchpad Skills¶

Session History Skills¶

Blogging Skills¶

Auditing & Health Skills¶

Planning & Execution Skills¶

Usage Examples¶

/ctx-status
/ctx-add-learning "Token refresh requires explicit cache invalidation"
/ctx-journal-enrich twinkly-stirring-kettle

Skills support partial matching where applicable (e.g., session slugs).

Cursor IDE¶

Cursor can use context files through its system prompt or by reading files directly.

Setup¶

# Generate Cursor configuration
ctx hook cursor

# Initialize context
ctx init --minimal

Configuration¶

Add to Cursor settings (.cursor/settings.json):

// split to multiple lines for readability
{
  "ai.systemPrompt": "Read .context/TASKS.md and 
  .context/CONVENTIONS.md before responding. 
  Follow rules in .context/CONSTITUTION.md.",
}

Usage¶

1. Open your project in Cursor
2. Context files are available in the file tree
3. Reference them in prompts: "Check .context/DECISIONS.md for our approach to..."

Manual Context Injection¶

For more control, paste context directly:

# Get AI-ready packet
ctx agent --budget 4000 | pbcopy  # macOS
ctx agent --budget 4000 | xclip  # Linux

Paste into Cursor's chat.

Aider¶

Aider works well with context files through its --read flag.

Setup¶

# Generate Aider configuration
ctx hook aider

# Initialize context
ctx init

Configuration¶

Create .aider.conf.yml:

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

Usage¶

# Start Aider (reads context files automatically)
aider

# Or specify files explicitly
aider --read .context/TASKS.md --read .context/CONVENTIONS.md

With Watch Mode¶

Run ctx watch alongside Aider to capture context updates:

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

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

GitHub Copilot¶

GitHub Copilot integrates with ctx at three levels: an automated instructions file, a VS Code Chat extension, and manual patterns.

Setup¶

# Initialize context
ctx init

# Generate .github/copilot-instructions.md
ctx hook copilot --write

The --write flag creates .github/copilot-instructions.md, which Copilot reads automatically at the start of every session. This file contains your project's constitution rules, current tasks, conventions, and architecture: giving Copilot persistent context without manual copy-paste.

Re-run ctx hook copilot --write after updating your .context/ files to regenerate the instructions.

VS Code Chat Extension (@ctx)¶

The ctx VS Code extension adds a @ctx chat participant to GitHub Copilot Chat, giving you direct access to all context commands from within the editor.

Installation¶

1. Build from source (requires Node.js 18+):

cd editors/vscode
npm install
npm run build
npx @vscode/vsce package

1. Install the .vsix file:

code --install-extension ctx-context-0.7.0.vsix

1. Reload VS Code. Type @ctx in Copilot Chat to verify.

Slash Commands¶

Usage Examples¶

@ctx /init
@ctx /status
@ctx /add task Implement user authentication
@ctx /drift
@ctx /hook copilot
@ctx /recall

Typing @ctx without a command shows help with all available commands. The extension also supports natural language: asking @ctx about "status" or "drift" routes to the correct command automatically.

Configuration¶

Follow-Up Suggestions¶

After each command, the extension suggests relevant next steps. For example, after /init it suggests /status and /hook; after /drift it suggests /sync.

Session Persistence¶

ctx init creates a .context/sessions/ directory for storing session data from non-Claude tools. The Markdown session parser scans this directory during ctx recall, enabling session history for Copilot and other tools.

Manual Patterns¶

These patterns work without the extension, using Copilot's built-in file awareness:

Pattern 1: Keep context files open

Open .context/CONVENTIONS.md in a split pane. Copilot will reference it.

Pattern 2: Reference in comments

// See .context/CONVENTIONS.md for naming patterns
// Following decision in .context/DECISIONS.md: Use PostgreSQL

function getUserById(id: string) {
  // Copilot now has context
}

Pattern 3: Paste context into Copilot Chat

ctx agent --budget 2000

Paste output into Copilot Chat for context-aware responses.

Windsurf IDE¶

Windsurf supports custom instructions and file-based context.

Setup¶

# Generate Windsurf configuration
ctx hook windsurf

# Initialize context
ctx init

Configuration¶

Add to Windsurf settings:

// Split to multiple lines for readability
{
  "ai.customInstructions": "Always read .context/CONSTITUTION.md first. 
  Check .context/TASKS.md for current work. 
  Follow patterns in .context/CONVENTIONS.md."
}

Usage¶

Context files appear in the file tree. Reference them when chatting:

• "What's in our task list?" → AI reads .context/TASKS.md
• "What convention do we use for naming?" → AI reads .context/CONVENTIONS.md

Generic Integration¶

For any AI tool that can read files, use these patterns:

Manual Context Loading¶

# Get full context
ctx load

# Get AI-optimized packet
ctx agent --budget 8000

# Get specific file
cat .context/TASKS.md

System Prompt Template¶

You are working on a project with persistent context in .context/

Before responding:
1. Read .context/CONSTITUTION.md - NEVER violate these rules
2. Check .context/TASKS.md for current work
3. Follow .context/CONVENTIONS.md patterns
4. Reference .context/DECISIONS.md for architectural choices

When you learn something new, note it for .context/LEARNINGS.md
When you make a decision, document it for .context/DECISIONS.md

Automated Updates¶

If your AI tool outputs to a log, use ctx watch:

# Watch log file for context-update commands
your-ai-tool 2>&1 | tee /tmp/ai.log &
ctx watch --log /tmp/ai.log

The AI can emit updates like:

<context-update type="complete">implement caching</context-update>
<context-update type="learning"
  context="Implementing caching layer"
  lesson="Important thing learned today"
  application="Apply this insight going forward"
>Caching Insight</context-update>

Context Update Commands¶

The ctx watch command parses update commands from AI output. Use this format:

<context-update type="TYPE" [attributes]>Content</context-update>

Supported Types¶

Simple Format (tasks, conventions, complete)¶

<context-update type="task">Implement rate limiting</context-update>
<context-update type="convention">Use kebab-case for files</context-update>
<context-update type="complete">rate limiting</context-update>

Structured Format (learnings, decisions)¶

Learnings and decisions support structured attributes for better documentation:

Learning with full structure:

<context-update type="learning"
  context="Debugging Claude Code hooks"
  lesson="Hooks receive JSON via stdin, not environment variables"
  application="Parse JSON stdin with the host language (Go, Python, etc.): no jq needed"
>Hook Input Format</context-update>

Decision with full structure:

<context-update type="decision"
  context="Need a caching layer for API responses"
  rationale="Redis is fast, well-supported, and team has experience"
  consequences="Must provision Redis infrastructure; team training on Redis patterns"
>Use Redis for caching</context-update>

Learnings require: context, lesson, application attributes. Decisions require: context, rationale, consequences attributes. Updates missing required attributes are rejected with an error.

Further Reading¶

• Skills That Fight the Platform: Common pitfalls in skill design that work against the host tool
• The Anatomy of a Skill That Works: What makes a skill reliable: the E/A/R framework and quality gates