Guide · Open source

How to use autoharness: install and run it in Claude Code

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

autoharness is an open-source plugin for Claude Code, Anthropic's coding assistant. It watches your working sessions, turns useful episodes into skill files under .claude/skills/, and keeps that library tidy over time. This guide shows you how to install it, what it does in the background, how to find and control the skills it writes, and how to tune or remove it.

AutoHarnesstigerless-labs/autoharness · ★ 10.6k · MIT Install options & downloads

Quick start

1Confirm Python 3.11+ is on PATH. Run python3 --version in your terminal. If it reports a version older than 3.11, install a newer Python and make sure python3 points to it.
2Add the marketplace. In the Claude Code input box, type /plugin marketplace add tigerless-labs/autoharness.
3Install the plugin. Type /plugin install autoharness@autoharness in Claude Code.
4Reload plugins. Run /reload-plugins, or restart Claude Code, so the plugin starts.
5Work normally. Use Claude Code as usual. Learned skills appear in .claude/skills/ over time as reflection runs in the background.
6Review the skills. Open .claude/skills/ and check the files that carry the self-authored marker. Edit or delete any you do not want.

What autoharness does

While you work in Claude Code, autoharness distills useful episodes from your sessions into reusable skill files. It merges skills covering the same scenario instead of stacking near-duplicates, updates skills as they are used, and removes ones that stop being used.

It only manages skills it generated itself. Skills you wrote or installed are left alone.

Check the prerequisites before you install

autoharness runs entirely as Python with no third-party dependencies, but it needs Python 3.11 or newer available as python3 on your PATH. Its hooks and MCP server will not run without it.

Claude Code installed
Python 3.11+ available as python3 on your PATH
The README notes that macOS Xcode ships Python 3.9.6 at /usr/bin/python3; if that is the python3 found first, the hooks stay off for the session and autoharness reports this on stderr

python3 --version

Install the plugin inside Claude Code

Type these two commands in the Claude Code input box. The first adds the marketplace, the second installs the plugin from it.

Then run /reload-plugins, or restart Claude Code. The plugin needs no configuration to start working.

/plugin marketplace add tigerless-labs/autoharness
/plugin install autoharness@autoharness

Let it learn in the background, or trigger a lesson with /learn

You do not need to invoke autoharness for normal use. Reflection is counted in tool calls rather than turns, so a working stretch triggers it and a conversation that only talks does not. Learned skills land in .claude/skills/ in the background.

If you want a lesson kept right now, run /learn after you have worked something out. It distills the session you are in through the same proposal and validation process the background pass uses.

/learn

Find and manage the skills it creates

Each skill is a plain file. Skills autoharness wrote carry a self-authored ledger marker, so you can tell them apart from your own. Every create or update is logged with its scenario and decision to a per-skill ledger.

A merge is recorded as one skill absorbing another, so a merged skill is not mistaken for a deleted one. Every session starts with a grouped index of the skills it wrote.

Project skills: .claude/skills/ in your repository
State directory per project: <repo>/.claude/autoharness/
State directory for global use: ~/.claude/autoharness/

Tune the pace and layers with environment variables

Every setting is an AUTOHARNESS_* environment variable with a built-in default, so you only change these if you want to alter the pace or scope. The defaults below come from the README.

AUTOHARNESS_REFLECT_EVERY_N (default 50): tool calls between reflections. Lower values learn faster and spawn more child sessions.
AUTOHARNESS_CONSOLIDATE_EVERY_N (default 250): tool calls between library-wide merge passes.
AUTOHARNESS_DISABLE_GLOBAL (default 0): set to 1 for a project-only deployment. Existing global skills stay untouched.
AUTOHARNESS_INDEX_SUSPENDED (default 0): set to 1 to stop injecting the skill index into the model's context.
AUTOHARNESS_CARRIER (default bundle): bundle hands a redacted window to a fresh subagent; fork resumes and forks the session that just ended.

Update or uninstall autoharness

To update from a terminal, refresh the catalog by marketplace name, then update the plugin by its full plugin@marketplace id, then restart Claude Code. The README says the refresh step matters, since an update without it can check a stale catalog.

Uninstalling only stops the plugin from running. Its learned skills and state stay on disk until you delete them yourself. Your own skills are never touched.

Delete the state directory (~/.claude/autoharness/ globally, or <repo>/.claude/autoharness/ per project)
Delete the self-authored skills under .claude/skills/, identified by their self-authored marker

claude plugin marketplace update autoharness
claude plugin update autoharness@autoharness
claude plugin uninstall autoharness@autoharness
claude plugin marketplace remove autoharness

What people use it for

A developer who repeats the same kinds of tasks in one codebase and wants recurring procedures captured as project skills.
A team that wants project-level skills to build up without someone maintaining them by hand.
A user who wants to inspect and control what the assistant learns, since every skill is a plain file with a ledger.

Frequently asked questions

Is autoharness free to use?

autoharness is released under the MIT licence, as listed in its repository. The README does not mention any paid tier.

What do I need to run autoharness?

You need Claude Code and Python 3.11 or newer available as python3 on your PATH. The plugin has no third-party Python dependencies.

Does autoharness work outside Claude Code?

No. The plugin only runs inside Claude Code, so it is not useful if you do not use that tool.

Why aren't any skills being created?

Check that python3 on your PATH is version 3.11 or newer, since older versions turn the hooks off. Also remember that reflection is counted in tool calls, so a conversation with no tool use will not trigger it. You can run /learn to distill the current session on demand.

Will autoharness delete my own skills?

No. It only manages skills it generated through the plugin. Skills you wrote or installed are left completely alone.

How does autoharness compare to other tools?

This directory does not list a comparable project for autoharness, so we cannot make a direct comparison. The README says its skill quality is validated through use rather than a benchmark score.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

autoharness suits developers who use Claude Code heavily and repeat the same kinds of tasks, especially teams that want project skills to build up with little upkeep. Skip it if you do not use Claude Code, cannot run Python 3.11 or newer as python3, or need a measured benchmark score for skill quality.

Install options & downloads