terma doctor: verify your setup end to end

Run terma doctor after terma setup, after an update, or whenever sessions or trailers are not showing up. It writes nothing.

Usage

terma doctor

Run it inside the repository you are asking about. Outside a repository, the repository checks are skipped. Doctor opens with what this machine collects and what the repository has in progress (the active session, uncommitted agent edits). It then runs each check, reports it as it goes, and ends with the steps that remain. It exits with a non-zero status when any check fails, so you can use it in scripts.

Checks

Each check reports ok, warn (works, but only in part), FAIL, or skip (did not apply here, which is not the same as passing).

Check	What it verifies
terma on PATH	The `terma` your hooks run is the build you are running
signed in	A working sign-in exists for this machine: your account, or the team server key it was set up with
repository collected	Your team’s policy collects this repository, and which `origin` terma sees
commit hooks in effect	Commit stamping is wired in this repository’s `.git/hooks`, or why it is not (for example, husky v9 sets its own hooks path)
machine-wide hooks run	Each agent’s machine-wide hooks are in place
agent exporting to Terma	Each agent you use sends its telemetry through the local relay
Claude Code status line	The status line is wrapped, so your plan’s usage windows are captured
event spool	The local queue accepts writes, and how much is waiting
backend receives events	What is queued is delivered to Terma

Almost every fix is terma setup again. When a fix is something else, such as a PATH change or a repository your team should add to its policy, doctor says exactly what to do.

Example output

  ok    terma on PATH             /Users/ada/.local/bin/terma
  ok    signed in                 ada@example.com (Acme)
  warn  repository collected      github.com/acme/billing is not in the team's repositories, so nothing here is recorded
                                  → ask your team to add github.com/acme/billing in Terma (Team settings → Data collection)
  skip  commit hooks in effect    this repository is not collected, so no hook is installed here
  ok    machine-wide hooks run    Claude Code & Desktop, Codex TUI & Desktop
  ok    agent exporting to Terma  through the local relay on 127.0.0.1:43180 (running); it forwards the sessions your team's policy collects
  ok    Claude Code status line   capturing plan usage (terma's default line)
  ok    event spool               0 queued, spool writable
  ok    backend receives events   nothing queued at verification time (hooks may already have flushed)

Here the fix is not a command: an organization admin adds the repository to the team’s policy in Terma (Team settings → Data collection), and the next session in it is collected.

Overview

Commands

terma doctor: verify your setup end to end

Usage

Checks

Example output

​Usage

​Checks

​Example output

Usage

Checks

Example output