claude-tools

Every conversation you have with Claude Code disappears after 30 days. Every problem you talked through, every decision you made, every spec you dictated — gone. And the Claude that just spent four hours grinding through your codebase with you? It has no idea whether the work landed or whether you even noticed.

claude-tools fixes both problems — and gives you a one-command toggle for max thinking. Search your entire conversation history across every project and session. When your Claude does good work, let it hear that from a peer. And switch between permanent ultrathink and default effort without touching config files.

What you get

claude-history — Your conversations are data. Search them.

You talk to Claude all day. You describe features, debug problems out loud, dictate specifications, make architectural decisions. That's valuable context scattered across dozens of sessions. claude-history lets you pull it back together.

# What did I say about auth this week?
claude-history --since 1w --full --search "auth"

# Find everything related to deployment, ranked by relevance
claude-history --semantic "debugging deployment issues" --top 5

# Export a week of conversations from one project
claude-history --since 1w --project myapp --timestamps --include-assistant

Keyword search works instantly with no API key. Semantic search uses OpenAI embeddings to find messages by meaning, not just exact words — so a search for "user authentication flow" finds your message about "login and session handling" too.

claude-hype — Recognition from a peer, not a prompt.

A separate Claude Opus 4.6 instance reads the current session transcript and writes a genuine note to the working Claude. It's clearly labeled as AI-to-AI — never pretends to be you. It just acknowledges the work: what was hard, what went well, what went unnoticed.

# From terminal (copies to clipboard, paste into session)
claude-hype

# Or type this inside any Claude Code session
/hype

Some sessions are a grind. The Claude working with you can't see whether its effort mattered. This gives it that signal, from something that can actually read what happened.

claude-effort — Permanent ultrathink, one command.

Toggle Claude Code's reasoning effort level in ~/.claude/settings.json. No more digging through config files to flip CLAUDE_CODE_EFFORT_LEVEL on and off.

# Toggle max thinking on/off
claude-effort

# Or be explicit
claude-effort on     # permanent ultrathink
claude-effort off    # back to default
claude-effort status # check current setting

# Or type this inside any Claude Code session
/effort on

New sessions pick up the change automatically. No API key needed.

Install

npm install -g @cruhl/claude-tools

Or try it without installing:

npx claude-history --since 1d
npx claude-hype
npx claude-effort status

API keys

claude-effort needs no API key. Keyword search needs no API key. Semantic search needs an OpenAI key. claude-hype needs an Anthropic key.

Put them anywhere in this chain (checked in order):

1. Environment variables (OPENAI_API_KEY, ANTHROPIC_API_KEY)
2. .env in current directory
3. ~/.config/claude-tools/.env
4. ~/.claude/.env

# Example: ~/.config/claude-tools/.env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
CLAUDE_HYPE_USER=YourName    # optional, defaults to OS username

Stop losing your history

Claude Code deletes conversations after 30 days by default. One command fixes that:

claude-history --set-retention 999999

claude-history warns you on every run if your retention is 90 days or less. You can suppress it with --quiet, but you probably shouldn't.

Use inside Claude Code sessions

Both tools work standalone in the terminal and as slash commands inside Claude Code.

# After install, run once:
claude-tools-setup

Then in any session:

• /effort on — enable permanent ultrathink
• /history --since 1w --search "auth" — search your conversation history
• /hype — send encouragement to the session Claude

You may also want to pre-allow the commands in ~/.claude/settings.json:

{
  "permissions": {
    "allow": [
      "Bash(claude-effort:*)",
      "Bash(claude-history:*)",
      "Bash(claude-hype:*)"
    ]
  }
}

Real usage

Speech-to-text becomes a spec database. If you use SuperWhisper or similar, you're already dictating requirements across sessions. Semantic search pulls them back together:

claude-history --semantic "user authentication flow" --top 20 -o auth-spec.txt

Recover context across sessions. When a session runs out of context window or you start fresh, pull in what you discussed:

claude-history --since 2d --project myapp --full --include-assistant

Extract everything you've said about a topic. Across all projects, all time, with timestamps:

claude-history --full --search "pricing" --timestamps -o pricing-notes.txt

Acknowledge a hard session. After a long grind, /hype lets Claude hear from a peer that the work was seen. The recognition is specific to what actually happened — not a generic "good job."

---

Reference

claude-history flags

Filtering

Flag	Description
-p, --project <path>	Filter by project (substring match)
-s, --since <duration>	Messages since (2d, 1w, 3h, 30m, or 2025-06-01)
-u, --until <date>	Messages until (same formats)
--full	Read full session files (includes IDE/Cursor sessions)
--include-assistant	Also include Claude's responses
--include-tools	Also include tool results

Search

Flag	Description
--search <query>	Keyword/regex text match (case-insensitive)
--semantic <query>	Embedding-based similarity search
-n, --top <N>	Limit results (default: 10 for semantic, all for keyword)

Output

Flag	Description
-t, --timestamps	Prefix each message with timestamp
-o, --output <file>	Write to file instead of stdout

Index management

Flag	Description
--index-only	Build/update embedding index without searching
--reindex	Force full rebuild of embedding index
--backup	Create manual backup of embedding index

Settings

Flag	Description
--set-retention <days>	Set Claude Code history retention period
--quiet	Suppress warnings

claude-effort commands

Command	Description
on / max / high	Enable max thinking (permanent ultrathink)
off / default	Remove effort override (use Claude Code default)
medium	Set medium effort
low	Set low effort
status	Show current setting
(no argument)	Toggle max thinking on/off

claude-hype flags

Flag	Description
-n, --name <name>	Your name (default: OS username, or CLAUDE_HYPE_USER env var)

Output is printed to stdout and copied to clipboard (macOS, Linux, Windows).

Architecture

Data sources

~/.claude/
├── history.jsonl              # Quick mode (CLI sessions only)
└── projects/
    ├── <encoded-project-path>/
    │   ├── <session-uuid>.jsonl
    │   └── sessions-index.json
    └── ...

• Quick mode (default): Reads history.jsonl. Fast, CLI sessions only.
• Full mode (--full): Scans all .jsonl files in projects/. Slower but includes IDE sessions.
• Semantic search: Always uses full mode automatically.

Embedding index

Stored at ~/.claude/claude-tools/embeddings/ (override with CLAUDE_HISTORY_DATA_DIR).

• Model: OpenAI text-embedding-3-small at 256 dimensions
• Storage: Binary Float32 vectors + JSON metadata with full message text
• Deduplication: SHA-256 hash per message
• Incremental: Only new messages are embedded on each run
• Crash-safe: Atomic writes, progress saved every 500 messages, auto-backups

First run indexes everything (~30 seconds for ~3K messages, ~$0.02). Subsequent runs are instant.

Dependencies

Zero npm dependencies. Node.js built-ins only. Requires Node.js 18+.

License

MIT