npm package: @kam-l/claude-coach
Description: Session-aware coaching for Claude Code — curated tips and live contextual advice
Author: kam-l
Latest version: 2.0.0

# claude-coach

**Session-aware coaching for Claude Code — curated tips and live contextual advice.**

[![Claude Code Plugin](https://img.shields.io/badge/claude--code-plugin-8A2BE2)](https://code.claude.com/docs/en/plugins)
[![tests](https://github.com/kam-l/claude-coach/actions/workflows/test.yml/badge.svg)](https://github.com/kam-l/claude-coach/actions/workflows/test.yml)
[![npm](https://img.shields.io/npm/v/@kam-l/claude-coach)](https://www.npmjs.com/package/@kam-l/claude-coach)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![node](https://img.shields.io/node/v/@kam-l/claude-coach)](https://nodejs.org)

![claude-coach showcase](showcase.gif)

- **67 curated tips** — workflow, context, agents, hooks, quality, performance
- **Session advisor** — Sonnet sidecar that watches your session and coaches in real-time
- **Zero-cost fallback** — tips rotate in the spinner with no LLM calls when advisor is off
- **Survives updates** — runtime files live in `~/.claude/.coach/`, decoupled from plugin cache

## Install

```bash
npm install -g @kam-l/claude-coach
```

Alternatively:

```bash
claude plugin marketplace add kam-l/claude-plugins
claude plugin install claude-coach
```

## Quick Start

```bash
# 1. Inside Claude Code — set up spinner tips and session advisor
/claude-coach:tips init

# 2. Restart Claude Code — tips appear in the spinner
```

## How It Works

**Spinner tips** (always on): 67 hand-curated tips rotate during tool calls. You glance at them while waiting — passive reinforcement of best practices.

**Session advisor** (opt-in): Every 15 minutes, a detached Sonnet worker reads your session transcript and produces 1-3 tips grounded in what you're actually doing:

```
ℹ️ Run tests before committing the session-advisor changes
ℹ️ /compact — context is likely past 50%
ℹ️ Fix claudeline URL in marketplace.json before pushing
```

- `💡` — curated tip from the base pool
- `ℹ️` — contextual tip from the session advisor
- `🔍` — advisor is analyzing your session

**Cost:** ~$0.10-0.18/cycle, default every 15 min. Pro/Max users spend rate-limit budget, not dollars. Configure interval with `CLAUDE_COACH_INTERVAL` (seconds, default 900).

**Enable:**
```json
// ~/.claude/settings.json
{ "env": { "CLAUDE_COACH": "1" } }
```

Or run `/claude-coach:tips init` for guided setup.

## Tip Categories

| Category | # | Examples |
|----------|---|---------|
| Workflow | 15 | Plan mode first, `/rewind` for off-track runs, fan-out with `claude -p` |
| Context | 11 | 200-line CLAUDE.md limit, `/compact` at 50%, `.claudeignore` |
| Agents | 11 | File paths not content, `isolation: worktree`, scoped > generalist |
| Hooks | 10 | `exit 2` feedback, `statusMessage`, `async: true` for slow hooks |
| Quality | 11 | Screenshots for visual bugs, explain-back, ultrathink |
| Performance | 9 | `/model` downgrade, `effortLevel`, worktree parallelism |

## Commands

| Command | What it does |
|---------|-------------|
| `/claude-coach:tips init` | Full setup — spinner tips + statusline + advisor |
| `/claude-coach:tips refresh` | Re-scan friction data, update tips |
| `/claude-coach:tips add <tip>` | Add a custom tip |
| `/claude-coach:tips list` | Print all tips by category |
| `/claude-coach:tips uninstall` | Remove all traces |

## Sources

- [Anthropic Claude Code docs](https://code.claude.com/docs/en/best-practices)

## License

MIT