Skip to main content

Callix code navigation provider

Uses the native Callix 1.7+ binary, without Python bindings or a daemon. An enabled plugin starts warming the primary project's graph and navigation maps immediately on session start/reload, without waiting for a model request or the file-watch debounce timer. Startup does not wait for analysis. A semantic query runs or joins callix analyze <project> --quiet, parses schema version 1 JSON, and reuses the graph. Source files, resolver configuration, dependency manifests/lockfiles and ignore rules invalidate it. Prose and diagnostic logs do not. refresh: true forces analysis and is normally unnecessary. There is no automatic dependency installation. Set background:false for lazy synchronous indexing on the first semantic query instead of startup warming.

Invocation and slow-index diagnostics​

The model-facing tool is code_query, not callix. For example:

{"action":"status"}

status never starts analysis or waits for an active native build. It reports available, the selected executable, and state: unavailable, not-indexed, indexing, ready, stale or error. Active builds include elapsed time and attempt number; errors retain the last failure. A ready graph also has node and relation counts. Inspect this result when navigation seems stuck.

Start navigation with {"action":"definition","pattern":"MyFunction"} or {"action":"outline","path":"src/file.ts"}, then use an exact returned symbol ID for relationships or read_symbol. path is an exact file filter. The tool's on-demand help includes complete argument examples.

With background operation enabled, a semantic call waits up to queryWaitMs (default 10000 ms, configurable 50..600000). A slow call returns pending:true, complete:false, its requested action and current index state. This is not a semantic answer. The owned build continues; use glob, grep or read for immediate work, inspect status later and repeat the original query once ready. Avoid busy polling or repeated forced refreshes. Errors do not remove the tool or disable text search. When the native backend reports nothing to analyse, the tool explains that no supported semantic sources were found and directs the model to glob, grep or read. Repeated status/refresh calls cannot add support for a source language; retry only after the sources or backend capabilities change. Session end, reload, disable and close cancel and drain outstanding work. Removing an attached project's workspace grant also cancels its retained native query. With background:false, calls remain synchronous up to the analysis deadline. The deadline covers all source-change retry attempts, rather than restarting the whole timeout for each attempt.

If code_query is absent, first install/enable this plugin in the intended scope and /reload between turns. A model cannot activate code by inventing a tool name:

/extensions install callix@agent-compositor --project
/extensions enable callix --project
/reload

An external assistant does not automatically inherit Compositor's tools. It must use its configured integration or invoke the native executable by an available path; the plugin-local binary need not be installed on the shell's PATH.

Bundled distributions and source setup​

New compositor release builds include Callix 1.7.0 for Linux x64/arm64 and macOS x64/arm64. The executable lives in plugins/callix/bin/callix, alongside its upstream LICENSE and release.json provenance. CI verifies the archive's pinned SHA-256 and tests actual cross-file navigation after installation. Loading the plugin never downloads software. The older compositor v0.1.1 published archive predates bundling and needs the explicit setup below.

When working from source, run node plugins/callix/install.mjs to download the pinned 1.7.0 release, verify its SHA-256, and install it under this plugin's bin/. Linux x64/arm64 and macOS x64/arm64 are supported. This is an explicit setup step. A downloaded archive can be reused with --archive /path/to/release.tar.gz and is verified identically.

Binary selection remains: CALLIX_BIN → executable setting → plugin-local bin/callix → callix on PATH. Native packaging does not change provider selection, user/project overrides or the ability to disable this plugin.

Alternatively install the binary from the official release on PATH, or set CALLIX_BIN to its absolute path. You can also configure .agent-compositor/callix.json:

{"executable":"/path/to/callix","timeoutMs":120000,"queryWaitMs":10000,"maxOutputBytes":268435456}

The code_query tool supports symbols, definition, references, callers, callees, dependencies, and status. Use a returned symbol ID to disambiguate names. Results preserve relation positions and graph metadata describing resolver completeness. An empty relation list is not proof that no usages exist when resolution is degraded. Graphviz/Mermaid exports remain a CLI capability; navigation reads the underlying JSON graph directly.

