AgentS

One agent over many AI coding agents. AgentS gives you a single interface over Claude Code, Antigravity (Google's agy), and any OpenAI-compatible local LLM (Ollama / LM Studio / vLLM / OpenRouter / …). It keeps a shared, vendor-neutral memory and an append-only run ledger in your own database, so the same task can run on one provider or several, be compared and merged, and pick up where another agent left off — without sharing vendor credentials.

Install & Getting Started

AgentS ships as a single desktop application for Windows, macOS, and Linux. This guide covers installing the app, satisfying its two prerequisites (the Antigravity and Claude Code CLIs), fixing the most common startup problem (agents not found on PATH), and taking your first steps in the GUI.

This guide covers the GUI (desktop) application only. The desktop app is self-contained: it bundles the AgentS engine and starts it for you in the background — there is nothing else to install or run from a terminal.

---

1. Prerequisites

AgentS is an orchestrator: it drives the official Antigravity and Claude Code CLIs as subprocesses. It does not ship, replace, or embed them, and it never reads, stores, or reuses your credentials — each agent uses its own login.

Before installing AgentS, both agent binaries must be installed and authenticated on your machine:

Agent	Binary	Install	Authenticate	Verify
Claude Code	claude	npm i -g @anthropic-ai/claude-code (or the official installer)	Run claude once and log in (or set ANTHROPIC_API_KEY)	claude --version
Antigravity	agy	Follow Google's official Antigravity install guide	Run agy once and sign in (or set ANTIGRAVITY_API_KEY)	agy --version

Both checks must succeed in a terminal before you launch AgentS:

claude --version     # e.g. 1.x.x
agy --version        # e.g. 0.x.x

If either command prints a version but the agent later fails inside AgentS, it is almost always a PATH problem — see §4 below.

You only need the agent(s) you intend to use. If you install just claude, the Claude Code agent works and Antigravity simply shows as unavailable (and vice-versa).

---

2. Download

Download the installer for your operating system from the latest release:

OS	Download	Notes
Windows	AgentS_<version>_x64-setup.exe (or the .msi)	64-bit Windows 10/11
macOS	AgentS_<version>_aarch64.dmg	Apple Silicon (M-series)
Linux	AgentS_<version>_amd64.AppImage or .deb	AppImage runs anywhere; .deb for Debian/Ubuntu

---

3. Install

Windows

1. Run the downloaded .exe (or .msi) installer and follow the prompts.
2. Launch AgentS from the Start menu.
3. If SmartScreen shows a "Windows protected your PC" dialog, click More info → Run anyway (the app is signed on official releases; this can appear on first launch).

macOS

1. Open the .dmg and drag AgentS into Applications.
2. Launch it from Applications (or Spotlight).
3. Official releases are signed and notarized, so Gatekeeper clears the app on first launch (an online check — the first launch needs network). If a download is still flagged, clear the quarantine attribute once:

   xattr -d com.apple.quarantine /Applications/AgentS.app
   

Linux

AppImage (no install — runs anywhere):

chmod +x AgentS_*_amd64.AppImage
./AgentS_*_amd64.AppImage

Debian / Ubuntu (.deb):

sudo apt install ./AgentS_*_amd64.deb
# then launch "AgentS" from your app menu, or run:
agents

On first launch AgentS creates its local state under ~/.ags/ (%USERPROFILE%\.ags\ on Windows) — a configuration file, a SQLite database, and logs. Everything stays on your machine; there are no daemons or servers to manage.

---

4. Fixing PATH issues (agents not found)

The single most common problem. Everything works in your terminal, but inside AgentS the Claude Code or Antigravity agent shows as unavailable or its runs fail with something like "binary not on PATH".

Why it happens: a desktop app launched from the Start menu, the macOS Dock, or an app menu does not inherit the PATH from your shell startup files (.bashrc, .zshrc, .profile). So agents installed to a non-standard location — npm's global prefix, nvm, Homebrew on Apple Silicon (/opt/homebrew/bin), a custom ~/.local/bin, etc. — are visible in your terminal but invisible to AgentS.

You have two ways to fix it. Either one works — pick whichever you prefer.

Option A — Put the agents on a system-wide PATH

First, find where each agent actually lives:

# macOS / Linux
which claude
which agy

# Windows (PowerShell)
where.exe claude
where.exe agy

Then make that location visible to GUI apps:

• macOS / Linux — symlink (or move) each binary into a standard system directory that GUI apps always see:

  sudo ln -sf "$(which claude)" /usr/local/bin/claude
  sudo ln -sf "$(which agy)"    /usr/local/bin/agy
  

• Windows — add the folder that contains claude.exe / agy.exe (or the npm global folder, e.g. %APPDATA%\npm) to the System PATH: Settings → System → About → Advanced system settings → Environment Variables → System variables → Path → Edit → New. Then log out and back in so the desktop environment picks up the change.

Option B — Set the full path explicitly in config.yaml

If you'd rather not touch your system PATH, tell AgentS exactly where each binary is. Edit the config file:

OS	Config file
macOS / Linux	~/.ags/config.yaml
Windows	%USERPROFILE%\.ags\config.yaml

Find the providers: section and set each agent's params.bin to the full absolute path you got from which / where.exe above:

providers:
  - name: claude
    kind: claude_code
    enabled: true
    model: claude-opus-4-8
    params:
      bin: /usr/local/bin/claude          # ← full path instead of just "claude"
      permission_mode: plan
      timeout_s: 600

  - name: antigravity
    kind: antigravity
    enabled: true
    model: gemini-1.5-pro
    params:
      bin: /opt/homebrew/bin/agy          # ← full path instead of just "agy"
      pty: true
      timeout_s: 600

Windows path note: use the full path including the extension, and prefer forward slashes or a quoted string, e.g. bin: "C:/Users/you/AppData/Roaming/npm/claude.cmd". npm-installed CLIs on Windows are usually claude.cmd / agy.cmd, not .exe.

After either fix

Fully quit and reopen AgentS so it restarts its engine and re-reads the config. Then confirm the agents are healthy in the GUI:

• Open Settings → Adapters and click Test next to claude and antigravity. A green result means the binary was found and responded.

If it still fails, check the diagnostic logs for the exact error:

• ~/.ags/sidecar.log — did the engine start? (%USERPROFILE%\.ags\sidecar.log)
• ~/.ags/server.log — runtime errors from the engine.

---

5. Getting started with the GUI

When AgentS opens you get a dashboard with a left sidebar: Dashboard, New session, Sessions, and a Settings group (Project selection, Remote hosts, Adapters, MCP, Usage, Approvals).

5.1 Add a project (local or remote)

Agents work inside a project folder. Set it under Settings → Project selection:

• Local — keep the Local tab selected and browse to the folder on this machine you want agents to read and edit. Click a folder to choose it.
• Remote — run agents against a folder on another machine over SSH:
  1. First save the machine under Settings → Remote hosts: give it a label and an SSH target (e.g. user@build-box). AgentS uses your existing ~/.ssh config, keys, and agent. The agent CLI (claude / agy) must be installed on the remote host too. Use Test to verify the connection and that the CLI is present.
  2. Back on Project selection, switch to the Remote tab, pick the saved host, and browse to the folder on that host.

Changes apply to the next turn — no restart needed. The current project (and whether it's local or remote) is shown at the top of the page.

5.2 Start a session — pick an agent and model

Click New session in the sidebar:

1. Agent — choose Antigravity (antigravity) or Claude Code (claude) from the dropdown. Only installed, healthy agents appear here.
2. Model (optional override) — pick a specific model for the chosen agent (e.g. claude-opus-4-8 for Claude Code, gemini-1.5-pro for Antigravity), or leave it to use the agent's default.
3. First message — type your task (e.g. "Audit the cache layer and propose the safest fix"). You can also drag-and-drop or paste files to attach them.
4. Mode — Plan (read-only; the agent proposes but doesn't write) is the default. Switch to Edit to let the agent modify files.
5. Private workspace — leave checked to work on an isolated git branch and merge back when you're happy; uncheck to edit the project folder directly.
6. Click Start session (or press ⌘/Ctrl+Enter).

Responses stream live with Markdown rendering, and tool calls (file reads, edits, commands) show compactly as the agent works. You can switch the active agent mid-conversation from within the session.

5.3 Add MCP servers (external tools)

MCP (Model Context Protocol) servers give agents extra tools — filesystems, GitHub, databases, and more. Manage them under Settings → MCP:

1. Click Add server and choose a transport:
   • stdio — a local command, e.g. command npx with args -y @modelcontextprotocol/server-filesystem /path/to/project.
   • http — a remote endpoint URL, e.g. https://api.githubcopilot.com/mcp/. Provide the token via an environment variable reference (stored as a 0600 secret file, never inline).
2. Optionally set a tool allowlist (empty = all tools) and mark the server read-only so its tools are offered even in Plan mode.
3. Enable the server, then click Test to connect and list the tools it advertises. Tools appear to agents namespaced as mcp__<server>__<tool>.

Changes take effect immediately on the next run — no restart required.

---

6. Where things live

Path	What it is
~/.ags/config.yaml	Providers (agents), models, MCP servers, memory settings
~/.ags/harness.db	Local SQLite database (sessions, run ledger, memory)
~/.ags/sidecar.log	Desktop-app ↔ engine startup diagnostics
~/.ags/server.log	Engine runtime log

On Windows these live under %USERPROFILE%\.ags\.

To fully reset AgentS, quit the app and delete the ~/.ags folder — it is recreated with defaults on the next launch.