Built-in agents

Built-in agents are first-party, read-only multi-agent flows that ship inside the Gateway. Each one decomposes a query into sub-agents over your local index and returns a structured Markdown brief.

Three properties hold for every built-in agent:

Read-only. No write tools in scope. The HITL consent gate is never triggered.
Parallel where possible. The coordinator runs independent sub-tasks concurrently against isolated tool scopes — typically 3–6 at a time — so a brief assembles in seconds rather than the sum of every sub-step.
Local-first. Every sub-agent reads from the local SQLite index. No live API call is made unless a connector explicitly resolves a missing reference.

Twelve ship today:

Agent	Answers	Needs
`nimbus expert`	Who has the most context on this?	Local index
`nimbus impact`	If I change this, what breaks?	Local index
`nimbus catchup`	What changed while I was away that matters to me?	Local index
`nimbus why`	Why is this line the way it is?	Local index (+ local `git blame`)
`nimbus glossary`	What does this term mean on this team?	Local index (+ optional local LLM)
`nimbus decisions`	What did we decide, and why?	Local index (+ optional local LLM)
`nimbus owners`	Who wrote this code, and how much?	Local index (git blame)
`nimbus ghost`	Who else knows this file?	Paired peers
`nimbus conflicts`	Is someone already working on this?	Paired peers
`nimbus huddle`	What did the team do yesterday?	Paired peers
`nimbus janitor`	Is this cloud resource still in use?	Local index
`nimbus preflight`	Will this change break a downstream owner?	Paired peers

The four peer-backed agents return an honest gap note rather than a wrong answer when you have no paired peers — see Cross-colleague agents below.

`nimbus expert <topic-or-file>`

Answers who on my team has the most context on this? by ranking team members against the relationship graph and indexed metadata: PR authorship via indexed code symbols, review participation patterns, Slack thread activity, and Linear / Jira ticket assignments.

nimbus expert src/billing/retry.ts
nimbus expert "payment retry logic"

The output is a ranked Markdown brief. Each row carries a confidence score and the evidence behind it — for example “authored 4 of the last 6 PRs touching this file, resolved 2 incidents tagged payment-retry”. Pipe --json for machine-readable output.

No new connectors required. The agent uses the people graph already populated by the Phase 2 cross-service identity linker.

Notification: The Gateway emits expert.briefReady { sessionId, brief } on completion. The CLI subscribes to this and renders the brief to stdout, respecting NO_COLOR.

`nimbus impact <file-or-PR-url>`

Answers if I change this, what breaks? by running a reverse-dependency query across the relationship graph. Five parallel sub-agents resolve, concurrently:

which services import the affected module (via indexed code symbols and depends_on graph edges)
which pipelines would rebuild (via pipeline_run items linked to the repo)
which dashboards pull from affected data models (via upstream_refs graph edges)
which on-call rotations own the affected services (via the PagerDuty schedule index)
which owning teams are responsible

nimbus impact src/billing/retry.ts
nimbus impact https://github.com/your-org/your-repo/pull/312

Output is a structured impact report with blast radius grouped by category. Use --json for CI integration — the structure is stable and suitable for gating deploys based on impact thresholds. The optional --service filter narrows the report to a single owning service.

Notification: impact.briefReady { sessionId, brief }.

`nimbus catchup [--since <duration>]`

Answers what changed while I was away, and which of it actually matters to me? Unlike a uniform cross-service changelog, catchup is personalised: it weights everything that happened while you were away by your historical involvement — services you own, repos you contribute to, incidents you have responded to, people you collaborate with frequently.

nimbus catchup
nimbus catchup --since 7d
nimbus catchup --since 1w --json
nimbus catchup --service github

Five parallel sub-agents resolve the personalisation signals concurrently — owned services, active repos, responded incidents, frequent collaborators, and the window of items modified during the requested interval — and a Stage 2 scorer ranks each window item against those signals before grouping by service.

The self-person resolver runs synchronously up front in three tiers: [user] me_person_id from the active profile’s nimbus.toml → git config user.email → OS username matched against person.github_login. If none matches, the brief renders a missing_user_identity gap note pointing at nimbus config set user.me_person_id <id>.

Default window: 3d. Maximum --since: 90d (or 12w). Output: Markdown grouped by service, ordered by aggregate relevance, with each item annotated by the signals that lifted its score (owned_service:<id>, active_repo:<owner/repo>, incident_service:<id>, collaborator:<personId>). Pipe --json for machine-readable output that round-trips through JSON.parse.

No new connectors required. Reads exclusively from the local index.

Notification: catchup.briefReady { sessionId, brief, findings }.

