Freshness is visible
Search, snippet, trace, and impact output disclose fresh, stale, or missing state. code_index can report partial indexing, and metrics or traces can report unavailable graph context.
Code graph evidence
Use repo-local code intelligence to reduce blind exploration.
MARS builds a local SQLite-backed code graph so roles and users can search symbols, inspect bounded snippets, trace known relationships, map changed files to likely tests and docs, and measure whether graph context reduced broad repository probing. Code intelligence is local by default, writes no target files, and is evidence, not a replacement for source review or tests.
Decision Map
Use code intelligence when the user question is structural: where a symbol lives, which tests or docs are likely affected, whether graph context was injected, or whether agents are doing too much broad search. Use ordinary commands and validation when the question is behavioral: does the product build, run, or satisfy a user workflow?
| Need | Use | Why |
|---|---|---|
| Let a role start with compact repo context. | mars run, mars start, or mars serve with code intelligence enabled. | The runtime can inject ## CODE GRAPH CONTEXT before the LLM loop. |
| Search implementation without bulk reads. | code_search then code_snippet. | Find candidate symbols first, then read exact bounded source. |
| Estimate affected tests, docs, and feature contracts. | code_impact. | Maps changed paths or a diff to related repo artifacts. |
| Measure whether graph assistance helped recent runs. | mars code-intel metrics. | Aggregates persisted trace counters from the per-repo database. |
| Compare graph context against a local control path. | mars code-intel benchmark. | Runs a no-model control/treatment benchmark for a named case. |
| Record a real build, test, lint, or smoke outcome. | mars checks run. | Runs the check and records whether it passed or failed. |
| Validate foundation role/runtime behavior. | mars validation agent-smoke. | Creates ephemeral targets and exercises roles through the server job path. |
Enable Or Disable
Code intelligence is enabled by default from local configuration.
The runtime resolves the setting in this order: command flag,
MARS_CODE_INTEL_ENABLED, then
code_intel.enabled in local config. Prefer explicit
true or false values in commands and
automation.
| Surface | Example | Effect |
|---|---|---|
| One role run | mars run engineer --repo /path/to/repo --code-intel false | Disables automatic graph context for that command. |
| Scoped lifecycle | mars start --repo /path/to/repo --code-intel true | Enables graph context and loop maintenance for that run. |
| Multi-repo serve | mars serve --code-intel false | Disables automatic graph context for served jobs. |
| Environment | MARS_CODE_INTEL_ENABLED=false mars start --repo /path/to/repo | Overrides local config when no flag is passed. |
| Local config | code_intel.enabled: true | Default behavior when no flag or env var is set. |
code_intel:
enabled: true
Enabled does not mean every role receives graph context. The role
must also have code-intel tools in its manifest allowlist.
Runtime Context
When code intelligence is enabled and a role is allowed to use
code-intel tools, MARS attempts a bounded auto-refresh of the local
graph and assembles a compact ## CODE GRAPH CONTEXT
block before the model loop starts. The context can include
freshness state, changed-path impact hints, related tests, and
documentation candidates. Large stale sets are intentionally left
stale so users can refresh deliberately with code_index.
If the graph cannot be refreshed, traces record unavailable
evidence rather than pretending the graph was useful.
Graph evidence is bounded
Code intelligence narrows what to inspect. It does not prove behavior and should be corroborated with tests, source reads, or runtime checks.
Traces carry counters
Runs record codeintel:* and repo_exploration:* counters so users can compare graph use with broad search and bulk reads.
Agent Tools
The code-intel tools are part of the same governed tool registry described in the Tools And MCP Guide. They are non-mutating to target repo files. Index refreshes write only MARS SQLite state under the configured per-repo database.
| Tool | User purpose | Typical order |
|---|---|---|
code_index | Refresh the local code graph for the current repo. | Run first when output reports missing, stale, or partial state. |
code_search | Search indexed files and symbols with filters. | Use before broad grep or bulk file reads. |
code_snippet | Read an exact bounded source span for an indexed symbol. | Use after code_search identifies a likely symbol. |
code_trace | Inspect known import and call relationships. | Use when relationships matter, then confirm in source. |
code_impact | Map changed paths to likely symbols, tests, docs, feature scenarios, and tickets. | Use before implementation, review planning, or release risk summaries. |
Refresh the index from the CLI tool surface
mars tools run code_index --repo /path/to/repo --args-json '{"full":false}' --jsonUse "full":true only for corruption repair, parser/schema changes, or an explicit operator request.
Inspect likely impact
mars tools run code_impact --repo /path/to/repo \
--args-json '{"paths":["internal/app/app.go"]}' --jsonImpact output is guidance for inspection and validation selection, not proof of correctness.
mars code-intel metrics
Metrics summarize persisted local trace evidence for a target repo. They answer whether recent jobs had graph context enabled, disabled, unavailable, or unused, how many code-intel tool calls happened, how much graph context was injected, and how much broad exploration still occurred.
| Flag | Meaning | Default |
|---|---|---|
--repo | Target repository whose persisted trace evidence should be summarized. | Current directory. |
--db | SQLite database to read. Must be outside the target repo. | ~/.mars/db/{repo}/mars.db. |
--window-days | How many days of trace evidence to aggregate. | 30. |
--json | Emit structured output for scripts or reports. | Human-readable text. |
mars code-intel metrics --repo /path/to/repo --window-days 30
mars code-intel metrics --repo /path/to/repo --json
A low graph count is not automatically bad. It may mean the role did
not have code-intel tools, the repo had little persisted evidence,
or the job was not code-oriented. Compare metrics with the role
manifest and the trace you are investigating.
mars code-intel benchmark
The benchmark is a local, no-model control/treatment check for code graph impact. It is useful when maintainers want to know whether code-intel context finds expected files, tests, or docs for a defined case before relying on it in role guidance or validation claims.
| Flag | Meaning | Use |
|---|---|---|
--repo | Target repo under test. | Point at the repo whose graph should be measured. |
--db | SQLite database. Must be outside the target repo. | Use an isolated DB for reproducible local comparisons. |
--case | Stable case name in the benchmark output. | Use a meaningful slice name, such as docs-code-intel. |
--trials | Number of control/treatment trials. | Raise for less noisy local timing comparisons. |
--changed-paths | Comma-separated paths to evaluate instead of the current git diff. | Use for targeted scenarios or clean working trees. |
--expected-files | Comma-separated implementation paths expected in impact output. | Produces expected file hit-rate evidence. |
--expected-tests | Comma-separated test paths expected in impact output. | Produces expected test hit-rate evidence. |
--expected-docs | Comma-separated documentation paths expected in impact output. | Produces expected doc hit-rate evidence. |
--report | Optional JSON report path. | Must be outside the target repo. |
--json | Print structured benchmark output. | Use for scripts or durable summaries. |
mars code-intel benchmark \
--repo /path/to/repo \
--case docs-code-intel \
--trials 3 \
--changed-paths docs/code-intel-reference.html \
--expected-docs docs/code-intel-reference.html \
--json--report is intentionally guarded outside the target
repo. If a benchmark supports a source-change claim, summarize the
outcome in the owning validation or release artifact rather than
dropping raw local benchmark JSON into the target.
Checks And Validation
Code intelligence explains likely relevance. It does not record that a real check passed and it does not replace validation matrices. Use the adjacent evidence commands for those jobs.
Record a local check outcome
mars checks run --repo /path/to/repo --name go-test -- go test ./...
mars checks run --repo /path/to/repo --role qa --name playwright -- npm testThe command after -- is the real check. MARS records whether it passed or failed.
Run source-maintainer agent smoke validation
mars validation agent-smoke --suite fast --json
mars validation agent-smoke --case static-web-ticket --role engineer --project-type static-web --suite fastAgent smoke creates ephemeral target repos and exercises roles through the server job execution path. Use the agent-smoke command reference for flags, report fields, retention, and evidence boundaries.
Keep validation boundaries honest
mars validation agent-smoke --fixture-only
mars validation agent-smoke --cleanup-only--fixture-only is a diagnostic fixture check, not live role evidence. Fake or scripted model endpoints are not validation evidence for source-change claims.
For full agent-smoke report contracts, clean-project validation gates, and integration boundaries, use the Integrations And Validation Guide and Validation guide.
State And Reports
Code intelligence stores index and trace evidence in the MARS SQLite database, not in target source files. Code-intel commands reject database and benchmark report paths inside the target repo so local state does not become product content by accident.
| Artifact | Default location | User rule |
|---|---|---|
| Per-repo database | ~/.mars/db/{repo}/mars.db | Contains code-intel tables plus queue, trace, scoring, and trust state. |
| Trace summaries | Per-repo database and local traces. | Used by mars code-intel metrics. |
| Command logs | ~/.mars/traces/logs/ | Use --log-file for durable local logs outside the repo. |
| Benchmark report | User-supplied --report path outside the target repo. | Summarize into durable repo docs only when it supports a maintained claim. |
| Validation report | docs/validation/reports/ for source-maintainer matrix evidence. | Use when running or attempting required validation matrices. |
The Files And State Reference covers database isolation, logs, traces, generated evidence, upgrade preservation, and eject cleanup in more detail.
Recipes
Preview role context with code intelligence off
mars run engineer --repo /path/to/repo --dry-run --no-init --code-intel falseUseful when comparing prompt shape or isolating a graph refresh issue.
Inspect recent graph value
mars code-intel metrics --repo /path/to/repo --window-days 7Look at graph-enabled jobs, unavailable jobs, code-intel calls, broad search calls, and bulk reads.
Benchmark a known change set
mars code-intel benchmark \
--repo /path/to/repo \
--case release-risk \
--changed-paths internal/release/notes.go,docs/release-update-guide.html \
--expected-tests internal/release/notes_test.go \
--expected-docs docs/release-update-guide.htmlUse expected path hit rates to decide whether graph guidance is good enough for this slice.
Record check evidence after graph-guided edits
mars checks run --repo /path/to/repo --name targeted-go-test -- go test ./internal/releaseGraph impact helped choose the command; the check command proves the command result.
Troubleshooting
| Symptom | Likely cause | Next action |
|---|---|---|
No ## CODE GRAPH CONTEXT appears in dry-run output. | Code intelligence is disabled, the role lacks code-intel tools, or graph refresh failed. | Check --code-intel, MARS_CODE_INTEL_ENABLED, local config, and the role manifest tool allowlist. |
| Metrics show disabled jobs. | A flag, env var, or config disabled code intelligence. | Run with --code-intel true or clear the env override. |
| Metrics show unavailable jobs. | The graph could not refresh or persisted evidence is incomplete. | Run mars tools run code_index --repo /path/to/repo --args-json '{"full":false}' --json and inspect the error. |
| Search finds stale results, or indexing reports partial results. | The repo changed after the last index run, the auto-refresh was intentionally bounded, or parser support is partial. | Refresh the index and confirm important decisions with source reads. |
--db is rejected by a code-intel command. | The path is inside the target repo or otherwise unsafe as runtime state. | Use the default per-repo database or another path outside the checkout. |
--report is rejected. | Benchmark reports must be outside the target repo. | Write the raw JSON outside the checkout and summarize durable evidence in a repo doc if needed. |
| Agent-smoke output is being used as product acceptance. | Agent smoke validates role/runtime behavior, not target product behavior. | Pair it with product-specific build, test, smoke, or E2E evidence. |