AI Session Tools

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.

For multi-step tasks, follow a workflow below.

Workflows

1. Recover lost context after compaction

# 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_ID --output session-context.md

2. Recover a file the AI (e.g. Claude / Gemini) wrote that is missing from disk

# Find which sessions wrote or edited the file
aise files search --pattern "filename.py"

# Every version: how many edits, which sessions, which dates
aise files history filename.py
aise files history filename.py --export   # write versioned files: filename_v1.py, filename_v2.py, ...
aise files history filename.py --stdout   # all versions to stdout for piping

# Preview a specific version
aise files extract filename.py --version 3

# Restore the latest version to its original path on disk
aise files extract filename.py --restore

# Or write to a backup directory instead
aise files extract filename.py --output-dir ./backup

3. Audit what the AI (e.g. Claude / Gemini) did in a session

# Find the session
aise list --project myproject

# Tool counts, files touched — quick overview without reading everything
aise messages inspect SESSION_ID

# Chronological event timeline with timestamps
aise messages timeline SESSION_ID

# Read the full conversation
aise messages get SESSION_ID

4. Turn recurring AI mistakes into permanent fixes in skills, prompts, and guidelines

Use this to find what the AI gets wrong repeatedly, extract corrections, and turn them into skill rules, CLAUDE.md additions, or hook integrations to prevent recurrence (see Workflow 6).

# Find messages where the user corrected the AI
# Built-in categories: regression, skip_step, misunderstanding, incomplete
aise messages corrections

# Filter to a specific project, session, or date range
aise messages corrections --project myproject --since 2026-01-01
aise messages corrections --session ab841016

# Add a custom pattern to detect a specific failure type (LABEL:regex)
aise messages corrections --pattern 'tool_misuse:you used the wrong'
aise messages corrections --pattern 'context_loss:you forgot'

# Pipe correction session IDs to another command
aise messages corrections --since 14d --ids-only | \
    xargs -I{} aise messages search "you deleted" --session {} --context-after 3

# How often were planning commands used? (add --commands to count custom slash commands)
aise messages planning
aise messages planning --commands '/myteam:plan,/myteam:review'

# Full qualitative analysis across all sessions:
#   - technique taxonomy, error graph, project classification
#   - use output to extract effective prompts, find recurring failure types,
#     build new skills, update CLAUDE.md rules, hook integrations, or skills (see Workflow 6)
aise analyze --status                  # check which stages are stale before running
aise analyze                           # run the full pipeline
aise --provider claude analyze         # scope to one source only (--provider is a root flag)
aise analyze --step analyze            # run one stage: analyze | graph
aise analyze --force                   # re-run all stages regardless of staleness
aise analyze --org-dir ~/my-org        # override output directory for this run

To make custom patterns permanent across all future runs, add them to correction_patterns in the config file — see Workflow 5.

5. Make custom failure categories permanent across all future sessions

aise config path    # find the config file location
aise config show    # view all current values
aise config init    # create a starter config if it doesn't exist yet

correction_patterns — persistent failure categories for aise messages corrections. Format: "LABEL:regex" — label names the category, regex matches in message text.

"correction_patterns": [
  "regression:you deleted",
  "regression:you removed",
  "skip_step:you forgot",
  "skip_step:you missed",
  "misunderstanding:that's wrong",
  "incomplete:also need",
  "tool_misuse:you used the wrong tool",
  "context_loss:you forgot what we were working on",
  "overengineered:that's too complex"
]

planning_commands — which slash commands count toward aise messages planning. Add your own project-specific planning commands:

"planning_commands": ["/ar:plannew", "/ar:planrefine", "/ar:planupdate", "/myteam:plan"]

keyword_maps — classify sessions by project, task type, and workflow for aise analyze taxonomy. Empty by default — fill in to get meaningful session categorization:

"keyword_maps": {
  "project_map": {
    "myproject": ["myproject", "my-project", "myproj"]
  },
  "task_categories": {
    "auth": ["login", "jwt", "oauth", "token"],
    "api": ["endpoint", "rest", "graphql"],
    "testing": ["pytest", "unittest", "test suite"]
  }
}

scoring_weights.corrected_bonus (default: 25) — sessions where the user corrected the AI score higher in the aise analyze pipeline, making them more prominent in the output taxonomy. Increase to weight corrected sessions more heavily when looking for improvement signals.

6. Act on analysis — turn findings into permanent improvements

After running aise messages corrections or aise analyze, apply what you found. The goal: each recurring failure becomes a rule that prevents it in future sessions.

Where to apply fixes (pick the right target):

CLAUDE.md — add rules from corrections:

# Find what you corrected the AI about most
aise messages corrections --since 30d

