ScopeKit

ScopeKit — task-complete context packs for AI coding agents. Use the CLI/skill workflow by default; MCP is optional for agents that want live tool access.

npm package: scopekit. Binaries: scopekit (primary), plus deprecated aliases repo-context and repo-context-mcp.

Works with Cursor, OpenAI Codex, Claude Code, Claude Desktop, and any stdio MCP client.

Install and run

Install globally

npm install -g scopekit

One-command repo setup

Configures repo-local agent instructions (Cursor, Claude, Codex) in the current repository:

scopekit setup

No global install

npx scopekit setup

Index and pack

scopekit index .
scopekit pack "Find auth/session logic" --profile claude

Query

scopekit query "Where is auth handled?"

Per-assistant integration

scopekit install cursor
scopekit install claude
scopekit install codex
scopekit install mcp    # writes .scopekit/mcp-config.example.json

Optional MCP server

scopekit mcp

Profiles

scopekit pack "..." --profile ultra     # smallest (Codex-style)
scopekit pack "..." --profile claude    # richer relationships (Claude/Cursor)
scopekit pack "..." --profile default   # balanced

Local development

npm install
npm run build
npm link
scopekit --help
scopekit setup --dry-run

Backward compatibility

repo-context and repo-context-mcp still work as deprecated aliases and print a rename notice.

Remote / cloud agents

Commit the repo-local instruction files created by scopekit setup so remote agents can see them:

git add CLAUDE.md AGENTS.md .cursor/rules/scopekit.mdc .scopekit/
git commit -m "chore: add ScopeKit agent instructions"

ScopeKit installs repo-local instructions — not a global install into Claude/Codex accounts.

Token savings are not guaranteed. This project includes A/B tooling to prove or disprove savings per client/task. Benchmarks measure MCP output size, not end-to-end client usage.

Proven Scope

One real Codex proof is complete:

• Client: Codex CLI 0.137.0-alpha.4
• Task: auth-discovery
• Mode: context_broker_locked
• Routing: context_status + context_pack only
• No-MCP baseline: 210,298 / 450,685 / 273,530
• Locked combined: 62,509 / 62,495 / 62,276
• Mean savings: 80.0%
• Median savings: 77.2%
• Quality: 9/10 vs 9/10
• Expected files: 5/5
• Verdict: PROVEN_SAVINGS_STABLE

Allowed claim: repo-context-mcp locked broker proved stable savings for Codex CLI auth-discovery in this repo. See docs/proofs/codex-auth-discovery-locked.md.

Skill-mode head-to-head (auth-discovery, no MCP, supplied context): SCOPED_SKILL_HEAD_TO_HEAD_SUPPORTS_REPO_CONTEXT — see docs/benchmarks/skill-head-to-head.md. Scoped claim only; not a universal Graphify superiority claim.

Best-effort skill benchmark (auth-discovery): repo-context ultra pack is ~89% smaller context than Graphify best-effort with 5/5 vs 1/5 files locally; Codex median reduction ~7.6% (fixed client overhead — see npm run benchmark:token-floor). Context-efficiency metrics: npm run benchmark:context-efficiency.

Claude supplied-context benchmark (2026-06-11, separate metric from Codex): the --profile claude pack produced 70%+ smaller supplied context than Graphify-derived context on 5/5 tasks with equal-or-better quality on 5/5 tasks (graphify query unavailable in 0.8.36; exact Claude token usage not captured, so no Claude token-savings claim). See docs/benchmarks.md.

Not yet proven:

• MCP-mode token superiority vs Graphify (different usage modes; not apples-to-apples).
• Not proven for Cursor, Claude, Gemini, or other clients.
• Not proven for all tasks.
• Not proven for full context_broker mode.

Graphify diagnostic head-to-head (auth-discovery, Graphify 0.8.36 Gemini): complete — diagnostic only, no superiority claim. Real client usage comparison not yet recorded. Protocol: docs/benchmarks/graphify-head-to-head.md.

Diagnostic compression (raw repo tokens ÷ context_pack tokens) is comparable in shape to Graphify-style metrics but is not proof of real agent savings. Run npm run benchmark:compression. Real savings require ab:real-check with parsed client usage.

Usage modes

| Mode | When to use | |------|-------------| | Skill/CLI (default) | repo-context query / repo-context pack — paste or pipe markdown into any assistant; avoids MCP client overhead | | MCP (optional) | repo-context mcp — live context_status + context_pack for MCP-capable agents |

What this is

A local, read-only context broker that builds deterministic repo intelligence (graph, capsules, multimodal metadata) offline, then answers with compact task-specific context packs instead of full file dumps or graph tool loops.

What problem it solves

Agents often waste context on repeated repo_map / search / full-file reads. repo-context-mcp lets agents call context_pack once with a task description and a token budget, then drill down only when needed.

How it works

1. Build (npm scripts): scan the repo → .repo-context-graph/graph.json + capsules
2. Serve (stdio MCP): agents call context_status → context_pack → fallbacks
3. Measure (optional): MCP_TELEMETRY=1 logs tool output sizes locally

MCP tools never write source code. Only local cache/telemetry files are written by npm scripts.

Quick start (from source)

git clone https://github.com/shrey1110-dotcom/CLAUDE_API_SAVER.git
cd CLAUDE_API_SAVER   # or your fork path
npm install
npm run build
scopekit setup
scopekit index .
scopekit status
scopekit pack "Where is auth implemented?" --budget 500 --format markdown
scopekit pack "Plan a safe refactor" --profile claude
npm run doctor
npm run benchmark:context
npm run benchmark:compression

