Documentation

CodeLens MCP — Multi-Agent Integration

View source on GitHub

Public integration pattern for planner/reviewer and builder/refactor agents that share one CodeLens project scope.

This document describes how to use released CodeLens features to coordinate multiple agents on one repository. It does not require a custom codex-builder agent file, and it does not assume Claude/Codex-specific local harness hacks.

For the higher-level operating shapes that sit above these primitives, see Harness modes. For the machine-readable contract that a host can reuse directly, see Portable harness spec.

What CodeLens Provides vs What the Host Provides

CodeLens provides:

  • shared stdio or HTTP MCP access
  • role-based profiles such as reviewer-graph and refactor-full
  • bounded bootstrap via prepare_harness_session
  • advisory coordination via register_agent_work, claim_files, list_active_agents, and release_files
  • mutation safety via verify_change_readiness, safe_rename_report, and runtime mutation gates
  • session-scoped builder audit via audit_builder_session, get_tool_metrics(session_id=...), and export_session_markdown(session_id=...)
  • session-scoped planner/reviewer audit via audit_planner_session
  • canonical runtime/doc surface inventory via codelens://surface/manifest

The host or harness still provides:

  • the user-facing conversation loop
  • the decision to dispatch one agent to another
  • branch policy, merge policy, and release policy
  • any Claude-specific or Codex-specific custom agent wrapper

CodeLens is exploring a move from shared coordination/verification toward a bounded code-work orchestrator, per ADR-0014. Separate what ships today from where that ADR points:

  • Today (shipped). orchestrate_change produces an advisory dry-run orchestration plan. It emits a dry_run: true artifact and performs no file mutation of its own. Approval is session-scoped and held in memory only, so it is lost when the daemon restarts. The plan is never self-enforcing; it is enforced opt-in, only when a subsequent mutation call passes the matching orchestration_run_id through the mutation gate.
  • Direction (ADR-0014, not yet built). A durable, typed code-work run state machine — with a persistent audit trail, preflight, approval, dispatch, and verification flow that survives restarts — is a future candidate, not current behavior.

Either way, the host still owns the general chat/runtime loop and any host-specific agent wrapper.

Host-Neutral Execution Intents

Successful CodeLens responses do not synthesize a model- or vendor-specific handoff action. When CodeLens can derive a concrete follow-up, it emits the actual callable tool and arguments in suggested_next_calls. A mutation tool such as rename_symbol is a mutation intent, not an executor assignment.

The host owns agent selection, worktree policy, approval, and execution. It may use the provided arguments directly only after applying the target tool's normal preflight and mutation gates. Session metrics evaluate this guidance by whether the next actionable call accepted or diverted from the suggestion and whether an accepted call succeeded; raw emission count is not treated as value.

