{"id":50413547,"url":"https://github.com/gael55x/grape","last_synced_at":"2026-06-14T14:00:19.370Z","repository":{"id":359751957,"uuid":"1238586910","full_name":"gael55x/Grape","owner":"gael55x","description":"Better context compiler and transport for AI coding agents (CLI + MCP).","archived":false,"fork":false,"pushed_at":"2026-06-14T12:07:05.000Z","size":6770,"stargazers_count":10,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-14T13:22:35.478Z","etag":null,"topics":["ai-agents","cli","coding-agents","context-engineering","developer-tools","local-first","mcp","model-context-protocol","nodejs"],"latest_commit_sha":null,"homepage":"https://github.com/gael55x/Grape#readme","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gael55x.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","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-05-14T08:58:42.000Z","updated_at":"2026-06-14T11:56:16.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/gael55x/Grape","commit_stats":null,"previous_names":["gael55x/grape"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/gael55x/Grape","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gael55x%2FGrape","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gael55x%2FGrape/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gael55x%2FGrape/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gael55x%2FGrape/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gael55x","download_url":"https://codeload.github.com/gael55x/Grape/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gael55x%2FGrape/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34323994,"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-14T02:00:07.365Z","response_time":62,"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":["ai-agents","cli","coding-agents","context-engineering","developer-tools","local-first","mcp","model-context-protocol","nodejs"],"created_at":"2026-05-31T05:00:38.714Z","updated_at":"2026-06-14T14:00:19.290Z","avatar_url":"https://github.com/gael55x.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/grape-nw.png\" alt=\"Grape logo\" width=\"128\" /\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003eGrape\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n   Better context transport for AI coding agents.\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"docs/README.md\"\u003e\u003cstrong\u003eDocumentation\u003c/strong\u003e\u003c/a\u003e\n  ·\n  \u003ca href=\"docs/v1/architecture/overview.md\"\u003e\u003cstrong\u003eArchitecture\u003c/strong\u003e\u003c/a\u003e\n  ·\n  \u003ca href=\"ROADMAP.md\"\u003e\u003cstrong\u003eRoadmap\u003c/strong\u003e\u003c/a\u003e\n  ·\n  \u003ca href=\"CONTRIBUTING.md\"\u003e\u003cstrong\u003eContributing\u003c/strong\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cimg alt=\"Local-first\" src=\"https://img.shields.io/badge/local--first-repository%20native-176f45\" /\u003e\n  \u003cimg alt=\"Artifact-first\" src=\"https://img.shields.io/badge/artifact--first-context%20packs-6f42c1\" /\u003e\n  \u003cimg alt=\"CLI and MCP\" src=\"https://img.shields.io/badge/interfaces-CLI%20%2B%20MCP-044a64\" /\u003e\n  \u003cimg alt=\"Dependency-tracked\" src=\"https://img.shields.io/badge/tracking-dependency%20hashes-111827\" /\u003e\n\u003c/p\u003e\n\n\n\n**Stop making agents rediscover your codebase.** \n\nAI coding agents are powerful, but they waste context.\n\nThey reread the same files.\nThey rediscover the same project rules.\nThey forget what changed between turns.\nThey keep stale assumptions after branch switches and file edits.\nThey burn tool calls rebuilding context they already had.\n\nGrape gives coding agents a local context layer for real repositories.\n\nIt compiles the useful parts of your repo into dependency-tracked context artifacts, remembers what a specific agent session has already seen, and sends only what is new, changed, pinned, restorable, or stale.\n\nThe result is cleaner agent context, safer omission, and fewer repeated “let me inspect the repo again” loops.\n\n## What Grape does\n\nGrape sits between your repository and your AI coding agent.\n\nIt helps the agent answer three questions every turn:\n\n1. **What context does this task need?**\n2. **What context has this session already received?**\n3. **What previous context is now stale because the repo changed?**\n\nInstead of shipping a fresh wall of files every time, Grape returns a structured context pack:\n\n| Item                  | Meaning                                                               |\n| --------------------- | --------------------------------------------------------------------- |\n| `NEW`                 | Context the current session has not seen yet.                         |\n| `CHANGED`             | Context that changed since the session last saw it.                   |\n| `PINNED`              | Safety-critical context that must be resent.                          |\n| `OMIT_UNCHANGED`      | Context safely omitted because this same session already received it. |\n| `RESTORE_AVAILABLE`   | Omitted context that can be fetched back if needed.                   |\n| `INVALIDATE_PREVIOUS` | Prior context that should no longer be trusted.                       |\n\nGrape is not trying to replace your coding agent. It makes your existing agent better at carrying repository context across turns.\n\n## Install\n\nRequirements:\n\n* Node.js 22.13 or newer\n* npm\n* Git\n\nInstall Grape:\n\n```bash\nnpm install -g grape-context@beta\n```\n\nVerify the install:\n\n```bash\ngrape help\ngrape doctor\n```\n\n## Quick start\n\n1. Install: `npm install -g grape-context@beta`\n2. Initialize: `grape init --connect` (from your repository root)\n3. Connect MCP: `grape mcp --print-config` and add Grape to your coding agent\n4. Agent loop: call `grape_get_context` each turn with a stable `sessionId` and stable task text\n\nFull walkthrough: [Getting started](docs/v1/interfaces/getting-started.md).\n\nInitialize it inside a repository:\n\n```bash\ngrape init --connect\n```\n\nThis creates local Grape state, captures the initial repository snapshot, and prints MCP setup guidance for your coding agent.\n\nCheck local privacy settings:\n\n```bash\ngrape doctor --privacy\n```\n\n## Use it with an agent\n\nGrape works best through MCP.\n\nAfter setup, your MCP-capable coding agent calls:\n\n```text\ngrape_get_context\n```\n\nThe agent can then request task-specific repository context without manually rebuilding the same prompt every turn.\n\nA typical loop looks like this:\n\n```text\nUser asks coding agent to fix a task\nAgent calls grape_get_context\nGrape returns relevant repo context\nAgent edits code\nRepo changes\nAgent calls grape_get_context again\nGrape sends only the useful delta and invalidates stale context\n```\n\nManual CLI usage is available for debugging and fallback:\n\n```bash\ngrape sync\ngrape compile --task \"Explain the files I need to edit\"\ngrape diff-context --task \"Explain the files I need to edit\"\ngrape status\ngrape doctor\ngrape sessions\ngrape artifacts\ngrape run --session \u003cid\u003e -- npm test\ngrape omitted --session \u003cid\u003e\ngrape stale\ngrape conflicts\ngrape bench --fixture \u003cname\u003e\ngrape mcp --print-config\n```\n\nSee [Getting started](docs/v1/interfaces/getting-started.md), the full [CLI reference](docs/v1/interfaces/cli.md), and [MCP tools](docs/v1/interfaces/mcp-tools.md).\n\n## Why this matters\n\nMost agent workflows still treat context as disposable text.\n\nThat breaks down on larger tasks because the agent needs more than search results. It needs to know:\n\n* which files matter\n* which rules apply\n* which context it already saw\n* which context changed\n* which assumptions are stale\n* which omitted context can be restored\n* which safety constraints must be repeated\n* which evidence supports a claim\n\nGrape treats context like a build artifact.\n\nIt is compiled from repository state, linked to dependencies, scoped to a session, and invalidated when its inputs change.\n\n## Local-first by design\n\nGrape runs against your local repository.\n\nBy default, it does not send repository content, artifacts, proofs, summaries, embeddings, or telemetry to a remote Grape service.\n\nLocal runtime state lives under `.grape/`. Grape keeps this state out of Git through `.git/info/exclude`.\n\nGrape also:\n\n* respects Git ignores and local privacy ignores\n* excludes `.grape/` runtime state from snapshots\n* blocks common raw secret shapes before artifact output\n* avoids exposing raw secret values in diagnostics\n* separates raw evidence from assistant-written summaries\n* prevents summaries from becoming durable proof\n\nRepository content is still untrusted input. Source files, comments, docs, tests, and fixtures can contain prompt-injection text or private implementation details. Review context before forwarding it to an LLM, and keep real secrets in ignored files.\n\n## How Grape works\n\nGrape has three core stages.\n\n### 1. Compile\n\nGrape reads the working tree, branch state, source excerpts, project rules, manifests, observed command results, and narrow proof-backed claims.\n\nIt builds a `ContextArtifact` for the current task.\n\n### 2. Track\n\nEach artifact records the files, rules, proofs, config, branch state, manifests, and dependency hashes that shaped it.\n\nWhen those inputs change, Grape can detect stale context instead of silently reusing it.\n\n### 3. Diff\n\nGrape compares the latest artifact with what the same agent session already received.\n\nIt then returns a `ContextPack` containing only the useful delta.\n\n```mermaid\nflowchart LR\n  Agent[AI coding agent] --\u003e MCP[MCP or CLI]\n  MCP --\u003e Compile[Compile context]\n  Compile --\u003e Artifact[Context artifact]\n  Artifact --\u003e Diff[Session diff]\n  Diff --\u003e Pack[Context pack]\n  Pack --\u003e Agent\n  Repo[Git working tree] --\u003e Compile\n  State[(Local SQLite state)] --\u003e Compile\n  State --\u003e Diff\n```\n\n## Core guarantees\n\nGrape is built around strict context rules:\n\n* **Repository state is the source of truth.** Context comes from the working tree, branch state, rules, evidence, and local session ledger.\n* **Diffs are session-scoped.** One session cannot omit context just because another session saw it.\n* **Pinned context is resent.** Safety-critical rules and constraints are not optimized away.\n* **Stale context is invalidated.** Branch, file, rule, config, manifest, and proof changes can invalidate prior context.\n* **Proof is not summary.** Assistant-written summaries cannot promote themselves into durable truth.\n* **Compression is cache, not truth.** Summaries may reduce repeated transport cost, but they do not prove behavior.\n* **Current context beats merely relevant context.** Stale, private, branch-invalid, dirty-scope, or contradicted context is filtered before ranking.\n\n## What Grape is not\n\nGrape is not:\n\n* a chatbot\n* a coding assistant\n* a vector database\n* a cloud memory platform\n* a correctness prover\n* a full repo graph daemon\n* a replacement for tests or review\n\nGrape does not prove that an agent’s answer is correct. It gives the agent better repository context to work with.\n\n## Language support\n\nGrape currently has its strongest graph signal for TypeScript and JavaScript.\n\nFor other languages and text formats, Grape uses safe fallback behavior unless stronger support is proven through fixtures.\n\nFallback coverage includes:\n\n* Python\n* Java\n* Kotlin\n* Go\n* Rust\n* C#\n* Ruby\n* PHP\n* Swift\n* C\n* C++\n* shell\n* JSON\n* YAML\n* TOML\n* Markdown\n\nFallback does not mean ignored. It means Grape avoids pretending it has precise graph knowledge when it only has exact source, paths, lexical matches, or explicit references.\n\n## Benchmark evidence\n\nGrape includes benchmark fixtures and scripts for local comparison. Recorded numbers are fixture evidence only. They are not production performance proof or claims that Grape beats naive context, search, or external tools unless a committed result file, command, date, and limits are named together.\n\n### Transport fixtures\n\n`npm run bench` exercises the installed package on six named fixtures. On the three no-change transport fixtures, the second same-session turn reduced body-token context with zero unsafe omissions and zero stale sends:\n\n| Fixture | Turn 1 body tokens | Turn 2 body tokens | Reduction |\n| --- | ---: | ---: | ---: |\n| `clean-typescript-app` | 2811 | 1663 | 50.4% |\n| `polyglot-fallback-repo` | 3132 | 2523 | 31.46% |\n| `monorepo-lite-repo` | 3388 | 1885 | 52.07% |\n\nThe same run also passed branch-switch, stale-source, and session-reset invalidation fixtures.\n\nThat supports the core beta transport claim on these fixtures: Grape can omit unchanged same-session context, keep restore metadata for omitted items, and invalidate prior context when files, branches, or sessions change.\n\n### Published-package baselines\n\n`npm run bench:post-beta` compares the published npm package with naive and search baselines on three small tasks. Results report file-level recall, known-noise ratio, layered output metrics, and rough serialized output size.\n\nPost-beta baselines help answer whether Grape finds the right files and where known-irrelevant paths enter the compiled output. They do not prove token-size savings against naive or search, production readiness, or superiority over external tools.\n\nSee [Benchmarks](docs/v1/quality/benchmarks.md) for commands, fixture names, result files, and caveats.\n\n## Project status\n\nGrape is currently in 1.0 beta.\n\nThe beta focuses on local context transport, session-aware diffs, restore behavior, stale context invalidation, proof separation, and MCP integration.\n\nImplemented today:\n\n* global npm install through `grape-context`\n* `grape init --connect`\n* local SQLite runtime state\n* CLI and MCP context retrieval\n* session-aware context packs\n* omitted context restore\n* branch, source, and session invalidation\n* dependency-tracked context artifacts\n* exact source and rule proof rows\n* narrow current-valid claims\n* TypeScript and JavaScript indexing for common imports, exports, symbols, calls, and related test hints\n* safe fallback for supported text files\n* observed command and test evidence through `grape run` and `grape test`\n* local check suite, benchmark fixtures, package smoke, and packaged MCP smoke\n\nNot promised yet:\n\n* production stability\n* cloud sync\n* broad agent memory\n* full semantic ranking\n* embeddings\n* complete call graphs\n* broad language-aware graph extraction\n* automatic conflict resolution\n* broad durable claim promotion\n* benchmark superiority claims\n* guaranteed behavior in every IDE MCP client without a human client trial\n\nAPIs, schemas, command names, setup guidance, and internal contracts may still change before stable 1.0.\n\n## Development\n\nInstall dependencies:\n\n```bash\nnpm ci\n```\n\nRun the local gate:\n\n```bash\nnpm run check\n```\n\nRun the extended beta-readiness gate:\n\n```bash\nnpm run beta:check\n```\n\n`npm run check` covers documentation structure, fixtures, in-memory context loop checks, architecture boundaries, storage migrations, TypeScript typechecking, package dry-run contents, and behavior tests.\n\n`npm run beta:check` runs the local check suite, benchmark fixtures, and packaged MCP smoke. The packaged MCP smoke validates stdio MCP behavior from an installed package. It is not a replacement for a human Cursor or Claude Code UI trial when release policy requires one.\n\nAfter installing the published package globally, run:\n\n```bash\nnpm run global:smoke\n```\n\n## Documentation\n\nStart here:\n\n* [Documentation index](docs/README.md)\n* [V1 documentation](docs/v1/README.md)\n* [Implementation contract](docs/v1/SPEC.md)\n* [Architecture overview](docs/v1/architecture/overview.md)\n* [State machine](docs/v1/architecture/state-machine.md)\n* [Invariants](docs/v1/architecture/invariants.md)\n* [Roadmap](ROADMAP.md)\n* [Contributing](CONTRIBUTING.md)\n\nCore references:\n\n* [Trust model](docs/v1/core/trust-model.md)\n* [Context artifact](docs/v1/contracts/context-artifact.md)\n* [Context diff](docs/v1/contracts/context-diff.md)\n* [Agent sessions](docs/v1/interfaces/agent-sessions.md)\n* [Compression](docs/v1/core/compression.md)\n* [Storage](docs/v1/core/storage.md)\n* [Security](docs/v1/core/security.md)\n* [MCP tools](docs/v1/interfaces/mcp-tools.md)\n* [CLI](docs/v1/interfaces/cli.md)\n* [Testing](docs/v1/quality/testing.md)\n* [Benchmarks](docs/v1/quality/benchmarks.md)\n\n## Contributing\n\nGrape is not ready for broad feature expansion yet.\n\nContributions should preserve the implementation contract and avoid expanding the product surface before the current roadmap goal is proven.\n\nBefore contributing, read:\n\n* [Contributing guide](CONTRIBUTING.md)\n* [Invariants](docs/v1/architecture/invariants.md)\n* [Roadmap](ROADMAP.md)\n\nImplementation standards:\n\n* no godfiles\n* no generic utility dumps\n* no hidden state transitions\n* no direct SQLite access outside storage repositories\n* no summaries as proof\n* no MCP writes that promote durable truth\n* no stale dependency manifests in returned context\n\n\n## Star History\n\u003cp align=\"center\"\u003e\n\n  \u003ca href=\"https://www.star-history.com/?repos=gael55x%2FGrape\u0026type=date\u0026legend=top-left\"\u003e\n   \u003cpicture\u003e\n     \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://api.star-history.com/chart?repos=gael55x/Grape\u0026type=date\u0026theme=dark\u0026legend=top-left\" /\u003e\n     \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://api.star-history.com/chart?repos=gael55x/Grape\u0026type=date\u0026legend=top-left\" /\u003e\n     \u003cimg alt=\"Star History Chart\" src=\"https://api.star-history.com/chart?repos=gael55x/Grape\u0026type=date\u0026legend=top-left\" /\u003e\n   \u003c/picture\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgael55x%2Fgrape","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgael55x%2Fgrape","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgael55x%2Fgrape/lists"}