Keeping your CodeGraph index fresh

Goal

By the end you'll know when CodeGraph keeps your index up to date automatically, when you have to do it by hand, and how to check the state of the index.

The index is a copy of your code. When the code changes and the index does not, your agent trusts a map that no longer matches the territory. A stale index is worse than none.

Prerequisites

CodeGraph installed and a project indexed with codegraph init (see the install guide).
A coding agent connected to CodeGraph through MCP.

This guide covers CodeGraph v1.6 as of October 2026.

Steps

1. Understand the automatic sync

When your agent launches the CodeGraph MCP server (codegraph serve --mcp), the server starts a file watcher over the project. Per the official docs it uses native file events (FSEvents on macOS, inotify on Linux, ReadDirectoryChangesW on Windows):

When one or two files change, it syncs about 300 ms later, and only what changed.
Bursts of edits are collapsed into a single sync (default debounce: 2 seconds).
If some files are pending re-index, the tool responses carry a warning so the agent reads those files directly.

The key limit: the watcher runs only while the MCP server is running. When you close the agent session, it stops.

2. Know when you must sync by hand

Run a manual sync when changes happened while the watcher was not running:

You edited code with the agent closed (in another editor, for example).
You ran git pull, git checkout, or git rebase and many files changed.
The operating system ran out of file-watch resources. CodeGraph disables auto-sync once and prints a message telling you to run codegraph sync.

3. Sync manually

cd path/to/your/project
codegraph sync

This is an incremental update of what changed since the last index. It is fast. Its --quiet flag suppresses output and is meant for git hooks.

4. Check the index

codegraph status

It shows the number of files, nodes, and edges, and flags an index that was built by an older version of the engine than the one you are running.

5. After upgrading CodeGraph

codegraph upgrade --check   # is there a newer version?
codegraph upgrade           # install it
codegraph sync              # incremental refresh of your index

Existing indexes keep working after an upgrade, but they were built by the previous version. codegraph sync is the fast refresh. If you want the new version's extraction improvements applied everywhere, the upgrade output also suggests codegraph index -f, a full rebuild that takes longer.

Expected result

You edit a file while your agent is open, and the graph updates by itself within seconds.
After a git pull, codegraph sync brings the index up to date.
codegraph status shows no stale-index warning.

Troubleshooting

Common issues

The graph does not reflect your edits: the watcher may not be running (agent closed) or may be blocked (some sandboxed environments, or an exhausted OS file-watch limit). Run codegraph sync.
Edits made on a different filesystem than the one the agent runs on (for example across a network or virtualization boundary): file events may not arrive. Run codegraph sync by hand and, if possible, edit and run the agent in the same environment.
Too many syncs while editing: raise the debounce with the CODEGRAPH_WATCH_DEBOUNCE_MS environment variable (between 100 ms and 60 s).
You want to turn auto-sync off: set CODEGRAPH_NO_DAEMON=1. You will then have to run codegraph sync yourself.

Next step

Put the index to work: ask your agent structural questions about your own project (what calls this, what breaks if I change it) and watch how it uses the graph.