Note — inline brief mode: When dispatching an implementation agent via MCP (mcp__codex__codex), pass the task description inline as the prompt argument rather than writing a file to /tmp. If the host harness settings do not include Write(/tmp/**) in allowedTools, writing the brief to disk will be blocked by the permission gate. The inline pattern (passing the brief directly as prompt) avoids this and has been verified to work in host-managed agent sessions. If you must write a brief file, ensure Write(/tmp/**) appears in the session's allowedTools.

For multi-agent HTTP deployments, keep the surfaces asymmetric:

  • planner / reviewer agents -> reviewer-graph on a read-only daemon
  • builder / refactor agents -> refactor-full on a mutation-enabled daemon

Typical topology:

# one writer; planner/reviewer sessions request a read-only profile
codelens-mcp /path/to/project --transport http --profile refactor-full --daemon-mode mutation-enabled --port 7838

All hosts attach to :7838. The session profile and RBAC principal keep planner/reviewer calls read-only while the process-level project lease prevents a second writer daemon from sharing the same store.

Operational rule:

  • one mutation-enabled agent per worktree
  • additional agents stay read-only
  • keep small slices inline when they fit within about 30 net LOC or one obvious file
  • use subagents for independent read-only scans, large docs audits, or high-accuracy reviews
  • never accept subagent self-report as completion evidence; the parent session reruns the targeted test, package test, lint/check, and daemon probe that match the slice
  • before ending a slice, inspect git diff --name-status, git diff --cached --name-status, and git status --short --untracked-files=all so unrelated WIP is not staged or reported as done

Fixed Preflight Order

Before dispatching a builder/refactor agent, run the CodeLens preflight in this order.

1. Bootstrap the session

{
  "name": "prepare_harness_session",
  "arguments": {
    "profile": "reviewer-graph",
    "detail": "compact"
  }
}

Why first:

  • establishes the active project/session view
  • returns bounded surface and health state
  • exposes current coordination counts for the session snapshot

2. Inspect each target file structurally

{
  "name": "get_symbols_overview",
  "arguments": {
    "path": "src/example.rs"
  }
}

Run once per target file.

3. Inspect diagnostics for each target file

{
  "name": "get_file_diagnostics",
  "arguments": {
    "file_path": "src/example.rs"
  }
}

Run once per target file.

4. Run the verifier across the full change set

{
  "name": "verify_change_readiness",
  "arguments": {
    "task": "Refactor example flow without changing behavior",
    "changed_files": ["src/example.rs", "src/lib.rs"],
    "profile_hint": "refactor-full"
  }
}

Run this once for the whole intended change set, not file-by-file.

Dispatch Gate

Interpret the verifier result conservatively:

  • mutation_ready == "blocked" -> stop and report blockers
  • mutation_ready == "caution" with overlapping_claims -> stop and report the conflicting session, branch, and claimed paths
  • otherwise -> dispatch the builder/refactor agent

Why this order matters:

  • skipping prepare_harness_session weakens the session-local view that the host sees during bootstrap
  • skipping per-file structure/diagnostics makes the builder brief less precise
  • running the verifier on partial file sets hides cross-file overlap and readiness evidence

Coordination Discipline

If the host is about to start a builder/refactor pass, publish that intent first.

1. Register the agent intent

{
  "name": "register_agent_work",
  "arguments": {
    "agent_name": "builder-agent",
    "branch": "feature/refactor-example",
    "worktree": "/abs/path/to/worktree",
    "intent": "Refactor example flow after preflight",
    "ttl_secs": 600
  }
}

2. Claim the mutation targets

{
  "name": "claim_files",
  "arguments": {
    "paths": ["src/example.rs", "src/lib.rs"],
    "reason": "planned refactor pass",
    "ttl_secs": 600
  }
}

Use the same TTL for registration and claims.

3. If overlap appears, stop

Do not auto-dispatch through an overlap. Report it back to the orchestrator.

  • overlapping claims are advisory, not hard locks
  • the correct policy decision still belongs to the orchestrator

4. Release claims explicitly on completion

{
  "name": "release_files",
  "arguments": {
    "paths": ["src/example.rs", "src/lib.rs"]
  }
}

TTL expiry is only a safety net. Explicit release is better because it keeps the shared view current.

Builder Session Audit

audit_builder_session is the public session-level check for builder/refactor discipline. It does not add new hard blocks. It scores whether a builder session used CodeLens in the expected order and with enough evidence.

Typical compact call:

{
  "name": "audit_builder_session",
  "arguments": {
    "session_id": "builder-session-id",
    "detail": "compact"
  }
}

Expected status meanings:

  • pass -> bootstrap, preflight, diagnostics, and coordination evidence are all present
  • warn -> mutation succeeded, but the session skipped bootstrap, diagnostics, or coordination discipline
  • fail -> mutation/preflight contract was violated
  • not_applicable -> no builder/refactor flow was recorded for that session

Related session tools:

  • get_tool_metrics({"session_id":"..."}) -> machine-readable per-session telemetry
  • export_session_markdown({"session_id":"..."}) -> human-readable markdown with the same session's audit summary appended

Current scope:

  • builder / refactor sessions only
  • planner / reviewer sessions use audit_planner_session

Planner / Reviewer Session Audit

audit_planner_session is the read-side companion to audit_builder_session. It stays audit-only: no new runtime hard blocks are added.

Typical compact call:

{
  "name": "audit_planner_session",
  "arguments": {
    "session_id": "planner-session-id",
    "detail": "compact"
  }
}

Expected status meanings:

  • pass -> bootstrap, workflow-first routing, and read-side evidence all line up
  • warn -> the session skipped bootstrap, lacked change evidence, fell into low-level chains, or reviewed files without symbol/diagnostic evidence
  • fail -> the planner/reviewer session attempted content mutation or shows mutation-gate denial traces
  • not_applicable -> the session never entered a planner/reviewer read-side flow

Related session tools:

  • get_tool_metrics({"session_id":"..."}) -> machine-readable per-session telemetry for either builder or planner sessions
  • export_session_markdown({"session_id":"..."}) -> appends the role-appropriate builder or planner audit summary automatically

Canonical Surface Manifest

CodeLens now publishes a single machine-readable surface manifest at codelens://surface/manifest.

Use it when you need the authoritative source for:

  • workspace version and members
  • live registered tool count and output-schema coverage
  • profile/preset membership
  • supported language families and extensions
  • server-card summary inputs

Repository docs consume the generated form of the same manifest at docs/generated/surface-manifest.json.

TTL Guidance

Recommended rule:

  • ttl_secs = expected_duration * 1.5
  • default to 600 seconds when unsure
  • cap long claims at 3600 seconds unless there is a concrete reason to hold them longer

Short TTLs are safer than stale claims. Renew intentionally if the work is still active.

Rename and Broad Refactor Notes

For rename-heavy changes, do not jump straight from verify_change_readiness to mutation.

Use:

  • safe_rename_report
  • or unresolved_reference_check

before:

  • rename_symbol
  • or any broad rename/refactor pass that depends on symbol identity

Minimal Planner -> Builder Pattern

The public pattern is:

  1. planner attaches to the read-only surface
  2. planner runs bootstrap + structure + diagnostics + verifier
  3. planner registers intent and claims files
  4. builder attaches to the mutation-enabled surface
  5. builder performs the bounded change
  6. planner or builder runs post-edit diagnostics
  7. builder releases claims

This pattern works with any orchestrator that can call MCP tools. Custom agent wrappers can improve ergonomics, but they are not required for the core CodeLens integration.