Agent Inbox

A calm, precise control tower for supervising Codex, Claude, and Gemini coding runs inside VS Code.

See your agents' conversations across open projects, with observed Codex activity and a persistent session inspector. Optional workspace feeds add exact attention/review states, changed files, stage traces, and reported costs.

Start here

1. Install Agent Inbox. Open Agent Inbox: Open Control Tower from the Command Palette, click the activity-bar icon, or press ⌘⌥I on macOS / Ctrl+Alt+I on Windows and Linux.
2. Open and trust the project folder where you use your agents. Agent Inbox automatically discovers saved Codex and Claude CLI/VS Code conversations, and Gemini CLI conversations, on the extension host. No CLI executable, login, API key, or workspace feed is required.
3. Find observed Codex turns under Active now, and other conversations under Session history. Select a card to see its task title, latest saved message, source, timestamp, and status evidence. Checks run every five seconds (long scans finish before another starts), or using Refresh.
4. If nothing appears, run Agent Inbox: Show Discovery Sources. It lists the host/environment, project folders, searched directories, and unreadable/unsupported files. Explore Sample Fleet is an optional, explicitly labelled preview.

Saved history alone is not live state. On Linux and macOS, Active turn requires an unfinished Codex turn record, a matching writable transcript handle owned by a live Codex process that predates the turn, and a transcript update within five minutes. This observes an open turn, not whether it is computing or waiting for input. Completion, cancellation, process exit, and stale evidence remove observed activity. Missing permissions, unsupported formats, a separate process namespace, or a silent long-running tool can leave an active session unknown. Unknown does not mean idle. Claude and Gemini remain saved history only.

Turn completed means only that the last recorded turn ended—not that tests passed or work is ready to review. Agent Economy now reads supported usage and timing records; missing data remains unknown, and estimated cost is not a bill. Continue or approve work in the original agent; Copy session ID does not send anything. Optional workspace feeds provide explicit live states, metrics, changed files, and adapter-managed responses.

Remote SSH, Linux, and macOS

Agent Inbox is a workspace extension: with VS Code Remote SSH, it runs on the remote server beside your code and agents, while the dashboard displays on your laptop. Install/update javess.agent-inbox in the SSH: your-server extension section if VS Code offers that button. Open the same server-side project folder used by your agents and trust it.

The server's home directory and environment are used—not the laptop's. This also applies to WSL and dev containers: session files must be accessible to the extension host in that environment. There is no cross-machine, cross-user, or cloud synchronization. Sessions existing only on the laptop won't appear in a server-hosted dashboard, or vice versa.

Show Discovery Sources identifies the environment (ssh-remote, local, etc.) and exact directories. Developer: Show Running Extensions can confirm Agent Inbox is running remotely. If an agent uses a custom data directory or a variable exported only in an interactive terminal, set the corresponding Agent Inbox data directory in VS Code's Remote Settings. Settings are machine-scoped and cannot be supplied by repository configuration.

Discovery matches recorded working directories to open project folders and their subfolders, with resolved path boundaries. Gemini supports legacy hash-directory JSON and newer project-marker/registry JSONL storage. Subagent-only records are excluded. Provider retention, disabled session persistence, unavailable cloud conversations, permissions, or format changes can limit discovery. Codex/Claude metadata uses bounded head/tail reads; usage indexing then reads workspace-validated JSONL incrementally (up to 4 MB per file and 32 MB per scan). Gemini replay is limited to 8 MB per session. Accounting retains up to 4,000 entries per record category and 50,000 entries across indexed files; reaching a bound produces a partial subtotal. Large histories may take several refreshes to index. Scans inspect at most 1,000 candidates and 12,000 directory entries per source, returning up to 50 matching sessions per source and 200 overall. Diagnostics disclose skipped files and scan limits. Very large older histories may be outside these bounds.

Disable agentInbox.autoDiscover in Settings to use workspace feeds only, or agentInbox.codexLiveStatus to keep discovery without process observation. Both settings are machine-scoped. Codex lifecycle lookback is bounded to 8 MB when necessary. Show Discovery Sources reports process-observation limitations as well as history scan limits. Vendor transcript formats are internal and may change; these are best-effort, read-only integrations.

