Start here

How to work with Firekeeper

Keep Firekeeper beside your agent terminals. Use it to decide where to look next, then do the work in the agent itself.

Watch several agents at once

Start your agents as usual, in separate tabs, windows, or multiplexer panes. Open another terminal and run firekeeper. Leave it on Processes while they work.

The list refreshes every two seconds. Each row represents a runtime and its child processes, not necessarily a single conversation. A +N next to the session ID means the runtime has more sessions.

Select a row with Up / Down or j / k. The bottom panel shows session metadata and the process tree. If your terminal is too small for that panel, press Enter to expand details inline.

State	How to use it
`ACTIVE`	The latest observable activity suggests work is in progress.
`WAITING`	The agent appears idle or finished with its latest turn. Check the reply before giving it another task.
`NEEDS INPUT`	The provider exposed an input or approval request. Switch to its terminal to respond.
`UNKNOWN`	Firekeeper cannot infer a state from the available data. Check the original terminal.

These are hints from provider events, not guaranteed ground truth. Not every provider exposes every state: Kimi matches are shown as active, and Gemini and Cursor never show needs-input. See provider-specific behavior.

Read the latest reply without switching away

On Processes, select a runtime and press c. The chat view shows the matched session's prompts and assistant replies, read-only. It leaves out tool calls, tool results, and injected harness context.

New messages appear on the two-second refresh while you follow the bottom of the conversation. Scroll up to read earlier messages; press G to return to the latest. Press Esc, c, or q to return to the view you came from.

The view keeps the latest 1,000 messages. OpenCode replies appear after they finish. To reply, approve a tool call, or inspect full tool output, use the agent's own terminal.

Go where your attention is needed

Back on Processes, press s to focus the selected runtime's terminal.

macOS: Ghostty 1.3+, Terminal.app, and iTerm2 are supported. Allow Automation access when macOS asks. Ghostty versions without TTY matching use a best-effort working-directory match, which can be ambiguous when several panes share a directory.
Windows: Firekeeper raises the hosting window. It cannot pick a tab inside Windows Terminal; choose the tab yourself.
Linux: terminal switching is not supported. Use your terminal or multiplexer controls.

Firekeeper also attempts to focus a matching Herdr pane on macOS before raising the terminal. Herdr is optional; Firekeeper does not create or manage its sessions.

Check usage between tasks

Press Tab to open Overview for provider totals and available limits. Tab again to Usage for model breakdowns and historical sessions. Use Left / Right to switch providers there.

These views answer different questions from Processes: a session can disappear from the live list when its runtime exits but remain in local usage history. Read Understand usage before treating token totals as a quota or bill.

Work on another machine

Firekeeper discovers processes on the machine where it runs. If your agents run on a remote host, install Firekeeper on that host and run it inside your usual SSH session:

ssh you@workbox
firekeeper

This monitors that host, not your laptop and remote host together. Terminal switching does not focus a local terminal through SSH. Firekeeper is not a multiplexer: it does not keep agents alive when SSH disconnects. Use your existing session-management workflow for that.

Close the dashboard, leave the work running

Press q from a main view to quit, or Ctrl+C from anywhere. Only Firekeeper exits. Run firekeeper again to rediscover the agents still running.