Metadata-Version: 2.4
Name: ags-cli
Version: 0.1.0
Summary: AgentS: one unified interface over Claude Code, Google CLI (agy), and OpenAI-compatible local LLMs.
Author: Platform Engineering
License: Apache-2.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.115
Requires-Dist: uvicorn[standard]>=0.32
Requires-Dist: pydantic>=2.9
Requires-Dist: pydantic-settings>=2.5
Requires-Dist: python-dotenv>=1.0
Requires-Dist: sqlalchemy[asyncio]>=2.0.35
Requires-Dist: aiosqlite>=0.20
Requires-Dist: httpx>=0.27
Requires-Dist: typer>=0.12
Requires-Dist: rich>=13.9
Requires-Dist: structlog>=24.4
Requires-Dist: prometheus-client>=0.21
Requires-Dist: opentelemetry-api>=1.27
Requires-Dist: opentelemetry-sdk>=1.27
Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0
Requires-Dist: pyyaml>=6.0
Requires-Dist: mcp>=1.2
Requires-Dist: python-multipart>=0.0.12
Requires-Dist: bcrypt>=4.2
Requires-Dist: pyjwt>=2.9
Requires-Dist: ags-sdk>=0.1.0
Provides-Extra: embed
Requires-Dist: fastembed>=0.4; extra == "embed"
Provides-Extra: vec
Requires-Dist: sqlite-vec>=0.1.6; extra == "vec"
Provides-Extra: dev
Requires-Dist: pytest>=8.3; extra == "dev"
Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
Requires-Dist: pytest-cov>=5.0; extra == "dev"
Requires-Dist: anyio>=4.6; extra == "dev"
Requires-Dist: ruff>=0.7; extra == "dev"
Requires-Dist: mypy>=1.13; extra == "dev"
Requires-Dist: respx>=0.21; extra == "dev"

# 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:

```bash
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](#4-fixing-path-issues-agents-not-found)
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](https://github.com/farookmfk/AgentS/releases/latest)**:

| 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:
   ```bash
   xattr -d com.apple.quarantine /Applications/AgentS.app
   ```

### Linux

**AppImage** (no install — runs anywhere):

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

**Debian / Ubuntu (`.deb`):**

```bash
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:

```bash
# 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:
  ```bash
  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:

```yaml
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.
