ai-session-tools

What this skill does

# AI Session Tools

Search, recover, and analyze AI session histories across Claude Code, AI Studio, and Gemini CLI.

**Invoke with:** `/ar:ai-session-tools` or natural language like "find that file from last week", "search sessions for authentication", "recover context from session ab841016"

After a context compaction, a lost file, or a confusing session — `aise` finds it. In under a minute you can recover a file the AI (e.g. Claude / Gemini) wrote, restore the sequence of user requests, search every conversation you've ever had, or export a full session to markdown. Works across Claude Code, AI Studio, and Gemini CLI sessions simultaneously.

**Full flag reference:** `aise COMMAND --help`

## How It Works

1. **Find sessions** — `aise list` discovers sessions from `~/.claude/projects/` (Claude Code), AI Studio exports, and Gemini CLI. Filter by `--provider`, `--project`, `--since`.
2. **Search and recover** — `aise messages search`, `aise files search`, `aise tools search` find content across all sessions. `aise files extract` recovers files missing from disk.
3. **Analyze patterns** — `aise messages corrections` detects where users corrected the AI. `aise commands list/context` tracks slash command usage. `aise analyze` runs the full qualitative coding pipeline.
4. **Improve from mistakes** — Turn recurring corrections into permanent CLAUDE.md rules, skill updates, or hook blocks. Compare before/after correction counts to verify fixes worked (see Workflow 6).

---

## Quick Reference

All commands accept `--format json` for machine-readable output and `--full-uuid` for full 36-char session IDs.

| Goal | Action | Command | Key Options |
|------|--------|---------|-------------|
| How much history is indexed? | Count sessions, files, versions | `aise stats` | `--since 7d` `--provider claude` |
| Know which session contains the work you need | List all sessions, newest first | `aise list` | `--project P` `--since 7d` `--limit 20` |
| Narrow to Claude Code sessions only, excluding AI Studio / Gemini | Filter by provider | `aise list --provider claude` | `--since` `--until` `--full-uuid` |
| What did the user ask for in this session? | User request sequence — primary context signal | `aise messages get SESSION_ID --type user` | `--limit 10` |
| Restore the full conversation context | Every message in a session | `aise messages get SESSION_ID` | `--type user\|assistant` `--limit 10` |
| See what the user was asking for across recent sessions | User messages from the last N days | `aise messages search "" --type user --since 7d` | `--project P` `--context 3` `--no-compaction` |
| Find when a specific topic was discussed | Search all messages with surrounding context | `aise messages search "query"` | `--type user` `--context-after 3` `--regex` `--limit 20` |
| What tools did the AI (e.g. Claude / Gemini) call and how often? | Tool counts and files touched | `aise messages inspect SESSION_ID` | `--format json` |
| Reconstruct the exact sequence of events in a session | Chronological timeline with timestamps | `aise messages timeline SESSION_ID` | `--since 14:00` `--preview-chars 80` |
| Which sessions touched a specific file? | Search writes/edits by filename pattern | `aise files search --pattern "name.py"` | `--min-edits 2` `--include-sessions ID` `--include-extensions py ts` |
| See every version of a file the AI (e.g. Claude / Gemini) produced across sessions | Every saved version with session and date | `aise files history filename.py` | `--export` (write versioned files) `--stdout` (pipe all versions) |
| Recover a file missing from disk | Print latest saved version to stdout | `aise files extract filename.py` | `--version 3` `--restore` `--output-dir ./backup` |
| Did the AI's (e.g. Claude / Gemini) edits actually land on disk? | Present vs. missing edit check | `aise files cross-ref ./file.py` | `--session ID` `--format json` |
| See every file change the AI made to a specific file | Search tool calls by filename | `aise tools search Write "filename"` | `aise tools search Edit "file"` `aise tools search Read` |
| See every shell command the AI ran | Search Bash calls by substring | `aise tools search Bash "git commit"` | `--format json` `--limit 20` |
| Recover clipboard content the AI prepared | Extract pbcopy content | `aise messages extract SESSION_ID pbcopy` | `--format json` |
| Produce a persistent readable record of a session | Export session to markdown | `aise export session SESSION_ID` | `--output file.md` `--dry-run` |
| Document a sprint of AI-assisted work | Export last N days to a file | `aise export recent 7 --output week.md` | `--project myproject` |
| Find something that could be in a file or a message | Cross-domain search (`aise find` is an alias) | `aise search --pattern "*.py" --query "error"` | `--tool Write` `--query only` `--pattern only` |
| Identify where the AI (e.g. Claude / Gemini) went wrong and the user had to correct it | Detect correction patterns by category | `aise messages corrections` | `--pattern 'LABEL:regex'` `--project P` `--since` |
| Measure how consistently planning workflows were followed | Count planning invocations across sessions | `aise messages planning` | `--commands '/custom,/cmd'` |
| List every slash command invocation with metadata | When/where was each command used? | `aise commands list` | `--command /ar:plannew` `--ids-only` `--since 14d` |
| See what happened after a slash command | Context window post-invocation | `aise commands context /ar:plannew` | `--context-after 5` `--format json` |
| Pipe session IDs to another command | Composable workflows with xargs | `aise list --since 7d --ids-only` | `\| xargs -I{} aise messages get {}` |
| Filter to slash command messages only | Find real command invocations | `aise messages search "" --type slash` | `--since 14d` |
| Search with asymmetric context windows | See what came before/after a match | `aise messages search "error" --context-after 5` | `--context-before 2` |
| Exclude compaction summaries from search | Focus on real messages only | `aise messages search "query" --no-compaction` | |
| Search with regex pattern | Complex pattern matching with \| for OR | `aise messages search "forgot\|missed" --regex` | |
| Filter timeline events by pattern | Grep within a session timeline | `aise messages timeline SID --grep "error"` | `--regex` |
| Identify recurring AI mistakes across all sessions | Qualitative analysis pipeline | `aise analyze` | `--step analyze\|graph` `--org-dir DIR` `--status` `--force` |
| Turn recurring mistakes into permanent fixes | Apply corrections to CLAUDE.md, skills, or hooks | See Workflow 6 | Decision table: finding → target → example |
| Verify a fix actually reduced a failure | Compare correction counts before/after | `aise messages corrections --since 7d` | Compare to `--since 30d` baseline |
| Narrow analyze to one provider | Provider goes at root level | `aise --provider claude analyze` | `aise --provider aistudio analyze` |
| Stop indexing sessions from a removed or unwanted directory | Deregister a session source | `aise source remove /path/to/dir` | `aise source disable claude` |
| What date formats work with --since? | Date format examples and shorthands | `aise dates` | |

For multi-step tasks, follow a workflow below.

---

## Workflows

### 1. Recover lost context after compaction

```bash
# Find the session
aise list --since 7d

# Get the user request sequence — what was being accomplished, without assistant noise
# This is the primary context signal: ordered user intent, compact, no assistant verbosity
aise messages get SESSION_ID --type user

# Read the full conversation if more detail is needed
aise messages get SESSION_ID

# Find files the AI was editing in that session
aise files search --include-sessions SESSION_ID

# Restore a specific file to its original path on disk
aise files extract filename.py --restore

# Export session to markdown for persistent reference
aise export session SESSION_I