Skip to main content

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.

Metadata

Release files for ags-cli 0.2.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ags-cli 0.2.3
File Size Uploaded Provenance Actions
ags_cli-0.2.3.tar.gz 300.9 kB With provenance Details for ags_cli-0.2.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ags-cli 0.2.3
File Interpreter ABI Platform Actions
ags_cli-0.2.3-py3-none-any.whl Python 3 none any Details for ags_cli-0.2.3-py3-none-any.whl

Total release size: 675.5 kB

Release files / ags_cli-0.2.3.tar.gz

Download URL ags_cli-0.2.3.tar.gz
Size 300.9 kB
Tags Source
SHA-256 checksum
How to use checksums
18538aac107bb6300add1118dff997d97dbf5307ca44bfaf116f7d8f96c4af3f
BLAKE2b-256 checksum
How to use checksums
4bdd10101e5d6446f8598bf5b63880e2017ad63dc822667b7f56c878936ba033
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

Release files / ags_cli-0.2.3-py3-none-any.whl

Download URL ags_cli-0.2.3-py3-none-any.whl
Size 374.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6d539bf94287afb0ed02c3c0ac03601270c6da9206d2809a5540cc2b901f8840
BLAKE2b-256 checksum
How to use checksums
41e90543bf4196ef94d1382e3522e01f54fcb8c137e1e0c9fabc33148887405f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

Security for ags-cli 0.2.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ags_cli-0.2.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Sep 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page