sheal

<p align="center"> <img src="assets/sheal-mascot.png" width="200" alt="sheal mascot" /> </p> <h1 align="center">sheal</h1> <p align="center"><b>your ai agent keeps making the same mistakes. sheal fixes that.</b></p> <p align="center"> <a href="https://github.com/liwala/sheal/stargazers"><img src="https://img.shields.io/github/stars/liwala/sheal?style=flat-square" alt="stars" /></a> <a href="https://github.com/liwala/sheal/commits/main"><img src="https://img.shields.io/github/last-commit/liwala/sheal?style=flat-square" alt="last commit" /></a> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license" /></a> </p> <p align="center"> <a href="#install">Install</a> &bull; <a href="#quick-start">Quick Start</a> &bull; <a href="#commands">Commands</a> &bull; <a href="#how-it-works">How It Works</a> &bull; <a href="#supported-agents">Agents</a> </p>

---

<p align="center"> <img src="assets/sheal-hero.png" width="700" alt="sheal hero banner" /> </p>

A CLI toolkit that analyzes AI coding sessions to extract learnings, detect failure patterns, and continuously improve agent behavior.

Your AI agent has amnesia. Every session it repeats the same mistakes, burns the same tokens, forgets the same rules. sheal closes the loop — it reads your sessions, extracts the patterns, writes rules back to your agent config, and makes the next session smarter. It compounds.

<p align="center"> <img src="assets/sheal-evolution.png" width="700" alt="session 1 to session 20 — zero repeated mistakes" /> </p>

Install

npm install -g @liwala/sheal

Or from source:

git clone https://github.com/liwala/sheal
cd sheal
npm install
npx tsc
npm link

Quick Start

# Health check your project setup
sheal check

# Audit your Claude Code settings (permissions, hooks, MCPs)
sheal audit

# Run a retrospective on your latest session
sheal retro

# See your token spend per project
sheal cost

# Get a categorized digest of what you worked on
sheal digest --since "7 days"

# Ask a question across all your sessions
sheal ask "what went wrong with beads?" --agent claude

# Add a learning from experience
sheal learn add "Always inspect real data before writing parsers" --tags=parsing

Commands

sheal check

Pre-session health check. Detects environment issues before you start coding.

sheal check                    # Pretty output
sheal check --format json      # JSON output
sheal check --skip performance # Skip specific checkers
sheal check --strict           # Warnings are blockers: exit non-zero on any warning

Checkers: git status, dependencies, tests, environment, session learnings, performance & efficiency, Claude Code settings.

sheal guard

Point-in-time gates compiled from learnings, designed for hooks and CI.

sheal guard pr                 # Pre-PR gate: branch must be ahead of base, exit 1 otherwise
sheal guard pr --base develop  # Non-main base branch

guard pr verifies HEAD is a working branch (not the base itself), that git rev-list base..HEAD is non-empty (an empty PR is always a mistake), and warns on uncommitted changes. Wire it into a PreToolUse hook on gh pr create or a CI step.

The performance checker detects your AI agent (Claude Code, Cursor, Gemini, Copilot, Amp), checks for RTK token compression, and config file sizes. The claude-settings checker audits permissions, hooks, MCP servers, env vars, and plugins across all settings scopes.

sheal audit

Audit Claude Code settings across all scopes — permissions, hooks, MCP servers, environment variables, and plugins.

sheal audit                    # Pretty output
sheal audit --format json      # JSON output
sheal audit -p /path/to/project  # Different project root

Reads from all four settings files (global, global-local, project, project-local) and shows a merged view of what's configured where.

sheal retro

Session retrospective. Analyzes the most recent AI coding session for failure loops, wasted effort, and learnings.

sheal retro                        # Static analysis (latest session)
sheal retro --checkpoint <id>      # Specific session
sheal retro --enrich               # LLM-enriched deep analysis
sheal retro --enrich --agent amp   # Use a specific agent CLI
sheal retro --prompt               # Output raw prompt (pipe to any LLM)
sheal retro --format json          # JSON output

The --enrich flag invokes an agent CLI to perform deep analysis on top of the static retro. The agent extracts rules and offers to save them as learnings. Results are cached at .sheal/retros/.

sheal ask <question>

Query across your session transcripts using natural language. Uses a 3-phase pipeline:

1. Extract search terms from your question (agent-assisted, with local fallback)
2. Local grep across sessions using those terms (word-boundary matching)
3. Agent analyzes relevant excerpts to answer your question (falls back to raw excerpts)

# Search current project's sessions
sheal ask "what went wrong with beads?"

# Use a specific agent for analysis
sheal ask "how did we handle the auth migration?" --agent codex

# Search ALL projects globally
sheal ask --global "what patterns keep causing test failures?"

# Search a different project
sheal ask -p /path/to/other-project "what happened with the auth migration?"

# Search more sessions
sheal ask "show me all test failures" -n 20

Options:

• --agent <name> — Agent CLI to use: claude, gemini, codex, amp
• -n, --limit <count> — Max sessions to search (default: 10)
• --global — Search across ALL projects in ~/.claude/projects/
• -p, --project <path> — Project root to search (default: current directory)

Previously saved results can be browsed:

