A self-teaching AI harness for Claude Code that grows smarter through use.
Autodidact is a collection of skills, hooks, agents, and a SQLite-backed learning database that gives Claude Code structured orchestration, persistent memory, and the ability to learn from its own mistakes.
- Learns from errors — captures error patterns, remembers fixes, and injects relevant knowledge into future sessions via FTS5 full-text search
- Plans before it builds — a unified
/planpipeline that clarifies requirements (Socratic interview), researches the codebase (parallel agents), and produces implementation plans - Orchestrates complex work — three tiers of orchestration:
/run(single-session),/campaign(multi-session),/fleet(parallel git worktrees) - Experiments autonomously —
/experimentruns a metric-driven THINK → TEST → REFLECT loop that hypothesizes changes, measures impact, keeps improvements, and reverts regressions - Runs unattended —
/loopdrives any execution mode autonomously with intelligent exit detection, progress tracking, and auto-selects the right orchestrator based on plan structure - Routes cheaply — a cost-ascending
/dorouter resolves most requests with zero LLM tokens (pattern match → active state → keyword heuristic → plan structure) before falling back to LLM classification - Checks quality per-edit — hooks run ruff/mypy on Python files and eslint on JavaScript files after every edit, feeding results back into the learning DB
graph TD
DO["/do — cost-ascending router<br/>T0: pattern → T1: state → T2: keyword<br/>T2.5: plan structure → T3: LLM"]
DO --> plan
DO --> run
DO --> campaign
DO --> fleet
DO --> experiment
DO --> polish
DO --> research
DO --> learn
DO --> forget
DO --> learn_status["learn-status"]
DO --> gc
DO --> create_pr["create-pr"]
DO --> handoff
DO --> sync_thoughts["sync-thoughts"]
run --> LOOP["loop — autonomous driver<br/>Wraps run, campaign, or fleet<br/>Exit detection + circuit breaker"]
campaign --> LOOP
fleet --> LOOP
| Layer | Count | Description |
|---|---|---|
| Core library | 22 modules | src/ — db, router, confidence, graduate, interview, worktree, circuit_breaker, handoff, sync, documents, git_utils, response_analyzer, progress, exit_tracker, loop, experiment, convergence, fitness, rtk_integration, self_assessment, session_miner, task_graph |
| Hooks | 9 | Python scripts on Claude Code lifecycle events (8 lifecycle hooks + shared constants) |
| Skills | 16 | Markdown protocols with 5-section format (Identity, Orientation, Protocol, Quality Gates, Exit) |
| Agents | 12 | Specialized personas: interviewer, fleet-worker, quality-scorer, python-engineer, code-reviewer, code-simplifier, security-reviewer, and 5 research agents |
| Commands | 1 | Single /do entry point — routes to skills via cost-ascending classifier |
| Tool | Required | Purpose |
|---|---|---|
| Python 3.11+ | Yes | Runtime for hooks and core library |
| uv | Yes | Package/project management; hooks run through uv run |
| Claude Code | Yes | The AI coding tool this harness extends |
| git | Yes | Version control, worktree isolation for fleet |
| gh | For PRs | GitHub CLI for pull requests |
| rtk | Recommended | Token-optimized CLI proxy — 60-90% savings on dev tool output |
| ruff | For quality checks | Linting/formatting Python files on every edit |
| mypy | Optional | Type checking Python files (runs if project has mypy config) |
ruff and mypy are installed as dev dependencies via uv sync — no separate install needed.
rtk is a standalone CLI (brew install rtk-ai/tap/rtk) — once installed, autodidact automatically detects it, injects token savings summaries at session start, and feeds optimization opportunities into the learning database weekly via rtk discover.
git clone https://github.com/Jason-Adam/autodidact.git
cd autodidact
uv sync # install dependencies and create .venv
uv run pre-commit install # set up pre-commit hooks (ruff lint, ruff format, mypy)
./install # install globally to ~/.claude/This will:
- Symlink skills, agents, and commands into
~/.claude/ - Register 9 hooks in
~/.claude/settings.json(hooks run viauv runso they have access to project dependencies) - Initialize the learning database at
~/.claude/autodidact/learning.db
To uninstall:
./install --uninstallThe learning database is preserved on uninstall. Delete ~/.claude/autodidact/ manually to remove it.
Everything goes through /do -- the cost-ascending router resolves intent and dispatches to the right skill.
/do plan the auth refactor # routes to plan skill
/do research how caching works # routes to research skill
/do commit these changes # routes to gc skill
| Skill | Purpose | Docs |
|---|---|---|
| plan | Clarify -> Research -> Design pipeline | skill ref |
| run | Single-session sequential orchestration | skill ref |
| campaign | Multi-session persistent orchestration | skill ref |
| fleet | Parallel worktree execution (multi-wave, dependency-aware) | skill ref |
| experiment | Metric-driven autonomous optimization | skill ref |
| loop | Autonomous unattended execution (auto-selects mode) | loop.md |
| learn | Teach the system facts for future injection | skill ref |
| polish | Parallel code review, security review, and simplification | skill ref |
| forget | Decay or remove learnings from the database | skill ref |
| learn-status | Confidence stats and knowledge inventory | skill ref |
| gc | Autonomous git commits -- auto-branches, atomic commits | skill ref |
| create-pr | Create pull requests with thorough descriptions | skill ref |
| research | Parallel codebase research with persisted findings | skill ref |
| handoff | Compact session transfer document | skill ref |
| sync-thoughts | Sync docs to ~/.planning/ for cross-project access | skill ref |
- Skill reference — detailed usage and examples for every skill
- Loop and autonomous execution — exit detection, circuit breaker, auto-select mode
- Learning database — knowledge lifecycle, confidence math, FTS5 queries
- Planning and persistence —
.planning/directory structure, document syncing
uv run python3 -m pytest tests/ -v460 tests covering the learning DB, confidence math, router classification, model routing, interview scoring, circuit breaker, response analysis, git progress detection, exit tracking, loop orchestration, fleet recovery, conflict detection, task graph partitioning, experiment state management, convergence detection, fitness expression evaluation, RTK integration, self-assessment, and session mining.
- Python stdlib only — no pip installs in
src/orhooks/ - Global installation — one install serves all projects; learning persists across repos
- Cost-ascending routing — resolve at the cheapest tier; most requests cost zero LLM tokens
- Graceful degradation — all hooks catch errors and exit 0; a broken hook never blocks your work
- Confidence-based knowledge — learnings earn trust through repeated successful use, not just existence
- Worktree-aware — learnings shared across worktrees;
.planning/state isolated per task