ai-coach

ai-coach is a local-first skill set for people who use AI coding agents and want to get better at it.

It is not a transcript browser, dashboard, prompt optimizer, or workflow framework. The main path is simple: an agent invokes a skill, the scripts collect recent local sessions, and the agent coaches from evidence instead of vibes.

Use it when your AI sessions keep going sideways: vague prompts, scope churn, weak verification, false closure, overloaded instructions, or too much manual context-setting every time.

What ships

• npm package/bin: ai-coach with awc alias, Node 24+
• public skill family: coach:*
• shipped skills:
  • coach:analyze: diagnose recent AI coding sessions from deterministic evidence
  • coach:own: challenge the user to understand and own project decisions
• generated outputs: .ai-coach/sessions/, .ai-coach/evidence/, and .ai-coach/reports/
• default deterministic substrate: collect-sessions
• optional structured substrate: build-evidence
• agent layer: reads deterministic evidence, then gives a grounded coaching narrative

v0 makes equal invocation claims where installed harnesses can discover the skill. It does not claim equal diagnostic parity across every adapter. v1 needs fixture-backed adapter parity for Codex, Claude Code, Copilot, and OpenCode before it can claim equal evidence-backed diagnosis.

Try it

Collect a metadata-only session index:

npx ai-coach collect-sessions --json --tool all --days 14 --out .ai-coach/sessions/index.json

Optionally build a structured evidence bundle:

npx ai-coach build-evidence --json --tool codex --since 2026-04-16 --out .ai-coach/evidence/latest.json

Preview a project install:

npx ai-coach install --dry-run

Install coach:analyze into the default project targets:

npx ai-coach install --yes

Discover and install other skills:

npx ai-coach list
npx ai-coach info coach:own
npx ai-coach add coach:own --yes
npx ai-coach status coach:own

Search the curated harness corpus:

node src/skills/coach-analyze/scripts/search-harness-kb.mjs --query "completion needs proof" --dimension closure_integrity --json

From this repo, use node bin/ai-coach.mjs ... while developing.

Rules

• Always ask before reading local session logs.
• Session logs may contain prompts, code, file paths, and tool output.
• The collector owns session-file discovery and writes metadata only by default.
• Structured mode owns parsing, recurrence, evidence spans, candidate patterns, install state, and validation.
• The agent owns judgment, prioritization, teaching, and patch-ready advice.
• Structured findings must bind to candidate_pattern_ids.
• Structured recommendations must cite harness knowledge with knowledge_citations.
• Diagnosis is read-only. After user approval, the same agent may edit approved docs, skills, checklists, or plan docs.

Important paths

• src/core/contracts.ts: machine-readable evidence and report contract
• src/core/session-collector.ts: metadata-only local session discovery
• src/cli/main.ts: CLI entrypoint
• src/skills/coach-analyze/: canonical public analysis skill package
• src/skills/coach-own/: canonical public ownership skill package
• docs/prompts/ownership-decision-coach.md: reusable ownership coaching prompt
• docs/protocols/research-side-ideas.md: side-idea capture protocol
• docs/versions/v0.md: v0 boundary
• docs/versions/v1.md: v1 boundary