sheal ask-list              # List saved results
sheal ask-list --global     # List global results
sheal ask-show "beads"      # Show a specific saved result

sheal browse

Interactive TUI to explore sessions, retrospectives, and learnings across all your projects.

sheal browse                       # Full TUI (project list)
sheal browse sessions              # Jump to sessions view
sheal browse retros                # Jump to retros view
sheal browse learnings             # Jump to learnings view
sheal browse digests               # Browse digest reports
sheal browse -p myproject          # Pre-filter by project name
sheal browse --agent codex         # Pre-filter by agent

Supports Claude Code, Codex, Amp, and Entire.io sessions. Claude and Codex sessions that are visible in the live home directories but not yet present in .sheal/sessions/raw/ are marked as not backed up, and the sessions view offers to add them to the registry.

sheal sessions import

Import Claude Code and Codex transcripts from live home directories, or from an explicit source root, into the current project's raw session registry.

sheal sessions import              # Import from ~/.claude and ~/.codex
sheal sessions import --source /tmp/agent-home
sheal sessions import --format json

Imported sessions are written to .sheal/sessions/raw/<stable-session-id>/ with manifest.json, transcript.raw.jsonl, and normalized.json. Live-home and explicit-source imports do not create pull staging ingested.json markers.

sheal export

Export session data as JSON for scripting and piping.

sheal export                       # List sessions (current project)
sheal export --checkpoint <id>     # Export a specific checkpoint
sheal export --global              # Export all projects and sessions

sheal pull

Acquire local sandbox changes into sheal's staging area. The shipped local path supports sbx sandboxes and Docker containers, capturing git diff, agent artifacts, and transcripts from runtime home directories when present. Missing agent-specific transcript paths are reported as gaps in the pull output and provenance. Agent home artifacts are discovered by probing supported agent directories under the sandbox user's home directory ($HOME/.claude, $HOME/.codex, $HOME/.copilot, $HOME/.cursor, $HOME/.docker-agent, $HOME/.droid, $HOME/.gemini, $HOME/.kiro, and $HOME/.opencode). Missing home probes are ignored. Transcripts are pulled from known agent home paths such as $HOME/.claude/sessions.jsonl, $HOME/.claude/history.jsonl, $HOME/.claude/projects/<project-slug>/, and $HOME/.codex/sessions/ when present. Workspace files such as AGENTS.md, MEMORY.md, and .sheal/session.jsonl are not part of the pull capture contract.

sheal pull --list                  # List available sbx sandboxes and Docker containers
sheal pull sbx <name>              # Pull one sbx sandbox to ~/.sheal/pulls/
sheal pull sbx <name> --checkpoint # Write a checkpoint stage without registry import
sheal pull --checkpoint-run        # Run configured checkpoint targets once
sheal pull sbx --all               # Pull every sbx sandbox with a workspace
sheal pull docker <name>           # Pull one Docker container selected from --list

Use sheal pull --list first to copy the exact sandbox or container name. Docker selection is intentionally human-driven, so sheal pull docker --all is not supported. Pull acquisition output lands under ~/.sheal/pulls/<backend>/<name>/<timestamp>/ unless pull.stagingDir overrides it. Pulled Claude and Codex transcripts are normalized into the project-local raw registry at .sheal/sessions/raw/<stable-session-id>/; the pull staging directory gets an ingested.json marker pointing at the raw session IDs.

Use --checkpoint with sheal pull <backend> <name> for a manual mid-session capture before teardown. Checkpoint mode uses the same local adapter capture set and staging root, writes checkpoint.json, stamps provenance with captureKind: "checkpoint", and does not normalize transcripts into the raw registry or write an ingested.json marker. Long-running daemon scheduling is a future layer over this manual checkpoint primitive.

Use --checkpoint-run to run a one-shot checkpoint pass over explicitly configured local targets:

{
  "pull": {
    "checkpointTargets": [
      { "backend": "sbx", "name": "codex-before-teardown" }
    ]
  }
}

The runner never implies --all: only pull.checkpointTargets are checkpointed, unconfigured sandboxes are ignored, and checkpoint stages still do not import into the raw registry.

sheal init

Bootstrap sheal awareness into your project's agent configuration files (CLAUDE.md, .cursorrules, etc.).

sheal init                         # Add sheal instructions to agent configs
sheal init --dry-run               # Preview changes without writing

sheal graph

Cross-session knowledge graph showing file hotspots, agent activity, and patterns.

sheal graph                        # Pretty-print graph summary
sheal graph --file src/index.ts    # History for a specific file
sheal graph --agent claude         # Details for a specific agent
sheal graph --json                 # JSON output

sheal digest

Categorized digest of all your prompts across agents. See what you actually worked on.

sheal digest                           # Last 7 days, pretty output
sheal digest --since "1 month"         # Custom window
sheal digest --enrich                  # LLM-powered categorization (Haiku)
sheal digest --compare                 # Diff against previous digest
sheal digest -p myproject              # Filter to one project
sheal digest -f markdown -o report.md  # Export as markdown

The --enrich flag uses Haiku to smart-categorize prompts that rule-based matching missed. The --compare flag finds the previous digest for the same scope and shows what changed.

sheal cost

Token cost dashboard — see exactly where your Claude budget goes.