Code Index Nodes
Applies to: ChengOS v0.2.0+ ｜ Last verified: 2026-09-25 ｜ Source: crates/cheng-nodes/src/nodes/builtin/tools/code_index, crates/cheng-code-index/src
Code intelligence over an indexed workspace: jump to a definition, find every reference, or search
symbols across the project. These answer structural questions that grep cannot — a reference search
returns call sites, not string matches. They all depend on the workspace index, so check
tools/code_index_status first when a lookup comes back empty; an unindexed or stale workspace looks
exactly like a symbol that does not exist.
Code Index Status — tools/code_index_status
Report code-intelligence index status for the active workspace (files/symbols/references, lifecycle, parser version) and optionally run explicit incremental (re)indexing, blocking or async.
Inputs
| Field | Type | Required | Default | Description |
|---|
reindex | boolean | — | false | Run (incremental) workspace indexing before reporting status. Default false: status query only, never triggers indexing implicitly. |
reindex_mode | enum | — | null | With reindex=true: 'blocking' (default, waits for completion) or 'async' (enqueue a background job and return its id/state immediately; recommended for large workspaces). Options: blocking, async |
workspace_path | string | — | null | Optional; omit to use the session workspace. |
Outputs
| Field | Type | Description |
|---|
error | string | Error message if the operation failed |
index_missing | boolean | True when no files have been indexed yet |
indexed_files | integer | Number of indexed files |
job_id | string | Background indexing job ID (async reindex or when an active job exists) |
job_state | string | Background indexing job state: queued, running, completed, failed, or cancelled |
lifecycle | string | Index lifecycle state: missing, queued, running, ready, stale, or failed |
parser_version | string | Parser version used by the indexed content |
reindexed | boolean | True when (re)indexing was executed in this call (blocking completed or async enqueued) |
report | object | Summary of the indexing run (blocking reindex only) |
stale | boolean | True when the index is marked stale (e.g. grammar version changed or files modified) |
total_references | integer | Total number of references in the index |
total_symbols | integer | Total number of symbols in the index |
workspace_id | string | Workspace identifier (canonical root path for server-local, or client workspace label for client-local) |
Goto Definition — tools/goto_definition
Find the definition site(s) of a symbol by exact name in the active workspace's index. Returns precise name-identifier position plus full definition span. Read-only.
Inputs
| Field | Type | Required | Default | Description |
|---|
symbol | string | ✅ | — | Exact symbol name (unqualified, e.g. 'compute_total' not 'util::compute_total') |
workspace_path | string | — | null | Optional; omit to use the session workspace. |
Outputs
| Field | Type | Description |
|---|
auto_reindex_triggered | boolean | True when an async reindex was scheduled because this query found the index missing |
definitions | array<object> | List of definition sites (ambiguous symbols may have multiple definitions) |
error | string | Error message if the operation failed |
found | boolean | True when at least one definition was found |
index_missing | boolean | True when the index is missing (run code_index_status with reindex=true first) |
job_id | string | Auto-reindex job ID |
job_state | string | Auto-reindex job state: queued or running |
stale | boolean | True when the index is stale |
Find References — tools/find_references
Find usage sites (calls, type references, macro invocations, imports, identifiers) of a symbol by exact name in the active workspace's index. Read-only.
Inputs
| Field | Type | Required | Default | Description |
|---|
kind | string | — | — | Optional reference-kind filter: call, type, macro, identifier, import |
limit | integer | — | — | Max returned references, default 200, hard cap 2000 |
symbol | string | ✅ | — | Exact symbol name whose usages to find |
workspace_path | string | — | null | Optional; omit to use the session workspace. |
Outputs
| Field | Type | Description |
|---|
auto_reindex_triggered | boolean | True when an async reindex was scheduled because this query found the index missing |
error | string | Error message if the operation failed |
index_missing | boolean | True when the index is missing (run code_index_status with reindex=true first) |
job_id | string | Auto-reindex job ID |
job_state | string | Auto-reindex job state: queued or running |
references | array<object> | List of reference locations |
stale | boolean | True when the index is stale |
total | integer | Number of returned references |
truncated | boolean | True when results were truncated by the limit |
Workspace Symbols — tools/workspace_symbols
Search indexed symbol definitions across the active workspace by case-insensitive substring. A missing index is asynchronously warmed and reported without delaying this query.
Inputs
| Field | Type | Required | Default | Description |
|---|
limit | integer | — | — | Max returned symbols, default 50, hard cap 500 |
query | string | ✅ | — | Symbol name query (substring, case-insensitive) |
workspace_path | string | — | null | Optional; omit to use the session workspace. |
Outputs
| Field | Type | Description |
|---|
auto_reindex_triggered | boolean | True when an async reindex was scheduled because this query found the index missing |
error | string | Error message if the operation failed |
index_missing | boolean | True when the index is missing (async warm-up requested by this query) |
job_id | string | Auto-reindex job ID (null when the local executor has no persistent job ID) |
job_state | string | Auto-reindex job state: queued or running |
stale | boolean | True when the index is stale (results may be incomplete or drifted) |
symbols | array<object> | List of matched symbols |
total | integer | Number of returned symbols |
truncated | boolean | True when results were truncated by the limit |
Next steps