When a project is a codebase — an app, a site, a library — attach the folder and build a Codegraph index. That map is how Grok finds its way around: which files exist, what they contain, and how pieces of code connect. Without it, Grok still chats, but it spends more time hunting.
What Codegraph is
Codegraph reads the source in the project folder and builds a local map. You see it in the Workbench as an index: file count, languages, and “symbols” (named pieces of code such as functions, types, and classes). Grok uses that map to answer “where is this?”, “what calls this?”, and “what would break if I change this?” without opening every file.
The index lives on your computer next to the project. It is not uploaded as a zip of the repo.
Codegraph is an open-source project: github.com/colbymchenry/codegraph.
Why it helps on code projects
- Faster orientation. A new chat can see the stack, a short summary, and the top of the folder tree instead of guessing from the name.
- Better edits. Grok can jump to the function or file that actually owns a feature, instead of a lookalike in another folder.
- Safer changes. Callers and related code are easier to find, so a rename or a fix is less likely to miss a second site.
- Better Knowledge notes. Rebuild on the Knowledge pane uses this map for generated overview and architecture notes. See Knowledge.
- You still point when you know the path. Use
@for a specific file. The index is for everything you did not mention.
You can chat without an index. Build one when the folder is real source, not a single screenshot or an empty name.
How to build the index
- Attach a project folder (New project, or Change folder on an existing one). Point at the project directory — not your home folder, not a whole disk.
- On the project in the sidebar, or on the Project card in an empty chat, click Create index. If Codegraph is not installed yet, the button says Install & index — the Workbench downloads it once.
- Wait until the status says Indexed and shows a file count. First runs on a large repo take a while. You can keep chatting.
If it fails, the button becomes Retry. The usual cause is a folder that is too broad (home, a volume root) or a tool install that did not finish.
What you see
The Project card at the top of a new chat shows the name, detected stack (for example React + Vite), a short summary from README or project rules if those files exist, languages, file and symbol counts, and a compact tree. Sidebar status next to the project repeats Indexed / Indexing / Not indexed.
Status labels:
- Indexed — the map is ready.
- Indexing — building. Leave it running.
- Installing Codegraph — first-time download of the indexer.
- Not indexed — folder is attached; you have not built the map yet.
- Codegraph missing — the indexer is not installed. Use Install & index.
- No folder — attach a folder first.
Keeping it useful
After large structural changes (new packages, a moved src tree), build the index again if answers feel stale. Day-to-day file edits do not always need a rebuild. Do not index secrets-only dumps or giant vendor trees on purpose — the indexer already skips common folders such as node_modules and dist.