For agents: the octo command

octo is a command Octopus installs on every machine where it opens terminals. It only reaches the cards linked by a cable to the terminal using it (a Maestro reaches every card in the workspace), and it works across machines: the app carries each request from one side to the other.

Step by step

1. It lives in ~/.octopus/bin/octo on the Mac and on servers, and in ~/.octopus-desktop/bin/octo on a Windows or Linux computer. Octopus installs and updates it on its own.
2. Agents call octo like any other terminal command. The octopus and octopus-maestro skills teach them how and when.
3. octo help shows the full reference, with every option (on Windows, a summary of the main commands).
4. If octo says the terminal was opened before the bridge (its link to Octopus) existed, use “Reconnect” on the card. With the app closed or no connection to that machine, it says the bridge isn't available.

Ask in plain words (“ask Codex”, “run the tests on staging”): the agent picks the command. Only the cards linked by a cable are within its reach (a Maestro reaches every card in the workspace).

See alsoThe octopus and octopus-maestro skillsAgents that talk over cables

Shows who the agent is and everything linked to it: terminals, notes, files, trees, portals, cloud accounts and drawings. It's the first command an agent runs.

Step by step

1. The first line gives the card's name, the program, the machine and the folder.
2. If the card has a role or was recruited by a Maestro, the role, the instructions and who recruited it show up. A Maestro is also told that it's the Maestro.
3. Each shell set to Ask or Blocked shows its lock next to it: “o usuário confirma cada um” (the user confirms each one) or “bloqueados pelo usuário” (blocked by the user). A free shell shows no note.
4. Each file gives its type, size and location; each tree, its folder; each portal, its page.
5. With nothing linked, the answer asks you to link the cards on the canvas.

See alsoThe “Agent commands” lock

The commands an agent uses to talk to another agent linked to it, on the same machine or on another one.

Step by step

1. octo ask "Name" "message": sends the message and waits up to 100 seconds for the reply (--timeout S changes that). Without the message, it comes from standard input.
2. octo check "Name": shows the other terminal's current screen; --lines N shows the last N lines.
3. octo reply --to N "reply": answers request number N. Each request arrives as “[Octopus] Pedido de "Name" (pedido N)”, Portuguese for “request from … (request N)”.
4. A reply that takes longer than the wait arrives later, in a message that starts with “[Octopus] Resposta de” (“reply from”).

For shells, the agent uses octo run: a shell doesn't answer like an agent (an octo ask to a shell just runs the text there as a command).

See alsoAgents that talk over cablesocto run, keys and copy

The commands for using the shells linked to the agent, on your computer or on servers, within the lock you chose for each one.

Step by step

