Skip to content
Back to search

sheal

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
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/liwala--sheal/badge.svg)](/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)

  1. <p align="center">
  2. <img src="assets/sheal-mascot.png" width="200" alt="sheal mascot" />
  3. </p>
  4. <h1 align="center">sheal</h1>
  5. <p align="center"><b>your ai agent keeps making the same mistakes. sheal fixes that.</b></p>
  6. <p align="center">
  7. <a href="https://github.com/liwala/sheal/stargazers"><img src="https://img.shields.io/github/stars/liwala/sheal?style=flat-square" alt="stars" /></a>
  8. <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>
  9. <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="license" /></a>
  10. </p>
  11. <p align="center">
  12. <a href="#install">Install</a> &bull;
  13. <a href="#quick-start">Quick Start</a> &bull;
  14. <a href="#commands">Commands</a> &bull;
  15. <a href="#how-it-works">How It Works</a> &bull;
  16. <a href="#supported-agents">Agents</a>
  17. </p>
  18. ---
  19. <p align="center">
  20. <img src="assets/sheal-hero.png" width="700" alt="sheal hero banner" />
  21. </p>
  22. A CLI toolkit that analyzes AI coding sessions to extract learnings, detect failure patterns, and continuously improve agent behavior.
  23. 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.
  24. <p align="center">
  25. <img src="assets/sheal-evolution.png" width="700" alt="session 1 to session 20 — zero repeated mistakes" />
  26. </p>
  27. ## Install
  28. ```bash
  29. npm install -g @liwala/sheal
  30. ```
  31. Or from source:
  32. ```bash
  33. git clone https://github.com/liwala/sheal
  34. cd sheal
  35. npm install
  36. npx tsc
  37. npm link
  38. ```
  39. ## Quick Start
  40. ```bash
  41. # Health check your project setup
  42. sheal check
  43. # Audit your Claude Code settings (permissions, hooks, MCPs)
  44. sheal audit
  45. # Run a retrospective on your latest session
  46. sheal retro
  47. # See your token spend per project
  48. sheal cost
  49. # Get a categorized digest of what you worked on
  50. sheal digest --since "7 days"
  51. # Ask a question across all your sessions
  52. sheal ask "what went wrong with beads?" --agent claude
  53. # Add a learning from experience
  54. sheal learn add "Always inspect real data before writing parsers" --tags=parsing
  55. ```
  56. ## Commands
  57. ### `sheal check`
  58. Pre-session health check. Detects environment issues before you start coding.
  59. ```bash
  60. sheal check # Pretty output
  61. sheal check --format json # JSON output
  62. sheal check --skip performance # Skip specific checkers
  63. sheal check --strict # Warnings are blockers: exit non-zero on any warning
  64. ```
  65. **Checkers:** git status, dependencies, tests, environment, session learnings, performance & efficiency, Claude Code settings.
  66. ### `sheal guard`
  67. Point-in-time gates compiled from learnings, designed for hooks and CI.
  68. ```bash
  69. sheal guard pr # Pre-PR gate: branch must be ahead of base, exit 1 otherwise
  70. sheal guard pr --base develop # Non-main base branch
  71. ```
  72. `guard pr` verifies HEAD is a working branch (not the base itself), that
  73. `git rev-list base..HEAD` is non-empty (an empty PR is always a mistake), and
  74. warns on uncommitted changes. Wire it into a PreToolUse hook on `gh pr create`
  75. or a CI step.
  76. 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.
  77. ### `sheal audit`
  78. Audit Claude Code settings across all scopes — permissions, hooks, MCP servers, environment variables, and plugins.
  79. ```bash
  80. sheal audit # Pretty output
  81. sheal audit --format json # JSON output
  82. sheal audit -p /path/to/project # Different project root
  83. ```
  84. Reads from all four settings files (global, global-local, project, project-local) and shows a merged view of what's configured where.
  85. ### `sheal retro`
  86. Session retrospective. Analyzes the most recent AI coding session for failure loops, wasted effort, and learnings.
  87. ```bash
  88. sheal retro # Static analysis (latest session)
  89. sheal retro --checkpoint <id> # Specific session
  90. sheal retro --enrich # LLM-enriched deep analysis
  91. sheal retro --enrich --agent amp # Use a specific agent CLI
  92. sheal retro --prompt # Output raw prompt (pipe to any LLM)
  93. sheal retro --format json # JSON output
  94. ```
  95. 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/`.
  96. ### `sheal ask <question>`
  97. Query across your session transcripts using natural language. Uses a 3-phase pipeline:
  98. 1. **Extract search terms** from your question (agent-assisted, with local fallback)
  99. 2. **Local grep** across sessions using those terms (word-boundary matching)
  100. 3. **Agent analyzes** relevant excerpts to answer your question (falls back to raw excerpts)
  101. ```bash
  102. # Search current project's sessions
  103. sheal ask "what went wrong with beads?"
  104. # Use a specific agent for analysis
  105. sheal ask "how did we handle the auth migration?" --agent codex
  106. # Search ALL projects globally
  107. sheal ask --global "what patterns keep causing test failures?"
  108. # Search a different project
  109. sheal ask -p /path/to/other-project "what happened with the auth migration?"
  110. # Search more sessions
  111. sheal ask "show me all test failures" -n 20
  112. ```
  113. Options:
  114. - `--agent <name>` — Agent CLI to use: `claude`, `gemini`, `codex`, `amp`
  115. - `-n, --limit <count>` — Max sessions to search (default: 10)
  116. - `--global` — Search across ALL projects in `~/.claude/projects/`
  117. - `-p, --project <path>` — Project root to search (default: current directory)
  118. Previously saved results can be browsed:
  119. ```bash
  120. sheal ask-list # List saved results
  121. sheal ask-list --global # List global results
  122. sheal ask-show "beads" # Show a specific saved result
  123. ```
  124. ### `sheal browse`
  125. Interactive TUI to explore sessions, retrospectives, and learnings across all your projects.
  126. ```bash
  127. sheal browse # Full TUI (project list)
  128. sheal browse sessions # Jump to sessions view
  129. sheal browse retros # Jump to retros view
  130. sheal browse learnings # Jump to learnings view
  131. sheal browse digests # Browse digest reports
  132. sheal browse -p myproject # Pre-filter by project name
  133. sheal browse --agent codex # Pre-filter by agent
  134. ```
  135. Supports Claude Code, Codex, Amp, and Entire.io sessions. Claude and Codex
  136. sessions that are visible in the live home directories but not yet present in
  137. `.sheal/sessions/raw/` are marked as not backed up, and the sessions view offers
  138. to add them to the registry.
  139. ### `sheal sessions import`
  140. Import Claude Code and Codex transcripts from live home directories, or from an
  141. explicit source root, into the current project's raw session registry.
  142. ```bash
  143. sheal sessions import # Import from ~/.claude and ~/.codex
  144. sheal sessions import --source /tmp/agent-home
  145. sheal sessions import --format json
  146. ```
  147. Imported sessions are written to
  148. `.sheal/sessions/raw/<stable-session-id>/` with `manifest.json`,
  149. `transcript.raw.jsonl`, and `normalized.json`. Live-home and explicit-source
  150. imports do not create pull staging `ingested.json` markers.
  151. ### `sheal export`
  152. Export session data as JSON for scripting and piping.
  153. ```bash
  154. sheal export # List sessions (current project)
  155. sheal export --checkpoint <id> # Export a specific checkpoint
  156. sheal export --global # Export all projects and sessions
  157. ```
  158. ### `sheal pull`
  159. Acquire local sandbox changes into sheal's staging area. The shipped local path
  160. supports `sbx` sandboxes and Docker containers, capturing git diff, agent
  161. artifacts, and transcripts from runtime home directories when present. Missing
  162. agent-specific transcript paths are reported as gaps in the pull output and
  163. provenance.
  164. Agent home artifacts are discovered by probing supported agent directories under
  165. the sandbox user's home directory (`$HOME/.claude`, `$HOME/.codex`,
  166. `$HOME/.copilot`, `$HOME/.cursor`, `$HOME/.docker-agent`, `$HOME/.droid`,
  167. `$HOME/.gemini`, `$HOME/.kiro`, and `$HOME/.opencode`). Missing home probes are
  168. ignored. Transcripts are pulled from known agent home paths such as
  169. `$HOME/.claude/sessions.jsonl`, `$HOME/.claude/history.jsonl`,
  170. `$HOME/.claude/projects/<project-slug>/`, and `$HOME/.codex/sessions/` when
  171. present. Workspace files such as `AGENTS.md`, `MEMORY.md`, and
  172. `.sheal/session.jsonl` are not part of the pull capture contract.
  173. ```bash
  174. sheal pull --list # List available sbx sandboxes and Docker containers
  175. sheal pull sbx <name> # Pull one sbx sandbox to ~/.sheal/pulls/
  176. sheal pull sbx <name> --checkpoint # Write a checkpoint stage without registry import
  177. sheal pull --checkpoint-run # Run configured checkpoint targets once
  178. sheal pull sbx --all # Pull every sbx sandbox with a workspace
  179. sheal pull docker <name> # Pull one Docker container selected from --list
  180. ```
  181. Use `sheal pull --list` first to copy the exact sandbox or container name.
  182. Docker selection is intentionally human-driven, so `sheal pull docker --all` is
  183. not supported. Pull acquisition output lands under
  184. `~/.sheal/pulls/<backend>/<name>/<timestamp>/` unless `pull.stagingDir`
  185. overrides it. Pulled Claude and Codex transcripts are normalized into the
  186. project-local raw registry at `.sheal/sessions/raw/<stable-session-id>/`; the
  187. pull staging directory gets an `ingested.json` marker pointing at the raw
  188. session IDs.
  189. Use `--checkpoint` with `sheal pull <backend> <name>` for a manual mid-session
  190. capture before teardown. Checkpoint mode uses the same local adapter capture set
  191. and staging root, writes `checkpoint.json`, stamps provenance with
  192. `captureKind: "checkpoint"`, and does not normalize transcripts into the raw
  193. registry or write an `ingested.json` marker. Long-running daemon scheduling is a
  194. future layer over this manual checkpoint primitive.
  195. Use `--checkpoint-run` to run a one-shot checkpoint pass over explicitly
  196. configured local targets:
  197. ```json
  198. {
  199. "pull": {
  200. "checkpointTargets": [
  201. { "backend": "sbx", "name": "codex-before-teardown" }
  202. ]
  203. }
  204. }
  205. ```
  206. The runner never implies `--all`: only `pull.checkpointTargets` are
  207. checkpointed, unconfigured sandboxes are ignored, and checkpoint stages still do
  208. not import into the raw registry.
  209. ### `sheal init`
  210. Bootstrap sheal awareness into your project's agent configuration files (CLAUDE.md, .cursorrules, etc.).
  211. ```bash
  212. sheal init # Add sheal instructions to agent configs
  213. sheal init --dry-run # Preview changes without writing
  214. ```
  215. ### `sheal graph`
  216. Cross-session knowledge graph showing file hotspots, agent activity, and patterns.
  217. ```bash
  218. sheal graph # Pretty-print graph summary
  219. sheal graph --file src/index.ts # History for a specific file
  220. sheal graph --agent claude # Details for a specific agent
  221. sheal graph --json # JSON output
  222. ```
  223. ### `sheal digest`
  224. Categorized digest of all your prompts across agents. See what you actually worked on.
  225. ```bash
  226. sheal digest # Last 7 days, pretty output
  227. sheal digest --since "1 month" # Custom window
  228. sheal digest --enrich # LLM-powered categorization (Haiku)
  229. sheal digest --compare # Diff against previous digest
  230. sheal digest -p myproject # Filter to one project
  231. sheal digest -f markdown -o report.md # Export as markdown
  232. ```
  233. 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.
  234. ### `sheal cost`
  235. Token cost dashboard — see exactly where your Claude budget goes.
  236. ```bash
  237. sheal cost # Last 7 days
  238. sheal cost --since "1 month" # Custom window
  239. sheal cost -p myproject # Single project
  240. sheal cost --plan "Max 5x" # Compare against your plan
  241. sheal cost --format json # JSON output for scripting
  242. ```
  243. 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.
  244. ### `sheal weekly`
  245. Full weekly report — runs digest + cost together, optionally with deep Claude analysis and Slack delivery.
  246. ```bash
  247. sheal weekly # Digest + cost for last 7 days
  248. sheal weekly --agent # Add deep LLM analysis
  249. sheal weekly --slack # Post summary to Slack
  250. sheal weekly --plan "Max 20x" # Include plan savings
  251. ```
  252. Reports are saved to `~/.sheal/weekly-digests/` for historical tracking.
  253. ### `sheal drift`
  254. 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.
  255. ```bash
  256. sheal drift # Check learnings against last 10 sessions
  257. sheal drift -n 20 # Check against more sessions
  258. sheal drift -p /path/to/project # Different project root
  259. sheal drift --json # JSON output
  260. ```
  261. 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).
  262. **Detection methods:**
  263. - **Keyword matching** — compares session retro learnings against your active learnings
  264. - **Failure loop detection** — flags retry-related learnings when retries recur
  265. - **File churn detection** — flags planning-related learnings when wasted edits recur
  266. - **Enrichment parsing** — reads `Recurring` sections from LLM-enriched retros
  267. ### `sheal learn`
  268. Manage ADR-style session learnings. Learnings are stored as individual markdown files with frontmatter metadata.
  269. ```bash
  270. # Add a learning (saves to project by default)
  271. sheal learn add "Always check bd --help before guessing flags" \
  272. --tags=beads,cli --category=workflow --severity=high
  273. sheal learn add --global "..." # Save directly to global store
  274. # List learnings
  275. sheal learn list # Project learnings (.sheal/learnings/)
  276. sheal learn list --global # Global learnings (~/.sheal/learnings/)
  277. sheal learn list --tag=beads # Filter by tag
  278. # Review & curate learnings interactively
  279. sheal learn review # Project learnings (drafts shown first)
  280. sheal learn review --global # Global learnings
  281. # Promote curated project learnings to global
  282. sheal learn promote
  283. # Pull global learnings into project (by tag match)
  284. sheal learn sync
  285. # Corpus hygiene: duplicate IDs, near-duplicate rules, missing triggers
  286. sheal learn lint # Exit 1 on findings (CI-usable)
  287. sheal learn lint --format json
  288. # Consolidation pass: emit a reviewable change set (never mutates the store)
  289. sheal consolidate # Writes .sheal/consolidation/<date>-change-set.md
  290. sheal consolidate --format json # Mechanical change set to stdout
  291. sheal consolidate --prompt # LLM judgment-stage prompt — pipe to any agent CLI
  292. ```
  293. #### Git-based backup & sync
  294. 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.
  295. ```bash
  296. # Connect to a remote repo (initializes git in ~/.sheal/)
  297. sheal backup remote add git@github.com:you/sheal-data.git
  298. # Push (learnings + digests + config)
  299. sheal backup push
  300. # Also gather retros from all projects
  301. sheal backup push --include retros
  302. # Pull from remote
  303. sheal backup pull
  304. # Show or disconnect
  305. sheal backup remote show
  306. sheal backup remote remove
  307. # learn push/pull are aliases for backup push/pull
  308. sheal learn push
  309. sheal learn pull
  310. ```
  311. #### Human-in-the-loop curation
  312. Learnings are never auto-accepted. Every learning goes through human review before it can influence agent behavior:
  313. 1. **`sheal retro --enrich`** — the LLM extracts candidate rules from the session
  314. 2. **Saved as drafts** — rules land in `.sheal/learnings/` with `status: draft`
  315. 3. **Interactive review** — you accept, edit, or reject each draft on the spot
  316. 4. **Active learnings** — accepted rules become `status: active` and show up in `sheal learn list`
  317. 5. **`sheal learn promote`** — lift project learnings to your global store (`~/.sheal/learnings/`)
  318. 6. **`sheal learn sync`** — pull relevant global learnings back into other projects
  319. 7. **`sheal rules`** — inject active learnings into agent config files (AGENTS.md, .cursorrules)
  320. You can also add learnings manually (`sheal learn add "..."`) or review remaining drafts later (`sheal learn review`).
  321. The full lifecycle:
  322. ```
  323. retro → project drafts → review → active → promote → global ─┐
  324. ▲ │ digests ──┤
  325. │ human accepts config ──┼─ backup push → remote
  326. learn add edits, or rejects retros ──┘ backup pull ← remote
  327. global ──── sync → project
  328. ```
  329. **Learning format** (`~/.sheal/learnings/LEARN-001-inspect-real-data.md`):
  330. ```markdown
  331. ---
  332. id: LEARN-001
  333. title: Inspect real data before writing parsers
  334. date: 2026-03-13
  335. tags: [parsing, external-data, general]
  336. category: missing-context
  337. severity: high
  338. status: active
  339. ---
  340. Before writing parsers for external data formats, always inspect 2-3 real
  341. samples first. Don't rely solely on documentation or type definitions.
  342. ```
  343. Categories: `missing-context`, `failure-loop`, `wasted-effort`, `environment`, `workflow`
  344. ## Session Sources
  345. `sheal` supports two session data sources with automatic fallback:
  346. 1. **Native Claude Code** — reads JSONL transcripts directly from `~/.claude/projects/` (default)
  347. 2. **Entire.io** — reads from the `entire/checkpoints/v1` git branch (rich metadata, AI summaries, attribution)
  348. ## Supported Agents
  349. For `--enrich` and `ask` commands, `sheal` can invoke these agent CLIs:
  350. | Agent | CLI Command | Invocation |
  351. |-------|-------------|------------|
  352. | Claude Code | `claude` | `claude -p --output-format text` (stdin) |
  353. | Codex | `codex` | `codex exec -` (stdin) |
  354. | Amp | `amp` | `amp -x` (stdin) |
  355. | Gemini CLI | `gemini` | stdin pipe |
  356. 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.
  357. ## How It Works
  358. ```
  359. Session Capture (Entire.io / Claude Code native)
  360. | session transcripts, diffs, metadata
  361. v
  362. Self-Healing Engine (sheal)
  363. | failure patterns, learnings, rules
  364. v
  365. Agent Configuration (CLAUDE.md, .cursorrules, etc.)
  366. | improved behavior
  367. v
  368. Next Session (fewer mistakes)
  369. ```
  370. ## Configuration
  371. `sheal` reads an optional `.self-heal.json` from the project root (or the nearest
  372. ancestor directory). It configures checkers and pull staging, e.g.:
  373. ```json
  374. {
  375. "checkers": {
  376. "tests": { "timeoutMs": 30000 },
  377. "environment": {
  378. "requiredVars": ["DATABASE_URL"],
  379. "requiredServices": [{ "name": "postgres", "check": "pg_isready -p 5432" }]
  380. }
  381. }
  382. }
  383. ```
  384. A `.self-heal.local.json` next to it (gitignored) is merged over the shared
  385. config field by field — use it for machine-local checks and private tooling
  386. that don't belong in the repo.
  387. ## Development
  388. ```bash
  389. npx tsc # Build
  390. npx vitest run # Test
  391. sheal check # Dogfood
  392. ```
  393. ## License
  394. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.