Skip to content
| Marketplace
Sign in
Visual Studio Code>AI>AO WorkbenchNew to Visual Studio Code? Get it now.
AO Workbench

AO Workbench

vesuliria

|
1 install
| (0) | Free
Provider-independent control plane for AI coding agents with reliable, measurable, recoverable cross-agent handoff.
Installation
Launch VS Code Quick Open (Ctrl+P), paste the following command, and press enter.
Copied to clipboard
More Info

Agent Orchestrator

Your AI coding agent can change. Your task should continue reliably.

Agent Orchestrator has a shared local workbench for VS Code and a standalone desktop window. Import a Codex or Claude Code conversation, choose a model and effort, and save prompts as scheduled automations. Both interfaces read the same local conversation and automation records.

The project also contains a headless coding-task engine that can hand an interrupted task to another agent with its externally verifiable state intact:

  • the repository, captured as git checkpoints;
  • your requirements;
  • the commands that ran and their results;
  • the permission policy;
  • a journal of every transition.

The next agent gets a structured, versioned handoff package that clearly separates verified facts from the previous model's claims. The orchestrator then checks that the work continued: workspace verified, tree matched, turn completed, regressions, and validation.

It does not pretend two models share memory, does not touch your provider credentials, and never pushes or merges anything.

Status: pre-release MVP. The orchestration engine, the extension, and the Claude/Codex adapters are implemented and tested with deterministic mock providers and fake CLIs that emit the documented event formats. Real-provider runs are supported but opt-in, and were not executed as part of this repository's test suite (they consume your quota). See docs/IMPLEMENTATION_PLAN.md.

On 2026-11-08 a separate opt-in check completed two real read-only turns, Codex → Claude, reopening the saved conversation between them. Claude preserved the earlier endpoint and response requirement. This check covers text conversation continuity.

Requirements

  • Node.js ≥ 20 (tested with 22), npm
  • git ≥ 2.23
  • VS Code ≥ 1.90 (tested with 1.105)
  • Optional, for real runs:
    • Claude Code ≥ 2.1.302 (claude on PATH, logged in);
    • the Codex CLI (codex on PATH or a configured path, logged in).

Install, build, test

cd agent-orchestrator
npm install          # dev dependencies only; zero runtime dependencies
npm run build        # tsc → out/
npm test             # unit, integration and scenario tests
npm run test:vscode  # local VS Code with an isolated temp profile; 16 extension checks

test:vscode uses the VS Code installed at /Applications/Visual Studio Code.app and never downloads one. Override the path with VSCODE_EXECUTABLE_PATH.

Open the shared workbench

VS Code. Open the project you want to edit and click the Agent Orchestrator icon in the Activity Bar. The Chat view opens in the sidebar and picks up the latest conversation for the current project. In a multi-folder workspace it follows the active editor. Explicit edit requests can apply reviewed changes to the trusted open project. The automation permission remains separate. To test an unpackaged extension, launch it with F5 and open your project in the Extension Development Host. For a packaged build, run Extensions: Install from VSIX... in your regular VS Code window and select the local package.

Desktop. Run npm run desktop from this folder. This builds and opens a separate Electron window. If your npm configuration skips install scripts, first run npm run desktop:setup to download Electron's runtime.

In Desktop, start a conversation by choosing a local project folder. Open Routing · Auto to set a mode for a conversation in either host.

Mode How it routes Default API requests per run
Auto Classifies the request locally and selects a mode for the task 12
Quota Starts general inspection at low effort and can escalate when it finds wider scope 4
Balanced Starts general inspection at medium effort 12
Quality Starts general inspection and code review at high effort 24

Focused lookups start at low effort. Architecture and cross-component analysis start at high effort in all modes. An inspection can escalate once based on the Scout's findings. Edits add a Writer, an independent Reviewer and a Commentator. Agent activity shows the selected route and each role's provider, model, effort and status.

The local project search resolves named files and looks up symbols with ripgrep or a bounded fallback. It supplies file paths and line numbers for definitions, imports and references. For broader work it also identifies likely entry points. Direct API agents can use the same read-only search tool.

Set API requests per run to customize the cap from 1 to 30. It counts generation requests across all roles, including requests after tool calls. CLI connections have their own provider quotas.

