Token-efficient codebase context for AI assistants.
Indexes your repo locally, ranks relevant files with hybrid retrieval, and returns token-budgeted context packs via MCP — no LLM required in this package.

Works with Cursor, Claude Desktop, Windsurf, and any Model Context Protocol client.

The host LLM (Cursor, Claude, etc.) does the reasoning.
This agent finds, ranks, and compresses codebase context.

npm install -g developer-context-agent

Or use without installing:

npx developer-context-agent --help

Requirements: Node.js 20+

cd your-project
context-agent index
context-agent pack --task "how does auth work"

Add .cursor/mcp.json in your project:

{
  "mcpServers": {
    "context-agent": {
      "command": "npx",
      "args": ["-y", "developer-context-agent", "mcp"],
      "env": {
        "REPO_PATH": "${workspaceFolder}"
      }
    }
  }
}

Restart Cursor, enable the MCP server in Settings → MCP, then chat as usual. The model can call get_context_pack before reading files.

Recommended Cursor rule (.cursor/rules/context-agent.mdc):

Before reading large files or searching the codebase manually, use context-agent MCP tools:
1. get_context_pack for the user's question
2. find_files / search_symbols only if more detail is needed

{
  "mcpServers": {
    "context-agent": {
      "command": "npx",
      "args": ["-y", "developer-context-agent", "mcp"],
      "env": {
        "REPO_PATH": "/absolute/path/to/your/repo"
      }
    }
  }
}

You ask in Cursor chat
       ↓
Host LLM calls get_context_pack("auth middleware")
       ↓
Agent: grep + symbols + import graph (+ optional vectors)
       ↓
Returns small markdown context pack (token-budgeted)
       ↓
Host LLM answers using that context

Local index is stored in .context-agent/ inside your project (SQLite). Nothing is sent to a cloud service by this package.

Examples:

context-agent index --repo .
context-agent status --repo .
context-agent pack --task "explain hybrid retrieval" --max-tokens 6000

Environment variables (optional):

Hybrid retrieval works without Ollama (grep + symbols + import graph).
For vector similarity search:

ollama pull nomic-embed-text
context-agent index

Clone and work on the source repo:

git clone https://github.com/SinuxDev/developer-context-agent.git
cd developer-context-agent
npm install
npm test
npm run context-agent -- index --repo .
npm run mcp

An optional Fastify API (POST /chat, POST /runs) with Postgres/Redis is still in the codebase for supervised runs. It is not required for the MCP agent.

npm run docker:up
npm run db:migrate
npm run dev

See docs/IDE_BRIDGE.md for HTTP API details.

• npm: https://www.npmjs.com/package/developer-context-agent
• Repository: https://github.com/SinuxDev/developer-context-agent
• Issues: https://github.com/SinuxDev/developer-context-agent/issues

MIT