Running an agent
Claude Code, Codex and Gemini CLI run in Opsty as in any terminal. A few things are different, all aimed at what terminals usually get wrong for them.
Typing to an agent
- Shift+Enter is a new line. While a program is in front, rather than your shell, ⇧↵ sends ESC and Return, the same bytes the agents’ own terminal setup uses for a line break, instead of submitting a half-written prompt. At your shell’s prompt ⇧↵ is still Enter. ⌥↵ is a new line in programs too.
- Write a message. ⌥⌘⏎,
Shell
▸Write to the agent
, or✎ Write a message
in the line under the grid opens an ordinary Mac text box. Korean and other input methods compose there exactly as in any other app. ⏎ is a new line, ⌘⏎ sends, and a file dropped on it adds its path.Send ⌘⏎
pastes the whole text into the agent in one piece, as ⌘V would, then presses Enter. Unsent text stays as that tab’s draft. It works with any program in front. - Screenshots. With an image and no text on the clipboard, ⌘V in front of an agent sends ⌃V, which is how Claude Code takes a pasted image: the agent reads it from the clipboard itself.
- ⌥ shortcuts.
Settings
▸Advanced
▸Use ⌥ as Meta
, off by default, lets ⌥ chords reach the program (Claude Code’s ⌥P, for one); ⌥ then no longer types é or ü.
Reading what it did
- Copy as clean text.
Edit
▸Copy as clean text
(⇧⌘C), after selecting, drops the indent an agent draws in front of every line, the spaces that pad each row and blank lines at either end, and rejoins lines the terminal wrapped to fit the window. Line breaks the program wrote itself stay. - Full screen stays full. The Ledger’s marks step aside while a program uses the whole screen, as Claude Code’s interface and
vimdo. - What each turn changed. While an agent runs in a folder on your Mac, Opsty notes which files each of its turns created, changed or deleted; see the Ledger. The names feed the away panel.
- Coming back to it. The tab turns to
your turn
when the agent stops, and you can answer from the notification; see Notifications. The next morning, each Claude Code tab is offered back in its own conversation; see Starting what was running.
Two agents in one folder
When two agents are editing the same folder at once, an amber note says so, once: they may overwrite each other’s files. Make a new working folder…
opens a split with git worktree add … placed and read back, a copy of the repository on its own branch next to this one, so you can move one agent into it. It’s fine
dismisses the note.
What Opsty reads, and what it doesn’t
To recognize an agent, Opsty looks at the program running in the tab, the window title the agent sets and, for Codex, the status it sends every terminal; see How Opsty knows an agent. To answer from a notification it reads the agent’s question off the screen, as you would. To bring a Claude Code tab back to its own conversation it reads the names and dates of Claude Code’s conversation files for that folder, never their contents. Nothing else.
It installs nothing into the agents, adds no plugin or hook, and changes none of their settings. In the shells it starts, it sets TERM_PROGRAM=opsty and FORCE_HYPERLINK=1, which asks programs to print links you can open with ⌘-click. If Opsty itself was started from inside an agent’s session, it removes that session’s markers (CLAUDECODE and similar), so an agent you start in Opsty does not think it is a sub-session.
Some agents decide features by the terminal’s name: Claude Code sends its own desktop notifications only to terminals on its list, and Opsty is not on it yet. That is why Opsty’s notifications come from the title instead.