Claude Helpers

Claude Helpers

Interactive CLI tools for managing Claude Code sessions.

Project Overview

This is a Bun-based CLI tool that provides:

• Semantic search across Claude session history using semtools
• Session management - browse, resume, and explore past conversations
• Agent launcher - quick access to predefined Claude agents (reviewer, debugger, etc.)

Architecture

src/
├── types.ts      # TypeScript interfaces
├── sessions.ts   # Session loading and parsing from ~/.claude/projects/
├── search.ts     # Semantic search using semtools
├── agents.ts     # Predefined agent definitions
└── ui.ts         # Terminal UI formatting (chalk, etc.)

index.ts          # Main CLI entry point

Key Files

• ~/.claude/projects/ - Where Claude stores session JSONL files
• Sessions are stored as {project-path}/{session-id}.jsonl
• Each line is a JSON object with type, message, timestamp, etc.

Commands

ch                    # Interactive menu
ch search      # Semantic search (requires semtools)
ch sessions           # List recent sessions
ch resume [id|query]  # Resume a session
ch agent        # Launch with agent
ch agents             # List available agents

Development

bun run dev           # Run the CLI
bun test              # Run tests

Dependencies

• @inquirer/prompts - Interactive prompts
• chalk - Terminal colors
• ora - Spinners
• glob - File pattern matching
• semtools - For semantic search (external: npm i -g @llamaindex/semtools)

---

Bun Guidelines

Default to using Bun instead of Node.js.

• Use bun instead of node or ts-node
• Use bun test instead of jest or vitest
• Use bun install instead of npm install
• Bun automatically loads .env, so don't use dotenv.
• Prefer Bun.file over node:fs's readFile/writeFile
• Use Bun.$\ls`` instead of execa
• Always recompile the bin after making code changes.