Your first code graph

Before you start#

You need a local checkout containing source code and the arbor executable on your PATH. Follow the installation guide if you have not installed it yet. Git is needed for the change-analysis commands.

The CLI and MCP bridge run locally. You do not need an Arbor Cloud account.

arbor --version
arbor --help

1. Index your project#

Open a terminal in the project you want to understand. Replace your-project with its directory.

cd your-project
arbor setup
arbor status

setup initializes Arbor and indexes the source files. It writes local configuration and graph data under .arbor/. status then scans the project again and reports what it found. For a four-file Python project, v3.0.3 prints:

📊 Arbor Status

  Files indexed: 4
  Nodes: 9
  Edges: 5
  Extensions: .py

Check these counts before trusting a query result. If Nodes is 0 or your language's extension is missing, start with troubleshooting.

Add .arbor/ to your .gitignore. It holds a graph built on your machine and, if you use receipts, the text of your requests to Claude Code. v3.0.3 does not ignore it for you (issue #233).

2. Get your bearings#

Start with a compact view of the repository, then search for a name you know. The symbol names below are examples; use a function from your own project.

arbor map . --exclude-test
arbor query parse_file
arbor callers parse_file
arbor callees parse_file

The map ranks symbols by their position in the graph. Callers show who uses a symbol; callees show what that symbol uses. When several files define the same name, both commands answer for each definition separately; the CLI reference shows that output. Open the reported source locations to confirm the relationship.

3. Investigate a change#

arbor refactor parse_file --why
arbor diff
arbor diff --base main

refactor explores the graph around one symbol. diff looks at your uncommitted Git changes; --base main covers everything since your branch left main, as a pull request shows it. Use the affected symbols to decide where to read next and which tests to run.

Keep the graph current#

Since v3.0.3, the graph records the commit it was built from. After a checkout, commit or rebase, the next command that reads the graph refreshes it and prints a note first:

note: HEAD moved from d4be9b0 to 7c569d4 since the last index; refreshing the graph.

After an upgrade, the note reads the saved graph was built by a different Arbor version; rebuilding it. While arbor bridge runs, the CLI leaves the graph to the bridge instead; troubleshooting covers that case. When results still look surprising, rebuild from scratch and check the counts again:

arbor index --no-cache
arbor status

Ready to use the same graph from an assistant? Connect an MCP client. Using Claude Code? Receipts show what each turn changed. For a walkthrough without installing anything, explore the recorded example.