Index code into a CodeGraph SQLite graph and query symbols, callers, and impact from the CLI or MCP.
1.1K
Index code into a CodeGraph SQLite graph and query symbols, callers, and impact from the CLI or MCP.
You learn to use codegraph in a Docker container.
This image contains CodeGraph, the
@colbymchenry/codegraph package on npm. CodeGraph parses source code into a local
SQLite graph of symbols, calls, and imports. AI coding assistants use this graph over
MCP to find code with fewer tool calls and tokens.
.codegraph/ directory of your project.CODEGRAPH_TELEMETRY=1 to enable the statistics.The base image is node:latest. The working directory is /workspace. The default
command starts Bash.
To run the tool server and the affected-tests Job on Kubernetes or Amazon EKS, use the manifests in codegraph/kubernetes. The AWS guide gives the steps.
| Tag | Meaning | Platform |
|---|---|---|
latest | Latest successful build from main with the newest CodeGraph release. | linux/amd64 |
View all tags on Docker Hub.
The latest tag changes when a new build passes its tests.
docker pull stden/codegraph:latest
Do these steps in your project directory. The commands mount the directory at
/workspace and run as your user, so the index files belong to you. Set a short
name for the command first:
alias codegraph='docker run --rm -i --user "$(id -u):$(id -g)" -v "$PWD":/workspace stden/codegraph:latest codegraph'
codegraph init .
codegraph status .
init creates .codegraph/ and builds the index. The directory has its own
.gitignore, so git does not see the database. status shows the number of files,
symbols, and edges for each language.
codegraph query UserService
codegraph callers login
codegraph callees login
codegraph explore "login session"
query finds symbols by name. callers and callees follow the calls in each
direction. explore returns the source code and the call paths of the symbols that
match the query. Add --json to query, callers, callees, impact, or affected for
machine-readable output.
codegraph impact login
codegraph affected src/auth.ts
impact lists the code that depends on a symbol. affected lists the test files
that depend on the changed files. This command runs git on your computer and sends
the changed file names to the container:
git diff --name-only HEAD | codegraph affected --stdin
codegraph sync .
sync reads only the changed files. Use codegraph index . --force to build the
index again from the start.
Add this server to the MCP configuration of your assistant. Replace /path/to/project
with the absolute path of your project.
{
"mcpServers": {
"codegraph": {
"command": "docker",
"args": [
"run", "--rm", "-i", "-v", "/path/to/project:/workspace",
"stden/codegraph:latest", "codegraph", "serve", "--mcp", "--path", "/workspace"
]
}
}
}
The server watches the project and updates the index when a file changes. If your
Docker host does not send file events to the container, add --no-watch. Then run
codegraph sync . after changes.
mcpo starts the CodeGraph MCP server and publishes each tool as a POST /<tool>
endpoint. The API description is at /openapi.json, and the interactive documentation
is at /docs. With --strict-auth, every request must send the key as
Authorization: Bearer <key>. CODEGRAPH_NO_DAEMON=1 keeps the MCP server in the
process tree of mcpo, so both stop at the same time.
openssl rand -hex 32 > mcpo-api.key
docker run -d --name codegraph-tools -p 127.0.0.1:8001:8000 --user "$(id -u):$(id -g)" \
-e CODEGRAPH_NO_DAEMON=1 -v "$PWD":/workspace stden/codegraph:latest \
mcpo --port 8000 --api-key "$(cat mcpo-api.key)" --strict-auth -- \
codegraph serve --mcp --path /workspace --no-watch
curl -H "Authorization: Bearer $(cat mcpo-api.key)" -H 'Content-Type: application/json' \
-d '{"query": "login session"}' http://127.0.0.1:8001/codegraph_explore
By default, the server has one tool: codegraph_explore. To add tools, set a list of
tools, for example -e CODEGRAPH_MCP_TOOLS=explore,search,node,callers,callees,impact. In
this mode, a project with fewer than 500 files gets only explore, search, and node.
To connect Open WebUI, put both containers on
one Docker network. Run docker network create ai-tools. Then run
docker network connect ai-tools open-webui and
docker network connect ai-tools codegraph-tools.
In Open WebUI, open Admin Panel → Settings → Integrations. In the Tools section,
under External Tool Servers, select Add Connection. Then select the OpenAPI
type. Enter the URL http://codegraph-tools:8000, the path openapi.json, and the Bearer
key.
The Open WebUI server calls the tool server for this connection, so the container name
works. For a connection in the personal Settings → Integrations, your browser calls the
tool server, so the connection must use the URL http://127.0.0.1:8001 instead.
codegraph uninit --force .
This command deletes .codegraph/. Your source files do not change.
init builds the full index. sync is fast because it
reads only the changed files. Use index . --force after a large refactor or a
branch switch with many changes..codegraph/. The database is local to each computer. Every
developer and every CI job builds its own index.affected to make CI faster. Run the affected tests on each change first.
Also run the full test suite on main, because affected sees only static
dependencies. It does not see dynamic imports, reflection, or configuration files.codegraph impact <symbol> before you
rename or delete a symbol. Then review each caller in the list.codegraph unlock ..--json in scripts. The text output can change between releases.--api-key and --strict-auth. Publish
the port on 127.0.0.1 only. Keep the key file out of git. The tools return your source
code to any person with the key.latest tag changes. If a CI job must give the same
result every time, pin a digest, such as stden/codegraph@sha256:....The smoke test runs the tutorial steps on TypeScript and Python files. It checks
init, status, query, callers, callees, impact, affected, sync, and
uninit. It also checks a codegraph_explore call to the MCP server, and the same tools
through mcpo with its API key.
Content type
Image
Digest
sha256:3e3b76704…
Size
520.6 MB
Last updated
1 day ago
docker pull stden/codegraph