Code Graph & Knowledge Base

The code graph is experimental. Its interface, data format and indexing behavior may change in later versions.

The code graph uses CodeGraph to analyze the symbols in a project and the relationships between them. The Session Knowledge Base stores design decisions, constraints and lessons learned. Code references connect the two, so that you can see both the current structure of the code and the reasons behind it.

Pages

The code graph opens as a dialog with the tabs "Overview", "Symbols", "Explore code" and "Files". Its "Knowledge Base" button opens the knowledge base.

Overview: the number of files, symbols and relationships, the distribution of languages and symbol kinds, and the synchronization state ("Automatic sync active" or "Sync before queries"). Click a distribution item to see the matching results.
Symbols: search by name or file path ("Search symbols or file paths…"). A symbol's page shows its source with syntax highlighting and its "Incoming relationships" and "Outgoing relationships", grouped by relationship type and file. Relationships inferred by the analysis are marked "Inferred relationship", and line numbers jump to the place of the call.
Explore code: describe a feature or a flow, or name a file or symbol, and see the relevant source and relationships. This query runs locally and does not use an AI model.
Files: browse the indexed files; click a file to list its symbols.
Callers and Callees: on a symbol's page, show several levels of calls. The "Traversal depth" is 3 by default and at most 6. Up to 500 results are shown; when there are more, the total and a notice are shown.
Impact analysis: on a symbol's page, show the symbols and files that a change could affect, up to the chosen depth (3 by default, at most 6). Up to 500 symbols and 2,000 relationships are shown, with the total and a notice when the result is cut off.
Call path: on a symbol's page, search for a destination symbol ("Find a destination symbol…") to see the shortest path along call relationships. "No directed call path was found in the index." means only that the index contains no such path.

Switch the working directory from the directory menu, which also shows the full path. The page, the question in Explore code, the symbol, the depth, the destination and the source line are all part of the URL, so you can refresh the page, open it in a new tab or use the browser's back and forward buttons. A link works on the same backend with a valid login.

Enabling a project index

Right-click a project or collection in the sidebar and choose "Experimental" → "Code Graph".
The first time, click "Download CodeGraph". The backend you are connected to downloads the fixed CodeGraph 1.6.0 release from GitHub and checks it against a built-in SHA-256 checksum ("The download checksum did not match. The runtime was not installed." means the check failed). No separate Node.js installation is needed.
Choose the "Working directory" and click "Enable indexing". The project directory and other working directories used by its sessions and groups are listed separately; each Git worktree has its own index. A collection needs at least one session with a valid working directory.
Wait until the status is "Ready", then search for symbols or file paths. Indexing runs in the background ("An index task is running. You can close this page or disable indexing to stop it."), and closing the page does not cancel it.

"Synchronize" updates the index manually or retries after a failure. Before each code query, VelaTerm also brings the index up to date. For the same backend and working directory, one query process is reused, and while it runs it picks up file changes as they happen. It exits after five minutes without queries; the next query reopens the index and catches up. The Overview refreshes its synchronization state every 30 seconds; when automatic synchronization is unavailable, VelaTerm still synchronizes before every query and never presents an outdated result as current.

"Disable indexing" stops a running index task and keeps the index files and the links to knowledge entries, so you can enable it again later. When a task is interrupted, its state becomes a failure that can be retried within about two minutes ("The previous task was interrupted. Synchronize to retry."). One indexing task may run for at most 30 minutes.

Indexes are stored in a .codegraph/ folder in each working directory and are managed by CodeGraph. VelaTerm runs the indexing itself; it does not run CodeGraph's agent installer or install Git hooks. If the project directory is a subfolder of a repository, only that folder is indexed.

Viewing code relationships

Search results show each symbol's name, kind and location. A symbol's page shows its source, incoming and outgoing relationships and linked knowledge entries; click a neighboring symbol to continue.