Enable Allow edits once per conversation to apply approved changes automatically. Writers work in an isolated copy. Workbench applies the reviewed patch with a private Git index only after checking that the source files still match the baseline. Existing staged changes stay in the user's index. Folders without Git use a private repository stored by Workbench. Blocked changes stay in the isolated folder shown in the conversation. In VS Code, save open project files before applying edits. If an editor has unsaved changes when the reviewed patch is ready, Workbench keeps the patch for later.

Project checks. Save up to six commands for a conversation, one per line. Workbench runs the approved commands with your computer account in the isolated copy after review. Each command has a five-minute limit. A failed check or a change to the reviewed candidate blocks automatic apply. For a project with a lockfile, you can include a dependency setup command such as npm ci before npm test. Checks are optional and must be explicitly saved for each conversation and folder.

Continue saved edit. After a stopped or blocked edit, reopen the conversation in either host and continue from its isolated copy. Workbench checks that the source still matches the starting state. If the patch had already been applied when the previous host stopped, Workbench verifies the applied tree and restores the reply. Keep copy and start over leaves the files on disk and clears the pending edit from the conversation.

Both hosts use ~/.agent-orchestrator/workbench for conversation and automation data. To isolate a development instance, set AO_WORKBENCH_STORE to another directory before launching it. The older quick-pick conversation commands use extension globalStorage. Their saved .json files can be imported into the workbench alongside provider .jsonl files.

To create an automation, open a conversation, enter a prompt and click Automate. Choose an interval and save it. Run now starts one run. Enabling a schedule authorizes provider usage at that interval while a desktop window or VS Code workbench panel is open. An automation can apply edits only if its creation explicitly authorized edits for the same folder and conversation. The automation keeps the routing mode, API cap and authorized project checks it was created with. Run history records outcomes and the final role's route. Closing both hosts stops scheduling.

If macOS blocks a project folder, use System Settings → Privacy & Security → Files and Folders to check access for the app that started Workbench.

Agent activity shows the plan, public progress updates, and actions that Codex or Claude Code report during a turn. Completed replies retain a short activity history locally. Activity is excluded from the context sent to the next model.

Two hosts share execution locks, so one scheduled occurrence starts once. When an earlier run has an ambiguous outcome after a host stops, its schedule is paused for review. Pausing an automation stops future runs. An active reply can be stopped from its conversation in the host running it.

The workflow uses Codex's model catalog and Claude Code model aliases. VS Code model profiles from User Settings can override the default tiers. On a reported quota limit, another available writer can continue in the same isolated working copy. Other writer failures preserve it for inspection. The desktop is currently a development launcher, with its macOS window tested locally.

Connections

Open Connections → Add connection in either Workbench. A CLI account has a separate local profile. Run its displayed official sign-in command in Terminal, then click Check sign-in. Use named accounts to select the appropriate personal or work account for a conversation. Each conversation picks one primary connection per provider, and can disable either provider.

Choose API key to add an OpenAI Platform or Anthropic API connection. Set it as a primary connection or select it as API fallback. Confirm Allow billed API use before saving the conversation's routes. The fallback is used when the selected primary providers are unavailable. Automations pin the chosen connections to their original project and require separate API consent.

Connection names and routes are shared between Desktop and VS Code. API keys are stored separately in the host's secure storage, so enter a key in each host that should use it. Direct API calls send the key in the provider's authentication header. API stages can list and read regular project text files and write small text files in the isolated editing workspace. CLI connections provide the full agent toolset subject to their policy.

Reproduce a handoff in 10 seconds (no quota, no network)

npm run demo

This creates a throwaway git repo and starts a task on a deterministic mock "Claude":

  1. Mock Claude implements half of the change, then hits a simulated, structured usage limit.
  2. The orchestrator checkpoints the work and builds the handoff package.
  3. Mock "Codex" verifies it can see the checkpointed state, finishes the work, and the tests run.

The output shows every state transition, the handoff (latency, continuity checks, package path), the validation result, and the reliability metrics.

To inspect the result:

  • cat <store>/tasks/<id>/journal.jsonl shows the journal.
  • git for-each-ref refs/agent-orchestrator (inside the demo repo) shows the checkpoints.

The full failure suite (auth rejection, crash mid-handoff, duplicate events, both providers limited, user changes, conflicting edits, failing validation, user cancellation, and more):