Optional MCP: scopekit mcp (legacy alias: repo-context-mcp).

Build graph and context

Run in the repository you want indexed (usually the project root):

npm run graph:build   # code + deterministic multimodal docs/assets
npm run context:build

Re-run after large refactors.

Universal LLM mode (no MCP)

Generate a portable context pack for any LLM client:

npm run context:pack -- --task "your task" --budget 1000 --format markdown --out .context-packs/task.md

See docs/universal-llm-usage.md.

Broker-first architecture

The knowledge graph and multimodal ingestion feed context_pack internally. Agents should not wander through graph/search tools — use context_pack first, fallbacks only when needed. Locked mode (codex_locked) exposes only context_status + context_pack to prevent tool loops.

Strategy: docs/broker-first-context-strategy.md · Status: docs/product-status.md · Proofs: docs/proofs/README.md · Handoff: docs/handoffs/cursor-continuation-after-codex-proof.md

Real token savings require per-client A/B proof (ab:real-check), not benchmarks alone.

Add to an MCP client

1. Point the client at dist/index.js (or repo-context-mcp after npm link).
2. Set the compact env block (see examples/generic-stdio/mcp-server.json).
3. Reload MCP in the client.

Client guides: docs/client-configs/

Recommended agent instructions

Give your agent this policy (also in docs/agent-instructions/AGENTS.md):

Use repo-context-mcp as a context broker. First call context_status, then context_pack with budgetTokens 1000. Use full file reads only when exact implementation verification is needed.

Tool order: context_status → context_pack → impact_pack (for diffs) → graph_query / graph_symbol → get_symbol_context → search_code / repo_map

MCP tools

| Tool | When to use | | --- | --- | | context_pack | First — task-specific files, symbols, commands | | impact_pack | Changed files / diff impact | | context_status | Check if index exists | | graph_query | Fallback if context_pack is not enough | | graph_symbol | Fallback symbol lookup | | get_symbol_context | Exact code snippets | | search_code / repo_map | Index missing or last resort |

Environment (compact defaults)

{
  "MCP_TELEMETRY": "1",
  "MCP_OUTPUT_MODE": "compact",
  "MCP_MAX_RESPONSE_CHARS": "9000",
  "MCP_DEFAULT_SEARCH_RESULTS": "5",
  "MCP_TREE_DEPTH": "2",
  "MCP_SYMBOL_CONTEXT_LINES": "14"
}

Use MCP_TOOL_PROFILE to limit exposed tools for controlled client tests. Default is full.

| Profile | Exposed tools | | --- | --- | | full | all MCP tools | | context_only | context_status, context_pack, impact_pack | | codex_locked | context_status, context_pack | | graph | graph tools | | search | repo map/search/symbol command tools |

CLI

After npm run build:

npm start
# or
npx repo-context-mcp   # when linked or installed

Benchmarks

npm run benchmark:context   # recommended path (~668 MCP tokens in reference repo)
npm run benchmark:context-locked
npm run benchmark:graph
npm run benchmark:workflow

See docs/benchmarks.md. Benchmarks measure MCP output size, not client billing.

Telemetry

export MCP_TELEMETRY=1   # in MCP server env
npm run telemetry:clean  # before a measured session
npm run telemetry:report

Safety

Read-only MCP tools; local cache only. Details: docs/safety.md

Supported clients

| Client | Doc | | --- | --- | | Cursor | docs/client-configs/cursor.md | | Codex | docs/client-configs/codex.md | | Claude Code | docs/client-configs/claude-code.md | | Claude Desktop | docs/client-configs/claude-desktop.md | | Generic stdio | docs/client-configs/generic-stdio.md |

Setup checklist: docs/setup-checklist.md

Limitations

• Heuristic graph (not a typechecker)
• No embeddings or LLM summaries in v0.1.0
• No guaranteed token savings without per-client A/B tests

Measuring real savings

Use docs/multi-client-ab-tests.md and docs/ab-test-templates/.

client_total_with_mcp + MCP_estimated_output_tokens < client_total_without_mcp

Quality must be equal or better.

Guided A/B tooling

npm run ab:create -- --client cursor --repo . --task auth-discovery
npm run ab:prompt -- --mode no_mcp
npm run ab:record -- --mode no_mcp
npm run ab:report
npm run ab:compare

Guide: docs/ab-testing.md

Codex A/B testing quickstart

Use locked mode for the primary Codex proof path. The first real Codex A/B test increased usage because Codex entered a tool exploration loop; context_broker_locked limits exposed MCP tools to context_status and context_pack.

npm run ab:codex:plan
AB_ENABLE_CODEX_ADAPTER=1 npm run ab:codex -- --mode no_mcp --repo . --repeat 3 --yes
npm run telemetry:clean
AB_ENABLE_CODEX_ADAPTER=1 npm run ab:codex -- --mode context_broker_locked --repo . --repeat 3 --yes
npm run telemetry:report
npm run ab:report
npm run ab:compare
npm run ab:real-check

The Codex adapter is experimental and disabled by default. If Codex usage cannot be parsed from real JSON usage output, enter real usage manually with npm run ab:record. Do not claim real savings unless ab:real-check returns PROVEN SAVINGS.

Development

npm run dev
npm run test:all
npm run doctor
npm run smoke:mcp
npm run release:check
npm run compat:report

Product overview: docs/product.md · Status: docs/product-status.md · Next benchmarks: docs/next-benchmark-phase.md · Changelog: CHANGELOG.md

License

MIT — see LICENSE