Relationships come from static analysis and may be incomplete or uncertain ("Relationships come from static analysis and may be incomplete or uncertain."); they do not replace running the code. A symbol page shows at most 200 relationships in each direction and 600 lines of source, with a notice when more exist. Source files larger than 4 MiB are not displayed. If a file changes while you are viewing it, VelaTerm asks you to synchronize again before relying on its line numbers.

Linking and reviewing entries

On a symbol's page, choose "Link knowledge entry", pick an existing entry, compare its text with the code, and save. On the entry's page, "Code references" leads back to the code, and the entry links in the code graph open the full entry.

A link stores the project, working directory, file path, symbol identity and the SHA-256 digest of the file as reviewed. When the file changes, the link shows "Needs review"; when the file can no longer be read or has been deleted, it shows "Unavailable"; otherwise it shows "Unchanged". The check works per file, so any change in the same file triggers a review. An open entry page checks its references regularly.

Choose "Review code and entry" to see the current code, and "Confirm review" when the entry still holds. The backend checks again that the file and the entry have not changed in the meantime and asks you to reload if they have. Confirming only updates the code reference; it does not change the entry's text. To change the conclusion, edit the entry as usual.

When a symbol is deleted or renamed, the link does not move to another symbol with the same name. Use "Remove link" and link the right symbol. Deleting an entry removes its links; deleting a project removes its index records and links, but not other entries or the index files in the working directories.

Queries from a session

Every terminal and agent session that VelaTerm starts has the vkb command. Other agents that can run terminal commands can use it too. If an existing session cannot find vkb after an update, restart the session.

With "Vela Skills" installed (Settings ▸ General), Claude can use /vkb and Codex $vkb. The skill runs only when you ask for it explicitly; agents do not call it on their own during other work. If an agent does not list the skill after an update, click "Reinstall" and restart that agent's session.

vkb status
vkb explore "how a session is created and its working directory chosen"
vkb search "greet"
vkb node "<symbol ID from a search result>"
vkb callers "<symbol ID>" 2
vkb callees "<symbol ID>" 2
vkb impact "<symbol ID>" 3
vkb path "<start symbol ID>" "<end symbol ID>"
vkb files "src/session"
vkb memories "design decision"
vkb memory "<entry ID from a search result>"
vkb notes "reading notes"
vkb note <knowledge-base-ID> "folder/note.md"

explore returns the same result as Explore code.
callers, callees and impact accept an optional depth; their results include relations, total, depth and truncated.
path takes two exact symbol IDs from search results, and files can filter by path.
search returns code results (sorted by relevance, with hasMore when there are more), knowledge entries and local notes separately.
node returns a symbol's source, relationships and linked entries.
memories and memory search and read Session Knowledge Base entries, including sources, revisions and code references.
notes and note search and read local knowledge bases (see Local Knowledge Bases).

Code queries use the index of the directory the command runs in. A subfolder uses its project's index, and a nested separate worktree never borrows the main checkout's index. When no index is enabled or a query fails, the result says that code is unavailable, and knowledge queries still work. These commands do not install anything, enable indexing or change entries.

Where data lives

The CodeGraph runtime is installed in codegraph/1.6.0/ in the application data directory. Index tasks and entry links are stored in the application database (knowledge_* tables). Indexing runs on the backend where the code lives; browser clients and SSH connections read the results through their existing connection, so no extra port is opened. Each backend keeps its own index settings and knowledge base.

CodeGraph's telemetry, update checks and separate background service are turned off. VelaTerm manages the query process and talks to it over a private standard input and output channel, without listening on a port. Indexing itself does not use AI. Code or entries that an agent reads with vkb may be sent to that agent's configured model service, in the same way as when the agent reads source files.

Code graph events are written to logs/runtime-*.log in the application data directory. When VLX_LOG_DIR is not set, VLX_KNOWLEDGE_LOG_DIR sets their directory. VLX_KNOWLEDGE_LOG_LEVEL filters them (for example error or off). The log does not contain source code, query text, entry text or credentials.

CodeGraph is developed at github.com/colbymchenry/codegraph and released under the MIT license.