Docs

Dashbar works as soon as you open it: it reads what your agents already write on your Mac. This page covers the parts you set up yourself: the dashbar command for status bars and scripts, and the integrations in Settings that change another tool’s settings, what each one saves and how Remove puts things back.

The dashbar command

Dashbar comes with dashbar, a small command that prints what Dashbar knows, for tmux status bars, shell prompts and scripts. It reads a status file the running app keeps up to date and never reads agent logs itself, so it costs nothing, and Dashbar has to be running.

Install it

Homebrew links it for you. With the DMG, link it yourself, or copy the same command from Settings, under Integrations, Command-line tool:

sudo mkdir -p /usr/local/bin && sudo ln -sf /Applications/Dashbar.app/Contents/Helpers/dashbar /usr/local/bin/dashbar

Commands

  • dashbar or dashbar status: agents that need you, agents working and idle, every plan limit (the one closest to running out first, with its pace), today’s tokens and dev servers.
  • dashbar line: one line for a status bar or prompt. Add --ascii where ⚠ and · don’t draw. An arrow (↑, or (!) with --ascii) after a limit means it’s on course to run out.
  • dashbar status --json: the same status as JSON, with each limit’s pace worked out when you ask, and for weekly limits today’s share (todayShare) and what today has used (usedToday).
  • --local reads a local build (Dashbar Local) instead of the release. Without it, the release is read if it’s running, otherwise the local build.
  • dashbar --help and dashbar --version.
$ dashbar
Needs you
  billing-api  Claude · needs permission · 32s
Working
  storefront-web  Claude · 4m · 3 subagents
Idle
  docs-site  Claude · 1h 35m
Plan limits
  Claude 5-hour  55% · resets in 2h 11m
  Claude Weekly  38% · resets Thu 06:02
  Codex Weekly   34% · resets Thu 20:26
Today
  Claude 152.7M tokens · Codex 9.5M tokens
Servers
  storefront-web  :3000 node

$ dashbar line
⚠ 1 needs you · 1 working · Claude 5h 55%

Exit status

If Dashbar isn’t running, dashbar prints nothing on standard output, says why on standard error and exits non-zero, so a status bar shows nothing rather than old figures.

  • 0: printed the current status.
  • 2: Dashbar hasn’t saved a status yet. Open Dashbar 0.7.1 or later.
  • 3: Dashbar isn’t running.
  • 4: the status file can’t be read.
  • 64: an unknown command or option.

In tmux

In ~/.tmux.conf. tmux reruns it every status-interval seconds.

set -g status-right '#(dashbar line --ascii)'
set -g status-interval 10

In your zsh prompt

In ~/.zshrc:

setopt prompt_subst
RPROMPT='$(dashbar line 2>/dev/null)'

In Starship

In ~/.config/starship.toml:

[custom.dashbar]
command = "dashbar line"
when = "command -v dashbar"
format = "[$output]($style) "

In Claude Code’s status line

dashbar line works as Claude Code’s status line command too:

"statusLine": {"type": "command", "command": "dashbar line"}

If Dashbar’s plan limits bridge is already in your status line, press Remove in Settings, under Integrations, set the status line to dashbar line, then press Add to Status Line again. The bridge runs your status line after saving the limits, so both work.

For your agents

Agents that can run commands can check dashbar status --json themselves: your plan limits before heavy or parallel work, dev servers already running before starting another, and other agents working in the same folder. The dashbar-status skill tells them when to check and what to do with what they find. It only reads. Add it with the skills command, which asks which of your agents to add it to:

npx skills add stevenmckinnon/dashbar --skill dashbar-status

Or put the file in your agent’s skills folder yourself, such as ~/.claude/skills/dashbar-status/ for Claude Code.

The status file

The command reads ~/Library/Caches/Dashbar/CLI/status.json, readable only by you. It holds each session’s tool, state, workspace folder and how long it’s been in that state, plan percentages and reset times, today’s token counts and dev server ports. Never prompts, session titles, session ids, permission request details or sign-ins. Dashbar rewrites it only when something in it changes, at most every 3 seconds. Servers are as of the last time Dashbar read ports, which it does while its panel or window is open, and dashbar leaves out any that have stopped since.

Integrations

Everything here is off until you press Add in Settings, under Integrations. Each one changes a single setting or adds a single file of the other tool’s, and Remove takes out only what Dashbar added. None of them sends anything, and none answers anything for you.

Claude plan limits

Claude Code passes your 5-hour and weekly usage to its status line after each reply, on Pro, Max and Ultra plans. Add to Status Line points that status line at a small script that saves the usage, then runs the status line you had before, with the same input, so it looks the same.

  • Changes: the statusLine key in ~/.claude/settings.json (or $CLAUDE_CONFIG_DIR/settings.json), after a backup in ~/Library/Application Support/Dashbar/Backups.
  • Script: ~/Library/Application Support/Dashbar/claude-statusline-bridge.sh.
  • Saves: only the rate_limits part and the time, to ~/Library/Caches/Dashbar/claude-statusline.json. Never prompts, paths, session ids or tokens.
  • Remove: puts your previous status line back exactly.

