Skip to content

README.md

Latest commit

 

History

History
107 lines (87 loc) · 9.43 KB

README.md

File metadata and controls

107 lines (87 loc) · 9.43 KB
Raw

Graphit Code Documentation

Graphit is a context and control plane for AI software engineering. It connects structural code, maintained documentation, persistent memory, deterministic shared tasks, reusable ecosystem artifacts, and bounded live agent runs. This hub routes developers, operators, and coding agents to current guidance without mixing it with historical implementation records.

Graphit Knowledge Explorer showing this project's architecture

Choose your path

I want to… Start here Continue with
Install Graphit and initialize a repository Getting Started CLI Reference
Configure local accounts, enterprise OIDC, broker storage, or multiple profiles Authentication Broker Storage and UI Network
Integrate an enterprise identity provider end to end OIDC Integration Hub Access Control
Centralize OIDC/anonymous ACLs, restricted S3 sessions, embeddings and rerank Graphit Broker Authentication
Use Graphit day to day User Manual Troubleshooting
Understand every setting and feature switch Configuration Reference Configuration Specification
Choose an agent CLI, embedding model, or rerank provider AI Models, Providers, and Agent CLIs AI Engine
Start, monitor, and troubleshoot the background service Daemon Operations and Monitoring Daemon Module
Configure an agent or MCP client MCP Tools Reference Retrieval Architecture
Coordinate resumable work across agents Task workflow Task Module
Inspect or export complete Task records Task workflow CLI Reference
Choose between FTS, semantic, hybrid, graph, AI, and live search Retrieval Architecture AI Engine
Add or customize a language parser AST Grammars and Parser Extensibility AST Module
Share context across repositories and machines User Manual Hub Collaboration
Understand project IDs, names, rename, and early identity Project Identity Storage Layout
Design or operate selective Hub access Hub Access Control S3 and UI Network
Understand system boundaries Architecture Overview Storage Layout
Operate shared storage or networked UI S3 and UI Network Hub S3 Object Layout
Serve a team over MCP from a container Run as a Server in a Container MCP Tools Reference
Publish current AST and knowledge contexts from CI Publishing from GitHub Actions Hub Collaboration
Customize a private distribution Private Brand Customization Configuration Specification
Contribute to the project Contributing Repository README

Guides

Guides explain workflows from a user or operator perspective.

  • Getting Started — installation, setup, project initialization, first sync, and the Observatory.
  • Authentication providers and account profiles — named local, direct OIDC, and Broker-managed providers, login/logout, multiple profiles, MCP/Broker Bearer, dynamic broker storage, and non-interactive operation.
  • OIDC Integration — native consumer and confidential broker-admin registration, PKCE, claims, HTTP MCP bearer propagation, direct relay/RFC 8693 exchange, Keycloak, Entra ID, Auth0, CI, and troubleshooting.
  • Graphit Broker — provider modes, SQLite/PostgreSQL/MySQL persistence, OIDC/RBAC administration, transactional SQL ACLs, restricted STS issuance, embeddings/rerank, revision rollout, and troubleshooting.
  • User Manual — everyday AST, knowledge, memory, Hub, daemon, Dream, and ecosystem workflows.
  • Configuration Reference — every supported key, default, module switch, provider, deployment profile, and runtime environment control.
  • AI Models, Providers, and Agent CLIs — completion CLI resolution and protocols, local/remote embeddings, model dimensions, rerank providers, credentials, and data boundaries.
  • Daemon Operations and Monitoring — startup, schedulers, every monitored signal and loop, project parking, services, runtime files, logs, replacement, and recovery.
  • Capability and Surface Matrix — implemented modules, CLI/MCP/UI availability, gates, and current boundaries.
  • Filesystem, State, and Watchers — special files, generated state, adapter layouts, and change detection.
  • AST Grammars and Parser Extensibility — complete YAML schema, selectors, Tree-sitter and ANTLR extension boundaries, distribution, and validation.
  • CLI Command Reference — commands, flags, aliases, and expected effects.
  • MCP Tools Reference — agent-facing tool contracts and required parameters.
  • Retrieval Architecture — when to search, read source, traverse a graph, or use live search.
  • Ignore Files — source and documentation exclusion behavior.
  • S3 Credentials and UI Network — optional remote storage, credentials, binding, CORS, and security boundaries.
  • Run as a Server in a Container — the root Dockerfile: an MCP endpoint any AI agent can connect to, the daemon as PID 1, and serving Hub artifacts with no checkout on the server.
  • Publishing from GitHub Actions — non-interactive runtime setup plus provider/login, explicit indexing, and publication to a production Hub.
  • Private Brand Customization — branded binaries and private collaboration environments.
  • Troubleshooting — common operational failures and diagnostics.

Architecture

Module specifications

Specifications describe current module behavior and technical contracts.

Historical records

The following areas are intentionally preserved as chronological evidence:

  • Task history — authoritative LanceDB task/event/comment/check tables, queried through Graphit Task.
  • changelogs/ — feature and migration history.
  • decisions/ — accepted architectural decisions and their trade-offs.
  • reports/ and testing/ — point-in-time validation evidence.

Historical records may describe superseded behavior. For current usage, prefer guides, architecture pages, and module specifications; follow links into history when you need rationale or provenance.

Documentation conventions

  • Maintained documentation and the root README are written in English.
  • User workflows belong in guides/; system boundaries in architecture/; module contracts in specs/.
  • Implementation work is created, claimed, checked, commented, and completed through Graphit Task; do not create Markdown task logs.
  • Commands and file paths use code formatting; security limitations are stated next to the relevant configuration.
  • Screenshots should use the current Graphit Observatory UI and a first-party Graphit Code project context.

Keep the wiki current

The daemon watches the documentation tree and rebuilds the local knowledge wiki after edits. Use graphit sync when you need an explicit all-system checkpoint across AST, knowledge, memory, Task guidance, and Hub.