Troubleshooting
Run the doctor
align doctorchecks the installation and prints ✓ or × for each check, with a fix: line under each failure. It exits 1 when
any check fails; --json prints the same as {ok, checks: [{id, ok, label, fix}]}.
| Check | What a failure means | The fix it prints |
|---|---|---|
| Node | Node.js is older than 22.14 | install Node 22.14.0 or later |
| shim and bundle installed | the launcher in ~/.align/bin or the CLI in ~/.align/lib is missing | run align init |
| bundle matches version | the installed CLI is another version | run align init again to reinstall the bundle |
| signed in | no valid sign-in for this organisation | run align login |
| server reachable | the server did not answer | check the network or the server URL (--server) |
| clock within 2 minutes of the server | your clock is off | set the system clock to update automatically |
| repository registered and opted in | this repository is not set up or not opted in | run align init (or align on) in this repository |
When the repository is opted in, it also checks each agent: that the Claude Code, Cursor and Codex hooks point at the
launcher, the Claude Code /align command, the Cursor rule file, that recent transcripts can be read, and the git
hooks. Their fix is to run align init again in this repository. If an agent's transcript format changed, the fix
says so: upgrade the CLI to its latest version (capture continues from the hooks meanwhile). For Codex it also reports, on a best-effort basis,
whether Codex trusts the hooks (run /hooks once in Codex). With the Claude Code plugin enabled, it checks that no
hooks were left in .claude/settings.local.json next to the plugin, and offers to remove them (a backup is kept).
Then, always:
| Check | Meaning |
|---|---|
tokens in the macOS Keychain, or in ~/.align/credentials.json | where your sign-in is kept; the file must be private (chmod 600 ~/.align/credentials.json) |
| local files readable | a damaged local file: move it away and run align init again |
| spool | events waiting to upload; it fails when the oldest is a day old (run align flush to see why) |
| last upload | when events last went up (information only) |
| uploads signed in | the server refused the upload token: run align login |
Is it fast enough?
The hooks run in your agent's path, so they are kept fast.
align doctor --benchruns 200 synthetic hook calls per event in a temporary home (never your own data or server) and prints p50 and p95. It passes when p95 is under 200 ms and session start under 1.5 s.
Common situations
- Nothing is captured. Run
align status: the repository must be opted in, and each agent set up. - "connected to another organisation". The repository belongs to another organisation: ask one of its admins to invite you, or join from the link init prints if you collaborate on it on GitHub.
- The pack seems old. The server did not answer within its time limit, so the cached pack was used and your agent was told its age.
- The agent cannot confirm. That is on purpose: only you confirm, in your own terminal or the console.
Where things live on your laptop
Everything is under ~/.align: the launcher and CLI, your settings, the list of set-up
repositories, the spool of redacted events waiting to upload (events refused by the server or held back by redaction
are kept apart and never uploaded), cached packs and logs. On macOS your sign-in token is in the Keychain; elsewhere it
is in ~/.align/credentials.json with owner-only permissions. A token is only ever sent to the server that issued it.
Still stuck? Write to support@bharatreachdsp.com.