Tool Teacher

Local-first inventory & early-warning system for a developer's tool park.

Your machine briefs you — not the other way around. Tool Teacher scans what you actually have installed (Homebrew, global npm, macOS Applications, and the native self-installers in ~/.local/bin that the fastest-moving AI CLIs actually use), tells you which tools you've forgotten, and turns the flood of releases into one prioritized digest — breaking changes first.

Developers whose core tools change several times a day instantly know what affects them and what their tools can now do — before a breaking change bites, and without ever reading release notes.

The five surfaces

Command	What it does
tt scan	Read-only inventory scan of all four sources; dust states; rediscovery candidates
tt digest	Prioritized AI catch-up over unseen releases (breaking > behavior > feature > fix), summarized by your own AI CLI (claude -p; honest raw fallback without it)
tt mcp	MCP server so your coding agent can ask inventory / whats_new / tool_info
tt serve	Localhost dashboard — card grid, tool detail, digest inbox, report
tt report	Shareable Tool-Park report (terminal + self-contained HTML/MD)

Rules this product will not break

1. Read-only scanner — V1 never installs, updates, or removes anything.
2. Local-first & private — nothing leaves your machine; AI runs through your own CLIs and keys; no accounts, no telemetry.
3. Breaking beats feature — in every sort, digest, card, and MCP answer.
4. Every insight is pushable — terminal, MCP, and dashboard are equal citizens.
5. unknown is honest — no guessed versions, dates, or change kinds. Ever.

Install

npm install -g @moinsen-dev/tool-teacher
tt          # guided status — the tool tells you what to do next
tt scan     # first inventory (read-only, ~10 seconds)

Requires Node ≥ 20. The AI digest and lessons use your own claude CLI if present — without one, everything degrades honestly to raw facts.

Security note: npm audit may flag @hono/node-server@1.x via the official MCP SDK — that advisory concerns its HTTP static serving on Windows; tt mcp uses stdio only and never loads that code path. Tool Teacher's own dashboard server uses the patched 2.x line.

Development

TypeScript pnpm monorepo: packages/core (engine) · packages/cli (tt) · packages/dashboard (React/Vite) · packages/mcp (MCP server).

pnpm install
pnpm build          # tokens (from DESIGN.md) + all packages
pnpm test           # vitest incl. contract-drift + MCP protocol tests
node packages/cli/dist/index.js scan

DESIGN.md is the single design-token source; mockups/ is the frozen visual contract (changes only via a logged contract amendment). Built with the werft pipeline — founding docs: VISION.md · PRODUCT.md · DESIGN.md · PID.md · IMPLEMENTATION_PLAN.md.

Status: 0.1.0 on npm (2026-07-22) — early, local-first, read-only by design. Landing page: toolteacher.moinsen.dev