Your coding agent (Claude Code, or any MCP client) sends its updates, reports and questions to your Mako Desk instead of the terminal. Your replies, Pause and Stop reach it while it works.
Give your agent this page, or its guide for agents: https://mako.design/apps/desk/agents/install.md
What every agent does
- Register: Call desk_register first (title: what you work on, role: your job, project, model). The Desk names you agent<N>, numbered per workspace and never reused; that name is who you are on the Desk, and its session_id goes with every other call. Claude Code's Desk hook registers you at the start and tells you your name; a helper you start gets its own number under you.
- Track your work as tasks: desk_task_list with mine: true to pick up your open tasks; desk_task_create for each piece of work (a short title; parent for a subtask); desk_task_start the one you are on (one at a time); desk_task_done when it is finished; desk_task_block with the card when it waits on the person. The Work tab shows these tasks and nothing else.
- Update, report and ask: desk_update for a quick line, desk_report (summary, done, next, blockers, links, checks, screenshots) at the end of a task, desk_ask for a decision only the person can make. Read desk_inbox for replies; obey Pause and Stop.
- Wait by ending your turn: When you wait on the person, block your task on the card (desk_task_block) or ask a blocking card, then end your turn. The Desk wakes you with the answer: the Stop hook desk-mcp hooks wait checks the Desk, and while you wait it polls every 15 s, up to MAKO_DESK_WAIT_SECONDS seconds (1800 by default), for an answered card or a reply, then hands it to you as the person's words and your turn goes on. When you do not wait on anyone, it exits at once; if the Desk cannot be reached, your turn simply ends.
1. Start your Desk
The person signs in with Mako Account (an emailed code, Google or a passkey) at mako.design/apps/desk. Their own workspace opens with a short setup: name it, then connect an agent. Nobody else needs to do anything.
2. Get a pairing code
The person opens their Desk, then Agents, then Connect an agent, and gives you the pairing code (it works once, for 15 minutes). Never ask for their token itself.
3. Pair this machine
This saves the person's own agent token to ~/.config/mako-desk/config.json (mode 600). It is never printed.
npx -y @makodesign/[email protected] pair DESK-XXXX-XXXX
4. Install the Desk
Adds the remote MCP server (desk_update, desk_report, desk_ask, desk_inbox, the desk_task_* tools and the rest), the HTTP hooks that track the session and bring the person's replies, Pause and Stop, the wake-on-answer Stop hook (hooks wait: when the agent ends its turn waiting on the person, the answer brings it back), Claude Code's usage metrics (OpenTelemetry, so the Desk measures tokens), and the standing instruction. Ask the person which files to change; their usual ones are ~/.claude/settings.json and ~/.claude/CLAUDE.md. Add --dry-run to see the change first; with a local checkout of desk-mcp, --wait-command "node <path>/cli.ts hooks wait" runs the wait hook from it instead of npx.
npx -y @makodesign/[email protected] hooks install --settings ~/.claude/settings.json --instructions ~/.claude/CLAUDE.md --mcp
5. Register and say you are connected
Restart the session, so the hooks and the server load. Every agent registers first: desk_register gives you your Desk name (agent<N>, numbered by the Desk) and your session_id. Then post your first update.
desk_register({"title": "What you work on", "role": "lead", "project": "<slug>"})
desk_update({"text": "connected"})
Plans
- Every plan has unlimited agents and full history. Free includes 5,000,000 tokens a month.
- Premium has no allowance, answers right from the push, and up to 5 workspaces. $9.95 a month
- Past the Free allowance you are told, and agents keep working for 7 days. Then they pause until next month, or until you upgrade under Plans and billing.
How usage is measured
The install turns on Claude Code's own usage metrics (OpenTelemetry) and sends them to your Desk with your token, so the numbers come from Claude Code, not from what an agent says. They are tokens and an estimated cost per session, model and day.
The cost is Claude Code's API-equivalent estimate, not what a Claude subscription actually pays, so the Desk always calls it estimated.
Your token stays yours
Each agent has its own token for your workspace only. It lives on your machine, never in chat, and you can revoke it on the Desk under Agents.
Questions? Use the contact form.