{"id":51017972,"url":"https://github.com/kioie/aperture","last_synced_at":"2026-06-21T13:30:31.984Z","repository":{"id":365172490,"uuid":"1270879326","full_name":"kioie/aperture","owner":"kioie","description":"Budget-aware code context bundles for coding agents — MCP server and CLI with graph-based symbol selection and citations.","archived":false,"fork":false,"pushed_at":"2026-06-16T08:14:46.000Z","size":85,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-16T08:19:30.325Z","etag":null,"topics":["claude-code","code-intelligence","coding-agent","context-engineering","cursor","llm-tools","mcp","token-optimization"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kioie.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-16T06:10:11.000Z","updated_at":"2026-06-16T08:14:49.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/kioie/aperture","commit_stats":null,"previous_names":["kioie/aperture"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/kioie/aperture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kioie%2Faperture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kioie%2Faperture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kioie%2Faperture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kioie%2Faperture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kioie","download_url":"https://codeload.github.com/kioie/aperture/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kioie%2Faperture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34610832,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-21T02:00:05.568Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","code-intelligence","coding-agent","context-engineering","cursor","llm-tools","mcp","token-optimization"],"created_at":"2026-06-21T13:30:31.234Z","updated_at":"2026-06-21T13:30:31.976Z","avatar_url":"https://github.com/kioie.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Aperture\n\n**Open only the code your agent needs.**\n\n[![npm](https://img.shields.io/npm/v/@kioie/aperture?color=orange)](https://www.npmjs.com/package/@kioie/aperture)\n[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)\n[![eval](https://img.shields.io/badge/eval-19%2F19-brightgreen)](#evaluation)\n[![MCP](https://img.shields.io/badge/MCP-native-purple)](docs/cursor.md)\n\n---\n\n\u003e **The problem:** Your coding agent reads 40+ files before touching a single line. Token budgets blow up. Context windows fill with irrelevant code.\n\u003e\n\u003e **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.\n\n---\n\n## Before / After\n\n**Before Aperture** — agent uses grep + recursive reads:\n```\nreading src/auth/login.ts          (2,100 tok)\nreading src/auth/session.ts        (1,800 tok)\nreading src/users/profile.ts       (3,200 tok)\nreading src/api/router.ts          (4,500 tok)\nreading src/payments/stripe.ts     (3,800 tok)\n...18 more files...\nTotal: ~47,000 tokens consumed\n```\n\n**After Aperture** — task-targeted bundle in one call:\n```\naperture focus \"fix login validation bug\" --budget 4000\n\nTask: fix login validation bug\nSymbols: 21/23 · 1106 tok / 4000 budget\n\n  src/auth/login.ts        L1-8    score=0.378  54 tok\n    ↳ seed: \"login\" matches symbol login\n    ↳ seed: \"login\" matches symbol validateCredentials\n  src/api/router.ts        L15-20  score=0.071  317 tok\n    ↳ seed: \"login\" matches symbol handleLogin\n    ↳ resonance: attached via handleLogin\n```\n\n**Result: 1,106 tokens instead of ~47,000 for this task** (sample-repo fixture; run `npx @kioie/aperture demo` to reproduce).\n\n---\n\n## Quick start\n\n**Try it in 10 seconds — no install:**\n\n```bash\nnpx @kioie/aperture demo\n```\n\nRuns Aperture on the built-in sample repo (auth + payments + users + API) and prints a formatted tree with exact token counts.\n\n```bash\n# Focus a task on your repo\nnpx @kioie/aperture focus \"fix login validation bug\" --budget 4000\n\n# Index and warm the symbol graph cache\nnpx @kioie/aperture index .\n\n# Environment check + next steps\nnpx @kioie/aperture doctor\n```\n\n**Global install (optional):**\n\n```bash\nnpm install -g @kioie/aperture\naperture demo\naperture doctor\n```\n\n## Index and focus\n\n```bash\n# 1. Index your repo (fast — builds a symbol graph, cached to .aperture-cache/)\naperture index .\n\n# 2. Get a cited bundle for your task\naperture focus \"fix login validation bug\" --budget 4000\n\n# 3. See a beautiful tree view\naperture focus \"stripe webhook payment failed\" --format tree\n\n# 4. Export as markdown for @-mentioning in Cursor\naperture focus \"update user profile validation\" --format markdown \u003e .cursor/context.md\n```\n\n## Cursor / Claude Code / Codex\n\n**One-command setup for Cursor:**\n```bash\naperture cursor\n# → prints the JSON snippet — paste into Cursor MCP settings\n```\n\n**Claude Code:**\n```bash\nclaude mcp add aperture -- npx -y @kioie/aperture mcp\n```\n\n**Any MCP client (Cursor, Claude Code, Codex, Zed...):**\n```json\n{\n  \"mcpServers\": {\n    \"aperture\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@kioie/aperture\", \"mcp\"]\n    }\n  }\n}\n```\n\nOnce connected, agents call `aperture_focus` before reading any files.\n\n## MCP tools\n\n| Tool | What it does |\n|------|-------------|\n| `aperture_focus` | Build a cited context bundle — returns file paths, line ranges, scores, reasons |\n| `aperture_read_bundle` | Fetch source snippets with `path:start-end` citations |\n| `aperture_explain` | Per-symbol selection rationale for debugging bad selections |\n| `aperture_index` | Index a repo and warm the cache — returns files, symbols, edges |\n\n**Typical agent loop:**\n\n```\n1. aperture_focus(task, repo, budget=4000)\n   → { files: [{ path, ranges, score, tokens, reasons }], tokens, explain }\n\n2. aperture_read_bundle()\n   → { sections: [{ path, citation: \"src/auth/login.ts:1-8\", content }] }\n\n3. \u003cedit code using citations\u003e\n\n4. If something looks off: aperture_explain() → adjust task wording → retry focus\n```\n\n## How it works\n\n```\nIndex → Seed → Resonate → Pack → Cite\n```\n\n1. **Index** — extract symbols (functions, classes, exports) and dependency edges (imports, calls, containment) from TS/JS/Python; persist to `.aperture-cache/` for fast re-index\n2. **Seed** — score symbols by token overlap between task description and symbol names/paths\n3. **Resonate** — personalized propagation: high-seed symbols push score to their neighbors across the dependency graph\n4. **Pack** — greedy selection by `utility = resonance × cohesion / token_cost`, stopping at budget\n5. **Cite** — return file paths, line ranges, scores, and natural-language reasons\n\nSee [SPEC.md](./SPEC.md) for the full algorithm.\n\n## Evaluation\n\n```bash\nnpm run eval\n```\n\nCurrent score: **19/19** across sample-repo (auth, payments, users, API, barrels), monorepo (cross-package imports), and python-repo fixtures (mean recall@4000: **100%**).\n\n```\nsample-repo  — 11 cases · cold index ~26ms · disk cache ~2ms\nmonorepo     —  4 cases · cold index ~4ms  · disk cache ~1ms\npython-repo  —  4 cases · cold index ~15ms · disk cache ~2ms\n```\n\nReproduce: `npm run eval` or `aperture eval`.\n\nSee [eval/results.md](./eval/results.md) for the full report.\n\nReproducible examples with exact token counts: [EXAMPLES.md](./EXAMPLES.md).\n\n## Demo\n\n```bash\nnpx @kioie/aperture demo\n```\n\nRuns Aperture on the built-in sample repo (auth + payments + users + API) and prints a formatted tree. No repo needed.\n\n## Library API\n\n```typescript\nimport { focusContext } from \"@kioie/aperture\";\n\nconst bundle = await focusContext({\n  repo: \"/path/to/repo\",\n  task: \"fix stripe webhook signature validation\",\n  budget: 4000,\n});\n\n// bundle.files = [{ path, ranges, score, tokens, reasons }]\n// bundle.tokens = total tokens used\n// bundle.explain = per-symbol selection reasons\n```\n\n## For AI agents\n\n- [llms.txt](./llms.txt) — machine-readable tool docs and agent loop\n- [AGENTS.md](./AGENTS.md) — full integration playbook with budget guidance\n- [docs/agent-api.json](./docs/agent-api.json) — JSON schemas with example responses\n- [integrations/](./integrations/) — Cursor, Claude Code, and GitHub Action configs\n\n## MCP Registry\n\nPublish to the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.kioie/aperture`:\n\n```bash\nnpm run sync:server              # align server.json with package.json\naperture registry validate       # schema check\nmcp-publisher login              # one-time GitHub auth\naperture registry publish        # publish server.json\n```\n\nSee [docs/mcp-registry.md](./docs/mcp-registry.md) for details.\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md).\n\nMIT License.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkioie%2Faperture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkioie%2Faperture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkioie%2Faperture/lists"}