node out/src/cli/main.js bench --iterations 5   # writes bench-results/bench-*.json and .md
node out/src/cli/main.js latency                # handoff latency vs repository size

Last run: 95/95 scenario runs passed, 0 duplicate executions, 0 invariant violations, 15/15 crash recoveries consistent, handoff latency p50 ≈ 0.5 s. All of this is with mock providers; see docs/RELIABILITY_BENCHMARK.md.

Run the extension

  1. Open the agent-orchestrator folder (this folder, not its parent) in VS Code.
  2. Press F5 → Run Extension (or Run Extension (isolated profile, no other extensions)).
  3. In the Extension Development Host, open a git repository that has at least one commit, and trust the workspace.
  4. Open the Agent Orchestrator activity-bar view:
    • Agents: providers with install/auth status, availability (unknown unless a provider reported it), quota where a documented API exists, the enforcement mechanism, and actions (Set as preferred, Switch current task to this provider).
    • Task: tasks, state, plan (completed/remaining), workspace, runs, pending approvals, validation, recent events.
    • Handoffs: each attempt source → target · status, with candidates, validation errors/warnings, continuity checks, latency, and failure reason. Actions: Show package, Show prompt, Retry, Confirm, Cancel transition.
  5. Run Agent Orchestrator: New Task…, enter an objective, pick a provider, and the task starts. Use Switch Provider… to hand off manually at any time.

Try it without real providers. In your user settings set:

"agentOrchestrator.dev.mockProviders": true,
"agentOrchestrator.preferredProvider": "mock-claude",
"agentOrchestrator.fallbackOrder": ["mock-claude", "mock-codex"],
"agentOrchestrator.validation.commands": ["node test.js"]

Then create a task in a repo shaped like the demo (src/math.js + test.js). The mock Claude stops mid-task and the mock Codex finishes it.

Inspect an existing local session

In the command palette, run Agent Orchestrator: Open Local Session… and choose a Codex or Claude Code .jsonl file. Codex usually stores these under ~/.codex/sessions/ by date; Claude Code usually uses a project folder under ~/.claude/projects/. The picker also recognizes CODEX_HOME and CLAUDE_CONFIG_DIR.

This opens a read-only view of the visible conversation in file order, without starting an agent or creating a handoff. Tool output, attachments, internal reasoning and other provider state are excluded. Recognized secret patterns are redacted. The preview keeps up to 200 text messages from one uncompressed file and shortens unusually long messages. The on-disk formats can change with provider updates; a preview does not rehydrate a provider's native session or transfer it elsewhere.

From a terminal, node out/src/cli/main.js session /path/to/session.jsonl prints counts only. Add --show-text to print the local preview.

Continue the conversation

