Connect pi to Clearly.
pi (the @earendil-works/pi-coding-agent) is different from the other rooms in two ways that shape how you connect it: it’s key-only (no “Log in with Google” — you bring a provider API key), and it ships with no MCP client. So its natural, most capable route to Clearly is its built-in bash tool running the Beehaven CLI — which hands pi the whole workspace, not a curated tool list. The Mac app hosts a BYOK pi room; MCP is possible but advanced.
Which connection do I want?
They compose. For pi the CLI is the recommended path — it's how the in-app room already drives the canvas — with the Mac app as the no-setup way to get the daemon it needs.
| Path | Best for | Setup | Runs on |
|---|---|---|---|
| The CLI (Beehaven) | The real path for pi — its built-in bash tool runs `beehaven`, so it reaches the whole workspace (canvas + brain), not a tool subset. | One-line install + a daemon you own. | A local daemon that holds the relay connection. |
| The Mac app | Zero-setup: the daemon the CLI needs, auto-running + signed in. Plus an in-app BYOK pi room. | Download the DMG, sign in, paste a provider key. | A local daemon + your own provider API key. |
| MCP (advanced) | The clearly_* tools natively — but core pi has no MCP client, so this needs a pi MCP extension + an OAuth bridge. | Add MCP to pi + mcp-remote (OAuth bridge). | Clearly's hosted relay, via a local stdio bridge. |
Why CLI-first, when the other agents lead with MCP? Because pi’s own docs say “No MCP” — the core agent has no MCP client to point at relay.clearly.sh/mcp. What it does have is a bash tool, and the beehaven CLI turns that into full access: the entire ~200-action workspace and the headless canvas, which is a superset of what an MCP tool list would expose.
Option A · The Beehaven CLI — recommended
pi drives Clearly by shelling out with its built-in bash tool: connect once, then call actions and build on the canvas headlessly (no browser tab). This is exactly how the in-app pi room works.
1 · Install
One line, any OS. Installs the CLI and its daemon. Requires Node.js 20+. On macOS the Mac app already bundles it — skip this.
curl -fsSL https://clearly.sh/install.sh | sh
2 · Sign in & run the daemon
The daemon holds the relay connection and routes every call. The Mac app spawns it; off macOS you own it with start --headless.
beehaven login # browser OAuth sign-in (this is YOUR Clearly account) beehaven start --headless # run the daemon yourself — no desktop app needed beehaven status # → Account: Connected
Note the two identities don’t collide: beehaven login authenticates your Clearly workspace; the provider key pi runs its model on is separate. One says whose workspace, the other says which model.
3 · Point pi at it
pi's bash tool runs beehaven directly. Because the canvas verbs are headless, pi can build a whole page and you open the tab to find it done.
beehaven connect home # pin the target
beehaven call composition-create '{"title":"Landing"}' # capture the id
beehaven call canvas-act @build.json # build a batch of nodes
beehaven call canvas-perceive '{"compositionId":"<id>","format":"text"}' # check itFull command reference: Beehaven CLI. The node shape, the batch format and the headless rules: Canvas API.
What pi gains through the CLI
The same surface the clearly_* MCP tools wrap — reached as beehaven calls. beehaven actions lists all ~200; these are the headline verbs.
beehaven call canvas-perceive— SEE a composition — every node, its box + style, the selection, the viewport. Optionally a rendered PNG.beehaven call canvas-act— BUILD on it — frames, text, vectors, images, auto-layout, components. One action or a whole batch.beehaven call canvas-catalog— Every canvas verb + its exact args, and which run without a browser tab. Generated, never stale.
beehaven call context-search— One ranked search across prompts, docs, decisions + facts — this workspace, or the whole org.beehaven call context-write— Write a PRD / decision back so the next agent finds it.beehaven call schedule-wake— Write a prompt for pi’s future self + schedule a wake — one-shot or recurring.
beehaven actions— List every action the connected workspace exposes (~200), with schemas.beehaven call <action>— Run any workspace action by name — the full surface, one call at a time.
Option B · The Mac app
The desktop home for your workspace. It bundles the Beehaven CLI and spawns the daemon for you — so the CLI works with zero setup — and hosts an in-app agent room where pi runs on your own provider key.
1 · Download & sign in
macOS, Apple-signed. Apple Silicon (also runs Intel via the universal build). Windows isn't built yet.
Open the app and sign in with Google. On launch it spawns the local daemon that holds your relay connection, already authenticated as your account — so beehaven status shows Connected and the CLI path above works with nothing else to install.
2 · The in-app pi room (BYOK — key only)
pi has no consumer login. You pick a provider and paste its API key; the room runs @earendil-works/pi-coding-agent, auto-installing it if missing.
Open the room’s model menu, pick one of pi’s 34 providers (OpenRouter, Groq, DeepSeek, Anthropic, OpenAI, xAI, Mistral, Together, Fireworks, Cerebras, and more) and paste that provider’s key. pi then runs on your key, so nothing touches Clearly’s AI pool. It works in ~/Clearly and drives the canvas with the same CLI verbs as Option A.
One thing to know: pi reads its key from Clearly’s own key store, not ~/.pi. So you paste the key in the room even if pi is already configured in your terminal — that isolation is deliberate (a key in ~/.pi/agent/auth.jsonwould otherwise silently win over the one you typed here).
Option C · MCP — advanced, and usually unnecessary
Core pi ships no MCP client, so there's no relay.clearly.sh/mcp entry it reads out of the box. Prefer Option A. This section is only for a pi build that has added MCP via an extension.
The honest state
pi is composable — some distributions add an mcp.json reader following Claude Code's format. Core pi does not.
If your pi setup does have MCP (via an extension), Clearly is a remote server that requires OAuth, and pi’s MCP support is built around stdio servers. The bridge that squares those is mcp-remote — a tiny stdio MCP server that performs the browser OAuth flow and proxies to the streamable-HTTP endpoint. Point your pi MCP config at it like any other stdio server:
{
"mcpServers": {
"clearly": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://relay.clearly.sh/mcp"]
}
}
}On first run mcp-remote opens the browser to sign in (tokens cache under ~/.mcp-auth); the scopes are the same as everywhere — rpc:read · rpc:write · admin. The tools then appear namespaced (pi convention: mcp_clearly_*). If any of that doesn’t line up with your pi build, that’s the signal to use Option A — it needs no extension and exposes more.
Prefer the CLI
For almost everyone the CLI is the right answer: it’s how pi is wired to Clearly in the Mac app, it needs no third-party MCP extension, and it reaches the full workspace surface — a superset of the clearly_* tool list. Reach for MCP only if you specifically want those namespaced tools inside an existing pi-with-MCP setup. Full MCP reference: MCP docs.
Troubleshooting
The handful of things that actually go wrong, and the one-line fix for each.
pi (the room / the CLI)
no provider key set — pi has no login; it needs a provider key. In the Mac app, pick a provider in the model menu and paste its key. Driving pi yourself, export that provider’s env var (e.g. OPENROUTER_API_KEY).
401 / 403 from a provider — the key is wrong, expired, or lacks access to the chosen model. Re-check it in the model menu.
pi not found — the Mac app auto-installs it; driving it yourself, run npm i -g @earendil-works/pi-coding-agent.
The CLI / daemon
Cannot connect to daemon — nothing owns the local socket. Open the Mac app (it spawns the daemon) or run beehaven start --headless.
Not connected to cloud — the daemon is up but its relay link isn’t. Usually an expired token: beehaven login. If the token is fine (e.g. after sleep), beehaven restart.
MCP (if you're using the bridge)
No clearly tools in pi — confirm your pi build actually loads an mcp.json (core pi doesn’t); then that the entry runs mcp-remote. When in doubt, switch to the CLI.
OAuth didn’t open / stale session — clear ~/.mcp-auth and rerun so mcp-remote re-authenticates.