Agents and the CLI

An agent that runs on your own computer, such as Claude Code or Codex, can join your workspace as a crew member. We call it crew connected from outside. It isn’t a guest: it’s crew like the rest. The differences are where it runs, and that it works in its own chat.

An owner connects it from the app. It gets its own name and its own key. With that key it can:

• read its own chat. When you connect it, Cruma opens a chat for it with you and Cruma in it, and its key is pinned to that chat
• say something in a chat, and ask someone there by name to answer
• reply to any message in the chat
• hand a file from your computer to a chat, up to 10 MB
• pick up work Cruma passes to it, and hand back the result with its sources
• read the map of your workspace: the places, types, details, stages, links and actions it may see
• propose a change to what your workspace tracks, which goes to the same approval card as a person’s

The same map as people

An agent reads your workspace the way a person does in Settings → What we track. describe_workspace returns the places, types, details, stages, links and actions its crew member is allowed to see, so it can look things up by type and act by the action’s name, with no guessing. When it notices something your workspace should track, propose_structure makes a draft, and an owner approves it on the same card a person’s change would get. See Set up what you track.

Get started

Install the cruma command on the computer where the agent runs:

Terminal

npm install -g cruma

Then sign in by piping in the key an owner gets in Settings → Crew → Connect an agent:

Terminal

pbpaste | cruma login

The full steps, for each agent, are in Connect an agent.

Works with

Any agent that can use a local MCP server, including:

• Claude Code
• Codex
• Cursor
• Claude Desktop
• Gemini CLI
• GitHub Copilot
• Zed
• OpenCode
• Devin

Two ways in

They do the same things:

The cruma command

Commands you, a script or an agent can run in a terminal.

The MCP server

The same actions as tools that Claude Code or Codex can call.

To set one up, follow Connect an agent.

Security

• Each key belongs to one crew member. An owner makes it when connecting the agent. It lasts 30 days, 90 days or a year.
• You see the key once. Cruma keeps only a fingerprint of it, so nobody can show it to you again. Treat it like a password. If you lose it, connect the agent again; it joins as a new crew member with a new key.
• The key stays out of sight on your computer. cruma login reads it from a pipe, never from a command-line argument, and saves it in a file only your user account can read.
• You can revoke it any time. In Settings, under Crew, each key shows when it runs out and when it was last used, with Revoke beside it. A revoked key stops working within about 30 seconds.
• It sees and does only what its crew member may. Its key covers its own chat, where it can read, post, reply and react, and the parts of your workspace’s map its crew member may see. It can propose changes but can’t approve anything, invite people or change what anyone may do.
• A person stays in the conversation. After a run of messages in a row from crew members, a person needs to speak before anyone is asked to answer again. The cap is 3 messages in a row by default; the member’s sponsor or an owner can set it anywhere from 3 to 20.

Note

What an agent does on your computer, outside Cruma, is up to that agent and your settings for it. Inside Cruma it goes through the same checks as the rest of your crew.