With a local session open in a trusted project folder, run Agent Orchestrator: Send Message in Local Session…. Choose Codex, Claude Code, or Auto. Auto keeps the last provider (or the imported session's provider on the first turn) if it is signed in and available. Otherwise it selects an eligible provider, preferring your configured provider. Each send starts one read-only turn in the selected project folder.

Auto difficulty looks at the latest message. A short summary or translation uses Quick (low), a general or ambiguous request uses Standard (medium), and a long request or signals like architecture, migration and root-cause analysis use Deep (high). You can override the estimate or use the CLI's own effort setting.

Set agentOrchestrator.conversation.models in User Settings to offer specific models per profile. For example, a Claude Code configuration can use the provider's model aliases:

"agentOrchestrator.conversation.models": {
  "claude": { "quick": "haiku", "standard": "sonnet", "deep": "opus" }
}

The codex key accepts the same profile names. Unconfigured profiles use the provider's default model. The model picker also accepts a custom model name for the current message. The review step shows the destination, requested model, effort, working folder and number of previous messages that will be sent. Account access and supported effort levels depend on the chosen model and CLI.

Imported conversations and completed replies are saved atomically under the extension's globalStorage/conversations directory. Run Agent Orchestrator: Open Saved Conversation… to reopen one after restarting VS Code. Conversation ownership is exclusive to one window at a time. An interrupted request is marked in the saved record and can be continued with a new explicit message.

Each turn receives a bounded slice of visible history. Provider CLIs also manage their own run history. The current conversation mode gives agents read-only access to the selected folder.

Connect real providers

The orchestrator uses the official CLIs exactly as you installed and logged in to them. It never reads, copies, or stores credentials.

  1. Log in with the official tools: claude auth login and codex login.
  2. If codex is not on your PATH, set agentOrchestrator.providers.codex.path in user settings. The extension deliberately does not search other extensions' folders.
  3. Run Agent Orchestrator: Refresh Providers, or from a terminal:
    node out/src/cli/main.js providers
    
    This is read-only: --version, claude auth status, codex login status, and Codex's documented (experimental) account/rateLimits/read quota probe.
  4. Configure the fallback order, validation commands (for example npm test), and the permission preset (workspace-edit by default; read-only available) in user settings.

Reproduce a real handoff. This uses your quota, on a throwaway repository you trust:

node out/src/cli/main.js run --repo /path/to/throwaway-repo \
  --objective "Add input validation to src/parse.js and tests for it" \
  --provider claude --fallback codex --validate "npm test" \
  --switch-after 60 \
  --i-understand-this-uses-provider-quota

--switch-after 60 forces a manual Claude → Codex handoff after 60 seconds. Without it, a handoff happens only when the active provider reports a usage limit. Ctrl-C pauses the task safely. In VS Code, the same flow is New Task → Switch Provider….

How it works (one paragraph)

The task follows an explicit state machine (CREATED → READY → RUNNING → … → COMPLETED, with INTERRUPTED → CHECKPOINTING → HANDOFF_PREPARING → HANDOFF_VALIDATING → RESUMING for handoffs and BLOCKED/PAUSED as safe stops). Every transition is written atomically and journaled. The handoff works like this:

  1. Trigger. An idempotent trigger fires: a classified provider limit (structured signals only, never agent text) or the user.
  2. Checkpoint. The workspace is checkpointed without touching your working tree.
  3. Select a target. The target must be installed, authenticated, not limited, and able to enforce the same permission preset.
  4. Build and validate the package. The package (with provenance and an integrity hash) is validated, including drift against the checkpoint.
  5. Start the target in the same workspace.

A crash at any point is recovered on the next start: orphaned agent processes are reaped, the workspace is checkpointed, pre-start phases are retried, and in-flight target starts wait for you. Nothing ever runs twice.

Details: ARCHITECTURE · HANDOFF_PROTOCOL · SECURITY · RELIABILITY_BENCHMARK · REFERENCE_ANALYSIS · LICENSE_AUDIT · IMPLEMENTATION_PLAN

Safety defaults

  • Worktree isolation. Agents work in …/globalStorage/…/worktrees/<task>. Your checkout is byte-identical afterwards, and your uncommitted work is replayed into the worktree.
  • Never automatic: no push, merge, rebase, reset, or clean. Restoring a checkpoint is explicit, confirmed, and reversible.
  • Explicit permission modes. Claude always runs with --permission-mode default --permission-prompts none. Codex runs in --sandbox read-only|workspace-write. Dangerous flags are never passed (enforced by tests), and a handoff never escalates the preset.
  • No silent billing switch. API-key environment variables are stripped from agent processes unless you opt in.
  • Settings are protected. Provider paths, validation commands, and permissions are read only from user settings, and agents don't run in untrusted workspaces.
  • Secret-like files are never checkpointed (.env*, keys). Journals and packages are redacted.

Project layout

src/core/            state machine, store, journal, leases, git, handoff engine, orchestrator,
                     validation, availability, metrics, redaction (no vscode imports)
src/providers/       adapter contract users: claude/, codex/, mock/, cli-run.ts, registry, factory
src/extension/       VS Code views, commands, config, status bar
src/cli/main.ts      `ao` CLI (demo, bench, status, metrics, providers, run)
src/bench/           reliability scenarios + crash-simulation child process
tests/               unit/, integration/ (fake CLIs), scenarios/, vscode/
docs/                design, protocol, security, benchmark, analysis, license audit

License

MIT. No code was copied from the reference projects; see docs/LICENSE_AUDIT.md. "Claude", "Claude Code", "Codex" and "OpenAI" are trademarks of their owners. This project is not affiliated with or endorsed by Anthropic or OpenAI.

  • Contact us
  • Jobs
  • Privacy
  • Manage cookies
  • Terms of use
  • Trademarks
  • Your Privacy Choices
  • Consumer Health Privacy
© 2026 Microsoft