# Example output: 5x "you used cat instead of Read"
# → Add to CLAUDE.md:
#   "Never use cat/head/tail in Bash. Use the Read tool instead."

# Example output: 3x "you forgot to run tests"
# → Add to CLAUDE.md:
#   "After every code change, run the test suite before committing."

Rules go in your project's CLAUDE.md (checked into git) or ~/.claude/CLAUDE.md (global). One concrete sentence per rule. Avoid vague guidance — state exactly what to do or not do.

Hook integrations — block dangerous commands:

If corrections show repeated dangerous command usage, add a block:

/ar:globalno 'dangerous-command'   # block globally across sessions

Skills — extract reusable workflows:

When corrections reveal a missing workflow (not just a single rule), create a skill:

/claude-skill-builder

Verify the fix worked:

# After adding a rule, check if the same correction reappears
aise messages corrections --since 7d --pattern 'LABEL:the pattern you fixed'

# Compare before/after counts
aise messages corrections --since 30d   # before: 5 occurrences
# ... wait a week of sessions ...
aise messages corrections --since 7d    # after: 0 occurrences = success

7. Composable pipelines — pipe session IDs between commands

Use --ids-only to chain aise commands via xargs for multi-step analysis.

# Find sessions with corrections, then search each for specific patterns
aise messages corrections --since 14d --ids-only | \
    xargs -I{} aise messages search "you deleted" --session {} --context-after 3

# Find sessions using a specific slash command, export each
aise commands list --command /ar:plannew --since 14d --ids-only | \
    xargs -I{} aise export session {} --output {}.md

# List sessions, search each for error patterns
aise list --since 7d --ids-only | \
    xargs -I{} aise messages search "error|failed|bug" --session {} --regex

8. Analyze slash command patterns across sessions

Track slash command usage and post-invocation context with commands list and commands context.

# List all slash command invocations (auto-discovers all commands)
aise commands list --since 14d

# Filter to a specific command
aise commands list --command /ar:plannew --since 14d

# See what Claude did after each invocation of a command (context window)
aise commands context /ar:plannew --context-after 5

# JSON output for scripting
aise commands list --format json --since 14d

# Count unique commands used
aise commands list --since 30d --format json | python3 -c "
import json, sys; from collections import Counter
d = json.load(sys.stdin)
print(Counter(r['command'] for r in d).most_common())"

Sources

Claude Code sessions are auto-discovered from ~/.claude/projects/. AI Studio and Gemini CLI require configuration:

aise source scan --save                        # scan standard locations; --save writes found paths to config
aise source add /path/to/aistudio              # add AI Studio export directory (type auto-detected)
aise source add /path/to/aistudio --type aistudio  # add with explicit type
aise source add ~/.gemini/tmp --type gemini    # add Gemini CLI directory
aise source remove /path/to/dir               # remove a source directory from config by path
aise source disable aistudio                  # disable AI Studio auto-discovery (also: gemini_cli)
aise source enable aistudio                   # re-enable auto-discovery (also: gemini_cli)
aise source list                              # show all active sources (auto-detected + configured)

Configuration

The config file controls persistent failure detection patterns (correction_patterns), planning command tracking (planning_commands), session taxonomy keywords (keyword_maps), and analysis scoring weights — see Workflow 5 for details.

Config file location (priority order):

1. --config /path/config.json CLI flag — per-invocation override
2. AI_SESSION_TOOLS_CONFIG=/path/config.json env var — session-wide override
3. OS default: ~/Library/Application Support/ai_session_tools/config.json (macOS) or ~/.config/ai_session_tools/config.json (Linux)

Override ~/.claude location: --claude-dir /path or CLAUDE_CONFIG_DIR=/path

aise config show                             # view full config + resolved path
aise config path                             # print config file path only
aise config init                             # create default config (safe — errors if file exists)
aise config init --force                     # overwrite existing config
aise --config /custom/path.json config init  # create config at a specific path

Date Filtering

Three flags control date ranges on all commands that support them:

Accepted formats (all three flags):

Use --when for decade/month/partial-date patterns where a single expression sets the full window. Use --since + --until for explicit asymmetric ranges.

Run aise dates for the full reference.

Output Formats

All commands support --format / -f:

Session File Location

~/.claude/projects/<ENCODED-PATH>/<SESSION-ID>.jsonl

Path encoding: all non-alphanumeric characters → -

• /Users/alice/myproject → -Users-alice-myproject
• /Users/alice/.claude → -Users-alice--claude (dot → dash)

Each JSONL line is a JSON object with type (user/assistant/system), timestamp, and message containing tool calls and text content.

See references/session-format.md for the full format reference.

Full Flag Reference

aise COMMAND --help — every subcommand has a --help flag with full option descriptions.

aise not found? Run autorun --install --force or uv tool install ai-session-tools.