AgentS Multi-Agent Harness

Run Claude Code, Antigravity (agy), and any OpenAI-compatible model (Ollama, LM Studio, vLLM, Groq, OpenRouter, …) from a single chat panel inside VSCode — with shared history, approval gates, and real diffs.

Instead of juggling a terminal per agent, you get one conversation. Ask the same question of several agents at once and compare their answers, keep working in the same session when you switch models, and review every file change before it lands.

• One chat, many agents — pick the agent and model per turn, or let a routing policy decide.
• Fan out and compare — run one objective across several agents side by side, then have a judge rank the answers or merge them into one.
• Plan mode by default — agents read and analyze but can't write until you tick edit.
• Approval gates — shell commands and other risky tool calls pause for an inline Approve/Deny, even if the panel is closed.
• Real diffs — review a run's changes as a unified diff, or isolate a session in its own git worktree and get a native side-by-side diff before merging.
• Your credentials stay put — each agent uses its own existing login. Nothing is shared between vendors, and API keys are stored by the backend, never in VSCode settings.

This extension is a client. The agents run in the AgentS backend (ags), a local service on your machine. Install it first — see below. Nothing is sent to a server you don't control.

Quick start

Two steps: install the backend, then the extension. The backend is a single command — uv fetches Python for you, so nothing else is needed.

# 1. Backend — installs the ags CLI from PyPI and sets up local state
uv tool install ags-cli
ags init

# 2. Extension
code --install-extension agent-smith.agents-vscode

Open the chat with Ctrl+Alt+A (Cmd+Alt+A on macOS). The extension starts the backend on demand — you don't run ags serve yourself. Don't have uv? Install it first:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

The rest of this page covers agent prerequisites, discovery, and every feature in detail.

1. Install the backend

Prerequisites

AgentS drives the official agent CLIs as subprocesses — it doesn't embed or replace them. Install and sign in to whichever you plan to use. You only need one.

Verify before continuing:

claude --version
agy --version

Install ags

The backend installs with uv, which also fetches Python for you — you don't need a Python install of your own.

# 1. Install uv (skip if you already have it)
#    macOS / Linux:
curl -LsSf https://astral.sh/uv/install.sh | sh
#    Windows (PowerShell):
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# 2. Install the AgentS CLI and initialize local state
uv tool install ags-cli
ags init

ags init creates ~/.ags/ (%USERPROFILE%\.ags\ on Windows) — a config file, a SQLite database, and logs. Everything stays on your machine; there is no daemon to manage.

Confirm it worked:

ags doctor

You do not need to start the server yourself. The extension starts ags serve on demand.

2. Install the extension

Search for AgentS Multi-Agent Harness in the Extensions view (Ctrl+Shift+X) and click Install, or:

code --install-extension agent-smith.agents-vscode

An AgentS icon appears in the activity bar. On first use the extension finds your backend in this order:

1. The agents.apiUrl setting, or the HARNESS_API_BASE_URL environment variable
2. ~/.ags/api_url, written by the CLI
3. A probe of http://127.0.0.1:8770
4. Failing all of those, it spawns ags serve itself (unless agents.autoStartServer is off)

The status bar (bottom-right) shows the result:

If ags isn't found, open a fresh terminal first — uv adds its tool directory to PATH, but existing terminals won't have picked it up. Otherwise set agents.serverPath to the binary.

3. Using it

Start a session

Open the chat with Ctrl+Alt+A (Cmd+Alt+A on macOS), or click a session in the sidebar. Type an objective and press Enter (Shift+Enter for a newline). Replies stream as markdown; reasoning collapses into a 💭 Thinking block, and tool calls expand to show their full arguments and output.

The panel survives window reloads — it re-hydrates from the backend's event ledger, so an in-flight run is never lost.

Plan mode vs edit mode

New sessions are read-only. The agent can read and analyze but not modify anything until you tick edit in the top bar (or set agents.defaultWriteMode). Toggling it mid-session applies from the next turn.

Tick worktree on a new session to isolate its changes in a private git worktree on its own branch — nothing touches your working tree until you merge.

Choosing agents: policies

The Policy dropdown controls routing:

With fanout, tick two or more agents and send. When the columns finish you can Compare (judge) to rank the answers, Merge them into one result, or click use on a column to continue single-agent with that winner.

Approvals

When a run hits a gated action — a shell command, for example — it pauses and shows an Approval required card with the tool, reason, and command. Approve and the run continues streaming in place; deny and it stops.

