capy

Context-Aware Prompting ...or "Yet another solution to LLM context problem"

capy helps coding agents work with large outputs without filling their context window. It is a local MCP server with integrations for Claude Code and Codex CLI, distributed as a Go binary.

• Extract what matters. Process logs, API responses, web pages, and large files in subprocesses; return summaries or search results to the agent.
• Keep knowledge across sessions. Index project documentation and notes, then retrieve relevant passages on demand.
• Archive conversations. Search, browse, and restore Claude Code and Codex sessions from an encrypted session vault.

Storage and search run locally, with mandatory database encryption and no telemetry, account, or hosted service. Fetches and submitted code can make network requests; results returned to your agent follow that agent's data policies.

Contents

• Quick Start
• Everyday Use
• MCP Tools
• Session Vault
• Configuration
• Encryption
• Hooks and Permissions
• Troubleshooting
• CLI Commands
• Benchmarks
• Contributing
• Acknowledgements
• License

Quick Start

Install

Homebrew (macOS/Linux):

brew install serpro69/tap/capy

Shell script (Unix):

curl -sSfL https://raw.githubusercontent.com/serpro69/capy/master/install.sh | sh

Or build from source with Go 1.27.2+ and a C compiler. Put the resulting capy binary on your PATH.

Set an encryption key

The knowledge database requires a passphrase. For a new database, generate and save one:

export CAPY_DB_KEY=$(openssl rand -base64 48)
echo "export CAPY_DB_KEY='$CAPY_DB_KEY'" >> ~/.zshrc  # or ~/.bashrc

Keep this key: reuse it for an existing database instead of generating another. Generated passphrases of at least 32 characters are recommended. Start your agent from an environment that has the key. For separate project keys, use a private credential file.

Setup (Claude Code)

Run from your project root:

capy setup --platform claude-code
capy doctor

Setup registers the MCP server and hooks, and adds routing instructions for the agent. Use --local to put Claude hooks in .claude/settings.local.json; otherwise setup offers the shared .claude/settings.json target. Restart Claude Code to load the configuration.

Setup (Codex CLI)

Run from your project root with capy on your PATH:

capy setup --platform codex
capy doctor

Trust the project in Codex, then review and trust the generated definitions in /hooks. These are separate steps; setup does not change trust or enable explicitly disabled hooks. Restart Codex after changing its environment or installed configuration, and review changed hook definitions again.

Commit .codex/hooks.json, .codex/config.toml, and .codex/capy-owner together. The owner marker is an installation ID, not a secret; setup preserves it and existing external hooks. Every collaborator who enables these hooks needs a compatible capy on their own PATH. If you use --binary, it must identify that same executable.