Using Firekeeper

Troubleshooting

Start with the symptom you can see. You should not need to relaunch agents through a wrapper or enable reporting to fix the local dashboard.

My shell cannot find firekeeper

First check that the installer finished successfully. The macOS/Linux script installs to ~/.local/bin by default but does not change your shell configuration. In bash or zsh, add that directory for the current session:

export PATH="$HOME/.local/bin:$PATH"
firekeeper --version

Use your custom directory instead if you set FIREKEEPER_INSTALL_DIR. For persistent shell configuration, see the installation guide.

On Windows, the installer updates your user PATH and the terminal running it. Reopen other terminal windows to pick up that change. A manual install, or an install with PATH updates disabled, needs the installation directory added to your user PATH.

For Homebrew, follow Homebrew's shell setup instructions if brew itself is missing. For a Go install, add GOBIN (or the bin directory under go env GOPATH) to PATH.

My agent is not in Processes

1. Confirm that the agent is still running. Processes shows live runtimes, not every saved conversation. Check Usage for supported providers' historical sessions.
2. Run Firekeeper on the same machine and as the same user as the agent. Windows Firekeeper does not see agents inside WSL; run the Linux build inside WSL instead.
3. Wait for the two-second poll or press r. Check any error or metadata warning shown by the dashboard.
4. If you use a custom provider data directory, launch Firekeeper with the same environment override as the agent.

Provider formats can change. Check the supported layouts, especially if you run an older Kimi CLI or OpenCode version. Do not copy or modify provider databases to make discovery work.

The runtime has missing or wrong details

Finding a process and finding its conversation are separate steps. A runtime may be visible before Firekeeper can match metadata. Several agents of the same provider in one directory can also make directory-based matching ambiguous.

Check the session ID, directory, and the agent's own terminal before acting. Separate project worktrees can make directory-based matches less ambiguous, but are not required. On Windows, Codex matches use directory and recency because open-file discovery is unavailable.

Missing chat metadata is not repaired by enabling uploads. If the provider has not written a transcript yet, wait for a response and refresh.

Pressing s does not focus the right terminal

On macOS, use Ghostty 1.3+, Terminal.app, or iTerm2. Check System Settings > Privacy & Security > Automation if access was denied. A session without a controlling terminal cannot be selected this way.

Ghostty's first match can be ambiguous if several panes have the same working directory and its scripting API does not expose TTYs. On Windows, switching raises a window rather than a tab. Linux and SSH-to-local terminal switching are not supported. Use your terminal's controls in these cases.

Chat looks incomplete

The chat view intentionally shows prompts and replies, not the full event stream. Tool output and injected context are omitted; only the latest 1,000 messages are kept. OpenCode replies appear when complete. Press G to follow the latest messages or r to reload.

Read the original agent terminal when you need tool output, approvals, or context that Firekeeper does not display.

Usage totals or limits are missing

Live discovery and Usage have different provider coverage. Only Codex, Copilot, Kimi, and Claude have Usage pages. Token history is local and can be incomplete; it is not an authoritative billing record.

For Codex limits, confirm the Codex CLI is installed and signed in. For Claude, run firekeeper claude-limits status; if the sign-in has expired, open Claude Code to renew it. Firekeeper does not refresh credentials. Copilot plan details are best effort and can fail independently of local history.

See the data-source guide for missing cache counters, subagent undercount, and quota limitations.

Panels or columns disappeared

The dashboard hides lower-priority columns and summary panels when the terminal is small. Enlarge the window, or select a runtime and press Enter for inline details when the bottom panel is hidden. This does not mean session data was deleted.

Report a problem safely

Get the installed version:

firekeeper --version

Open an issue with the Firekeeper version, operating system, terminal application, agent CLI version, expected behavior, and a short reproduction. Include the displayed error only after checking it for private information.