The reading is as fresh as your last Claude Code reply, and Dashbar says how old it is.

The older, experimental way

Off by default, under Experimental in Integrations. Dashbar reads Claude Code’s sign-in from the Keychain with macOS’s security tool, as Claude Code does, and makes the same read-only request to api.anthropic.com as Claude Code’s /usage, at most every 5 minutes. It never refreshes or stores the sign-in. With both on, Dashbar shows the newer reading and doesn’t ask while the status line’s is current. The status line way is recommended: it sends nothing.

Answering permission prompts

When Claude Code is about to ask you to allow a tool, Dashbar shows what it wants to do (the command, file or address) under that session, in the window, on the island and on the notification, with Allow once and Deny. Add to Claude Code turns it on.

  • Changes: adds one `PermissionRequest` hook to ~/.claude/settings.json, after a backup, keeping any hooks you have.
  • Script: ~/Library/Application Support/Dashbar/claude-permission-bridge.sh. It leaves the request in ~/Library/Application Support/Dashbar/Permissions, readable only by you, with file contents and edits left out, and waits up to 5 minutes (adjustable) for your answer.
  • Never answers by itself. If you don’t answer, Dashbar isn’t running or anything goes wrong, it prints nothing and the terminal prompt is the one that counts. Claude Code keeps its own prompt up the whole time, so you can answer in either place.
  • Allow once adds nothing to your permission rules. Deny tells Claude you said no. Open session hands the prompt back to the terminal.
  • Remove: takes out only Dashbar’s hook.

Dashbar can only answer prompts Claude Code would show you anyway. With more than one account, Integrations lists each one, and Add puts the hook in that account’s own settings.

Antigravity CLI

For Antigravity’s 5-hour and weekly limits per model group, its usage and its sessions, Add to Status Line under Antigravity CLI points its status line at a small script, which then runs your own status line as before.

  • Changes: the statusLine key in ~/.gemini/antigravity-cli/settings.json, after a backup.
  • Saves: the plan quota and tier, and each session’s folder, model, token totals, estimated cost and state, to ~/Library/Caches/Dashbar/antigravity-*. Never your email, conversation titles or transcripts.
  • Remove: puts your previous status line back exactly.

The Antigravity app and Gemini CLI need nothing added: Dashbar reads them as they are.

OpenCode

Dashbar shows OpenCode’s sessions and usage from its database without any setup. To see when a session is waiting for you, Add to OpenCode adds a plugin.

  • Adds: one file, dashbar.js, in ~/.config/opencode/plugins/.
  • Saves: only each session’s id, folder, state (working, idle or waiting for you) and time, to ~/Library/Caches/Dashbar/opencode-sessions/. Never prompts, tool input or titles.
  • It never answers a permission.
  • Remove: deletes the file, and only if Dashbar wrote it.

GitHub Copilot

Dashbar shows Copilot’s sessions, in the terminal and as VS Code’s agent, and their usage without any setup. To see a session that needs you the moment it asks, Add to Copilot adds a hook, using Copilot’s own hooks.

  • Adds: one file, dashbar.json, in ~/.copilot/hooks/ ($COPILOT_HOME/hooks/ if set).
  • Saves: only each session’s id, folder, state and time, to ~/Library/Caches/Dashbar/copilot-sessions/. Never prompts, tool arguments or results.
  • It never answers a permission.
  • Remove: deletes the file, and only if every command in it is Dashbar’s.

More than one account

If you run Claude Code with `CLAUDE_CONFIG_DIR` (say ~/.claude-work beside ~/.claude) or Codex with CODEX_HOME, add each folder in Settings, under Accounts. Dashbar suggests ~/.claude-* and ~/.codex-* folders with logs, looking only at the top of your home folder.

It reads every account’s sessions and usage and names them by account once there’s more than one. Each Claude account has its own Add to Status Line in Integrations, so its plan limits come from its own status line.

Hiding a tool

Every tool other than Claude Code has a Show in Dashbar switch at the top of its section in Integrations (Gemini CLI and Antigravity share one). Off hides it everywhere: workspaces, Usage, History, limits, notifications, the island, the menu bar, widgets and the dashbar command. Dashbar stops reading its files at all. Anything you added to it stays installed, and switching it back on brings everything back.

Uninstalling cleanly

If you added Dashbar to Claude Code’s or the Antigravity CLI’s status line, added it to OpenCode or GitHub Copilot, or turned on permission prompts, press Remove for each in Settings, under Integrations, first, so their settings go back to how they were. Then quit Dashbar and drag it to the Trash. With Homebrew, run brew uninstall --cask dashbar, and add --zap to remove its settings, data and caches too.

What Dashbar reads and keeps on your Mac, folder by folder, is in the privacy policy. The source is on GitHub.