Skip to content
brnrdbrnrd

Troubleshooting

Is the daemon running?

Section titled “Is the daemon running?”
Terminal window
brnrd daemon status
brnrd daemon logs --no-follow

Drop --no-follow to keep following the service log. Use -n 200 to change the number of existing lines shown first.

For setup and development, run it in the foreground:

Terminal window
brnrd up --foreground

Is the gate configured?

Section titled “Is the gate configured?”
Terminal window
brnrd gate list
brnrd account status

account status is useful for managed setups; gate list shows gate state for the current repo.

Can brnrd see a Runner?

Section titled “Can brnrd see a Runner?”
Terminal window
brnrd runners list
brnrd runners list --all

Authenticate the selected Claude Code or Codex CLI outside brnrd, then retry.

A repo card reads “not initialised” or “init state unknown”

Section titled “A repo card reads “not initialised” or “init state unknown””

Two different facts wear these labels on /repos:

  • “not initialised” — a daemon measured the checkout and found AGENTS.md or the knowledge base missing. The advice on the card is the fix: run brnrd in that checkout.
  • “init state unknown” — no daemon has reported for this repository yet. Running brnrd in the checkout will not change this line, because nothing is watching that tree. Check brnrd daemon status in the checkout the daemon runs from, and confirm the repository is registered with brnrd account add <path> — a machine’s one daemon serves every repository it has been told about, and reports each one separately.

If the second line persists after the daemon restarts, the daemon predates per-repository reporting — update it (npm install -g brnrd).

A run died and the error mentions sleep

Section titled “A run died and the error mentions sleep”

If a run comes back with something like “your computer went to sleep mid-response”, take it literally. The agent CLI is reporting that its own process was suspended, and it is usually right.

On macOS, pmset -g log | grep -E "Sleep|DarkWake" shows the transitions with timestamps — line up a dead run’s start and end against them. A machine set to idle-sleep will wake briefly every fifteen minutes or so for maintenance, and a daemon that starts a run inside one of those windows gets about forty-five seconds before the machine sleeps on top of it. The symptom looks like an unstable agent or a flaky network; the cause is one setting.

The fix is in Prerequisites:

Terminal window
sudo pmset -a sleep 0 disksleep 0

While the machine is asleep, its daemon publishes no heartbeat, so the chat bot may also tell you no daemon is online and suggest re-pairing. Do not re-pair — queued messages drain by themselves as soon as the machine is awake again.

Update

Section titled “Update”

There is no brnrd update command. Use the installer that owns the tool:

Terminal window
npm update -g brnrd
# or: uv tool upgrade brnrd
# or: pipx upgrade brnrd

Running through npx? npx brnrd@latest <command> picks up the new version; the launcher installs whatever version you pin.

brnrd: command not found

Section titled “brnrd: command not found”

npx brnrd … runs brnrd without adding anything to your PATH, so it leaves no brnrd command behind. Either keep prefixing (npx brnrd up) or install it for real:

Terminal window
npm install -g brnrd

Both use the same durable environment under ~/.local/share/brnrd — installing after having used npx costs nothing and reuses what is already there.

Stop or uninstall the service

Section titled “Stop or uninstall the service”
Terminal window
brnrd daemon down
brnrd daemon uninstall

On Linux, uninstall may ask whether to disable systemd linger if brnrd enabled it earlier. The command has explicit --yes-disable-linger and --no-disable-linger choices for non-interactive use.

If the problem persists, report the command, output, operating system, and brnrd --version at hugimuni-labs/brnrd/issues.