Back to search
sheal
SkillGitHub
self-healing and self-learning loop for coding agents
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Checked today
Badge for your README
Markdown
[](/listings/liwala--sheal)HTML
<a href="/listings/liwala--sheal"><img src="/api/listings/liwala--sheal/badge.svg" alt="findsafeskills safety rating" /></a>Install
i
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
npm install -g @liwala/sheal
Or from source:
git clone https://github.com/liwala/sheal cd sheal npm install npx tsc npm link
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 529 lines
View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)
- <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> •
- <a href="#quick-start">Quick Start</a> •
- <a href="#commands">Commands</a> •
- <a href="#how-it-works">How It Works</a> •
- <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
- ```bash
- npm install -g @liwala/sheal
- ```
- Or from source:
- ```bash
- git clone https://github.com/liwala/sheal
- cd sheal
- npm install
- npx tsc
- npm link
- ```
- ## Quick Start
- ```bash
- # 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.
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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)
- ```bash
- # 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:
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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:
- ```json
- {
- "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.).
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- 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.
- ```bash
- sheal cost # Last 7 days
- sheal cost --since "1 month" # Custom window
- sheal cost -p myproject # Single project
- sheal cost --plan "Max 5x" # Compare against your plan
- sheal cost --format json # JSON output for scripting
- ```
- Shows per-model breakdown, per-project spend, project-by-model matrix, cost type split (input/output/cache-read/cache-write), and subscription savings vs Pro / Max 5x / Max 20x plans.
- ### `sheal weekly`
- Full weekly report — runs digest + cost together, optionally with deep Claude analysis and Slack delivery.
- ```bash
- sheal weekly # Digest + cost for last 7 days
- sheal weekly --agent # Add deep LLM analysis
- sheal weekly --slack # Post summary to Slack
- sheal weekly --plan "Max 20x" # Include plan savings
- ```
- Reports are saved to `~/.sheal/weekly-digests/` for historical tracking.
- ### `sheal drift`
- Detect when learnings aren't being applied in recent sessions. Compares your active learnings (both global and project-scoped) against session data to find patterns that should have been prevented but weren't.
- ```bash
- sheal drift # Check learnings against last 10 sessions
- sheal drift -n 20 # Check against more sessions
- sheal drift -p /path/to/project # Different project root
- sheal drift --json # JSON output
- ```
- Each drifted learning is labeled `[global]` or `[project]` so you can see where the violation originated. Severity dots indicate how often the learning was violated (● once, ●● twice, ●●● three or more times).
- **Detection methods:**
- - **Keyword matching** — compares session retro learnings against your active learnings
- - **Failure loop detection** — flags retry-related learnings when retries recur
- - **File churn detection** — flags planning-related learnings when wasted edits recur
- - **Enrichment parsing** — reads `Recurring` sections from LLM-enriched retros
- ### `sheal learn`
- Manage ADR-style session learnings. Learnings are stored as individual markdown files with frontmatter metadata.
- ```bash
- # Add a learning (saves to project by default)
- sheal learn add "Always check bd --help before guessing flags" \
- --tags=beads,cli --category=workflow --severity=high
- sheal learn add --global "..." # Save directly to global store
- # List learnings
- sheal learn list # Project learnings (.sheal/learnings/)
- sheal learn list --global # Global learnings (~/.sheal/learnings/)
- sheal learn list --tag=beads # Filter by tag
- # Review & curate learnings interactively
- sheal learn review # Project learnings (drafts shown first)
- sheal learn review --global # Global learnings
- # Promote curated project learnings to global
- sheal learn promote
- # Pull global learnings into project (by tag match)
- sheal learn sync
- # Corpus hygiene: duplicate IDs, near-duplicate rules, missing triggers
- sheal learn lint # Exit 1 on findings (CI-usable)
- sheal learn lint --format json
- # Consolidation pass: emit a reviewable change set (never mutates the store)
- sheal consolidate # Writes .sheal/consolidation/<date>-change-set.md
- sheal consolidate --format json # Mechanical change set to stdout
- sheal consolidate --prompt # LLM judgment-stage prompt — pipe to any agent CLI
- ```
- #### Git-based backup & sync
- Back up `~/.sheal/` to a git repo for cross-machine sync and team sharing. By default backs up learnings, digests, and config. Optionally includes retros from all projects.
- ```bash
- # Connect to a remote repo (initializes git in ~/.sheal/)
- sheal backup remote add git@github.com:you/sheal-data.git
- # Push (learnings + digests + config)
- sheal backup push
- # Also gather retros from all projects
- sheal backup push --include retros
- # Pull from remote
- sheal backup pull
- # Show or disconnect
- sheal backup remote show
- sheal backup remote remove
- # learn push/pull are aliases for backup push/pull
- sheal learn push
- sheal learn pull
- ```
- #### Human-in-the-loop curation
- Learnings are never auto-accepted. Every learning goes through human review before it can influence agent behavior:
- 1. **`sheal retro --enrich`** — the LLM extracts candidate rules from the session
- 2. **Saved as drafts** — rules land in `.sheal/learnings/` with `status: draft`
- 3. **Interactive review** — you accept, edit, or reject each draft on the spot
- 4. **Active learnings** — accepted rules become `status: active` and show up in `sheal learn list`
- 5. **`sheal learn promote`** — lift project learnings to your global store (`~/.sheal/learnings/`)
- 6. **`sheal learn sync`** — pull relevant global learnings back into other projects
- 7. **`sheal rules`** — inject active learnings into agent config files (AGENTS.md, .cursorrules)
- You can also add learnings manually (`sheal learn add "..."`) or review remaining drafts later (`sheal learn review`).
- The full lifecycle:
- ```
- retro → project drafts → review → active → promote → global ─┐
- ▲ │ digests ──┤
- │ human accepts config ──┼─ backup push → remote
- learn add edits, or rejects retros ──┘ backup pull ← remote
- global ──── sync → project
- ```
- **Learning format** (`~/.sheal/learnings/LEARN-001-inspect-real-data.md`):
- ```markdown
- ---
- id: LEARN-001
- title: Inspect real data before writing parsers
- date: 2026-03-13
- tags: [parsing, external-data, general]
- category: missing-context
- severity: high
- status: active
- ---
- Before writing parsers for external data formats, always inspect 2-3 real
- samples first. Don't rely solely on documentation or type definitions.
- ```
- Categories: `missing-context`, `failure-loop`, `wasted-effort`, `environment`, `workflow`
- ## Session Sources
- `sheal` supports two session data sources with automatic fallback:
- 1. **Native Claude Code** — reads JSONL transcripts directly from `~/.claude/projects/` (default)
- 2. **Entire.io** — reads from the `entire/checkpoints/v1` git branch (rich metadata, AI summaries, attribution)
- ## Supported Agents
- For `--enrich` and `ask` commands, `sheal` can invoke these agent CLIs:
- | Agent | CLI Command | Invocation |
- |-------|-------------|------------|
- | Claude Code | `claude` | `claude -p --output-format text` (stdin) |
- | Codex | `codex` | `codex exec -` (stdin) |
- | Amp | `amp` | `amp -x` (stdin) |
- | Gemini CLI | `gemini` | stdin pipe |
- Use `--agent claude`, `--agent codex`, `--agent amp`, or `--agent gemini` to pick one. Auto-detection tries the session's own agent first, then falls back to any available CLI.
- ## How It Works
- ```
- Session Capture (Entire.io / Claude Code native)
- | session transcripts, diffs, metadata
- v
- Self-Healing Engine (sheal)
- | failure patterns, learnings, rules
- v
- Agent Configuration (CLAUDE.md, .cursorrules, etc.)
- | improved behavior
- v
- Next Session (fewer mistakes)
- ```
- ## Configuration
- `sheal` reads an optional `.self-heal.json` from the project root (or the nearest
- ancestor directory). It configures checkers and pull staging, e.g.:
- ```json
- {
- "checkers": {
- "tests": { "timeoutMs": 30000 },
- "environment": {
- "requiredVars": ["DATABASE_URL"],
- "requiredServices": [{ "name": "postgres", "check": "pg_isready -p 5432" }]
- }
- }
- }
- ```
- A `.self-heal.local.json` next to it (gitignored) is merged over the shared
- config field by field — use it for machine-local checks and private tooling
- that don't belong in the repo.
- ## Development
- ```bash
- npx tsc # Build
- npx vitest run # Test
- sheal check # Dogfood
- ```
- ## License
- MIT
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.