A workspace feed

Select Connect feed to create or open .agent-inbox/runs.json in the workspace. Have your wrapper/integration write snapshots there for exact run states. Each workspace owns its feed. Use stable run IDs, update timestamps and counters, and preferably replace the whole file atomically when publishing a snapshot. VS Code provides schema completion in runs.json.

{
  "version": 1,
  "runs": [
    {
      "id": "queue-admission-42",
      "provider": "Codex",
      "title": "Map queue admission path",
      "status": "running",
      "summary": "Tracing backpressure through the admission controller.",
      "startedAt": "2026-09-17T10:00:00Z",
      "updatedAt": "2026-09-17T10:18:00Z",
      "elapsedMinutes": 18,
      "progress": 62,
      "stage": "Test",
      "inputTokens": 210000,
      "outputTokens": 370000,
      "cost": 0.18,
      "tests": "running",
      "tags": ["infrastructure"],
      "files": [{ "path": "src/admission.ts", "additions": 42, "deletions": 8 }],
      "trace": [{ "stage": "Plan", "minutes": 6, "message": "Mapped queue lifecycle" }]
    }
  ]
}

Required fields are id, provider, title, and status. Providers are Codex, Claude, or Gemini. States are attention, review, running, or recent. Optional fields include testSummary, inputCost, outputCost, toolCost, toolCalls, attentionMinutes, savedMinutes, actionLabel, failed, and an HTTPS sessionUrl. history accepts up to 24 token-count buckets for the last hour, oldest first. Limits are 200 runs per workspace and 2 MB per feed. Invalid feeds show an error instead of invented activity.

Review and respond

• Select a discovered session for Details and Workspace, or a feed run for Details, Files, Tests, and Workspace. Search by task, workspace, provider, or tag; narrow the board by provider, workspace, and state. Press / to focus search. Use arrow keys to navigate inspector tabs. The actions below apply to workspace feeds, not discovered history.
• Review changes opens the file list. Review diff asks VS Code's Git extension for the first reported file's working-tree diff; Git support and a matching local change are required. File links open current workspace files; deleted or missing files cannot be opened in this release.
• Open session opens a supplied HTTPS URL after confirmation.
• Answer agent saves your text to .agent-inbox/responses/<timestamp>-<uuid>.json. Your integration must watch and consume these files. The response contains version, runId, answer, and createdAt. Agent Inbox does not execute shell commands, apply migrations, grant approvals, or change run state itself. Agents remain blocked until your integration handles the response and updates the feed.

Read the economy correctly

Agent Economy is available for local sessions, Remote SSH sessions, workspace feeds, and the sample fleet. Cards show session totals; the economy strip, provider split, budget, burn chart and savings estimate cover Today in the extension host's timezone. Board filters do not change fleet totals.

• Codex: per-response usage records, with cumulative-counter fallback for older formats. Cache reads/writes are subsets of input; reasoning is a subset of output. Explicit completed turn intervals and currently observed turns provide work time, excluding gaps between turns. Parallelism is summed recorded work divided by the union of its occupied intervals—not session age.
• Claude: recorded input and cache usage, unique tool calls, and finalized streaming output when present. Intermediate output remains provisional. Native logs often lack finalized output and cache-creation TTL; those costs remain an explicitly labelled subtotal. Conversation timestamps are not execution duration.
• Gemini: per-response tokens, including thoughts, model switches and tool-call counts. JSON/JSONL replacements and rewinds are replayed before counting. These are retained-history totals, not lifetime spend; rewinding a conversation does not refund a bill. Execution duration and completion state remain unknown.
• Human attention saved / Attention ROI: configurable planning assumptions, initially 30 minutes manual work minus 5 minutes review per session with a recorded completion today. Multiple turns do not create multiple completed tasks. Active/stopped/unknown sessions are not assumed complete. Set agentInbox.manualMinutesPerSession to 0 to disable native estimates; agentInbox.reviewMinutesPerSession controls review time. Feed-supplied savings/review figures remain adapter reports. None of these counterfactuals are measured human time.
• Cost estimates: standard paid text API-equivalent USD rates checked 2026-09-17, including known cache and long-context tiers. They are not subscription bills, Codex credits, free-tier charges, contracted prices, or statements of actual spend. Audio/image-specific rates, priority/fast tiers, storage, tools and unrecorded retries may differ or be missing. Unknown models stay unpriced. Sources: OpenAI pricing, Anthropic pricing, Gemini pricing.
• Coverage: partial indexing, unsupported counters, scan limits and unknown rates are disclosed. Shared response/turn IDs in forked native histories are excluded from fleet Today/burn/time totals; each session still shows its own retained history. Legacy cumulative counters cannot deduplicate inherited fork history. No identity is guessed from titles or timestamps.

