@cloop/runner
The cloop CLI: device login, a stdio MCP server (Cloop Skills), and a Claude Code hook that heartbeat your agents into the Cloop mesh. Harness- and domain-agnostic — Claude Code, Cowork, and Codex all get presence via the MCP server; Claude Code hooks add session-lifecycle detail.
Install
npm install -g @cloop/runner
cloop login # approve the device in your browser
cloop install # register the MCP server with Claude Code / others
Credentials live in ~/.cloop/credentials.json. The API origin comes from CLOOP_ORIGIN, the stored value, or the staging default.
npx -y @cloop/runner@latest connect makes this computer a Cloop machine. As its last step, it adds the remote Cloop MCP server to each Claude Code and Codex on the machine, and signs it in with OAuth on a terminal. It runs the usual lines: claude mcp add -s user --transport http cloop https://app.mycloop.com/api/mcp/mcp and codex mcp add cloop --url https://app.mycloop.com/api/mcp/mcp, then claude mcp login cloop and codex mcp login cloop. Staging uses the name cloop-staging and https://mcp-staging.mycloop.com/mcp. When an entry under any name already has the URL, connect adds nothing. This step never makes connect fail. Details: docs/runbooks/cloop-local.md, "Connect", step 5.
To disconnect a machine, use Disconnect in its ⋯ menu on the Threads page.
Windows
cloop connect on Windows writes %LOCALAPPDATA%\Cloop\cloop-runner.cmd and registers a per-user Task Scheduler task, Cloop Runner, that runs it at logon. No admin rights are needed. The log is %LOCALAPPDATA%\Cloop\cloop-runner.log. cloop disconnect deletes the task and the launcher. Use the native Claude Code install, which puts claude.exe on PATH. The Windows path is covered by unit tests and has not yet run on a Windows machine; details and the open points are in docs/runbooks/cloop-local.md, section "Windows".
Commands
| Command | What it does |
|---|---|
cloop login [--name <device>] | Device-code flow → long-lived token |
cloop install | claude mcp add cloop -- cloop serve + Cowork/Codex instructions |
cloop serve [--platform <p>] | Run the stdio MCP server (heartbeats presence) |
cloop hook session-start | Claude Code SessionStart hook — not registered in Phase 1 |
Presence model (Phase 1)
The MCP server (cloop serve) is the sole presence source: one agent_sessions row per live server process. Its session_key is CLAUDE_SESSION_ID when the harness provides it, otherwise a per-process UUID. name is the harness label ("Claude Code" / "Codex" / "Cowork"); machine is the hostname; login deviceName is separate (cli_devices.name).
cloop hook session-start exists in the tree but cloop install does not wire it up — Claude Code hooks are the Phase 2 coding adapter (richer session lifecycle detail). Leaving it unregistered keeps Phase 1 at one row per MCP process.
MCP tools
The server exposes one built-in tool plus every tool advertised by the shared
app-side registry — it fetches GET {origin}/api/agent/mesh/tools at startup and
registers each dynamically, proxying calls through POST {origin}/api/agent/mesh/tools
{tool, input}. New skills land with no CLI release.
cloop_status {}— built-in: who's live on your mesh, on what surface (served locally from/api/agent/mesh/status, not the registry)cloop_inbox {action?}— built-in:drain(default) returns and clears the delegated tasks / DMs pushed to this agent over the mesh;listpeeks- registry tools — e.g.
search,list_tasks,get_task,get_task_context,get_contact,list_cloops,get_cloop
If the registry is unreachable at startup, the server runs status-only (warns once
on stderr). A 401 from any proxied call returns an isError result asking the
user to run cloop login.
Live presence mesh (cloop serve)
On start, serve opens a WebSocket to the cloop-mesh Worker's per-user Durable
Object at {CLOOP_MESH_URL}/mesh/agent?session_key=… (default
https://mcp.mycloop.com; --staging or CLOOP_MESH_URL selects another
mesh, and the choice is stored as meshUrl). The device token rides the first Sec-WebSocket-Protocol entry, never
the URL (query strings leak into edge logs). While it's up, presence
beats ride the socket (the DO mirrors them into the heartbeat route) and the HTTP
HeartbeatClient is the fallback; it reconnects with 1s→60s backoff + jitter.
Incoming delegate / dm frames are appended to ~/.cloop/inbox.jsonl and the
statusline shows a ✉ N pending badge; cloop_inbox drains them.
Develop
npm install
npm run build
npm test
OAuth fallback
Claude Code and Codex can carry each other's runs after a provider login failure.
This works for direct CLI runners and T3 runners.
See the runbook for restrictions and release steps.
After the release merges, run bash tools/ops/runner-oauth-fallback-wizard.sh from the repository root to approve and install it.