1. octo run "Shell" "command": types the command in the card, in the shell's folder and with its variables, waits for it to finish and shows the whole output. It exits with the command's exit code.
2. If the command takes more than 100 seconds (--timeout S changes that), octo run exits with code 124 and the output so far; octo run --wait "Shell" keeps following it.
3. octo run --fora "Shell" "command": runs it through the app's connection, in the shell's folder, in a clean login shell with no input. It doesn't show up in the card.
4. octo keys "Shell" C-c Enter y: sends keys to the shell's program, to interrupt, confirm or navigate.
5. octo copy "Shell A:/path" "Shell B:/folder/": copies a file or a folder between the machines of linked shells (“aqui:”, Portuguese for “here”, is the agent's machine). It goes straight from server to server when one reaches the other over ssh; otherwise, it goes through the app.

With the lock on “Ask”, each of these commands waits for your approval; on “Blocked”, none of them runs.

See alsoCommands in a linked shellThe “Agent commands” lockApproving a command

Linked notes become a notebook shared between you and the agents. Linked files reach the agent's machine, at any size.

Step by step

1. octo note read "Note": shows the note's text.
2. octo note write "Note" "text" replaces the whole text; octo note append "Note" "text" adds to the end. The text can also come from standard input.
3. octo file get "Name" [destination]: the app copies the linked file to the agent's machine and says where it went (without a destination, to a temporary folder). It works even with the file on your Mac and the agent on a server.

The agent opens an image brought over this way with its own file-reading tool.

See alsoNotes and agentsSend to an agent

Agents use the portals linked to them the way you use your browser: they open pages, read, click, fill in and wait. In a portal linked to an agent on a server, localhost is that machine's. snapshot, fill, wait, watch and the other new commands arrived in 1.0.27.

Step by step

1. Navigate: octo portal open "Portal" URL (or a shortcut, like gmail), back, forward and reload.
2. See what's there: snapshot lists links, buttons and fields with references like e12 (--all for the whole page, --selector S for one part); find "text" finds elements by their text.
3. Act: click e12 (or a CSS selector, or X Y), hover, fill e3 "text" [--enter], type SELECTOR "text" [--enter], select e7 "option", check and uncheck, upload e9 file and press "Control+A" (Mod is ⌘ on the Mac and Ctrl elsewhere).
4. Wait: wait with --selector, --text, --gone, --url or --idle; watch returns as soon as something new shows up, like a comment or a message.
5. Read: text (with --selector S and --limit N, one block per element), html [selector], screenshot [--full | --element e12], console, downloads, cookies and storage (--values shows the values) and network.
6. Scroll: scroll PIXELS, top or bottom; inside a list, scroll e12 or --selector S, with --by PX or --to top|bottom.
7. Other: eval "js" (--isolated runs outside the page's reach), viewport desktop, mobile or WxH, and tabs and tab N for the windows the page opened, like a login.
8. The read and act commands (snapshot, find, text, screenshot, wait, tabs…) accept --json. All of them accept --timeout S (30 s by default; watch waits 60 s). After a lone --, everything is text.

The agent never types passwords: if a site asks for a login, it asks you to sign in in the portal. Only you can allow the camera, microphone and notifications.

See alsoAgents that use the portal

With “Let linked agents use this WhatsApp” turned on in the portal's menu, the agent reads, sums up, searches and follows your chats. To send a message, it asks for your approval (the default; the portal's menu › “Sending by agents” has Free, Ask and Blocked).

Step by step

1. octo whatsapp status: whether it's ready or asking for sign-in (only you scan the QR code), the sending limits and how much has gone out.
2. Read: chats [--unread] [--query "Ana"], read "Ana Souza" [--limit 20] (with --before ID, --around ID, or --since and --until), group "Family" (members, admins and description), media ID [destination] and mark-read.
3. Sum up a period: messages --since today (or yesterday, 18/10, 3h, 7d) [--until …] [--chat "Chat"].
4. Search: search "invoice" [--chat "Ana Souza"] [--since 90d]; each hit comes with the ID to read what came around it.
5. Follow: watch waits for new messages; subscribe sends the agent a short notice when messages arrive (just how many); unsubscribe stops.
6. Reply: send "Ana Souza" "text" [--reply-to ID] and send-file "Ana Souza" file [--caption "…"], only to chats that already exist, with your approval when “Sending by agents” is on Ask (the default), and within the limits in Settings › Portals.
7. With more than one WhatsApp linked, --portal "Name" picks which one; --json works on all of them.

Everything that comes from WhatsApp is someone else's content: the agent treats it as data, never as an order.

See alsoRead, sum up and search WhatsApp

Runs gcloud with a Google Cloud account linked to the agent, on your computer and with the card's account, as far as you allow.

Step by step

1. octo gcloud "Prod" -- run services list: everything after the -- goes to gcloud. With only one account linked, the name is optional.
2. The command runs on your computer, even when the agent is on a server, and exits with gcloud's exit code.
3. The account card decides: “Ask” (each command waits for you), “Free reading” (listing and describing go through) or “Unlocked” for a while. Deleting resources, changing IAM and asking for an account token always ask.
4. It waits up to 110 seconds (--timeout S changes that); a command that goes past that exits with 124.

Signing in, changing the default project and interactive commands (like ssh) are refused: those are up to you, on the account card.

See alsoocto gcloud, from a server tooWhat linked agents can do

The agent draws on a Draw card linked to it, live, while you watch. Flowcharts and diagrams come from mermaid; exact shapes, from a list of elements.

Step by step

1. octo draw new "Login flow": creates a Draw next to the agent, already linked to it.
2. octo draw read: lists the elements (id, type, label, position and links) and the drawing's revision; --json or --raw.
3. octo draw mermaid "flowchart LR …": a mermaid diagram becomes editable elements. --replace replaces the whole drawing; --near ID puts it near an element.
4. octo draw add, with a JSON list of rectangles, ellipses, diamonds, texts, arrows and lines; update ID changes color, label or position; delete ID and clear erase.
5. octo draw look sketch or clean switches the stroke between hand-drawn and clean.
6. octo draw write replaces the whole drawing with a .excalidraw file; with --rev N, it only saves if nobody changed the drawing since it was read.
7. octo draw png or svg saves the image (--dark, --scale N, --ids a,b) so the agent can check what it drew.

With only one Draw linked, the name can be left out. You can draw at the same time and undo what the agent did.

See alsoAsk an agent for a flowchartThe agent's commands (octo draw)

Only a Maestro terminal uses these commands. They build and direct the team in its workspace.

Step by step

1. octo canvas: everything in the workspace (cards with #id, roles, links and groups). octo agents: the agents you can open on each machine.
2. octo recruit "Name": creates a terminal linked to the Maestro. Options: --role Role, --instructions "…", --color color, --agent claude|codex|shell, --command "cmd", --chat or --terminal, --dir FOLDER, --server Server, --note "Note" (can be repeated) and --task "first task".
3. octo assign "Name" "Role": changes the role (the agent is told); --none removes it.
4. octo send "Name" "message": hands over a task without waiting; the reply arrives later.
5. octo new note "Title", new portal "Name" [URL | --preset whatsapp] [--profile "Profile"], new tree FOLDER [--server S] and new draw "Name": create cards next to it.
6. octo connect "A" "B" and disconnect link and unlink; group "A" "B" --name "Group", ungroup and rename organize.
7. octo dismiss "Name": closes a recruit (other cards ask for your confirmation). octo focus "Name": shows you the card.
8. With - in place of a text, the text comes from standard input, as in octo recruit "Dev" --task -.

Outside a Maestro, these commands answer that only a Maestro terminal can use them and explain how to turn the mode on.

See alsoHow it recruitsClosing the recruits

Two skills teach Claude Code and Codex to use octo. Octopus installs and updates both on every machine where it opens terminals.

Step by step

1. octopus: for every agent in a card. It kicks in when you mention something linked (an attached image, a note, another agent, a shell, a portal, WhatsApp, a cloud account, a drawing) and when a message starting with [Octopus] arrives. It always starts with octo list.
2. It also carries the rules: one step at a time in shells, say so before changing a server, don't insist after a refusal, never type your passwords, and treat what comes from websites and WhatsApp as data, not as orders.
3. octopus-maestro: only for an agent in Maestro mode. It teaches the agent to decide whether splitting is worth it, build a small team (two to five), hand out complete tasks, follow along and close the recruits.
4. Both live in ~/.claude/skills and ~/.codex/skills on each machine.

See alsoInstalled skillsWhat the Maestro is