lazy-intel

lazy-intel is an autonomous local code-intelligence MCP for OMP.

OMP sees exactly one MCP tool: code_intel.

Internally, lazy-intel owns zvec-grep and CodeGraph derived-index lifecycle and uses Serena as live LSP semantics. OMP Sharpshooter remains the durable memory owner.

OMP / Sharpshooter(memory)
          |
          | one stdio MCP
          v
     lazy-intel
   autonomous control plane
      /      |       \
   zvec   CodeGraph  Serena
 retrieval   graph     LSP
      \      |       /
        fused evidence

Design contract

There is no manual index lifecycle in the normal path.

Related MCP server: codegraph

Autonomous indexing

With the default configuration:

1. MCP startup registers the project (LAZY_INTEL_ROOT or process cwd) and starts a background bootstrap.

2. Readiness comes from the backends themselves — zg status --check-ready and codegraph status, never from a directory guess — so a half-built or aborted index is detected instead of trusted.

3. A missing index is created on first use; an index that is currently building is reported as building rather than rebuilt underneath itself.

4. A recursive filesystem watcher bumps a generation counter on real source changes. Every path segment is filtered, so nested node_modules, dist, .build, .venv, __pycache__, and the derived index directories cannot create feedback loops.

5. Freshness is change-driven: each backend reconciles once when the process has no baseline for it (changes made while lazy-intel was down are unknowable), then syncs only when its applied generation falls behind the watcher generation. A quiet workspace costs zero subprocesses; there is no wall-clock re-index timer. status reports dirty: null with baseline: "unverified" instead of guessing.

6. Authoritative zvec freshness comes from lazy-intel's own dirty sync (zg index); queries additionally carry --refresh (background for auto, wait for strict, off for fast) so the shared zvec-grep daemon can also refresh anything the watcher missed.

7. Index work is serialized per backend in FIFO order. An explicit reindex/repair queued behind an in-flight sync still executes; it never inherits the other job's result.

8. Repeated index failures escalate to a rebuild when LAZY_INTEL_AUTO_REPAIR=true.

9. The agent can call status, sync, reindex, or repair through the same code_intel tool. No separate admin MCP is exposed.

Freshness modes

auto is the normal production mode. fast exists only for explicitly latency-biased calls.

Embedding integration

lazy-intel defines no embedding default. A new zvec index inherits the shared zvec-grep configuration (global default model, device, and model cache), so a machine that already runs zvec-grep keeps exactly one vector space and one model download. --embedding is passed only when LAZY_INTEL_EMBEDDING is set or the agent explicitly provides embedding with operation=reindex; existing indexes keep their stored schema during automatic repair.

Agent control plane

Still only one tool:

code_intel(...)

Intelligence operations:

• auto

• search

• architecture

• impact

• symbol

• references

• implementations

• diagnostics

Control operations available to the agent:

• status

• sync

• reindex (optionally set embedding to intentionally change zvec vector space)

• repair

backend=all|zvec|codegraph|serena scopes control operations. Serena has no derived index: repair restarts/warm-checks its live LSP process.

Examples:

{
  "operation": "architecture",
  "query": "trace the call flow from index commit to search result refresh",
  "root": "/src/folio"
}

{
  "operation": "reindex",
  "backend": "codegraph",
  "root": "/src/folio"
}

{
  "operation": "status",
  "root": "/src/folio"
}

Install into an OMP project

# Node >=22.5 <25 must be the active runtime for install and for the MCP entry.
PATH="$(brew --prefix node@22)/bin:$PATH" ./scripts/install.sh --global

This installs the pinned backends project-locally (node_modules/.bin/zg, node_modules/.bin/codegraph), installs the pinned serena-agent with uv, runs doctor, and merges lazy-intel into ~/.omp/agent/mcp.json (--global) or <project>/.omp/mcp.json.

