Guide

Using The Lobby

Install it, find your way around, and fix the common snags. For the picture tour, see the home page.

Install

You need Orca 1.4.248 or newer (that is the engines.orca range in the plugin's manifest).

orca plugin install Lilykos/orca-the-lobby
  1. Run the command above. Because the plugin runs code, Orca stops before writing anything, lists what it would be granted along with the publisher and repository, and prints the exact command to re-run with --approve <fingerprint>.
  2. Read the capabilities (what each is for), then re-run that command to approve. The approval is bound to this plugin, version, files and access.
  3. Open The Lobby from Orca's right sidebar. The status bar item Lobby also counts working agents and agents that need you.

The plugin is plain TypeScript and HTML that Orca loads directly; there is no build step.

Update with orca plugin update and remove with orca plugin uninstall. The plugin keeps its data only in Orca's per-plugin storage.

Using the panel

Office

  • Click a room sign to open or close its agent area. Rooms follow the order of Orca's sidebar. Point at a room and press ↑ or ↓ to set your own order, shared with Activity; Settings has Use the sidebar order again.
  • The list leads with the conversation title, an explicitly labelled prompt excerpt, or “Task not reported”, and shows the provider beside a friendly name. Activity keeps the original workspace and conversation title.
  • Up to four finished agents stand around the coffee machine; fewer in a narrow room.
  • Under each room is today's token count for that workspace.

Activity

  • Pan wide charts with a trackpad swipe, Shift + wheel, ← →, or by dragging the background. Reset view recentres.
  • All / Needs attention switches the highlighting. Your selection, scroll position and collapsed branches survive the switch.
  • A child without an exact matching agent id opens a drawer with its reported state, operation and description, and no invented chat or workspace link. An agent whose reported parent is not in the roster stays unlinked with a short note; no parent is guessed.

The drawer

  • Go to agent switches to the agent's terminal. For an Orca chat session it opens the workspace and says that it did.
  • The instruction box (terminal agents only, not for finished agents) sends your text to that terminal. If another agent resolves to the same terminal, typing is refused so it cannot reach the wrong one. Instructions can be up to 8,000 characters.
  • Compact conversation asks for confirmation, then types /compact. Only for Claude Code, where it was tried.
  • A draft and the last result are dropped when the drawer closes.

Shortcuts

KeysWhat happens
Mod+Alt+↑Previous agent: go to the previous agent, as Go to agent does. Also in the command palette.
Mod+Alt+↓Next agent. Order: agents that need you, then working, then the rest, in a steady order. It steps on from the agent in the drawer, or the last one it went to.
EscClose the drawer; focus returns to where you were.
EnterSend the instruction.
Shift+EnterNew line in the instruction box.
← →Pan a focused Activity chart.
Shift + wheelPan an Activity chart sideways.
Mod is ⌘ on macOS and Ctrl elsewhere.

Settings

SettingWhat it does
Notify me when an agent needs meDesktop notification when an agent becomes blocked.
Notify me when a long turn endsDesktop notification when a long working turn finishes.
Animate the officeBubbles pop and bob and the office moves. Off, or if your system asks for reduced motion, everything still shows without the movement.
Notify me when an agent seems stuckOff, or after 10, 20, 30 or 60 minutes (20 by default). One notification per quiet spell, for an agent working with no status, tool call or roster update, or still needing you.
PaletteOrca default (follows the app theme), Catppuccin Mocha / Latte, Dracula, GitHub Dark / Light. Changes surfaces, text, accents and room art; state colours keep their meaning.
List / GridOn Office and Activity. Two projects per line at 400px or wider; saved with your settings.
Clear local activity historyEmpties the local observation journal. Does not change Orca's unread flags.

Palette colours are adapted from the official Catppuccin palette, the Dracula specification and GitHub Primer primitives.

What it reads, exactly

No telemetry. The plugin makes no direct network requests. Orca uses its existing connections to list agents on your paired servers.

Roster and events (from Orca)

The worker uses orca worktree ps --json for the cross-worktree roster: workspace and project names, state, prompt, current operation, helpers and linked items. It also asks Orca's agents.list for the focused workspace when focus changes, and listens for status changes and tool calls. It polls every three seconds while an agent is working and every twenty seconds when idle.

Paired servers have separate rooms labeled with the server name; local rooms say local. Unreachable paired servers disappear until they reconnect. Go to agent can navigate to a remote terminal or worktree, but remote file/log details, sending instructions and Compact are unavailable.

Tokens today (from local logs)

Claude Code session files under ~/.claude/projects/<workspace>/ and Codex session files under ~/.codex/sessions/ (matched by their recorded working folder). Only usage numbers and model ids are read. Each file is read once, then only what is appended. Counts are per workspace and project for the local day.

Per-agent context (an exact id chain)

Never from titles, times or folders:

  1. A chat agent's pane key is structured-agent-session-<Orca session id>:<leaf>.
  2. Orca's own session store (agent-session-domain.db on Orca 1.4.261+, or agent-session-journal.db on older versions), read-only through the sqlite3 macOS ships, records that session's Claude Code session id or Codex thread id. Only the provider and the session id are selected, never prompts or messages.
  3. That id is in the log's file name: ~/.claude/projects/*/<id>.jsonl or ~/.codex/sessions/YYYY/MM/DD/rollout-…-<id>.jsonl.

The drawer then shows the latest request's tokens (cache included), the compactions the log records, and the session's tokens today. For Codex that is the input side of the last request; output is left out. The percentage uses the window the log states: Codex does, Claude Code does not. Tokens today count only the agent's current provider session; an earlier one before a resume or /clear is not added.

The store is an Orca internal, not a documented API. If a future Orca changes it, these lines simply disappear. The read runs in the background and never holds up a panel update or a notification; the store is asked at most every 30 seconds per session and not again for a minute after a failure.

Other

  • Claude transcripts can supplement task lists and changed-file names, matched by title and prompt similarity. Transcript model names are never attributed to an agent.
  • Git: git diff --shortstat HEAD for uncommitted changes.
  • Local journal: observed activity for up to 24 hours, oldest dropped first to fit Orca's 256 KiB storage limit, never sent to the panel. It may hold clipped result or tool details; it does not store prompts.
  • No money estimate is ever made from tokens.

FAQ

Is it safe? Does it send my code or prompts anywhere?

No. It has no direct network code. It reads local files and runs the Orca CLI and Git on your machine. Orca uses its existing paired-server connections for remote roster and navigation requests. Prompts are not stored in its journal. The source is public.

Why can't I type into a chat agent?

Orca has no way for plugins to pick or type into a chat tab. The instruction box and Compact work for agents running in a terminal. For chat agents, Go to agent opens their workspace.

Can I approve or deny a blocked agent's request from the panel?

No. Orca does not report what a blocked agent is asking, and plugins have no approve / deny controls. The panel says Needs you and takes you to the agent.

Why does a Claude agent show tokens but no context percentage?

Claude Code's logs do not state the context window, and The Lobby will not guess one. Codex logs do, so Codex agents show a percentage.

The token total under a room differs from the number in the drawer.

The room total is per workspace for the whole local day. The drawer figure is for one agent's current provider session, so earlier sessions before a resume or /clear are not included.

Does it show which model an agent uses?

No. Orca's supported agent metadata reports the provider kind (Claude, Codex, Pi, …) but not the selected model, so the label next to a name is the provider.

Where do finished agents go?

They stand around the coffee machine (up to four drawn) and stay in the roster and Activity. They get a Done · new tag until you have seen the result.

What are the colours?

Green is working, orange is Needs you, amber is waiting, red is failure, grey is done and blue is an unread result. Status pills appear on individual agents; there are no aggregate status chips.

Does it work on Windows or Linux?

The release is validated on macOS. Windows CLI discovery is improved in 1.2.0; independent Windows/Linux runtime checks remain outstanding. Per-agent context currently needs the macOS session-store path and sqlite3.

How do I get rid of the history it keeps?

Settings, then Clear local activity history. It also drops itself after 24 hours.

Troubleshooting

The panel says “No agents to show yet.”

Start an agent in an Orca workspace; the roster refreshes every three seconds while something is working, every twenty seconds when idle. If agents are running and nothing shows, the Orca CLI may be unavailable to the plugin: it then falls back to status and tool-call events and the focused workspace's agent list, so only agents Orca has told it about appear, chat tool calls are unavailable, and finished agents linger for four hours.

An agent has no Context line.

It needs the exact id chain: a chat session (pane key structured-agent-session-…), Claude Code or Codex, on macOS, with sqlite3 available and Orca's session store readable. Agents in a plain terminal tab and other providers have no verified link and show nothing. After a failure (no sqlite3, a locked or missing database), or if the log is not found, it retries only once a minute.

Claude agents show no percentage.

Expected: Claude Code logs do not state a context window. You still get tokens.

Go to agent only opens the workspace.

That is what it does for Orca chat sessions, which have no terminal for a plugin to bring forward. The panel tells you when it happens.

The instruction box or Compact button is missing.

Controls that do not apply are left out. The box needs a terminal agent that is not finished, with its terminal found by the id or pane key Orca reports, and the terminal:send capability granted. If two agents resolve to one terminal, typing is refused. Compact is Claude Code only.

I got no stuck or needs-you notifications.

Check Settings: the switches and the stuck time (Off disables the alert), and that Orca may show notifications from the plugin. You get one stuck notification per quiet spell, not repeats.

Tool calls or file changes look incomplete.

Short chat tool calls can fall between polls; Orca does not yet report terminal tool calls on SSH or WSL hosts; and the changed-files count ignores new untracked files.

Everything is still, nothing moves.

Check Animate the office and your system's reduced-motion setting. The window still follows local time at period boundaries.

Still stuck? Open an issue with your Orca version and what the panel shows. Please leave out real prompts, paths and project names.

Develop

orca plugin test .
npx --yes --package typescript tsc --noEmit
orca plugin check .
orca plugin dev watch .    # load this checkout and reload as files change

Orca transpiles the TypeScript when it loads the plugin. panel/banner.ts holds the fixed pixel title and mascot, so no runtime font or image assets are needed. The pixel title and orca on this site are generated from that file by scripts/site/pixel-art.py.