Atlas

Atlas is the repository navigation and inspection system. It resolves code and documentation subjects, loads chart context, builds graph-backed packets, and hydrates optional runtime layers through injected host capabilities.

Package Shape

Atlas is intentionally split across package roles:

• atlas-core: transport-agnostic inspection engine and provider seams.
• @getuserfeedback/atlas: higher-level host package, local MCP server, and local CLI surface.

Callers should treat Atlas as a layered inspection surface. Local and remote hosts provide environment capabilities; Atlas core stays transport-neutral.

Common Commands

Run commands from the repository root:

bun run atlas overview <path-or-symbol>
bun run atlas inspect <path-or-symbol>
bun run atlas inspect <path-or-symbol> --layer runtime
bun run atlas route <from> <to>
bun run atlas facts --files <paths...> --render atlas
bun run atlas review --staged
bun run atlas cold-roots
bun packages/atlas/src/mcp.ts

Use bun test --dots packages/atlas for the host package tests and bun test --dots packages/atlas-core for the core package tests.

Docs

• Package shape
• Runtime layer transport
• Chart authoring

Runtime Layers

Public Atlas surfaces should let callers ask for product layers, such as layers: ["runtime"]. Callers should not pass provider kinds, provider refs, binding IDs, or credentials. Atlas discovers provider bindings from charts and routes them through injected host providers. Runtime layers are opt-in; default inspect packets do not call runtime providers or emit provider-unavailable runtime issues.

MCP

Atlas exposes a local stdio MCP server as the default @getuserfeedback/atlas executable. The current agent-facing tools are:

• overview accepts { files?, staged? } and returns the same overview packet data as atlas overview inside a packet envelope with atlas.packetId.
• inspect accepts { target, layers? } and returns the same inspect packet data as atlas inspect inside a packet envelope with atlas.packetId.
• route accepts { from, to } and returns the same route packet data as atlas route inside a packet envelope with atlas.packetId.
• facts accepts { files?, staged?, render? } and returns the same output as atlas facts.
• feedback accepts { packetId, verdict, note?, missedTags?, openedTargets? } and records the same feedback telemetry as atlas feedback.
• review accepts { files?, staged? } and returns the same architecture review output as atlas review.
• cold_roots accepts { globs? } and returns the same cold-root query result as atlas cold-roots.

The server also exposes prompt and resource guidance for making Atlas useful in new or low-signal areas:

• setup-atlas is a prompt for adding the smallest useful chart coverage when Atlas output reports missing or incomplete chart context.
• answer-atlas-clarification is a prompt for handling atlas.clarifications.nextAction from MCP inspect output.
• atlas://docs/chart-jsonc describes the chart contract and setup triggers.
• atlas://docs/chart-examples provides small chart examples.
• atlas://docs/clarification-workflow describes how interactive and non-interactive MCP clients should ask or report pending chart questions.
• atlas://docs/navigation-workflow describes the default agent workflow.

When inspect returns atlas.clarifications.nextAction, interactive MCP clients should ask the user the supplied prompt, then call clarify with the selected choice's toolCall.arguments. Non-interactive clients should print the prompt and exact clarify payloads instead of guessing an answer. Prefer the MCP clarify tool over shelling out to applyCommand or editing chart.jsonc directly.

CLI and MCP share the same packet envelope contract. The CLI renders the envelope's packet as terminal JSON and prints the feedback CTA separately; MCP returns the envelope JSON so agents can pass atlas.packetId directly to the feedback tool.

Credentials and provider lookup details stay outside the tool input; hosts inject runtime providers when they want runtime-backed layers.

Codex can launch the local MCP server directly from this repository:

[mcp_servers.atlas]
command = "bun"
args = ["packages/atlas/src/mcp.ts"]
cwd = "/path/to/repo"
enabled = true
startup_timeout_ms = 5000
tool_timeout_sec = 30
default_tools_approval_mode = "approve"

After publishing, MCP clients can launch the package without repo-local paths:

{
  "mcpServers": {
    "atlas": {
      "command": "bunx",
      "args": ["-y", "@getuserfeedback/atlas"]
    }
  }
}

The published Atlas MCP executable currently targets Bun. Keeping cwd at the repository root makes the server easier to launch from different worktrees. Atlas still resolves the inspected workspace from MCP roots/list or Codex workspace metadata, so the process cwd is only the code loading location, not the authority for the target repository.

The local MCP server can be launched with an env-configured runtime hydration transport:

ATLAS_RUNTIME_HYDRATION_PROVIDER_KIND=agent-runner \
ATLAS_RUNTIME_HYDRATION_URL=https://runtime.example/hydrate \
ATLAS_RUNTIME_HYDRATION_TOKEN_ENV=CODEX_RUNTIME_TOKEN \
CODEX_RUNTIME_TOKEN=... \
bun packages/atlas/src/mcp.ts

Use ATLAS_RUNTIME_HYDRATION_PROVIDER_KINDS with a comma-separated list when the same host transport should serve multiple chart provider kinds. The token is sent as an HTTP authorization header by the local transport; callers still only ask for layers: ["runtime"]. The local MCP entrypoint also sends non-secret local repo context, such as root label, HEAD revision, and dirty status, plus the requested and resolved inspect targets inside the runtime hydration request so the remote host can diagnose and authorize with better hints.

Atlas MCP emits the same packet telemetry as the CLI when launched through the local entrypoint. Set ATLAS_DISABLE_TELEMETRY=1 for smoke tests that should not send telemetry. Set ATLAS_TELEMETRY_BASE_URL=http://127.0.0.1:<port> only for explicit local delivery tests; production defaults to https://telemetry.getuserfeedback.com.

The stdio smoke test covers tool listing, workspace-root resolution through MCP request context, all agent-facing tools, and local telemetry delivery:

bun test --dots packages/atlas/src/mcp-stdio.test.ts

telemetry/atlas-usage-report provides the first consumption shape for Atlas events. Feed it decoded atlas.event rows to summarize packet volume by view, low-signal packets, feedback verdicts, usage errors, and frequently requested files.