The context and control plane for AI software engineering.
Website · Install · First run · Configure · Documentation · Contributing
Models are probabilistic. Engineering work cannot be.
Coding agents usually enter a repository with four blind spots:
- source text does not tell them the exact structural relationships in the code;
- a new session does not remember yesterday's correction or architectural decision;
- concurrent agents can duplicate work, overwrite ownership, or stop without a resumable checkpoint;
- documentation, sibling projects, and reusable agent tooling live in disconnected places.
Graphit closes those gaps with one local-first system that works across agents, IDEs, repositories, machines, and model providers:
| Signal | What Graphit provides | What the agent can do |
|---|---|---|
| AST | Language-aware entities, source, and exact graph relationships | Find candidates with FTS + vectors, then prove callers, imports, inheritance, dependencies, and impact with Cypher |
| Knowledge | A compiled wiki built from maintained project documentation | Search pages, read only the relevant source, follow cross-references, and verify provenance |
| Memory | Durable project and user scopes with revision history | Carry corrections, conventions, decisions, and learned procedures across sessions and repositories |
| Task | A shared LanceDB scheduler with fenced claims, dependencies, checks, comments, immutable audit history, and complete JSON export | Coordinate parallel agents, make takeover safe, inspect work in the Task Explorer, and make incomplete work impossible to close |
| Hub | A versioned registry for reusable agent capabilities and contexts | Share rules, skills, agents, commands, MCP servers, languages, ASTs, and knowledge across systems |
| Observatory | One operational workspace over the same stores agents use | Explore code, docs, memory, live runs, daemon state, Dream, and ecosystem projects without a second data model |
Graphit does not make a language model deterministic. It puts deterministic discovery, ownership, validation, persistence, and completion gates around whichever coding agent you choose.
- One project, many agents. Atomic claims and fencing tokens prevent stale writers; checkpoints,
typed decisions, and
next_steplet another agent resume without reconstructing the work. - One engineer, many systems. Project memory stays repository-specific while user memory follows personal conventions across projects. Registered sibling projects retain independent stores.
- One team, many machines. S3-backed providers share versioned Hub artifacts and authoritative Memory/Task LanceDB tables. S3-enabled Broker providers receive restricted in-memory temporary credentials per project/user/Hub scope while deny-by-default ACLs and IAM policy govern the remote prefixes.
- One framework, many assistants. Native adapters support Codex, Claude Code, Cursor, Gemini CLI, Kiro, OpenCode, Antigravity, Qwen Code, Kimi Code, and Deep Code; any MCP client can use the server endpoint.
- One query, several retrieval modes. BM25 full-text search, semantic vectors, hybrid reciprocal rank fusion, exact graph traversal, and source slicing serve different evidence needs.
The web UI is an operational view over the same project context exposed to agents.
| Knowledge Explorer | Memory Explorer |
|---|---|
 |
 |
