# 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

- [Workspace Tool Nodes](/docs/nodes-workspace-tools)
- [Workspace Nodes](/docs/nodes-workspace)
- [Crate Structure](/docs/dev-crate-structure)