tigerless-labs/autoharness

AutoHarness – a self‑learning skill layer for Claude Code

What it is

• A Claude Code plugin that watches your coding sessions, extracts reusable “skills” (small snippets of logic or instructions) and stores them as plain files under .claude/skills/.
• The plugin continuously learns, merges similar skills, prunes unused ones, and keeps an index that Claude shows at the start of every session.
• All of this runs in pure Python 3.11+ with no third‑party dependencies.

Key ideas

Idea	How it works
Learn from real work	After a configurable number of tool calls (AUTOHARNESS_REFLECT_EVERY_N) the plugin captures the episode, distills it into a skill, and writes it to disk. You can also force a distillation with the /learn command.
Avoid duplicate bloat	New episodes are compared to existing skills; if they cover the same scenario the plugin folds them together, updating the original skill instead of creating a near‑duplicate.
Self‑maintaining library	Skills have a lifecycle: probation → maturity → possible archiving when a layer exceeds its capacity. Usage counters are based on actual loads (when Claude actually invokes the skill), not wall‑clock time.
Transparent indexing	At the start of each session Claude receives a grouped index of the plugin‑generated skills (short descriptions only). The host’s native recall mechanism is untouched; the plugin merely adds this extra surface.
Evidence ledger	Every creation, patch, or deletion is logged in an append‑only *.ledger.jsonl file with a human‑readable reason and a reference to the exact transcript slice that triggered the change.

Installation

1. Ensure python3 on your PATH is version 3.11 or newer.
2. In a Claude Code chat, run:

   /plugin marketplace add tigerless-labs/autoharness
   /plugin install autoharness@autoharness
   /reload-plugins   # or restart Claude Code
   

3. The plugin now runs in the background, watching sessions and writing skills under .claude/skills/ (project) or ~/.claude/skills/ (global).

Main entry point

• /learn – forces an immediate distillation of the current session into a skill.

Configuration (environment variables)

• Placement – AUTOHARNESS_DISABLE_GLOBAL=1 limits the plugin to the current repo.
• Cadence – AUTOHARNESS_REFLECT_EVERY_N (default 50) controls how many tool calls trigger a reflection; AUTOHARNESS_CONSOLIDATE_EVERY_N (default 250) controls the rarer whole‑library merge pass.
• Recall – AUTOHARNESS_INDEX_SUSPENDED=1 disables injecting the skill index; description length limits (*_DESC_MAX_CHARS) tune how much context the index consumes.
• Lifecycle – maturity thresholds (*_MATURITY_*) and capacity caps (*_CAPACITY_*) decide when a skill graduates and when excess mature skills are archived.
• Notifications – set AUTOHARNESS_NOTIFY=desktop for OS notifications, or point AUTOHARNESS_NOTIFY_CMD at a custom script to receive JSON run records.

How it works internally

• CAP captures each turn (user, Claude output, tool I/O) and redacts it.
• REF reads the captured episode, compares it to the current skill index, and proposes an intent (create/merge/patch/delete).
• Promoter validates the intent, lints the skill file, and atomically writes it to the live skill directory.
• IDX builds the session‑start index that Claude sees.
• MNG lazily computes usage rates and decides graduation/archival.
• Curator runs periodically to merge near‑duplicate skills across the whole library.
• LED records every change with reason and evidence.

Where the data lives

~/.claude/autoharness/          # global state
.claude/autoharness/            # per‑project state
.claude/skills/<skill‑name>/    # each skill (SKILL.md, .ledger.jsonl, references/…)

Uninstalling the plugin stops the background process, but the generated skills and state remain until you delete those directories manually.

Who might use it

• Developers who spend a lot of time in Claude Code and want their repeated patterns to become reusable, auto‑documented snippets.
• Teams that want a lightweight, version‑controlled skill library that self‑prunes without manual curation.
• Anyone interested in experimenting with a “self‑maintaining” LLM‑assistant that learns directly from production usage rather than a separate training dataset.