Code graph from the CLI
Index a repository on your machine, serve it to your agents over MCP, and upload CI results into the Oxagen code graph.
The code graph is a map of your code. Each function, table, test, doc, environment variable, and deploy step is a node, and each link between two of them is an edge. Agents ask the graph questions through MCP calls instead of opening files one at a time.
The oxagen codegraph commands cover two jobs:
init,status,rebuild, andstopbuild and manage a graph of one repository on this machine.uploadsends the data only CI has, such as coverage and test reports, into the Oxagen code graph.
Local graph
The CLI builds the local graph on your machine, from whatever the working tree holds, and writes it to tables on that machine. Nothing it builds is uploaded. The collector on the machine then serves it as the machine's one MCP endpoint for code graph questions.
The local graph reads the working tree as it stands when init runs, and every change after that: committed files, staged and unstaged changes, and untracked files that .gitignore does not exclude.
A copy's pin is the HEAD commit plus a SHA-256 digest over the paths and contents of every file that differs from it, written 9f31c2e+d41c07. A clean tree's pin is the commit alone, so it matches the cloud copy of that commit.
oxagen codegraph init
oxagen codegraph init [path] [--embed-url <url>] [--scip]Indexes the repository at path, the current directory by default, starts watching it, and writes the codegraph MCP entry for Claude Code, Codex, Cursor, and Stella. It needs an enrolled machine, and it reads the workspace's embedding mode from the steering repo.
| Flag | Description |
|---|---|
--embed-url <url> | Points this machine at an embedding server on the machine, such as http://127.0.0.1:11434/v1/embeddings. It overrides the workspace's embedding mode. The vectors stay on the machine and are never uploaded. |
--scip | Also builds SCIP links. SCIP indexers run the repository's build tools, so the local build runs them only with this flag. |
oxagen codegraph status
oxagen codegraph statusLists each local graph with its pin, its build state, the jobs pending or failed, the embedding mode, and the base its cloud facts come from.
oxagen codegraph rebuild
oxagen codegraph rebuild [path]Builds a fresh copy from the current working tree. It reuses every cached step output whose inputs did not change.
oxagen codegraph stop
oxagen codegraph stop [path] [--purge]Stops watching the repository and removes its MCP entries. --purge also deletes the local tables.
CI upload
oxagen codegraph upload [flags]Sends coverage, test reports, runtime profiles, schema dumps, infrastructure plans, and API specs for the commit a pipeline ran on. The command signs in with the CI provider's OpenID Connect token and nothing else. It needs no oxagen login and no enrolled machine.
GitHub Actions mints the token inside the command when the job has permissions: id-token: write. GitLab writes it into OXAGEN_CODEGRAPH_TOKEN when the job declares id_tokens. The token must be one GitHub Actions or gitlab.com minted for the audience oxagen-codegraph-upload.
Each file flag takes lines of the form source=pattern and can repeat. A flag wins over the variable it stands for.
| Flag | Variable | Sources |
|---|---|---|
--coverage <source=pattern> | OXAGEN_CODEGRAPH_COVERAGE | coverage.py, jacoco, istanbul, go-cover, lcov |
--test-report <source=pattern> | OXAGEN_CODEGRAPH_TEST_REPORTS | junit |
--runtime <source=pattern> | OXAGEN_CODEGRAPH_RUNTIME | otel, pprof, py-spy, async-profiler, parca, pyroscope |
--schema-dump <source=pattern> | OXAGEN_CODEGRAPH_SCHEMA_DUMPS | postgres, mysql, sqlite, mssql |
--infra-plan <source=pattern> | OXAGEN_CODEGRAPH_INFRA_PLANS | terraform-plan, pulumi-preview, cdk-template, helm, kustomize |
--api-spec <source=pattern> | OXAGEN_CODEGRAPH_API_SPECS | openapi |
| Flag | Variable | Description |
|---|---|---|
--environment <name> | OXAGEN_CODEGRAPH_ENVIRONMENT | The deployed environment a runtime profile or schema dump came from. |
--api-url <url> | OXAGEN_CODEGRAPH_API_URL | The Oxagen API to upload to. The default is https://api.oxagen.sh. |
--fail-on-unconnected | OXAGEN_CODEGRAPH_FAIL_ON_UNCONNECTED | Fails the job when no workspace holds this repository. Off by default, so a fork or a repository that is not connected yet passes with a skip. |
A pattern with a glob character matches every file under the working directory except node_modules and .git.
Before it sends anything, the command drops every value Terraform marks sensitive, every Pulumi secret, and the data and stringData of every Kubernetes Secret in rendered Helm and Kustomize output. It then runs the Oxagen secret scanner over the text that is left. The server runs the same checks again and reads the repository and commit from the token.
The command exits 0 when every matched file was stored or was already held. It exits 1 when a setting is wrong, no token could be read, no file matched, or an upload failed.
Example for a GitHub Actions job:
oxagen codegraph upload \
--coverage "coverage.py=coverage.xml" \
--test-report "junit=reports/junit.xml"On any other runner, pass the token yourself:
OXAGEN_CODEGRAPH_TOKEN="$CI_OIDC_TOKEN" \
OXAGEN_CODEGRAPH_COVERAGE="lcov=coverage/lcov.info" \
npx @oxagen/cli codegraph uploadRelated
- Command reference: every
oxagencommand. - Knowledge graph from the CLI: search the workspace graph.