ags-cli 0.1.0__tar.gz

ags_cli-0.1.0/PKG-INFO

@@ -0,0 +1,332 @@
+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.

ags_cli-0.1.0/README.md

@@ -0,0 +1,290 @@
+# 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.