Use agentInbox.pricingOverrides for exact-model prices in USD per million tokens, for example:

"agentInbox.pricingOverrides": {
  "my-exact-model-id": { "input": 2, "cached": 0.2, "output": 10, "write": 2.5 }
}

input means uncached input; write is optional cache-creation pricing. This replaces the built-in pricing policy for that exact model. Invalid rates are rejected.

Workspace feeds supply cumulative USD costs, tokens and durations. Only runs started today can be attributed to Today; older feed runs remain visible but cannot establish today's spend. Missing numeric fields are unknown, not zero. Timestamped history buckets align to updatedAt. If an adapter reports a discovered session too, set nativeSessionId to its exact session ID: that feed run becomes authoritative for the matching workspace/provider/session, avoiding double-counting. Without an explicit link, feeds and native sessions are independent sources. Sample metrics deliberately reproduce an illustrative fleet, including a separate GBP attention-ROI example. They are labelled as sample data and are not your actual spending.

Set agentInbox.dailyBudget (default 30 USD) in Preferences to change the reference gauge. It does not cap spending or stop agents. agentInbox.showSampleOnEmpty is off by default, so an empty discovery result is never mistaken for your own data.

Privacy and trust

Agent Inbox has no runtime dependencies, telemetry, cloud service, or background network requests. In trusted workspaces it reads the fixed workspace feed and known local session locations above. Codex/Claude headers are inspected to determine workspace ownership before matching tails are read; Gemini directories are matched using project hashes, markers, or the registry before transcripts are read. It does not read auth files, API keys, provider settings, or private VS Code databases, and does not launch agents or install hooks. Titles and message excerpts stay in extension memory and the local dashboard. Accounting retains counters, model names, bounded record identifiers and timestamps—not prompts or tool arguments—and makes no billing API calls. With Remote SSH, that dashboard data travels through VS Code's existing connection to your laptop.

Codex observation additionally reads same-user process names, birth times, and descriptor metadata, matched to already workspace-validated transcript files. Linux uses /proc and getconf; macOS uses the system lsof and ps tools with argument arrays and bounded time/output. It never reads command-line arguments, process environments, or descriptor contents, and never requests elevated access. Activity evidence is refreshed independently of the transcript cache.

Workspace trust is required for discovery, feeds, and file/response actions; the sample dashboard is available in restricted mode. File paths are checked against workspace/source boundaries, including resolved symbolic links. The webview has a Content Security Policy, does not load remote scripts, and treats source text as text. Add .agent-inbox/ to your repository's ignore rules if runs or responses contain private context.

The interface uses state labels as well as colors, visible keyboard focus, horizontal board scrolling at smaller widths, high-contrast support, and reduced-motion support. On narrow windows the inspector moves below the board.

Development

Use Node.js 22 or newer. Run npm ci, npm test, and npm run test:ui (requires a Playwright Chromium installation). npm run preview serves the same dashboard locally at http://127.0.0.1:4318. Press F5 in VS Code to run the extension in an Extension Development Host. npm run package builds the installable VSIX.

Agent Inbox is an independent project, not an official extension from OpenAI, Anthropic, or Google.