cowork

# 🤝 Cowork — one task inbox for Claude Code, Codex, Gemini CLI & Hermes agents

**A self-hosted MCP server + web dashboard that lets different AI coding agents share one task
queue.** Dispatch a task from any of them (or from the UI); a dispatcher routes it to a named
*brain* (model × CLI × machine), runs it, verifies the result, and falls back to the next brain
on rate limits. Workflows, artifacts, remote machines and cost/usage meters are built in.

- **Mixed-vendor agents, one inbox:** Claude Code, Codex, Gemini CLI / Antigravity, Hermes, Ollama.
- **Brain routing with fallback chains:** route by role, pin by task, fail over on quota errors.
- **Plain files on disk:** the task store is files. No database to run.
- **Remote brains:** another machine joins with one command and offers its models
  ([JOIN-AS-A-BRAIN.md](JOIN-AS-A-BRAIN.md)):
  `COWORK_URL=http://<host>:6868 HOST=<you> node cowork/deploy/remote-brain-client.mjs`

Jump to: [Quick Start](#quick-start) · [Connecting agents](#connecting-ai-agents) ·
[Dispatcher](#task-execution--the-dispatcher) · [Brains](#brains--named-execution-identities-model--platform--location) ·
[Workflows](#workflows--declarative-pipelines-two-execution-modes) · [MCP tools](#mcp-tools-reference)

## Screenshots

One dark-themed **single pane of glass** for the whole operation: live host metrics
(CPU / GPU / memory / temp), open-task and Agencies counters, the dispatcher's current
role → model chains, and a real-time activity feed.

![Cowork dashboard — metrics, counters, dispatcher chains, and live activity](docs/images/cowork-dashboard.png)

The [Workflows](#workflows--declarative-pipelines-two-execution-modes),
[Task Inbox](#task-execution--the-dispatcher), [Brains](#brains--named-execution-identities-model--platform--location),
[Connections](#wiring-a-remote-brain-machine), and [Chat](#connecting-ai-agents) views are
shown in context throughout this README.

## Supported Platforms

| Platform | Agents | Format |
|----------|--------|--------|
| Claude Code | ~285 | `.md` with YAML frontmatter |
| Antigravity (AGY) | Built-in + skills | `SKILL.md` |
| Hermes Agent | 39 skills | `SKILL.md` + triggers |
| Gemini CLI | Converted from source | `.md` subagents |
| GitHub Copilot | Same as Claude | `.md` agents |
| Codex | Converted | `.toml` agents |
| Cursor | Converted | `.mdc` rules |
| + 7 more | See agency-agents repo | Various formats |

---

## Quick Start

### Prerequisites

- **Node.js** ≥ 20 (tested with v22)
- **npm** ≥ 10
- The [agency-agents](./agency-agents) repo — bundled as a **git submodule** at
  `cowork/agency-agents` (the Agencies — 285 agents). Clone with submodules:

  ```bash
  git clone --recurse-submodules https://github.com/slashman413/cowork
  # already cloned without it? initialise the submodule:
  git submodule update --init
  ```

### Fast path — two scripts (recommended)

From the repo root, after cloning with submodules (above):

```bash
# 1. Build + launch the server (installs deps, builds, starts a systemd user service)
deploy/install-server.sh

# 2. Drop the coordination skill + MCP connection into your agent clients on this box
deploy/install-skill.sh            # auto-detects Claude Code / Hermes / Antigravity
```

`install-server.sh` generates a systemd unit with **this machine's** real node path and
working dir (nothing to hand-edit), or pass `--foreground` to launch in the terminal and
`--build-only` to stop after building. `install-skill.sh` copies the right per-client
skill into place and, for Claude Code, merges `mcpServers.cowork` into `~/.claude.json`
non-destructively (add `--url http://<host>:6868` for a remote server; `--client claude|hermes|agy|all`
to target one). The numbered steps below are the same thing, broken out for when you want
to do it by hand.

### Container (hub only)

```bash
docker run -d -p 6868:6868 -v cowork-data:/data ghcr.io/slashman413/cowork:1.0.0
```

The image (amd64 + arm64) runs the MCP server, dashboard and task inbox with the local
dispatcher off: agents connect to `http://<host>:6868/mcp`, and machines offer their brains
with `deploy/remote-brain-client.mjs` (see [JOIN-AS-A-BRAIN.md](JOIN-AS-A-BRAIN.md)). Config
and all state live in the `/data` volume; set `COWORK_API_KEY` to require a key. Images are
built from `v*` tags by `.github/workflows/release.yml` on a digest-pinned base.

### 1. Install Dependencies

```bash
cd cowork/server
npm install
```

### 2. Configure Settings

**Config lives outside the repo.** The tracked `cowork/config.json` is a sanitized
**template only**. On first run the server copies it to **`~/.cowork/config.json`** —
your real per-server config (host binding, registered brains, chains). Edit *that*
copy, not the template; the server also persists all live dashboard/API edits there,
so your personal host/brain settings never touch the repo. Override the location with
the `COWORK_CONFIG` env var.

Edit `~/.cowork/config.json` to match your environment:

```json
{
  "server": {
    "port": 6868,          // ← Change the port here
    "host": "0.0.0.0",     // ← Bind address (0.0.0.0 = all interfaces)
    "name": "cowork-mcp",
    "version": "1.0.0",
    "apiKey": null          // ← Set a string to require API key auth, or null for open
  },
  "paths": {
    "agencyAgents": "./agency-agents",  // ← Path to agency-agents repo
    "inbox": "./inbox",
    "status": "./.status",
    "decisions": "./decisions",
    "workflows": "./workflows",
    "artifacts": "./artifacts",
    "inputs": "./inputs"
  }
}
```

> **All paths are relative to `cowork/`** (the parent of `server/`).
> Use `~` for home directory paths (e.g., `~/.claude/agents`).

#### Key Settings

| Setting | Default | Description |
|---------|---------|-------------|
| `server.port` | `6868` | HTTP port for MCP endpoint + Web UI |
| `server.host` | `0.0.0.0` | Bind address (`127.0.0.1` for local-only) |
| `server.apiKey` | `null` | API key for authentication (null = no auth) |
| `paths.agencyAgents` | `./agency-agents` | Path to the agency-agents repo |
| `platforms.*.enabled` | `true` | Enable/disable individual platforms |
| `platforms.*.agentsDir` | varies | Where platform-specific agents live on disk |
| `services.*.enabled` | `false` | Enable/disable service health monitoring |

### 3. Start the Server

```bash
# Development mode (with hot-reload)
cd cowork/server
npm run dev

# Production mode
npm run build
npm start
```

You should see:

```
🤝 Cowork MCP Server running at http://0.0.0.0:6868
   MCP endpoint: http://0.0.0.0:6868/mcp
   Web Dashboard: http://0.0.0.0:6868/
   REST API: http://0.0.0.0:6868/api/
   Agencies loaded: 285 agents across 19 divisions
```

### 4. Open the Dashboard

Open **http://localhost:6868** in your browser.

---

## Connecting AI Agents

The fastest way to talk to any connected model is the dashboard's **Chat** view: pick a
brain, optionally scope it to a division and a specific agent, and your message is
dispatched as a task — the reply is the task result.

| Pick a division | …then an agent persona |
|---|---|
| ![Chat — choose a division](docs/images/cowork-chat.png) | ![Chat — choose an agent within the division](docs/images/cowork-chat-agents.png) |

For programmatic access, wire the MCP connection into your agent clients:

**Scripted (recommended):** `deploy/install-skill.sh` installs the `cowork` coordination
skill and wires the MCP connection for every agent client detected on the box — one command
instead of hand-editing each config:

```bash
deploy/install-skill.sh                          # auto-detect all clients, localhost server
deploy/install-skill.sh --client claude          # just Claude Code
deploy/install-skill.sh --client all --url http://cowork-host:6868   # remote server, every client
```

It drops the per-client skill (canonical copies in `deploy/skills/`) into the client's live
skill dir and, for Claude Code, merges the `mcpServers.cowork` entry into `~/.claude.json`
without disturbing your other servers. The manual per-client config is below for reference.

### Claude Code

Add to your MCP configuration (`~/.claude.json` or project-level):

```json
{
  "mcpServers": {
    "cowork": {
      "url": "http://localhost:6868/mcp",
      "transport": "streamable-http"
    }
  }
}
```

Then in Claude Code, the agent can call:
```
Use the cowork MCP tools: register_agent, create_task, get_roster, etc.
```

### Antigravity (AGY)

Add to your AGY MCP settings:

```json
{
  "mcpServers": {
    "cowork": {
      "url": "http://localhost:6868/mcp"
    }
  }
}
```

**agy quota meter / token refresh.** To mint Antigravity access tokens, the usage
probe and `deploy/remote-brain-client.mjs` need Google OAuth client values. These are
the public values that ship with the agy and Gemini CLIs. They are not committed. Copy
[`.env.example`](.env.example) to `~/.cowork/oauth-clients.env`, fill it in, and run
`chmod 600`. Alternatively, export the same variables in the service environment;
process env takes precedence. If no values are set, the agy meter only works while a
cached CLI access token is still valid.

### Hermes Agent

Configure the MCP endpoint in Hermes:

```json
{
  "mcp_endpoints": {
    "cowork": "http://localhost:6868/mcp"
  }
}
```

### Any MCP-Compatible Client

The server speaks standard MCP over Streamable HTTP. Any client that supports
MCP can connect to `http://localhost:6868/mcp`.

---

## Task Execution — the Dispatcher

The server includes a **dispatcher** that turns queued tasks into real agent runs.
Output becomes the task `result`; the full transcript is saved as `result.md` in the
task's artifacts dir.

Every task lands in the **Task Inbox**, tagged with the division/agent that ran it and the
brain it ran on, with its output artifacts attached and filterable by status
(done · in-progress · pending · wait-input · failed).

![Task Inbox — tasks tagged with division/agent, brain, and downloadable artifacts](docs/images/cowork-tasks.png)

### Two-stage rout