AI Session Tools

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

Invoke with:

/ar:ai-session-tools

After a context compaction, a lost file, or a confusing session —

aise

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

--full-uuid

aise stats

--since 7d

--provider claude

aise list

--project P

--since 7d

--limit 20

aise list --provider claude

--since

--until

--full-uuid

aise messages get SESSION_ID --type user

--limit 10

aise messages get SESSION_ID

--type user|assistant

--limit 10

aise messages search "" --type user --since 7d

--project P

--context 3

--no-compaction

aise messages search "query"

--type user

--context-after 3

--regex

--limit 20

aise messages inspect SESSION_ID

--format json

aise messages timeline SESSION_ID

--since 14:00

--preview-chars 80

aise files search --pattern "name.py"

--min-edits 2

--include-sessions ID

--include-extensions py ts

aise files history filename.py

--export

--stdout

aise files extract filename.py

--version 3

--restore

--output-dir ./backup

aise files cross-ref ./file.py

--session ID

--format json

aise tools search Write "filename"

aise tools search Edit "file"

aise tools search Read

aise tools search Bash "git commit"

--format json

--limit 20

aise messages extract SESSION_ID pbcopy

--format json

aise export session SESSION_ID

--output file.md

--dry-run

aise export recent 7 --output week.md

--project myproject

aise find

aise search --pattern "*.py" --query "error"

--tool Write

--query only

--pattern only

aise messages corrections

--pattern 'LABEL:regex'

--project P

--since

aise messages planning

--commands '/custom,/cmd'

aise commands list

--command /ar:plannew

--ids-only

--since 14d

aise commands context /ar:plannew

--context-after 5

--format json

aise list --since 7d --ids-only

| xargs -I{} aise messages get {}

aise messages search "" --type slash

--since 14d

aise messages search "error" --context-after 5

--context-before 2

aise messages search "query" --no-compaction

aise messages search "forgot|missed" --regex

aise messages timeline SID --grep "error"

--regex

aise analyze

--step analyze|graph

--org-dir DIR

--status

--force

aise messages corrections --since 7d

--since 30d

aise --provider claude analyze

aise --provider aistudio analyze

aise source remove /path/to/dir

aise source disable claude

aise dates

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

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

aise messages corrections

"LABEL:regex"

"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

aise messages planning

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

keyword_maps

aise analyze

"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

aise analyze

6. Act on analysis — turn findings into permanent improvements

After running

aise messages corrections

aise analyze

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

~/.claude/CLAUDE.md

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

# 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

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/

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_commands

keyword_maps

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

--claude-dir /path

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:

--since

--since 7d

--since 2026-01-15

--until

--until 2026-03-01

--when

--when 202X

--when 2026-01

Accepted formats (all three flags):

7d

2w

1m

24h

2026-01-15

2026-01

2026

202X

2026-01-1X

--since

2026-01/2026-03

Use

--when

--since

--until

Run

aise dates

Output Formats

All commands support

--format

-f

table

json

jq

csv

plain

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

message

See

references/session-format.md

Full Flag Reference

aise COMMAND --help

--help

aise

autorun --install --force

uv tool install ai-session-tools