Approvals raised while the panel is closed light up a badge on the Sessions view. Run AgentS: Review Approvals to handle them from a quick-pick.

Reviewing changes

After a run that writes files, click diff in the top bar, or right-click the session → View Session Diff.

• Normal sessions open a unified diff as a read-only document.
• Worktree sessions open a file picker, then a native side-by-side diff against your workspace copy.

Right-click a worktree session to Merge Worktree (conflicts are reported so you can resolve them) or Discard Worktree (deletes the branch and its changes). Both confirm first. AgentS: Prune Orphan Worktrees cleans up worktrees whose sessions are gone.

Plan-mode runs and runs that changed nothing have no diff.

Adding providers and MCP servers

Click + on the Providers view to add any OpenAI-compatible endpoint. The wizard asks for a name, base URL (e.g. https://api.groq.com/openai/v1), default model, optional API key, and whether to enable tool calling. It runs a connection test on save, and the provider then shows up in the agent picker.

The MCP Servers view works the same way, with stdio (a local command to spawn) or http (a remote endpoint with an optional bearer token) transports. You can set a tool allowlist and hit test to list the tools a server exposes.

Keys are stored by the backend as 0600 files — never in VSCode settings. When editing, leave the key blank to keep the stored one. Providers declared in the backend's config.yaml are edit-protected; change those in the file directly.

Overriding the model list

The Model picker shows whatever the backend reports for that agent, and how it gets that list depends on the agent:

The claude CLI has no machine-readable way to enumerate models, so the backend ships a hardcoded snapshot. It doesn't know which models your login is actually entitled to, and it won't grow when Anthropic ships new ones. If the picker is missing a model you know you have, this is why.

Fix it by setting params.models on the provider in ~/.ags/config.yaml (%USERPROFILE%\.ags\config.yaml on Windows). When present, the list is used verbatim — it replaces the built-in one entirely:

providers:
  - name: claude
    kind: claude_code
    enabled: true
    model: claude-opus-4-8      # the default selection
    params:
      bin: claude
      models:                   # replaces the built-in list
        - claude-opus-4-8
        - claude-fable-5
        - claude-sonnet-5
        - claude-haiku-4-5

This is also how you expose account- or CLI-specific variants the built-in list can't know about, such as claude-fable-5[1m].

Because the list is used verbatim, anything you leave out disappears from the picker — include every model you want selectable, not just the new ones. Keep model: pointing at something that's still in the list.

Then restart the backend so it re-reads the config, and refresh the extension:

# macOS / Linux
kill "$(cat ~/.ags/server.pid)"

# Windows (PowerShell)
Stop-Process -Id (Get-Content "$env:USERPROFILE\.ags\server.pid")

Then run AgentS: Reconnect / Start Server (it respawns the backend), followed by AgentS: Refresh Providers. Verify from a terminal with:

ags models list claude

Tip: the claude CLI also accepts the tier aliases opus, sonnet, haiku, and fable, which always resolve to the newest model in that tier. Adding those to models: gives you entries that never go stale.

params.models applies to claude_code providers only — Antigravity and OpenAI-compatible providers enumerate live, so setting it there has no effect.

From the editor

Select code, right-click, and choose Send Selection to Chat, Explain Selection, or Fix Selection. Each prefills the composer with the selection as a path:line-range code block — nothing sends automatically, so you can edit the prompt first.

Settings

All commands live under "AgentS:" in the Command Palette (Ctrl+Shift+P).

Troubleshooting

Status bar stuck on "down" — click it to reconnect. If it says ags not found, open a new terminal (so PATH refreshes) or set agents.serverPath. AgentS: Open Server Log shows ~/.ags/server.log for startup crashes.

Agent picker is empty — the backend isn't reachable, or no providers are enabled. Reconnect, then check the Providers view.

Model picker is missing a newer model — for Claude Code the list is a static snapshot in the backend, not a live query. Override it with params.models in config.yaml — see Overriding the model list.

An agent shows as unavailable — almost always PATH. VSCode may not inherit the shell PATH that has claude or agy on it. Run ags doctor to check, and set the adapter's binary path in the backend config if needed.

A run seems stuck — it's probably waiting on an approval. Check the panel or the Sessions badge. Dropped streams reconnect automatically.

Diff says "no changes" — the run was plan-mode, or genuinely wrote nothing.

License

Apache-2.0. Source: github.com/farookmfk/agents-vs-code