troubleshooting.md

Troubleshooting

Start With The Layer

Symptom	First check
Waybar shows nothing	agent-bar status --refresh
One provider is missing	agent-bar status --provider <id> --refresh
Waybar JSON/parser error	run the module command in a terminal
Waybar layout changed unexpectedly	inspect ~/.config/waybar/config.jsonc managed entries
Style broke after manual edits	inspect GTK CSS, not browser CSS assumptions
[agent-bar] Pollution detected in $HOME warnings	run agent-bar doctor

Runtime Checks

agent-bar status --refresh
agent-bar status --provider claude --refresh
agent-bar status --provider codex --refresh
agent-bar status --provider amp --refresh

If these fail outside Waybar, fix provider auth/runtime first. Waybar is not the first suspect.

Setup Finished But Modules Do Not Appear

Run setup again:

agent-bar setup

Then reload Waybar manually if needed:

pkill -SIGUSR2 waybar

Update Refuses To Run

agent-bar update refuses when it runs from a development checkout (a git checkout that is not ~/.agent-bar). Update a dev checkout with git directly:

git pull

For the managed ~/.agent-bar checkout (the install.sh path), agent-bar update works without extra steps. For system installs (AUR), use the package manager (paru -Syu agent-bar-bin).

$HOME Pollution

If leftover agent-bar artifacts are detected in $HOME, clean them up with:

agent-bar doctor

See Commands → doctor for flags.

Provider Auth

Claude

Claude uses Claude Code credentials from ~/.claude/.credentials.json.

Codex

Codex uses ~/.codex/auth.json, recent session rate-limit events, or the Codex app-server protocol when available.

Amp

Install Amp with the official installer:

curl -fsSL https://ampcode.com/install.sh | bash

Then run:

amp login

Reset Managed Waybar Entries

For a normal reset:

agent-bar setup

For removal:

agent-bar uninstall

For non-interactive forced cleanup:

agent-bar remove