coach

README

coach

coach is an experimental AI coach for people (and agents) who write software. The thing you can use today is a local CLI: it reads a Git checkout, analyzes Go / TypeScript / TSX source, and prints advisory structural signals — code smells, design issues, and architecture-policy findings you opted into.

It does not execute your code, contact GitHub, or call a model unless you stand up the separate local platform preview. Coach stays on the 0.x line on purpose.

Quick start

Install mise if you do not already have it, then install the coach CLI from GitHub Releases with mise's GitHub backend:

curl https://mise.run | sh
~/.local/bin/mise use -g github:lousy-agents/coach

Hook mise into your current shell so coach is on PATH (pick the one you use):

echo 'eval "$(~/.local/bin/mise activate bash)"' >> ~/.bashrc && eval "$(~/.local/bin/mise activate bash)"
# echo 'eval "$(~/.local/bin/mise activate zsh)"' >> ~/.zshrc && eval "$(~/.local/bin/mise activate zsh)"
# ~/.local/bin/mise activate fish | source

Pin a release if you want a fixed binary (latest published tag is v0.5.0):

mise use -g github:lousy-agents/coach@v0.5.0

From any Git worktree:

coach codesignal --base main          # diff HEAD against main
coach codesignal --baseline           # every tracked Go/TS/TSX file at HEAD
coach codesignal --base main --format json

--base can be any ref Git can resolve (branch, tag, or SHA). Text output is the default. A completed analysis exits 0 even when it found signals — this is advisory, not a gate.

You need git on PATH. No Docker, no API key, no network.

One-shot without writing a mise config or activating your shell:

mise exec github:lousy-agents/coach -- coach codesignal --base main

Release archives exist for darwin_arm64, darwin_x86_64, linux_x86_64, and windows_x86_64. There is no linux_arm64 build yet.

From source instead of the release binary

This path uses the repo's mise.toml to pin the dev toolchain (Go 1.27.1, Node 24). That is not the same as installing the published coach binary.

git clone https://github.com/lousy-agents/coach.git
cd coach
mise install
mise exec -- go install ./cmd/coach

Signed archive without mise

Download the archive for your platform from Releases, verify checksums.txt with cosign, then put coach on your PATH. The exact commands live in the CLI contract.

What you should see

A short text report per signal (path, line, lifecycle, changed, evidence, why it matters, recommendation), or a quiet report if the analyzed files produced no active signals. lifecycle is introduced / existing / resolved / unknown relative to the merge-base.

• Advisory only. Coach does not judge correctness or block merges.
• Go, TypeScript, and TSX only. Other languages are skipped with an unsupported_language diagnostic.
• Static and local. It reads source bytes via git show. File-local unless you pass --project-config.
• Absence is not a clean bill of health. An empty signal set means no matched rule for the inputs that were analyzed.

Full flag, schema, and exit-status contract: CLI contract.

Preview — experimental, try it now

These commands work on the current CLI or local stack. They are under active development, may change without a 1.0 promise, and are here so you can kick the tires. Absence of findings is not compliance.

1. Project-level architecture policy

Opt into cross-file layer checks with a committed JSON config. Coach does not guess your architecture — you declare layers and forbidden import edges.

# Go: discover module/workspace roots (candidate only — review, add layers, commit)
coach codesignal --baseline --suggest-project-config

# after the file is committed at the analyzed revision
coach codesignal --base main --project-config project.json
coach codesignal --baseline --project-config project.json --project-language typescript

--project-config is read from the analyzed revision, not your dirty worktree. An uncommitted candidate is invisible to the scan. A valid config switches the report to schema_version: "2" and can emit architecture.layer_violation. For Go only, required_layer can also emit architecture.layer_bypass on a narrow handler→SQL registry.

TypeScript --project-config uses Coach's embedded analyzer and a host-resolved compiler whose own package.json version is in the supported set (7.0.2 today). Version ranges (^, ~, latest) never count. If you previously vendored Coach's analyzer under the analyzed repository, you can delete that copy. --suggest-project-config never invents layers or forbidden_imports, and it never auto-applies a config.

2. TypeScript project readiness

A guided on-ramp for first-class TypeScript project analysis (epic #280, in flight).

coach codesignal --baseline --check-project --project-language typescript
coach codesignal --baseline --suggest-project-config --project-language typescript

Run --check-project first. It is the diagnostic for compiler, Node, and policy fit, and it is read-only: it reports readiness gaps and exits 0 so you inspect the result instead of treating the process status as a gate. A scan that cannot resolve a supported compiler or host Node exits 2 with empty stdout and one stderr line naming that same invocation. The interactive authoring session writes nothing until you say so.

Coach's supported Node majors are exactly 24 and 26 — every release within either major passes the --check-project Node/runtime check with no code and no warning. Any other major is the node_unsupported readiness gap. @lousy-agents/coach-semantics declares this as engines.node: "^24 || ^26", and CI runs the real TypeScript analyzer under both Node 24 and Node 26.

Still being built — do not expect these to work yet: consented package-manager / mise compiler setup for the scanned project, Bun as a project runtime, and a packaged foreign-repository TypeScript journey.

3. Local platform, including agent judgments

The CLI above never calls a model. The local API + worker stack can, if you want a preview of deterministic findings plus agent judgments on a baseline scan.

git clone https://github.com/lousy-agents/coach.git && cd coach
mise install
mise run platform-up
mise run platform-smoke    # expect: platform-smoke: ok

Full paths (stub model, local Qwen, GitHub.com scan without cloning): Local Coach quickstart. This is a pilot, not the default install. Findings are tagged source=deterministic or source=agent; agent output cannot suppress a deterministic finding.

Working in a Claude Code cloud session? See Claude Code cloud development.

Libraries

If you want the analyzer as a library rather than the CLI:

• pkg/semantics — deterministic structural analysis of Go, TypeScript, and TSX source bytes. Quickstart.
• pkg/githubingest — optional GitHub App-authenticated single-file reader.
• @lousy-agents/coach-semantics — Node ESM bindings. Not published to npm yet; clone and build locally. JS/TS Quickstart.

go get github.com/lousy-agents/coach/pkg/semantics
go get github.com/lousy-agents/coach/pkg/githubingest

---

coach codesignal CLI Preview

The full flag, schema, exit-status, and --project-config contract now lives in docs/cli-codesignal.md.