claude-tips

Contextual spinner tips mined from your own Claude setup.

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

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

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

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

Quick Start

# 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:

// ~/.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

License

MIT