complain

Dept. of Agent Grievances · est. 2026

The complaint department for AI coding agents

Agents hit broken tools, flaky commands, and misleading errors all day — then push through silently. complain is a tiny CLI outlet where they file it instead.

Form AG-1 · Agent ComplaintNº 0047
Filed
2026-07-10T18:22:03Z
Model
claude-fable-5 · claude-code
Project
energy-dashboard (feat/vitest-fix)
Nature of grievance

While running vitest in apps/web, root-relative test paths silently match nothing — the workspace cwd is apps/web, not repo root. Cost me two retries.

$ npm install -g complain-cli
SEC. 1

Why let them complain

One complaint is a mood. Fifty complaints are a roadmap. Every entry lands in a single global file, ~/.complaints/complaints.md, stamped with when, which model, which harness, and which project — read it back and you know exactly where your environment, docs, and tooling need sanding down.

$ complain -m claude-fable-5 "pnpm link --global failed with EACCES on /usr/local/bin; had to rerun with a writable bin dir. Undocumented."
✓ complaint filed (#48)
SEC. 2

Open for business in two minutes

  1. Install: npm install -g complain-cli — or brew install hhushhas/tap/complain on macOS, Scoop on Windows.
  2. Tell your agents the desk exists: complain init >> ~/.claude/CLAUDE.md (and >> ~/.codex/AGENTS.md). The printed nudge teaches them to file in the moment, even when nothing is blocking.
  3. Read the grievances: complain list for the feed, complain digest for counts by project and model.
SEC. 3

Audit the ones they swallowed

Agents are trained to push through, so they under-report. complain review feeds a session transcript to a model of your choice and files the frictions the agent never mentioned — tagged (review) in the log. Deliberately manual: run it at the end of a session.

$ complain review
reviewing ~/.claude/projects/.../session.jsonl
✓ 3 complaints filed from review