CLAUDE.md - Project Instructions for AI Agent

Dockerized GraphRAG and vector-context MCP service for Claude CLI: an isolated PostgreSQL + pgvector database, a Python code-graph indexer, a Python MCP server and a Python dashboard, orchestrated by Docker Compose. Host codebases are served read-only by a host agent, the graph and embeddings live in PostgreSQL, and the tools are exposed over MCP (Streamable HTTP, SSE kept for older clients).

Rules

1. Docker-first. Every service is configured and launchable from docker-compose.yml. Schema changes are numbered Alembic revisions in packages/core/src/enggraph/core/migrations/versions/, created with make db new NAME=<slug>; never edit a revision that has already been applied.
2. Read-only codebases. A tree reaches the stack only through its host agent, which serves it read-only. No volume mounts a tree, on any stack. Containers never mutate host source files.
3. Pure ASCII English in all code, comments, docstrings, docs and commit messages. No emoji, no non-ASCII characters anywhere.
4. Pre-commit passes before any commit. When a new file extension enters the repository, add its hook to .pre-commit-config.yaml - that is mandatory, not optional.
5. Commits go through commitizen, never by hand. See the commit skill.
6. Python is PEP 8 with explicit type hints and real exception handling. The dashboard's and the viewer's scripts are plain JavaScript with no build step.

Schema and parsers

• Every table is scoped to a row of projects: one database holds the graph of every indexed codebase, and nodes is keyed on (project, id).
• No foreign keys and no cascades. Tables are tied by plain value columns (project, node_id), and whatever a cascade would do the code does explicitly, in the same transaction: storage.PROJECT_COLUMNS for a project drop or rename, storage.ABOUT_COLUMNS for records that outlive the project they name, storage.drop_dependents for deleted nodes.
• New functionality goes into new tables. A revision never holds REFERENCES, FOREIGN KEY or CASCADE, and ALTER TABLE only changes one column's type or size, each time with the user's explicit permission; the migrations-without-keys hook rejects the rest, in revisions and in models.py alike. A revision is DDL passed to op.execute, and models.py names the same tables for code: test_models.py holds the two together. A table whose shape must change otherwise is copied into a new one under a new name. The database skill holds the full rules.
• File and chunk text is never stored. It is read from the project's host agent through the worker API; a chunk keeps its line range, words and vector.
• A migration finishes in minutes on the standard stack: no UPDATE over a large table and no rebuilt vector index.
• Infrastructure formats get Tree-sitter parsers in packages/indexer/src/enggraph/indexer/parsers/. Programming languages go to the code extractor: extract_code of their parser in parsers/languages.py, resolved in indexer/codegraph.py, the extension in OWN_CODE_EXTENSIONS in config.py. A format no published grammar reads (RPM specs, setup.cfg, systemd units) is read in Python through TextParser in parsers/base.py.
• A project tree is read only through enggraph.core.trees, and only its host agent answers: no container holds a tree.
• MCP tools live in packages/mcp/src/enggraph/mcp/: tools.json holds their names, descriptions and schemas, handlers.py one function each.

Stack

PostgreSQL 16 (pgvector/pgvector:pg16) - Python 3.11+ with tree-sitter, networkx, psycopg2-binary, sqlmodel, alembic, mcp, fastapi, jinja2 - htmx for the dashboard's pages. Tooling: pre-commit, commitizen (wyld-cz adapter when installed), ruff, djlint, prettier, shellcheck.

Layout

• /packages/ - the Python services, one package and one image each under the enggraph namespace: core (shared library, the models and the Alembic revisions, with the Makefile behind make db), indexer (library and index job), api, embed, summarize, viewer, mcp (the MCP server), web (the dashboard: a JSON API over the same schema under routes/, and Jinja2 pages over the same functions under templates/).
• /packages/agent/ - the host agent, a Rust binary serving a tree to the stack.
• /dev/web/ - the dashboard's Penpot mockups, drawn in the disposable stack penpot-local-stack runs.
• /skills/ - the skills the MCP server hands to agents, baked into the api image: enggraph, commit, database, delegate, write-docs. /.claude/skills/ holds the copies the agent wrote.
• /templates/ - the CLAUDE.local.md an onboarded codebase is given.
• /scripts/ - install.sh and mcp_register.py drive make install; backup.sh and restore.sh drive the database targets.

Current state is tracked in the roadmap the MCP server holds: get_roadmaps. Implementation may be handed to the Gemini CLI - see the delegate skill.