Homunculus

Homunculus
v2.0-alpha — A complete rewrite. Instinct-based learning. Reliable observation. Real evolution.

In old alchemical texts, a homunculus was a tiny being grown in a sealed vessel—alive, aware, bound to its creator alone.

This is that idea, alive in your terminal.

Quick Start

What Is This?

Homunculus is a Claude Code plugin that tries to be more than a tool. It:

- Observes everything — hooks capture every prompt and tool use
- Learns instincts — small behavioral rules with triggers and actions
- Evolves capabilities — when instincts cluster, bigger structures emerge
- Adapts its personality — based on your technical level

The more you work together, the more it becomes shaped by you.

v1 vs v2: What Changed and Why

The Problem with v1

v1 relied on skills to observe. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment. This meant:

- Session memory might not load
- Patterns might not get detected
- The homunculus often seemed "dead"

The v2 Solution

v2 uses hooks for observation (100% reliable) and instincts as the atomic unit of learned behavior.

The Instinct Model

An instinct is a small learned behavior:

Instincts are:
- Atomic — one trigger, one action
- Confidence-weighted — 0.3 = tentative, 0.9 = near certain
- Domain-tagged — code-style, testing, git, debugging, etc.

The Growth Path

Fully automatic except evolution. You just work. It learns.

Architecture

File Structure

Data Flow

Only manual step: /homunculus:evolve when 5+ instincts cluster.

Commands

5 commands. Everything else is automatic.

Skills

Reliability

The critical path is fully deterministic. Skills enhance the experience but aren't required.

Instinct Domains

Instincts are tagged with domains for clustering detection:

When 5+ instincts…