Aperture

Open only the code your agent needs.

The problem: Your coding agent reads 40+ files before touching a single line. Token budgets blow up. Context windows fill with irrelevant code.

Aperture: Give it a task, get back the exact symbols it needs — ranked by graph resonance, packed under your token budget, cited with file paths and line ranges.

Before / After

Before Aperture — agent uses grep + recursive reads:

reading src/auth/login.ts          (2,100 tok)
reading src/auth/session.ts        (1,800 tok)
reading src/users/profile.ts       (3,200 tok)
reading src/api/router.ts          (4,500 tok)
reading src/payments/stripe.ts     (3,800 tok)
...18 more files...
Total: ~47,000 tokens consumed

After Aperture — task-targeted bundle in one call:

aperture focus "fix login validation bug" --budget 4000

Task: fix login validation bug
Symbols: 12/21 · 443 tok / 4000 budget

  src/auth/login.ts        L1-8    score=0.333  54 tok
    ↳ seed: "login" matches symbol name
    ↳ seed: "validation" matches symbol name
  src/api/router.ts        L17-41  score=0.100  109 tok
    ↳ resonance: caller of login via handleLogin
  src/users/profile.ts     L11-28  score=0.000  280 tok
    ↳ resonance: attached via validateCredentials

Result: 443 tokens instead of ~47,000 for this task.

Install

npm install -g @kioie/aperture
aperture doctor

Or zero-install with npx:

npx @kioie/aperture focus "fix login validation bug" --budget 4000

Quick start

# 1. Index your repo (fast — builds a symbol graph, cached to .aperture-cache/)
aperture index .

# 2. Get a cited bundle for your task
aperture focus "fix login validation bug" --budget 4000

# 3. See a beautiful tree view
aperture focus "stripe webhook payment failed" --format tree

# 4. Export as markdown for @-mentioning in Cursor
aperture focus "update user profile validation" --format markdown > .cursor/context.md

# 5. Try the built-in demo (no repo needed)
aperture demo

Cursor / Claude Code / Codex

One-command setup for Cursor:

aperture cursor
# → prints the JSON snippet — paste into Cursor MCP settings

Claude Code:

claude mcp add aperture -- npx -y @kioie/aperture mcp

Any MCP client (Cursor, Claude Code, Codex, Zed...):

{
  "mcpServers": {
    "aperture": {
      "command": "npx",
      "args": ["-y", "@kioie/aperture", "mcp"]
    }
  }
}

Once connected, agents call aperture_focus before reading any files.

MCP tools

| Tool | What it does | |------|-------------| | aperture_focus | Build a cited context bundle — returns file paths, line ranges, scores, reasons | | aperture_read_bundle | Fetch source snippets with path:start-end citations | | aperture_explain | Per-symbol selection rationale for debugging bad selections | | aperture_index | Index a repo and warm the cache — returns files, symbols, edges |

Typical agent loop:

1. aperture_focus(task, repo, budget=4000)
   → { files: [{ path, ranges, score, tokens, reasons }], tokens, explain }

2. aperture_read_bundle()
   → { sections: [{ path, citation: "src/auth/login.ts:1-8", content }] }

3. <edit code using citations>

4. If something looks off: aperture_explain() → adjust task wording → retry focus

How it works

Index → Seed → Resonate → Pack → Cite

1. Index — extract symbols (functions, classes, exports) and dependency edges (imports, calls, containment) from TS/JS/Python; persist to .aperture-cache/ for fast re-index
2. Seed — score symbols by token overlap between task description and symbol names/paths
3. Resonate — personalized propagation: high-seed symbols push score to their neighbors across the dependency graph
4. Pack — greedy selection by utility = resonance × cohesion / token_cost, stopping at budget
5. Cite — return file paths, line ranges, scores, and natural-language reasons

See SPEC.md for the full algorithm.

Evaluation

npm run eval

Current score: 15/15 across sample-repo (auth, payments, users, API, barrels) and monorepo (cross-package imports) fixtures (mean recall@4000: 100%).

sample-repo  — 11 cases · cold index ~200ms · disk cache ~7ms
monorepo     —  4 cases · cold index ~620ms · disk cache ~70ms

See eval/results.md for the full report.

Reproducible examples with exact token counts: EXAMPLES.md.

Demo

aperture demo

Runs Aperture on the built-in sample repo (auth + payments + users + API) and prints a formatted tree. No repo needed.

Library API

import { focusContext } from "@kioie/aperture";

const bundle = await focusContext({
  repo: "/path/to/repo",
  task: "fix stripe webhook signature validation",
  budget: 4000,
});

// bundle.files = [{ path, ranges, score, tokens, reasons }]
// bundle.tokens = total tokens used
// bundle.explain = per-symbol selection reasons

For AI agents

• llms.txt — machine-readable tool docs and agent loop
• AGENTS.md — full integration playbook with budget guidance
• docs/agent-api.json — JSON schemas with example responses
• integrations/ — Cursor, Claude Code, and GitHub Action configs

Contributing

See CONTRIBUTING.md.

MIT License.