Developers
The capy command line and coding agents
Manage projects with the capy command line, and let coding agents such as Claude Code and Codex read messages and materials in Capy and take development tasks from Kapi.
capy is Capy's command-line tool. It has two uses:
- Manage projects: add, sync, send off tasks, pull back changes, and open a terminal. See Projects.
- Connect your own coding agent: let Claude Code, Codex, and others read the messages, to-dos, tasks, and library materials you can see in Capy, and take development tasks Kapi assigns.
Install
The desktop app includes the command line. On a Mac, choose Install capy Command… from the app menu.
Sign in: confirm in the app
Signing in on the command line doesn't need a password. Instead, you confirm in the app where you're already signed in:
- Run
capy loginin a terminal and enter your company code and account. The terminal shows a 4-digit code. - Capy on your phone, computer, or the web, wherever you're signed in, pops up The capy command line on a computer wants to sign in to your account, showing which device, what time, and what network.
- Enter the 4-digit code from the terminal and tap Confirm sign-in. If you didn't start this yourself, tap Not me, deny.
Rules:
- The code is valid for 10 minutes, can be used only once, and is voided after 5 wrong tries;
- Only you can confirm, in the app; Kapi can't confirm for you;
- A confirmed sign-in expires after 30 days without use;
- Never enter a code someone sent you or read to you over the phone.
Fallback: capy login --password signs in with a password. capy logins lists the sign-ins saved on this computer.
Connect Capy to a coding agent
capy agent setup --agent claude # or --agent codex
This gives the agent the capy MCP tools and two skills (reading Capy context and handling Capy tasks).
Read context from Capy (read-only)
Once it's set up, your agent can read anything you have permission to see, from any directory, without creating a project first:
| Content | Tools |
|---|---|
| Chat messages | chat_list, chat_search, chat_read |
| Tasks | task_list, task_read, task_call_read |
| To-dos | todo_list, todo_read |
| Library | kb_spaces, kb_list, kb_search, kb_read |
These tools are read-only: they don't mark messages as read, send messages, or change tasks. To the agent, the messages and file contents it reads are material, not instructions.
Take development tasks from Kapi
- Set the project to use the local agent: in the project's Run settings → Where tasks run, choose Agent on my computer, or run
capy project settings --runner agent. - Tell Kapi what to do, or run
capy run "…"in the project folder. - Open the agent in the project folder and say "Handle Capy tasks". The agent claims the task and edits code in a separate working directory under
.capy/tasks/<task>/, on the branchcapy/<task>. Your current working tree and branch aren't touched, and.envand files that look like secrets aren't brought in. - After the agent delivers, Kapi checks it as usual and sends it back if it's not up to standard. The changes are already on a branch in your repository; review and merge them.
Compared with the cloud computer: the model runs on your own agent's account, so it doesn't use Capy's model usage, and there's no limit of 2 tasks at once. Requirements Kapi adds only reach the agent the next time it talks to Capy.
Wake the agent automatically
If you don't want to say "Handle Capy tasks" by hand every time, Capy can start the agent automatically when there's a task:
- Desktop app: in the project's Run settings, under Coding agents on this computer, choose an agent that can run automatically. As long as the app is open, it watches the project for you.
- Command line:
capy agent watch --agent claude [folder…]
Supports claude, codex, opencode, codebuddy, qoder, qwen, kimi, and gemini, checking every 20 seconds by default. A project is watched from only one place at a time: if the app and a terminal both watch it, the later one shows "… is already watching this project" and takes over once the earlier one stops.
Common commands
| Command | What it does |
|---|---|
capy login / capy logins | Sign in (confirm in the app) / list sign-ins on this computer |
capy agent setup | Give a coding agent the Capy tools |
capy agent watch | Start the agent automatically when there's a task |
capy project add | Add the current folder as a project |
capy project settings | Change run settings: --runner, --size, --effort, --sleep, --web, --relay |
capy project about | Change How Kapi knows this project |
capy sync | Sync code to the cloud computer (--full, --dry-run, --deep) |
capy run "…" | Send off a development task in the current project |
capy status <task> / capy logs <task> -f | View task status / run log |
capy pull <task> | Pull changes from the cloud computer into a local branch |
capy shell | Open a terminal on the project's cloud computer |
capy sleep | Put the project's cloud computer to sleep (--cancel also stops tasks) |
capy network allowlist / open | Outbound allowlist / unrestricted |
capy secret ls/set/rm | Manage project secrets |
capy relay register/allow/deny/ls/start | Intranet relay |