# Code-intelligence tooling for the-architect role (https://jackin.tailrocks.com/research/platform/infrastructure/code-intelligence/)



**Research state:** Current

## Summary [#summary]

No single Rust code-intelligence tool covers every task. the-architect should combine `fff` for lexical discovery, `codedb` for code relationships, `ast-grep` for syntax shape, and `rust-analyzer` for compiler-resolved navigation, with Cargo tools as verification gates.

One consolidated `agent-instructions.md` source owns the routing guidance. The role copies that same content to each supported runtime path; it does not maintain parallel guidance documents.

## Research question [#research-question]

Which complementary Rust code-intelligence tools should the-architect expose, and how should one global guidance source route each query without overlapping search claims?

Delivery belongs to the external [`jackin-project/jackin-the-architect`](https://github.com/jackin-project/jackin-the-architect) repository. The stack is role-scoped and does not require a jackin❯ core change.

## Method [#method]

The comparison separates four jobs: lexical discovery, structural matching, semantic navigation, and relationship-oriented context. Candidate interfaces, indexing models, runtime support, and instruction behavior were compared against the broader [current retrieval-tools comparison](/research/context/tools/06-combining/) and [current release register](/research/context/tools/08-current-release-register/).

## Findings [#findings]

### Selected tools [#selected-tools]

| Tool                                                                | Job                                                        | Mechanism                                                | Decision                                           |
| ------------------------------------------------------------------- | ---------------------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| [`fff`](https://github.com/dmtrKovalenko/fff)                       | File, path, and literal-content discovery                  | Warm in-memory index with frecency and Git-aware ranking | Default lexical search                             |
| [`codedb`](https://github.com/justrach/codedb)                      | Symbols, callers, dependencies, outlines, and task context | In-memory code index exposed through MCP                 | Default relationship layer                         |
| [`ast-grep`](https://astgrep.com/)                                  | Syntax-shape search and deterministic rewrite              | tree-sitter AST patterns                                 | Default structural tool                            |
| [`rust-analyzer`](https://rust-analyzer.github.io/)                 | Definitions, references, types, and trait implementations  | Rust language server                                     | Semantic correctness floor where native LSP exists |
| Cargo `nextest`, `clippy`, and `rustfmt`                            | Tests, lint, and formatting                                | Rust toolchain CLIs                                      | Verification gates                                 |
| [`ast-index`](https://github.com/defendend/Claude-ast-index-search) | SQLite/FTS code index                                      | Persistent index and shell-out MCP wrapper               | Not selected; overlaps codedb on Rust workspaces   |

`fff` and `codedb` are complementary. `fff` answers where a file or literal occurs; `codedb` answers how symbols and files relate. Neither tool's blanket “use me for all search” instruction belongs in the role.

### Routing contract [#routing-contract]

```text
fff           → file / path / literal-content search
codedb        → symbols / callers / dependencies / outline / task context
ast-grep      → structural search and codemods
rust-analyzer → definitions / references / types / implementations
rg / grep     → logs / comments / config keys / error strings
```

The router prevents duplicate searches: a literal lookup should not fan out across `fff` and `codedb`, and a caller or dependency question should not be approximated with lexical search.

### Runtime support [#runtime-support]

| Runtime                | Native Rust LSP                                                 | Relationship and lexical layer                                    |
| ---------------------- | --------------------------------------------------------------- | ----------------------------------------------------------------- |
| Claude Code            | Full navigation through the official `rust-analyzer-lsp` plugin | `codedb` + `fff` MCP                                              |
| OpenCode               | Diagnostics; navigation remains runtime-dependent               | `codedb` + `fff` MCP                                              |
| Codex, Amp, Kimi, Grok | No established native Rust LSP client                           | `codedb` + `fff`; `rust-analyzer diagnostics` remains a CLI check |

An LSP-to-MCP bridge would add another resident server and overlap codedb. The role therefore keeps `rust-analyzer` on `PATH` and uses native LSP only where the runtime supports it.

### Current trust and resource boundary [#current-trust-and-resource-boundary]

The verified releases are fff v0.10.3 and codedb v0.2.5838. Pinned artifacts and role-scoped registration are required because installers, telemetry, hooks, schemas, and runtime behavior are part of the trust boundary. Codedb telemetry stays disabled, and its installer-owned hook that blocks conventional search commands is outside the selected architecture.

Claude Code can defer MCP schemas through native tool search. Runtimes without schema deferral carry the resident server schema cost. Large tree, snapshot, and remote-tree responses must remain bounded so the relationship layer does not cost more context than direct reads.

Both indexes keep cache state in the agent home, never in the mounted workspace or a host path. The indexed project root is the mounted workspace. This preserves a clean operator checkout while keeping third-party cache ownership separate from jackin❯ paths.

## Global guidance contract [#global-guidance-contract]

`agent-instructions.md` is the sole source for token-optimization and code-intelligence guidance. It is copied as a real file because agent config symlink behavior is not reliable ([Codex #11314](https://github.com/openai/codex/issues/11314), [Codex #8943](https://github.com/openai/codex/issues/8943)).

| Runtime     | Global guidance path                                          |
| ----------- | ------------------------------------------------------------- |
| Claude Code | `~/.claude/CLAUDE.md`                                         |
| Codex       | `~/.codex/AGENTS.md`                                          |
| Amp         | `~/.config/amp/AGENTS.md`                                     |
| Kimi        | `~/.kimi-code/AGENTS.md`                                      |
| Grok        | `~/.grok/AGENTS.md`                                           |
| OpenCode    | `~/.config/opencode/AGENTS.md`, owned by the installed plugin |

The copies must remain content-identical. Amp's global path is `~/.config/amp/AGENTS.md`. Kimi's home-level auto-load behavior remains uncertain; the upstream discussion is tracked in [kimi-cli #2152](https://github.com/MoonshotAI/kimi-cli/issues/2152).

## Implications for jackin❯ [#implications-for-jackin]

* The role `Dockerfile`, `preflight` hook, and default-home seeding are sufficient extension points; <RepoFile path="crates/jackin-image/src/derived_image.rs">derived-image ownership</RepoFile> does not need a new core feature.
* CLI tools stay on `PATH` for every runtime without per-turn schemas. Resident indexes use MCP only where a warm index supplies distinct value.
* Native LSP wiring and existing runtime state remain independent from the added lexical and relationship layers.
* Tool routing is a role instruction contract, not behavior duplicated in each runtime configuration.

## Limitations and unknowns [#limitations-and-unknowns]

* Kimi does not have established, reliable home-level global-rule loading at the cited path.
* Current codedb schema size, memory use, and bounded-output behavior need measurement on representative the-architect workspaces.
* `ast-index` has relationship primitives that codedb lacks, including hierarchy and recursive call-tree queries, but no evidence yet establishes enough distinct benefit for a second index.
* Native Rust LSP capability differs by runtime, so semantic navigation is not uniform across all supported agents.
* `fff` and codedb are fast-moving projects; release-specific installer and telemetry behavior remains part of every version review.

## Sources [#sources]

* [AGENTS.md](https://agents.md/) — cross-tool agent-instructions convention.
* [Current retrieval-tools comparison](/research/context/tools/06-combining/) — mechanisms and evaluation boundary.
* [Current release register](/research/context/tools/08-current-release-register/) — verified tool versions.
* [ast-grep](https://astgrep.com/) and its official [agent skill](https://github.com/ast-grep/agent-skill).
* [rust-analyzer](https://rust-analyzer.github.io/).
* [fff](https://github.com/dmtrKovalenko/fff).
* [fff installer](https://dmtrkovalenko.dev/install-fff-mcp.sh) — convenience installer excluded from the pinned-artifact contract.
* [codedb](https://github.com/justrach/codedb).
* [ast-index](https://github.com/defendend/Claude-ast-index-search).
* [Serena](https://github.com/oraios/serena) — LSP-backed alternative excluded because it adds a bridge that overlaps the selected stack.
* [Kimi Code](https://github.com/MoonshotAI/kimi-code) and [global-rules request](https://github.com/MoonshotAI/kimi-cli/issues/2152).

## Related work [#related-work]

* [Creating a Role](/developing/creating-roles/)
* [Role Manifest](/developing/role-manifest/)
* [The Construct Image](/developing/construct-image/)