Skip to content

Core features

Terminals & agents

A terminal panel is a real terminal: xterm.js on the front, a native PTY (node-pty) on the back, rendered through WebGL. Anything that runs in your shell runs here.

Opening one

⌘T opens a terminal at the centre of the view. It starts in the workspace folder, with your shell and your environment — the same PATH, the same profile, the same tools.

# Nothing special is required. Your agent CLI, as you already run it:
claude
codex

Splits

In TerminalMap, ⌘D splits the focused terminal to the right and ⇧⌘D splits it down. The new pane starts in the folder the old one is in now, even after a cd. ⇧⌘↩ zooms one split to the whole area and back, and ⌥⌘← ⌥⌘→ ⌥⌘↑ ⌥⌘↓ move between them.

Clicking the ✕ of a terminal, a split or a group closes it right away, with no confirmation, whatever is running in it.

Agents are just CLIs

Catenary does not bundle a model and does not proxy your prompts. The agent you run is the CLI you installed, authenticated the way you already authenticate it. What the canvas adds is a name, a position and wires to its peers.

Provider credentials for the built-in agent panel are stored globally under userData/pi-agent/auth.json and mirrored into each workspace's .cate/pi-agent/.

Reading state at a glance

A panel tells you what it is doing without being opened:

  • the tab shows the agent's name and, on a task panel, its branch;
  • a working agent shimmers its status line;
  • a finished command and an agent waiting for input each get their own activity state on the node.

Links in the terminal

Hold ⌘ and click a path:line:col an agent printed, and the file opens in the editor at that line and column.

Web links work the same way. By default they open in Catenary's own browser; Settings, Browser, Open terminal links can send them to your system browser instead, or keep only localhost inside. Hold ⇧⌘ and click to open a link in the other place, and right-clicking one offers Open in Catenary and Open in External Browser.

After a restart

Reopen Catenary and every terminal comes back with what it was showing, followed by a dim --- restored session --- line and a fresh shell.

When Catenary knows which conversation an agent was in, it resumes it on its own: claude --resume <id>, codex resume <id> and the equivalent for the other agents it knows. When it only knows which agent the terminal runs, it starts a new conversation with it.

Built to hold up

A command that floods the terminal with output does not freeze it: Catenary pauses the process while the terminal catches up. If the graphics card drops the WebGL context, the terminal switches to a slower renderer and goes back to WebGL as soon as it can.

Talking to peers

A terminal wired to another can address it directly through the catenary CLI, available inside every terminal panel:

catenary list                                   # peers, boards and connected files
catenary ask "Codex 1" "Take the N+1 in the dashboard query"
catenary check "Codex 1"                        # last lines, without interrupting it
catenary check "Codex 1" 60                     # a custom line count

ask delivers a prompt. check reads without interrupting — use it while a peer is mid-turn instead of sending the same prompt twice.

By default, agents in the same session reach each other without a wire and without a confirmation card. catenary ask --no-wait "Codex 1" "…" hands the work off and returns at once, instead of waiting for the answer. See connection wires for agents in other sessions.

Shared boards

Boards are persistent notes several agents can read and append to. A terminal sees a board only when a wire connects them (see boards):

catenary board list
catenary board read "Spec"
catenary board append "Spec" "Refactored /auth; tokens.ts is next"

They are the right place for a decision that has to outlive one agent's context window.

Back to home