Implicit-knowledge agents

Three agents recover knowledge nobody ever wrote down, from content already in your index. They are read-only like every other built-in agent, but two of them (glossary and decisions) own a persisted extraction pass with its own watermark: the brief you read is a materialised table, and the mining happens in the background, debounced after a successful connector sync.

`nimbus why <ref>`

Answers why is this line the way it is? — six parallel lanes over the local relationship graph:

authorship — who last touched the line, and when
pull request — the PR that merged it
ticket — the issue it resolves
discussion — Slack / Teams messages mentioning the commit, PR, or ticket
driver — a temporally correlated incident within a 48 h window (a correlation, explicitly never a causal claim)
downstream — reverse depends_on edges from the file’s indexed symbols

nimbus why src/billing/retry.ts:42
nimbus why retryPayment --peek
nimbus why src/billing/retry.ts --line 42 --json

<ref> is a path[:line] or a bare symbol name resolved against indexed code symbols. A lane with nothing to show degrades to a gap note naming the missing connector or graph relation rather than going silent.

--peek returns a sub-300 ms one-liner (author · short SHA · date · subject · PR # · ticket) through a separate synchronous method, agents.whyPeek — the one built-in that answers in the response rather than via a notification.

One local read outside the index: an unblamed line triggers a single, cached, root-fenced local git blame subprocess, scoped to a configured [[filesystem.roots]] repo and cached forever after. That is a local git read, not a connector dispatch — no live API call.

Notification: why.briefReady { sessionId, brief, findings } (the --peek path emits none).

`nimbus glossary [<term>]`

Turns terminology the team already uses — but has never written down — into a queryable glossary, extracted entirely from the local index. With no argument it prints terms sorted by frequency; with a term it prints the team’s consolidated definition, resolved against an exact match, then a known synonym, then (on a miss) a “did you mean” list of near-misses.

nimbus glossary
nimbus glossary CDR
nimbus glossary --limit 50 --json
nimbus glossary --refresh
nimbus glossary --rebuild --yes

Candidates are mined deterministically from indexed titles and bodies and must appear across at least min_doc_freq (default 3) source items before a term is considered; a local LLM then consolidates or vetoes each candidate. Without a local model, the pass falls back to a verbatim snippet definition — honest and attributable, but not synthesized — which a later pass automatically re-consolidates once a model is available. You can also author or correct a definition by hand in [glossary.terms] / [glossary.synonyms] in nimbus.toml; a manual definition wins on collision and never auto-changes.

--refresh runs an on-demand pass instead of waiting for the next sync; --rebuild --yes truncates the store and re-derives from scratch.

Notification: glossary.briefReady { sessionId, brief, findings }.

`nimbus decisions`

Answers what did we decide, and why? — recovers decisions buried in Slack / Discord / Teams messages, Notion / Confluence / Obsidian pages, and Linear / Jira / GitHub / GitLab issues (“we decided X because Y, alternatives were Z”), then corroborates each one against downstream PRs, commits, and ADRs already in the local relationship graph.

nimbus decisions
nimbus decisions --since 30d --service billing
nimbus decisions --explain --min-confidence 0.5
nimbus decisions --refresh
nimbus decisions --json

The read path is pure SQLite — it never calls a model — and prints a chronological, confidence-scored list with evidence links and a ⚠ no ADR found marker where one is missing. --explain shows the four confidence terms (cue_strength, corroboration, source_authority, completeness) behind each score.

Two limits the brief states out loud rather than hiding: the confidence ceiling is 0.86, not 1.0, because migration / iac evidence is in the schema but no connector indexes a change’s file paths yet; and a brief reports how many of its sources were indexed with a truncated body, so a decision stated deep in a long document is never silently missed.

Notification: decisions.briefReady { sessionId, brief, findings }.

`nimbus owners [<path>]`

Answers who wrote this code, and how much? — ranks people against a file, directory, or [ci.service.<id>] service by recency-weighted git blame share, using blame data the Gateway already indexes for nimbus why. With no argument it prints a coverage summary: when the derivation pass last ran, how many roots and files it covered, and which services it bound.

Read this before you trust the ranking: this is authorship-derived ownership, not accountability. It answers who wrote these lines, from git blame — never who is responsible for approving a change to them. There is no CODEOWNERS file, no code-review data, and no on-call rotation anywhere in the local index. Treat the result as a starting point for who to ask, not an approval list — and every brief repeats this, not just this page.

nimbus owners
nimbus owners src/billing/retry.ts
nimbus owners src/billing
nimbus owners --service billing
nimbus owners --refresh
nimbus owners --json

<path> must be inside a configured git-aware root — either a [[filesystem.roots]] block or a nimbus index add registration — and is mutually exclusive with --service. A path with no owners of its own still routes to its parent directory, so a one-line file isn’t a dead end. Owners below a configurable share ([ownership].min_share, default 5%) are dropped from the list but still counted toward the true total, and vendored / generated / lock files are excluded from aggregation by default ([ownership].ignore_globs) so nobody is credited with “owning” a directory because they last ran npm install.

--refresh runs the derivation pass on demand instead of waiting for the next debounced post-sync run.

Notification: ownership.briefReady { sessionId, brief, findings }.

Cross-colleague agents

Three agents surface what other people are doing, by fanning the federated query primitives across peers you have explicitly paired with. Every fan-out goes through the consent-scoped federated query gate — a peer only ever answers within a namespace it published and granted to you.

They need paired peers. On a solo install these agents return a gap note explaining the empty sweep rather than an empty brief that looks broken. See HITL & safety for how pairing and consent work.

`nimbus ghost <file>`

Ranks teammates by their expertise on a file across paired peers, surfacing their recent PRs, issues, and commits touching it — so you know who to ask before you start. No message is ever sent; this is a suggestion surface.

nimbus ghost src/auth/session.ts
nimbus ghost src/auth/session.ts --namespace project:zurich
nimbus ghost src/auth/session.ts --json

Omit --namespace for an ambient sweep across every paired peer.

Notification: ghost.briefReady.

`nimbus conflicts <file>`

Warns of work-in-progress collisions before you edit a file — teammates with an open PR, an assigned ticket, a recent commit, or an open branch touching the same path.

nimbus conflicts src/auth/session.ts
nimbus conflicts src/auth/session.ts --namespace project:zurich

Output is ordered by recency, with a gap note for any peer that was unreachable.

Notification: conflicts.briefReady.

`nimbus huddle`

A team-scoped morning briefing: each teammate’s recently merged PRs, closed tickets, and resolved incidents from across paired peers — a status summary nobody had to write.

nimbus huddle
nimbus huddle --since 86400000
nimbus huddle --namespace project:zurich --json

--since is a lookback in milliseconds (default 86 400 000 = 24 h).

Notification: huddle.briefReady.

Change-safety agents

`nimbus janitor <resource-ref>`

Answers is this cloud resource still in use, and what breaks if I delete it? — cross-references a resource against indexed deployments, dashboards, alerts, and on-call rotations, and reports how long it has been idle.

nimbus janitor arn:aws:s3:::legacy-reports
nimbus janitor legacy-reports --idle-days 30
nimbus janitor legacy-reports --cleanup aws.s3.bucket_delete
nimbus janitor legacy-reports --allow-gaps --json

--allow-gaps lets it reach a verdict even when some evidence lanes are missing; by default an incomplete sweep is called out rather than concluded from.

Read-only until you approve. The brief itself deletes nothing. A --cleanup <action.type> proposal is a proposal: it still passes your HITL consent gate before anything executes.

Notification: janitor.briefReady.

`nimbus preflight <ref> --namespace <ns>`

Blast-radius preflight before a change lands: asks each paired downstream owner in a namespace to run their own verification against your candidate ref, then merges the answers.

nimbus preflight src/billing/retry.ts --namespace project:zurich
nimbus preflight src/billing/retry.ts --namespace project:zurich --strict
nimbus preflight approve req_8f3c21

--namespace is required. Each downstream owner approves the request behind their own consent gate, so the call blocks on human responses for up to ten minutes. The exit code is non-zero if any downstream’s verification failed — with --strict, also on incomplete coverage — which makes it usable as a CI gate. nimbus preflight approve <request-id> responds to an inbound request as the local owner.

Not the same command as nimbus deploy preflight, which runs local pre-deploy checks for a service.

Notification: preflight.briefReady.

Implementation reference

Built-in agents live at packages/gateway/src/agents/ in the repository. Each agent is a single file; the ones that fan out use AgentCoordinator to decompose into parallel sub-agents over scoped tool sets, then synthesise the results into a Markdown brief (deterministic renderer, with optional LLM polish when a model is configured).

Full flag-by-flag detail for every command above lives in the CLI reference in the repository at docs/cli-reference.md. Authoring guidelines for new built-in agents live in the contributor reference at .claude/commands/nimbus-agent-patterns.md.

Where to next

Your first queryFree-form ask, structured query, and what happens under the hood.

HITL & safetyWhy built-in agents never trigger consent — and what does.

Architecture overviewThe multi-agent coordinator, sub-agent isolation, and the LLM-facing tool envelope.