These screenshots use Graphit Code itself as the example project. The same Observatory also includes a Task Explorer with a paginated task catalogue, server-side status/search filters, complete specs, checks, dependencies, subtasks, comments, lifecycle events, revision history, and JSON download.
Prebuilt releases support Linux, macOS, and Windows.
curl -fsSL https://raw.githubusercontent.com/graphit-labs/graphit-code/main/install.sh | shirm https://raw.githubusercontent.com/graphit-labs/graphit-code/main/install.ps1 | iexThe installers detect the platform, download the latest archive, verify its SHA-256 checksum, and install the launcher in a user directory. On the next invocation, the launcher extracts a changed Core, the daemon replaces itself, and the stdio MCP proxy asks connected clients to refresh their tool catalog through the protocol's list-change notification. Pin a release with --version <tag>. See the getting started guide for manual downloads, custom paths, and source builds.
For the usual local workflow, run Graphit from the repository it should understand:
cd your-project
graphit setup
graphit init --agent codex
graphit sync
graphit uigraphit setup prepares installation/runtime defaults and persists a real provider named local
with local embedding/rerank and ONNX auto/0. It does not create a profile. With no active
profile, AI resolution uses that provider, recreating it if it was removed, while identity remains
anonymous and remote Hub remains unavailable. init, AST, Knowledge, Memory, and Task still work.
Inspect the default provider and log in only when a named identity is needed:
graphit provider show local
graphit login --profile personal --provider local --username "$USER"Use graphit provider update local to select CPU, CUDA, CoreML, or remote AI services. Local models
download lazily on first use.
graphit init
ensures the project identity, preserving an ULID already created by an earlier stateful operation,
installs the selected agent's native MCP/hooks, and performs the first synchronization. graphit sync
is the explicit all-system checkpoint; the daemon keeps incremental indexes current afterwards.
Use the exact agent identifier supported by your environment; graphit init --help lists the available values.
The local workflow above does not require a server deployment. When external agents (including
web-based agents) need to connect over MCP, you can run Graphit as a shared service instead.
The root Dockerfile builds a server with the daemon as PID 1, publishing an MCP endpoint and
the UI.
Any MCP-capable AI agent can connect to it — Claude Code, Codex, Gemini, Cursor, OpenCode, Copilot, Kiro, Qwen Code, Kimi Code, Deep Code, or your own client. The agent runs wherever the developer is and brings its own model; the server supplies published code graphs, documentation wikis, and memory it reasons over. One container can serve a team without requiring each remote client to index anything locally.
docker build -t graphit-code .
docker run -d --name graphit \
-p 127.0.0.1:8080:8080 \
-p 127.0.0.1:8081:8081 \
-v graphit-global:/opt/graphit \
graphit-codePoint a client at http://your-server:8081/mcp with Authorization: Bearer <key>. In the UI, open System → Daemon to copy the full active key from MCP bearer key and confirm the endpoint. The server holds no source checkouts and needs none—it answers about Hub artifacts addressed reproducibly as id@version.
Remote agents can load the server's current routing contract with graphit_mandates and fetch the
complete source of any core module skill with graphit_module_skill. Start from the copy-ready
remote agent skill.
For a broader enterprise or team ecosystem, the optional, separately deployed Graphit Broker complements the MCP server with centralized identity, access control, shared storage, and embedding/rerank services. It is not required for the local workflow or for a basic MCP server.
The MCP endpoint accepts the fresh runtime key shown in System → Daemon. A local provider may
also define a static MCP key. With a direct OIDC or Broker-managed provider, each remote caller
sends its own access token; Graphit verifies its JWT signature, issuer, audience, expiry, client,
scope, and identity claims through the configured or Broker-discovered JWKS and
preserves that identity through broker Hub ACL, S3, embedding and rerank calls. Direct OIDC may use
bearer relay or explicit RFC 8693 exchange; Broker-managed login uses the Broker-issued token.
graphit mcp --stdio always bridges to this daemon listener and resolves the active profile before
each HTTP request, so OIDC/Broker token refresh is picked up automatically; without such a session,
it uses the local profile key or current daemon runtime key.
For a broker provider, Graphit is always a standard native OIDC client: the Broker owns the login
page and may offer local password/MFA, upstream OIDC, or both without exposing those credentials or
upstream tokens to Graphit.
Provider/profile secrets live in the
mode-0600 global authentication store, while the generated runtime key remains in its restricted
runtime file. The UI has no built-in authentication, and CORS is not authorization,
so keep both ports on a trusted
network or put an authenticated proxy in front. Read
Running Graphit Code as a server in a container before exposing them.
Graphit indexes declarations and relationships from Tree-sitter and ANTLR grammars into an Icebug/LadybugDB graph. A separate Lance sidecar combines BM25 full-text and semantic vector results with reciprocal rank fusion. Agents use ranked search to find the likely entity, exact Cypher to establish relationships, and a source call to read only the relevant lines.
MATCH (caller)-[:CALLS]->(target:Function {name: 'RunSync'})
RETURN caller.name, caller.pathThe graph opens on the fly from Icebug files into an in-memory catalog, so published contexts remain
portable without running a separate graph server. Optional local, direct, or broker-based
second-stage reranking is active in AST and Knowledge searches when search.rerank=true. See the
AI Engine specification.
The knowledge module compiles docs/ and the root README into a searchable wiki. Pages retain their source, confidence, links, and update history; agents read the selected page after search instead of treating a ranked title as the answer.
Project memory captures repository-specific decisions and corrections. User memory captures portable personal conventions. Both are stored outside the checkout and exposed through the same search-and-read workflow.
Graphit Task replaces host-native TODO lists and repository Markdown task logs with one local project task database. Agents search prior work, atomically claim a ready task, checkpoint progress and decisions, revise scope through expected-revision fencing, supersede obsolete checks without erasing history, verify active acceptance/test checks with evidence, and release or complete through fenced transitions. Dependencies and nested subtasks gate readiness and completion; flags carry a reason and block completion until resolved. Task IDs are compact hashes that lengthen only on a detected collision, while conditional writes prevent one task from overwriting another. Direction changes deterministically cancel useful history or remove certainly erroneous, unreferenced tasks so no obsolete work is left open. The Observatory discovers work through a lightweight paginated catalogue and loads the same versioned complete JSON export as CLI and MCP only for exact detail or an explicit project download.
Registered sibling projects keep their own AST, wiki, and memory. Hub artifacts package reusable capabilities when a project or team intentionally publishes them. An optional broker exposes shared catalogs and published contexts through short-lived per-operation URLs; everyday local operation does not require a hosted database.
Live Search prepares a throwaway project from selected Hub artifacts, installs the requested agent environment, streams a bounded agent session, and removes the project data when the session is deleted. It is the on-the-fly path for questions that genuinely span several codebases or knowledge bundles; direct AST, Wiki, Memory, and Task tools remain the cheaper path for focused questions.
| Goal | Setting |
|---|---|
| Keep everything local | configure no broker and use local embedding/rerank modes |
| Share Hub artifacts | configure S3 on a local provider, configure STS on a direct OIDC provider, or use a Broker provider that advertises graphit-s3-credentials-v2 |
| Use enterprise SSO | configure an OIDC provider with claim mappings, an MCP audience, and either shared-audience broker relay or RFC 8693 exchange |
| Run without an installed coding-agent CLI | modules.agent=false |
| Keep autonomous Dream work off/on | modules.dream=false (default) or true |
| Serve the Observatory from the daemon | modules.daemon_ui=true |
| Disable the daemon filesystem watcher | modules.sync=false (manual graphit sync still works) |
| Disable background embedding work | modules.embedding=false |
| Select a remote embedding backend | use a brokerless provider with --embedding-mode direct, or configure a broker with both embedding and rerank modes set to broker; then supply account secrets through graphit login |
| Select a remote rerank backend | use native Cohere/Voyage/Jina or embedding-simulated OpenAI/OpenAI-compatible/Google with --rerank-mode direct; simulated modes also require --rerank-dimensions |
| Restrict indexed languages | ast.grammars_whitelist / ast.grammars_blacklist |
| Move or narrow the documentation tree | knowledge.docs_dir, knowledge.extensions, knowledge.include_readme |
Every normal key can be set per command, environment, project, global installation, or private-build default. The complete configuration reference documents every key, default, switch, provider, network boundary, and runtime resource control.
- Mutable project sources and compiled local stores remain on the machine by default.
- Hub publication is optional. When enabled, Graphit mounts S3 directly. Local providers use the configured AWS identity; direct OIDC and Broker providers receive short-lived, scope-specific STS credentials only in process memory when storage is configured or the Broker advertises storage. Without that capability, the authenticated Broker profile uses local storage.
- S3 is authoritative for Hub artifact data; broker SQL or standalone
projects.jsonis selected as the provider's one ACL authority.~/.<brand>/hubis only a bounded, subject-isolated metadata cache; it never grants access or replaces remote validation. - A project name is mutable discovery metadata. Its immutable ULID owns remote paths, locks, and exact grants.
- The UI binds according to
ui.hostand has no built-in authentication layer. - Remote UI access requires an appropriate firewall, VPN, or authenticated reverse proxy; CORS is not authorization.
- Local work uses its active profile. HTTP MCP verifies each caller's OIDC token and carries that request identity to the broker by relay or RFC 8693 exchange; local providers may use a static broker key. The Broker maps its current ACL to a short-lived STS session policy; S3 bucket/IAM policy remains the final data-plane boundary and object bodies travel directly between Graphit and S3.
See S3 STS storage and UI network configuration before exposing the UI or configuring shared storage. The normative contracts are Project identity, Hub access control, and Hub S3 object layout.
Start with the document that matches your intent:
- Getting started — install and initialize a project.
- OIDC integration — register native consumer and confidential broker-admin clients, map claims, propagate HTTP MCP identity, configure web-identity STS, and troubleshoot Keycloak, Entra ID, or Auth0.
- Graphit Broker — operate the SQL/OIDC/RBAC control plane, centralize transactional consumer ACLs, issue restricted STS sessions, and own embedding/rerank credentials, routes and caches.
- User manual — daily workflows and operational concepts.
- Configuration reference — every setting, default, feature switch, provider, and environment override.
- AI models, providers, and agent CLIs — completion delegation, every CLI protocol, embedding models, credentials, dimensions, rerank, and local/remote boundaries.
- Daemon operations and monitoring — start paths, schedulers, watched signals, module loops, MCP service, logs, parking, and recovery.
- Capability and surface matrix — every module, CLI/MCP/UI exposure, gate, and current limitation.
- Filesystem, state, and watchers — special files, generated state, adapter layouts, and change detection.
- AST grammars and parser extensibility — every YAML field, selector, parser extension path, precedence rule, and validation workflow.
- CLI reference — commands and flags.
- MCP tools reference — agent-facing tool contracts.
- Architecture overview — system boundaries and data flow.
- Storage layout — what lives in a project and what lives globally.
- Task module — shared lifecycle, ordered batches, durable claims, checks, hooks, and takeover guarantees.
- UI specification — Observatory behavior and backend contract.
- Documentation hub — the complete maintained documentation map.
Task history lives in the authoritative LanceDB tables; changelogs and accepted decisions remain documentation evidence. The documentation hub separates historical records from current operational guidance.
Source builds require Go 1.26.6+, Node.js 22+, Make, and a C/C++ toolchain. The normal build downloads an immutable, checksum-verified native dependency bundle from graphit-labs/graphit-libs. That companion repository owns the LanceDB patch and its explicit Rust source-build target.
git clone https://github.com/graphit-labs/graphit-code.git
cd graphit-code
make install
graphit setupPlatform-specific targets and development checks are documented in Getting Started and Contributing.
Graphit Code is under active development. Interfaces, storage formats, and supported integrations may evolve between releases. Prefer the documentation on the same branch or release as the binary you are using.
Licensed under the MIT License.
If Graphit improves your agent workflow, consider sponsoring its development.