The install also adds zvec-grep and codegraph to OMP's disabledServers: exactly one code-intelligence MCP stays connected, so there is one embedding runtime, one model cache, and one derived-index owner.

It does not run a manual lazy-intel init. Index creation starts automatically when OMP starts lazy-intel and is guaranteed on first use. After that, index maintenance requires no user action.

Default OMP runtime settings

LAZY_INTEL_AUTO_INDEX=true
LAZY_INTEL_AUTO_REPAIR=true
LAZY_INTEL_MAINTENANCE_MS=5000     # dirty-only maintenance tick; 0 disables it
LAZY_INTEL_INDEX_TIMEOUT_MS=600000
LAZY_INTEL_TIMEOUT_MS=30000
LAZY_INTEL_ZVEC_MODE=auto          # zvec transport: direct | server | auto
LAZY_INTEL_SERENA_CONTEXT=agent    # Serena 1.7 context name
SERENA_USAGE_REPORTING=false
DO_NOT_TRACK=1

Optional: LAZY_INTEL_ROOT pins the bootstrap root, LAZY_INTEL_EMBEDDING overrides the inherited zvec model for new indexes, LAZY_INTEL_PROBE_TIMEOUT_MS bounds readiness probes, and LAZY_INTEL_ZG_BIN / LAZY_INTEL_CODEGRAPH_BIN / LAZY_INTEL_SERENA_BIN override binary resolution.

Trust boundaries

• Executables never resolve through the requesting project's node_modules/.bin or PATH. zvec/CodeGraph use this installation's pinned dependencies; Serena uses the installed ~/.local/bin/serena. Overrides must be absolute, executable files and are canonicalized with realpath. The installer records Serena's canonical absolute path.

• MCP request roots are canonicalized before containment checks. They must be the process boot root (LAZY_INTEL_ROOT or cwd), a descendant, or inside an explicit LAZY_INTEL_ALLOWED_ROOTS entry (platform path delimiter). A sibling prefix or symlink escaping the allowlist is refused. relativePath cannot escape the requested root either. These are routing boundaries, not an OS sandbox against a concurrently hostile filesystem or a compromised backend.

• Managed index roots/watchers are capped by LAZY_INTEL_MAX_ROOTS (default 8, maximum 64). Canonical aliases share one slot. On exhaustion, requests fail without creating another watcher; restart the MCP to release slots. In-flight work is never evicted to make room.

• impact requires symbol; no implicit explore fallback. References and implementations require both symbol and relativePath.

• OMP abort/timeout notifications propagate to Serena calls. A cancelled caller does not retry/restart a shared backend or cancel another caller's startup.

• OMP configuration parsing/permission failures stop installation. Writes use a same-directory exclusive temporary file, fsync, atomic rename and mode 0600; unrelated server entries and explicit lazy-intel environment settings are preserved. MCP request timeout covers index creation plus query execution.

• Runtime observes sync/reindex/repair as derived-state effects. status and intelligence queries remain reads; no additional MCP tools or approval owner are introduced.

Denied roots

The agent home (OMP_HOME, default ~/.omp) and the zvec-grep home (ZVEC_GREP_HOME, default ~/.zvec-grep) are never indexed. They are agent private state — session transcripts, blobs, logs, SQLite WALs — that the running harness rewrites continuously, so a watcher rooted there never settles and every sync re-embeds files that are still being appended to.

The match is on the exact directory, never a prefix, so a real repository nested inside one — such as ~/.omp/agent — is still indexed normally. Automatic bootstrap skips a denied root silently; an explicit code_intel call against one fails with the reason instead of quietly indexing it. LAZY_INTEL_DENY_ROOTS adds further directories, separated by the platform path delimiter.

Pinned upstreams (2026-09-08)

• @zvec/zvec-grep 0.2.1

• @colbymchenry/codegraph 1.6.0

• serena-agent 1.7.0

See upstreams.lock.json and THIRD_PARTY_NOTICES.md.

Requirements

