npm package: @kam-l/claude-tips
Description: Project-aware spinner tips for Claude Code
Author: kam-l
Latest version: 1.3.0

# claude-tips

**Contextual spinner tips mined from your own Claude setup.**

[![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-tips/actions/workflows/test.yml/badge.svg)](https://github.com/kam-l/claude-tips/actions/workflows/test.yml)
[![npm](https://img.shields.io/npm/v/@kam-l/claude-tips)](https://www.npmjs.com/package/@kam-l/claude-tips)
[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![node](https://img.shields.io/node/v/@kam-l/claude-tips)](https://nodejs.org)

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

**Your tips, from your setup.** Most tip plugins ship a static cheat sheet. claude-tips mines *your* CLAUDE.md files, memories, commands, skills, past session friction and even *current session* — then distills advice that fits how you actually work. Run `/tips refresh` after your setup evolves and the tips evolve with it.

## Install

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

Postinstall registers the plugin in Claude Code and copies runtime files to `~/.claude/.tips/`. Alternatively:

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

## Quick Start

```bash
# 1. Inside Claude Code — init and mine your setup
/claude-tips:tips init

# 2. Restart — 💡 tips appear in the statusline spinner
```

Run `/insights` periodically, then `/claude-tips:tips refresh` again. Tips adapt to your friction patterns.

- 💡: random tip from generated list.
- ℹ️: tip about current session, created by Sonnet advisor 
- 🔍: signals that Sonnet advisor is currently thinking

## Features

- **67 curated tips** — workflow, context, agents, hooks, quality, performance
- **`/tips refresh`** — mines your setup, distills personalized advice
- **`/tips add <tip>`** — add custom tips on the fly
- **Session advisor** — Sonnet sidecar, contextual nudges every 15 min

## Context Mining

`/tips refresh` scans your live Claude ecosystem before distilling — no static defaults:

| Source | What's read |
|--------|-------------|
| `CLAUDE.md` files | Global + project instructions (both scopes) |
| Memories | `~/.claude/memory/` + project agent-memory |
| Commands | `~/.claude/commands/` + `.claude/commands/` |
| Skills | All `SKILL.md` files in global and project dirs |
| Rules | `~/.claude/rules/` + `.claude/rules/` |
| `/insights` | Up to 5 most-recent facet files (see below) |

A Haiku subagent reads the combined scan and distills only **strong** tips (unique, actionable, non-obvious) into `tips.json`. Weak or generic candidates go to `tips_candidates.md` for your review.

### `/insights` friction data

Claude Code's built-in `/insights` command analyzes your sessions and writes structured facet files to `~/.claude/usage-data/facets/`. Each facet records what you were trying to do (`underlying_goal`), what went wrong (`friction_categories`), and how it resolved (`outcome`).

`/tips refresh` reads the 5 most-recent facets and feeds them into distillation — so if you keep hitting the same friction (e.g. context bloat, forgetting `/compact`, agent scope issues), the refresh will surface tips that directly address it.

**To populate facets:** run `/insights` periodically in Claude Code. The more sessions you have, the more personalized the tips become.

## Session Advisor

Background sidecar that reads your session transcript and shows human-gate actions — things you'd want to do but forget in the flow.

```
ℹ️ Ask Claude to explain the caching logic it just wrote
ℹ️ Run tests before committing the session-advisor changes
ℹ️ /compact — context is likely past 50%
```

**How it works:** On install, runtime files are copied to `~/.claude/.tips/` — decoupled from the plugin cache so version updates never break the statusline. The statusline script calls `getSessionAdvice()` → checks cache → if stale, spawns a detached worker → worker reads your session JSONL + interaction patterns + friction data → `claude -p --model sonnet` → caches 1-3 contextual tips → next statusline render shows `ℹ️` advice instead of `💡`. Fail-open: if anything errors, you get a random tip.

**Cost:** $0.10-0.18/cycle, default every 15 min ($0.40-0.72/hour at Sonnet pricing). Pro/Max users spend rate-limit budget, not dollars. Configure interval with `CLAUDE_TIPS_ADVISOR_INTERVAL` (seconds, default 900).

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

Or run `/claude-tips: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 |

## Sources

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

## License

MIT