glob and grep use lightweight project discovery/text search through the same service.project.query contract. They do not trigger graph analysis. Calls use argument arrays, bounded stdout/stderr, a timeout and agent cancellation. Use a project-relative file glob such as **/* to discover unknown filenames; grep searches literal source text by default, not semantic task descriptions or filenames. Its optional path filter should use an existing path. A complete empty first page returns recovery guidance; exhausted later pages and scan-limited searches keep their own pagination/limit meaning. Hints enter the ordinary result budget before formatting. They do not invent matches or issue another query. A missing literal search directory or filter returns ENOENT and suggests using the default cwd or an existing attached project.

The native project-text backend returns long-line previews around the first occurrence, bounded to 2000 UTF-8 bytes without splitting a Unicode code point. textTruncated marks an excerpt; textOffset is its zero-based UTF-16 position in the line and column is the first match's one-based UTF-16 column. Regex byte locations are converted before those fields are returned. A preview is not guarded edit source. Copy the result's readArgs object into read to inspect that location directly, including in an attached project. It supplies the canonical absolute path and line window, with a snapshot cursor when the preview starts inside the line. Then copy the read result's editRef into edit.target for an exact edit. A changed search view invalidates the cursor; rerun the search or read the indicated line window. These selectors grant no permission: the read and edit retain normal checks. Short complete lines keep their existing path/line/text result shape. Regex search uses raw UTF-8 bytes (rg --encoding none) so a UTF-8 BOM remains part of the same source view used by read; columns and snapshot hashes include it. Native text search skips NUL/binary and non-UTF-8 files, matching native read support; an unrelated invalidly encoded file cannot poison a regex result page. This refines the previous NUL-only filtering and BOM-transcoding behavior. Inherited ripgrep configuration is disabled; it cannot change the source view through preprocessing, encoding or multiline options. Use the discovery layer's .agentignore, .geminiignore or project/Git ignore rules for exclusions rather than ripgrep-specific configuration. Callers needing other encodings should supply a compatible query/read provider. Third-party query providers can return different optional navigation fields.

To replace the backend, install a plugin declaring "provides":["service.project.query"] and implementing that event. Set the application configuration:

{"serviceProviders":{"service.project.query":"my-navigation"}}

The Callix plugin's model tools still call the selected provider. Add "disabledPlugins":["callix"] as well if the replacement supplies its own tools. Guard hooks continue to run for selected providers. Missing binaries, failures, unsupported graph schemas and timeouts return tool errors, without silently pretending another backend produced Callix results.

For the optional real-binary integration test:

CALLIX_TEST_BIN="$PWD/plugins/callix/bin/callix" npm test -- packages/app/test/callix.test.ts

It analyses a temporary TypeScript project and checks a resolved cross-file call. The regular suite tests cache invalidation, errors and provider replacement without requiring a local Callix installation.

glob and grep declare loopGuard: 'query': the default agent loop warns after three repeated model steps with no new query observations, then stops after six with saved progress. A changed query/result resets the streak. This metadata does not grant permissions, cache results or alter arguments. code_query is unannotated because its actions also include indexing/status operations. Polling tools remain outside this guard; configure agent.maxRepeatedQuerySteps when a different ceiling is needed.

Precise navigation and guarded edits​

code_query now supports outline, read_symbol and bounded reverse impact in addition to the existing graph queries. Query an exact ID when names are ambiguous; path is an exact project-relative file filter, not a suffix match. references includes indexed calls and alias-resolution edges. Resolver status and metrics remain visible: an empty graph result never proves that dynamic or unresolved usages do not exist.

A typical semantic edit uses these tools:

  1. Find a definition or file outline, then select its symbol ID.
  2. code_query {"action":"read_symbol","pattern":"<id>"} returns the source syntax-node slice, editRef and an edit object with path, expectedHash, range and strict. Older host SDKs without reference support retain the explicit anchor.
  3. Copy editRef verbatim into the native editor's target field, then supply the exact oldText and intended newText. If only the explicit anchor is available, use its path as target and copy expectedHash, range and strict. The symbol range disambiguates identical expressions elsewhere in the file. The editor resolves the path before plugin guards and permission checks. For older hosts, follow the installed editor's schema for passing the reference or explicit anchor.
  4. Re-read on a stale-snapshot error, then run relevant checks.

Callix spans use one-based UTF-8 byte columns and an exclusive end; model edit ranges use UTF-16 offsets. The adapter validates/converts them against the actual UTF-8 snapshot, including non-ASCII prefixes and CRLF. Modifiers outside the syntax-node span, such as export, are retained. A missing/ambiguous/unlocated symbol returns candidates or an error. A source body that cannot fit its budget has no edit anchor or editRef; increase the budget or select a smaller symbol.

Ordinary read also returns an anchor for its returned line range, so known-path literal edits can use grep + ranged read without building a graph. Hash checks and exact range matching reject stale, out-of-range and ambiguous changes. Guarded edits never fall back to whitespace normalization. All edits retain the normal permission/service/secret-guard/checkpoint path, and guarded inverses are recorded without sending their full content back to the model. Writes/edits are serialized across cores in one process. External editors are outside that lock; the hash is checked at mutation preparation, not an OS-wide atomic transaction.

Bounded output, freshness and cost​

Graph results default to compact symbol locations and about 2000 estimated JSON tokens. Set maxTokens (256..16000), limit, kinds or detail:"raw" explicitly. nextCursor continues a graph page and is rejected when its snapshot/filter changes. Text/file search supports offset / nextOffset. Budgets reduce whole records and preserve returned edge endpoints. Truncation and resolver metadata are explicit, not silently sliced strings.

maxOutputBytes bounds the full native graph before query filtering, separately from the model-facing maxTokens budget. It defaults to 256 MiB (allowed range 1024..268435456 bytes); earlier versions defaulted to 64 MiB. A narrow path or limit does not reduce the graph built by the native analyzer. Large graphs still need memory for the parsed graph and adjacency maps. Explicit smaller limits are honored on new builds; an overflow reports the byte limit and recovery guidance. Graphs above the maximum require a smaller attached project root or text tools. No partial graph is cached or advertised as complete.

metrics.estimatedTokens and bytes describe the compact JSON payload using the application's UTF-8-weighted heuristic, not provider billing. Cache state and query duration are included; indexMs records the original build cost rather than charging it again on each warm query. Actual input/output/cache token usage comes from provider events. Core tool transcripts use compact JSON and a valid truncation envelope above 128 KiB, rather than cutting through JSON or an anchor.

Warm exact-ID/adjacency queries use maps instead of scanning every node. Concurrent consumers share an index build; cancelling one does not cancel the others. Source timestamps/file membership and ignore configuration are checked; a source change during analysis causes a bounded retry, not a stale result tagged as current. Disk caches include root, effective executable and binary identity; changing timeout/output limits reuses a valid graph. Earlier v3 caches containing resource limits remain readable without reanalysis. Builds with different limits have separate cancellation/deadline ownership. Attached projects have separate disk-cache directories so switching projects does not evict another project's persisted index. The v3 fingerprint rebuilds older caches once under the new source-input rules. Extra agent ignore rules filter graph results and stored nodes; the native CLI still discovers/analyzes the root under its own rules.

File search respects Git inventory and agent ignores, and uses nested gitignore rules outside Git. When the selected project root is itself ignored by an ancestor repository, untracked discovery starts at the selected root while its own Git ignore rules, repository/global Git excludes and agent ignores still apply; tracked files remain included. Repository/global excludes and specific ancestor .gitignore rules are also checked against the enclosing path. Rules that hide the selected root itself are lifted from ancestor .gitignore files; other exclusions are conservative and can hide an untracked file even if a different rule would re-include it. If Git cannot enumerate a repository, search reports an error rather than falling back to a walk that bypasses repository and global exclusions. Escaping symlinks, deleted entries, binary and oversized text files are excluded. Regex search streams ripgrep in argument-safe batches; literal search has no ripgrep dependency. Search scanning is bounded to 32 MiB and approximately 10 seconds, with scanLimited requiring a narrower scope. Pagination discards skipped matches rather than retaining them all in memory.

Deep tests and comparisons​

npm run test:callix
npm run eval:navigation
npm run eval:navigation:live

test:callix requires the installed pinned binary (or CALLIX_TEST_BIN) and covers real aliased callers, UTF-8/CRLF spans, exact edits and permission denials as well as races, stale snapshots, pagination, ignored files, cache provenance and cancellation. The regular suite skips optional native cases when absent. Release smoke also tests actual packaged symbol reading and guarded editing with PATH empty, so native-platform releases exercise the new contract.

eval:navigation generates a controlled project and compares broad text + full file read, text + ranged read, and graph + symbol read. All protocols verify the same edited function, untouched neighbor and caller paths. The report includes schema/argument/result estimates, repeated-input estimates and cold/warm latency. eval:navigation:live runs the same guarded-edit task on the configured Ollama models, capturing provider-reported usage and actual tool trajectories. Set NAV_MODELS, NAV_OUTPUT or CALLIX_TEST_BIN to change the run. See the evaluation guide for measured results and limits; these are comparisons of methods, not branded assistant benchmarks.

Attached projects​

Omit cwd on glob, grep and code_query to use the primary project. The exact attachment spelling "@." also selects it when the primary project has no entry named @.. An existing entry takes precedence and goes through ordinary directory and workspace checks, including symlink resolution. Use "./@." for an explicit literal lookup. Use an attached directory's absolute path or ~/path to search another project. Absolute/home path filters select an attached directory or a file inside a selected project. Returned results include the resolved cwd; relative result paths belong to that project. A single-file attachment permits read, while project navigation requires its containing directory to be attached.