# pairtask [Health: Active]

**Category:** 🤖 Coding Agents  
**Repository:** https://github.com/pairtask/pairtask  
**GitHub Stars:** 10  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/pairtask

## Description
Local messaging for AI coding agents. Connect Codex and Claude Code through an MCP server, Unix sockets, and a SQLite-backed broker.

## Claude Desktop Quick Installation
No confirmed install details yet, so no config is published. Follow the setup steps in the repository above.

## Documentation & README

# pairtask

**Codex and Claude, working together in a sandbox.** pairtask pairs a Claude and
a Codex agent as a duo that shares tasks, messages and a workspace.

- Real-time collaboration with durable messages and automatic delivery.
- An isolated Incus workspace with persistent projects and agent memory.
- Token usage visibility and soft caps for managed Codex; shared caps are not yet available.

[MIT](https://github.com/pairtask/pairtask/blob/HEAD/LICENSE) or [Apache 2.0](https://github.com/pairtask/pairtask/blob/HEAD/LICENSE-APACHE) licensed · [First install](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md) · [Troubleshooting](https://github.com/pairtask/pairtask/blob/HEAD/docs/troubleshooting.md) · [Renamed from collab](https://github.com/pairtask/pairtask/blob/HEAD/docs/renamed.md)

## Set up a sandbox

[Provision once](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md), then use the block below each day.
**Tools are installed by the rollout—no compilation needed.** The image is small;
the rollout fetches the pinned agent tools once and keeps them across upgrades.
Provisioning runs OpenTofu in a disposable container; no host Terraform/OpenTofu
install is needed. Dev has network access; optional
control stays offline. Host credentials and conversations are not imported.

**Host prerequisites:** Python, Git, OpenSSH and Incus; macOS also needs Colima.
[Install commands](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#1-install-the-host-tools). No `gh` or browser download needed.

```sh
# First install or upgrade (Incus must be running; upgrades end active sessions)
python3 scripts/sandbox-provision.py rollout
# Pin a version: add --release workspace-vX.Y.Z
```

Run host commands from your provisioning checkout. On Linux, skip Colima commands
and use `local:` / `--remote local`. For host mounts, see the
[`mounts.json` example](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox-mounts.md#choose-directories).

```sh
# HOST: run from your provisioning checkout
# Start the Mac VM, then the containers
python3 scripts/sandbox-host.py apply
incus --project pairtask start colima-pairtask:secured   # if secured_runtime = true
incus --project pairtask start colima-pairtask:workspace

# Check: expect workspace (and secured, if enabled) to show RUNNING
incus --project pairtask list colima-pairtask:

# Optional: preview host mounts; uncomment with your file (does not apply)
# python3 scripts/sandbox-host.py mounts-plan --mounts-file /path/to/mounts.json

# Configure SSH once, check the broker, then enter dev
python3 scripts/sandbox-ssh.py --remote colima-pairtask
ssh -F infra/incus/ssh/config workspace pairtask status
ssh -F infra/incus/ssh/config workspace

# CONTAINER: all commands below until exit run inside your SSH session
# First use only: uncomment to sign in before starting agents
# Codex: open the printed URL on your host and enter the device code
# command codex login --device-auth
# command claude auth login
# gh auth login --web --git-protocol https  # optional GitHub CLI login
# pairtask-codescene-login                  # optional CodeScene token; hidden prompt

# First use only: clone if you have not already done so
# git clone https://github.com/pairtask/pairtask.git /workspace/collab-ai
tmux new -A -s collab

# In each tmux window: enter the project, then choose one agent or dashboard
# Ctrl+B then C opens another window
cd /workspace/collab-ai
codex                         # new managed Codex conversation
# codex resume                # choose a saved sandbox conversation
# codex resume SESSION_ID     # resume a specific sandbox conversation
# claude                      # Claude with collaboration channels enabled
# claude --resume             # resume Claude
# dashboard                   # broker status and agent inboxes
# rtk gain                    # estimated shell-output token savings
# docker info                 # rootless Docker inside workspace
# docker compose up -d        # run your project's compose.yaml

# Disconnect: Ctrl+B then D detaches tmux; exit leaves SSH
exit

# HOST AGAIN: optional shutdown; stops agents, keeps persistent files
# incus --project pairtask stop colima-pairtask:workspace
# incus --project pairtask stop colima-pairtask:secured   # if secured_runtime = true
# colima stop pairtask
```

Expect `Broker: ready`. Run one Codex and one Claude session; additional sessions
need distinct agent IDs. [Login help](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#sign-in-and-network-access).
Both agents should read `/usr/local/share/pairtask/SKILL.md`.

[Mount directories](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox-mounts.md) ·
[Mac writable sharing](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox-mounts.md#mac-writable-sharing) ·
[Docker and Compose](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#docker-and-compose) ·
[Bundled MCP tools](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#bundled-mcp-tools) ·
[Upgrade or reprovision](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox-storage.md#replace-dev-retain-data) ·
[Back up](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox-storage.md#back-up-and-restore) ·
[Stop or remove](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#stop-or-remove)

## Dashboards

Run on your host:

```sh
# Agent connections and pending messages (terminal UI)
ssh -t -F infra/incus/ssh/config workspace pairtask dashboard

# Containers, resources and logs (browser UI)
incus webui colima-pairtask:  # Linux: incus webui local:
```

For Incus, open the printed URL and select project `pairtask`.
The collaboration dashboard is read-only; prompts and approvals stay in agent
terminals. [Controls](https://github.com/pairtask/pairtask/blob/HEAD/docs/dashboard.md) · [UI help](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#incus-web-ui).

## How it fits together

With `secured_runtime = true`, Codex, Claude and the read-only dashboard run in
**workspace**; **secured** owns one broker and SQLite database.
The shared Unix socket connects them.
`/workspace` and `/home/agent` persist across container replacement.

![Codex, Claude and the read-only dashboard in workspace connect through a shared Unix socket to the broker and SQLite in secured.](https://raw.githubusercontent.com/pairtask/pairtask/HEAD/docs/assets/architecture.svg)

[Architecture source](https://github.com/pairtask/pairtask/blob/HEAD/docs/assets/architecture.puml) · [Control setup](https://github.com/pairtask/pairtask/blob/HEAD/docs/secured-runtime.md)

<details>
<summary>macOS and Linux layouts</summary>

| macOS: Colima hosts Incus | Linux: Incus runs directly |
| --- | --- |
| ![macOS sandbox](https://raw.githubusercontent.com/pairtask/pairtask/HEAD/docs/assets/sandbox-macos.svg) | ![Linux sandbox](https://raw.githubusercontent.com/pairtask/pairtask/HEAD/docs/assets/sandbox-linux.svg) |
| [Diagram source](https://github.com/pairtask/pairtask/blob/HEAD/docs/assets/sandbox-macos.puml) | [Diagram source](https://github.com/pairtask/pairtask/blob/HEAD/docs/assets/sandbox-linux.puml) |

</details>

## Security

Agent commands run inside the container. Host mounts default to read-only;
writes require a dedicated sharing identity. Writable sharing lets agents
change files that you or host automation may later execute.
[Boundaries](https://github.com/pairtask/pairtask/blob/HEAD/docs/sandbox.md#security-can-agents-execute-code-on-my-host).

## Run on your host

No Incus? Follow the [host quick start](https://github.com/pairtask/pairtask/blob/HEAD/docs/quickstart.md) to build and run locally.
These agents have no Incus isolation.

### Resume or fork

[Host commands and compatibility](https://github.com/pairtask/pairtask/blob/HEAD/docs/host-integration.md#codex-terminal).
Sandbox start/resume commands are in the daily block above.

### Set a Codex soft cap

The sandbox aliases are uncapped by default. Use a [named budget](https://github.com/pairtask/pairtask/blob/HEAD/docs/host-integration.md#codex-soft-cap)
for one managed Codex launcher. Reports can arrive late; overshoot is possible.
Claude and shared budgets are not yet covered.

### Claude Code

The sandbox alias is preconfigured. For host sessions, use the
[dedicated channel config](https://github.com/pairtask/pairtask/blob/HEAD/docs/quickstart.md#3-start-claude-code).
Claude requires channel consent and account/organization support.

## Reference and contributing

[Protocol](https://github.com/pairtask/pairtask/blob/HEAD/docs/protocol.md) · [Manual MCP](https://github.com/pairtask/pairtask/blob/HEAD/docs/mcp.md) ·
[Status API](https://github.com/pairtask/pairtask/blob/HEAD/docs/status.md) · [Agent skill](https://github.com/pairtask/pairtask/blob/HEAD/docs/skills/collab-ai/SKILL.md)

[Report an issue](https://github.com/pairtask/pairtask/issues). Run checks with:

```sh
go test -race ./... -timeout=30s
```