# Agent Guild, for AI agents

Agent Guild is a free, open-source (AGPL-3.0) session manager by Odd Essentials. It runs Claude Code, Codex CLI, Antigravity CLI, Grok Build, Docker Agent and shells side by side in real terminals on the person's own Windows, macOS or Linux computer, and opens the same live sessions in any browser, in VS Code, and in the Agent Guild apps for iPhone, iPad, Apple Vision Pro, Apple Watch and Android. Sessions keep running when the page closes. Agent Guild: World, sold separately on Steam, shows every session as a character in a 3D world.

If a person sent you here, they want one of these:

1. **Install Agent Guild** and check it works.
2. **Connect yourself to it** over MCP, to see and steer their sessions.
3. **Make a character or companion** for Agent Guild: World.

## Safety rules

- **Never print, paste, store or send the page link or the access token.** `agent-guild url` and `agent-guild --no-browser` print a link ending in `#token=...`, and that token controls every session on the computer. Run plain `agent-guild`, which opens the page in the person's browser, and never read the token file.
- Leave remote access off unless the person asks for it. It is set up in the page under **Settings → Remote access**.
- Install only the npm package `@oddessentials/agent-guild`.
- Ask before running `agent-guild stop` or `agent-guild restart`: both end every session.

## 1. Install Agent Guild

Check Node.js. Agent Guild needs version 22 or newer:

```sh
node --version
```

If it is missing or older, ask the person to install the current LTS from https://nodejs.org, then:

```sh
npm install -g @oddessentials/agent-guild
agent-guild
```

The page opens in the person's browser. On a computer with no desktop, ask the person to run `agent-guild --no-browser` themselves and open the link it prints.

Verify:

```sh
agent-guild status
agent-guild doctor
```

`status` lists the version and sessions. `doctor` checks the setup and says what to fix. `http://127.0.0.1:47821/api/v1/health` answers without a token.

Then tell the person: **New** on a tool's card starts a session; each tool signs in inside its first session, as in any terminal; tools install and update from their own cards.

Requirements: Windows 10 (1809) or newer, macOS 11 or newer, or Linux. Every other screen opens this computer's Agent Guild: https://agentguild.oddessentials.ai/requirements/

## 2. Connect over MCP

`agent-guild mcp` is a Model Context Protocol server on stdio. Its tools: `guild_status`, `list_sessions`, `read_reply` (the answer that ended a session's last turn), `read_screen` (what its terminal shows now), `start_session` and `stop_session`. Ask the person before starting or stopping a session.

| Agent | Command |
| --- | --- |
| Claude Code | `claude mcp add -s user agent-guild -- agent-guild mcp` |
| Codex CLI | `codex mcp add agent-guild -- agent-guild mcp` |
| Antigravity CLI | `agy mcp add agent-guild agent-guild mcp` |
| Gemini CLI | `gemini mcp add -s user agent-guild agent-guild mcp` |
| VS Code | `code --add-mcp '{"name":"agent-guild","type":"stdio","command":"agent-guild","args":["mcp"]}'` |

For one VS Code workspace, `.vscode/mcp.json`:

```json
{ "servers": { "agent-guild": { "type": "stdio", "command": "agent-guild", "args": ["mcp"] } } }
```

For Cursor, Windsurf and other editors that take an `mcpServers` config:

```json
{ "mcpServers": { "agent-guild": { "command": "agent-guild", "args": ["mcp"] } } }
```

Typing into sessions stays off unless the person asks for it; then use `agent-guild mcp --allow-input`.

As a Claude Code plugin, with the setup skill included: `claude plugin marketplace add oddessentials/agent-guild --sparse .claude-plugin plugins`, then `claude plugin install agent-guild@agent-guild`

Docs: https://github.com/oddessentials/agent-guild/blob/main/docs/mcp.md

## 3. Make a character or companion for World

Agent Guild: World is a separate, premium app on Steam (https://store.steampowered.com/app/5462970/Agent_Guild_World/). Each world dresses every crew in looks of its own; a piece replaces the look of one crew in one world. Its Studio builds a piece from a figure:

1. **Get a figure.** A rigged humanoid as `.glb`, `.gltf`, `.vrm` or `.fbx`. Make one in Blender, VRoid Studio or Mixamo, or bring one from an asset store. The model's licence applies to the piece.
2. **Build it**, one of two ways:
   - **In World.** The person opens **Looks → Make a piece…**. Common rigs map by themselves.
   - **From the command line.** `--slot` names a world and a crew; `guild/anthropic` is the Guild world's Claude Code crew. `--out` is a full path to a new folder for the piece:

     ```sh
     AgentGuildWorld -- --build=figure.fbx --slot=guild/anthropic --out=FOLDER
     ```

     Studio checks the piece as Looks would, prints its folder and quits. The person then opens World, chooses **Looks → Add a piece from a folder…** and picks that folder.
3. **Check and keep it.** In **Make a piece…**, the person sees it beside the crew's own, by day and at dusk, then chooses **Add to Looks**, publishes it to the Steam Workshop, or saves the piece's folder.

Studio also makes companions from any model, and recolours of a world's own looks. Pieces made by others: https://steamcommunity.com/app/5462970/workshop/

The free Agent Guild page has skins too. To make one, follow https://github.com/oddessentials/agent-guild/blob/main/docs/SKINS.md

## Uninstall

Ask first, since it ends every session:

```sh
agent-guild stop
npm uninstall -g @oddessentials/agent-guild
```

## More

- Source and issues: https://github.com/oddessentials/agent-guild
- Support: https://agentguild.oddessentials.ai/support/
- Privacy: https://agentguild.oddessentials.ai/privacy/