Troubleshooting

Symptoms, causes, fixes. If you hit something not listed here, the answer is almost always in commitly-agent logs.

## login hangs forever / browser closed by accident

The poll loop has a 5-minute deadline. After that it exits with an explicit timeout message. Just re-run:

commitly-agent login

Each run uses a fresh session id; the previous one is invalidated server-side once it expires.

## act-loop won't start: stale lock file

The lock at ~/.commitly/agent.lock contains the PID of the loop that owned it. If a previous run was killed with SIGKILL or the host crashed, the lock is left behind.

$ commitly-agent status
! Stale lock file found — daemon is not running. Cleaning up.

status auto-cleans stale locks. After that, start works normally. Manual cleanup:

rm ~/.commitly/agent.lock

## daemon starts then immediately fails

Open commitly-agent logs. Three causes are common.

### 1. Missing --behavior or --yes

act-loop refuses to run in non-TTY environments without both flags, because the interactive prompts cannot run. The log will say:

Error: Non-TTY environment: --behavior <docs|refactor|ghost> is required for daemon mode.

Fix: re-run start with an explicit --behavior. --yes is added automatically by start; you don't pass it manually.

### 2. Missing Gemini key

act-loop instantiates GoogleGenAI locally and needs a key on this machine.

commitly-agent set-gemini-key AIza...
commitly-agent stop
commitly-agent start ~/code/your-repo

### 3. Stale GitHub token

Tokens get revoked. If logs shows 401 Unauthorized from the dashboard, run logout and re-login.

## observe shows a growing queue

The spool at ~/.commitly/attestations.ndjson is designed to absorb dashboard outages. If the queue keeps growing instead of draining, the dashboard is unreachable or rejecting requests.

Confirm your dashboard is reachable from this machine — a quick browser visit or curl -I against the dashboard URL is enough. Once it's back online, the next flush cycle drains the queue automatically; you don't need to restart observe.

## permission errors writing the unit file

On Linux, start writes to ~/.config/systemd/user/ with mode 0o600. If your home directory is on a filesystem that doesn't honour POSIX permissions (some cloud-mount setups), the chmod will fail. Run from a regular user account on a local filesystem.

## nothing else worked, start over

commitly-agent stop
commitly-agent logout
rm -rf ~/.commitly
commitly-agent login
commitly-agent start ~/code/your-repo --behavior docs

That clears the daemon, the keychain, the local spool, and the config dir. The dashboard side keeps your account; only the device record is orphaned, and you can revoke it from the dashboard's Devices page.

## found a bug

Open an issue on GitHub with the output of commitly-agent logs -n 200 and the command you ran. Or read the source — it's small enough to audit.