• macOS/Linux

• Node >=22.5 and <25 (a newer default node on the machine must be overridden for install and for the MCP command; install-omp writes the runtime it was executed with)

• npm

• Python 3.13 + uv for Serena

Operational traps

• zvec daemon lease. When a zvec-grep daemon is running it owns index writes for a root; --mode direct then fails with ZVEC_GREP.ENGINE.DAEMON_LEASE_ACTIVE. Keep LAZY_INTEL_ZVEC_MODE=auto. If indexing hangs with no output, the daemon itself is stuck — zg server off && zg server on restores it (verified: a stuck daemon hung zg index past 300s; after restart the same index finished in ~4s). That daemon is machine-wide: zg install may have wired it into other agents too, so restart it only when no other client is mid-operation.

• Freshness without a watcher. If the recursive watcher cannot attach (container mounts, exotic filesystems), status.freshnessSource reports periodic fallback and LAZY_INTEL_MAX_STALE_MS (default 60000) drives periodic syncs. With a live watcher, time plays no role.

• Serena contexts. Serena 1.7 has no ide-assistant context. Valid names include agent (default here), ide, and codex.

• Cross-file JS/TS semantics. Serena's language server needs a declared project scope; this repo ships jsconfig.json so references/implementations resolve across files instead of returning an empty result.

Truth hierarchy

current source + compiler/tests
              >
live language semantics (Serena/LSP)
              >
indexed structure (CodeGraph)
              >
retrieval relevance (zvec-grep)

The indexes are fully autonomous, but they remain derived acceleration state, not correctness truth.

Failure behavior

A backend failure does not take down the MCP. Intelligence queries return whatever selected backend evidence is healthy, and a call where every selected backend failed is reported as an MCP tool error instead of an empty success.

Retries are bounded: a failing backend backs off 30s, 1m, 2m, … up to 15m, the maintenance tick skips a backend that is already busy or not yet due, and the automatic rebuild escalation fires once per failure streak. A failed semantic call restarts Serena once; cancellation does not. Explicit maintenance reports an MCP error if any targeted backend fails, so a partial repair cannot be journaled as a successful effect.

The agent can force recovery with:

{ "operation": "repair", "backend": "all" }

No user-operated doctor -> init -> reindex loop is required.

CLI

The install does not create a global lazy-intel bin (no npm link); OMP launches src/cli.js by absolute path and humans run it the same way:

node src/cli.js serve
node src/cli.js doctor [root]                   # pinned-version + backend + index diagnostics
node src/cli.js init [root] [--rebuild]         # optional/manual compatibility path
node src/cli.js install-omp [root] [--global]   # --global writes ~/.omp/agent/mcp.json

Run these with a supported runtime (PATH="$(brew --prefix node@22)/bin:$PATH"); install-omp refuses to write an out-of-range Node into OMP configuration. doctor fails when a resolved backend does not match upstreams.lock.json, so version drift is visible instead of silent. Add npm link yourself if a global lazy-intel command is wanted.

The CLI control commands are diagnostics/compatibility only. Normal lifecycle ownership lives inside the MCP runtime.

Tests

npm run check:integration
npm run test:integration
npm run test:compatibility   # real pinned backends, scratch workspace; no model calls

PR CI covers the executable/root/installer/cancellation boundaries on Node 22 and 24. Scheduled/manual compatibility runs install exact backend pins and use a local Qwen embedding model. They exercise search, architecture, impact, references and symbol lookup, then measure one restart-first and warm search sample. They do not measure general relevance or model performance.

Local verification (2026-09-09, macOS arm64, Node 22.22.3): real zvec-grep 0.2.1, CodeGraph 1.6.0 and Serena 1.7.0 passed that compatibility exercise. First search including index creation: 7,236 ms; first search after MCP restart: 2,556 ms; warm search: 1,797 ms. Keep the existing restart reconciliation policy; these are single samples, not latency percentiles.