agent-history

Imported from kvsankar/agent-history (SKILL.md). Install upstream with npx skills add kvsankar/agent-history. Copyright stays with the author.

Agent History Skill

Setup

mkdir -p ~/.claude/skills
cp agent-history SKILL.md ~/.claude/skills/
chmod +x ~/.claude/skills/agent-history

Once installed, Claude Code will automatically use this skill when you ask about past conversations, usage patterns, or want to search your history.

Browse, search, and analyze AI coding assistant conversation history using the agent-history CLI tool.

When to Activate

• User asks about past conversations: "what did we discuss about X", "find that conversation where we..."
• User wants to find previous solutions: "how did we fix that error", "what approach did we use for..."
• User asks about usage patterns: "how much time did I spend", "which tools do I use most"
• User wants to export or backup: "export my conversations", "backup this project's history"
• User references earlier sessions: "yesterday we talked about", "last week's work on..."

Available Commands

List Sessions

# Current workspace
agent-history lss

# All sources (local + WSL + Windows + remotes)
agent-history lss --ah

# Filter by workspace pattern
agent-history lss myproject

# Filter by date
agent-history lss --since 2025-11-01
agent-history lss --since 2025-11-01 --until 2025-11-30

Export

# Export current workspace sessions
agent-history export

# Export specific workspace
agent-history export myproject

# Export with date filter
agent-history export --since 2025-11-24

# Export minimal (no metadata, cleaner for reading)
agent-history export --minimal

# Export to specific directory
agent-history export -o /tmp/history-export

# Export offline HTML with progressive detail controls
agent-history export --format html --html-single

# Print one small session as concise Markdown to stdout
agent-history export /path/to/session.jsonl -o - --markdown-level 1

Usage Statistics

# Summary dashboard
agent-history stats

# Time tracking (work hours per day)
agent-history stats --time

# Tool usage breakdown
agent-history stats --tools

# Model usage
agent-history stats --models

# Daily trends
agent-history stats --by-day

# Per-workspace breakdown
agent-history stats --by-workspace

List Workspaces

# All local workspaces
agent-history lsw

# Filter by pattern
agent-history lsw myproject

Data Location

Supported agents store conversations in different locations:

• Claude Code: ~/.claude/projects/ as JSONL files
• Codex CLI: ~/.codex/sessions/ as JSONL files organized by date
• Gemini CLI: ~/.gemini/tmp/ as JSON files under project-hash folders
• Pi: ~/.pi/agent/sessions/ as JSONL files under workspace folders

Workspace directories may be encoded paths, date folders, or hashes depending on the agent. Use agent-history lsw and agent-history lss instead of assuming a single storage layout.

Search Strategy (No Built-in Search Yet)

Since the tool doesn't have a search command, use this workflow:

Method 1: Export + Grep (Recommended)

# Export recent sessions from ALL workspaces to temp directory
agent-history export --aw --since 2025-11-24 -o /tmp/history-search --minimal

# Search the exported markdown files
grep -r -i "search term" /tmp/history-search/

Method 2: Direct Raw Session Search

# Claude example: find the workspace directory
ls ~/.claude/projects/ | grep myproject

# Search within JSONL files (content is in message.content)
grep -i "search term" ~/.claude/projects/-home-user-myproject/*.jsonl

# Multi-agent broad search
grep -r -i "search term" ~/.claude/projects ~/.codex/sessions ~/.gemini/tmp ~/.pi/agent/sessions 2>/dev/null

Method 3: Multi-term Semantic Search

For questions like "what did we discuss about database connections":

1. Generate related search terms based on the topic
2. Run multiple grep searches
3. Synthesize the findings

Example for "database connections":

# Export recent history from all workspaces first
agent-history export --aw --since 2025-11-24 -o /tmp/search --minimal

# Search for related terms
grep -r -i -l "database" /tmp/search/
grep -r -i -l "connection" /tmp/search/
grep -r -i -l "postgres\|mysql\|sqlite\|mongo" /tmp/search/
grep -r -i -l "sql" /tmp/search/
grep -r -i -l "pool\|timeout" /tmp/search/

Then read the matching files to find relevant conversations.

Common Workflows

"What did we discuss about X last week?"

1. Export recent sessions from all workspaces:

   agent-history export --aw --since 2025-11-24 -o /tmp/history --minimal

2. Search for the topic and variations:

   grep -r -i -l "TOPIC" /tmp/history/
   grep -r -i -l "RELATED_TERM1" /tmp/history/
   grep -r -i -l "RELATED_TERM2" /tmp/history/

3. Read matching files to summarize findings

"How did we fix that error?"

1. Search for error-related terms:

   agent-history export --aw --since 2025-11-01 -o /tmp/history --minimal
   grep -r -i "error\|exception\|failed" /tmp/history/ | head -50

2. Look for solution patterns:

   grep -r -i -A5 "fixed\|resolved\|solution" /tmp/history/

"How much time have I spent on this project?"

agent-history stats --time

"Which tools do I use most?"

agent-history stats --tools

"Show me my activity this month"

agent-history stats --by-day --since 2025-11-01

"Export everything for backup"

agent-history export --ah --aw -o ~/agent-history-backup/

Tips

• Use --minimal for reading: Omits UUIDs and metadata, much cleaner
• Use --since to narrow scope: Faster searches on recent history
• Check multiple workspaces: Use lsw to see all available workspaces
• Claude subagent files exist: Claude tasks spawn agent-*.jsonl files with sub-conversations
• Incremental export: Re-running export skips unchanged files

Output Formats

Markdown exports include:

• Message timestamps
• User/Assistant labels
• Tool use details (name, input, output)
• Token usage (in non-minimal mode)
• Navigation links between messages (in non-minimal mode)

Markdown stdout export (-o -) is only for one full .jsonl/.json session file path. Do not pass a workspace and a separate session filename; pass the actual session file as the only export target.

Offline HTML exports add:

• Turn-centered conversation layout
• Light/dark mode
• Per-turn and global detail controls
• Raw views for friendly-rendered text, code, tool output, and diffs

Limitations

• No built-in semantic search (use grep + Claude reasoning)
• No full-text index (searches scan files each time)
• Remote sources require SSH access configured