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

# Add the marketplace
/plugin marketplace add humanplane/homunculus

# Install the plugin
/plugin install homunculus@homunculus

# Birth it
/homunculus:init

---

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.

v1	v2
Skills try to observe (unreliable)	Hooks observe (100%)
Analysis in main context	Analysis in background agent (Haiku)
Evolves big chunks (commands/skills)	Evolves instincts first, clusters into bigger things
No sharing	Export/import instincts

The Instinct Model

An instinct is a small learned behavior:

---
trigger: "when writing new functions"
confidence: 0.7
domain: "code-style"
---

# Prefer Functional Style

## Action
Use functional patterns over classes.

## Evidence
Observed 5 instances of functional pattern preference.

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

Session Start
     ↓
Observer agent runs (background, Haiku)
     ↓
Observations → Instincts (auto-approved)
     ↓
Instincts cluster around a domain
     ↓
User runs /homunculus:evolve
     ↓
Bigger structures emerge:
  - Command (if user-invoked)
  - Skill (if auto-triggered)
  - Agent (if needs isolation/depth)

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

---

Architecture

File Structure

plugins/homunculus/
├── .claude-plugin/
│   └── plugin.json           # v2.0.0
├── hooks/
│   └── hooks.json            # Observation capture
├── scripts/
│   ├── observe.sh            # Captures prompts and tool use
│   ├── on_stop.sh            # Updates session count
│   └── test-homunculus.sh    # Test suite
├── agents/
│   └── observer.md           # Background analyzer (Haiku)
├── skills/
│   ├── session-memory/       # Spawns observer, loads context
│   └── instinct-apply/       # Surfaces relevant instincts
└── commands/
    ├── init.md               # Birth/wake
    ├── status.md             # Check in
    ├── evolve.md             # Create capability from clusters
    ├── export.md             # Share instincts
    └── import.md             # Adopt instincts

your-project/.claude/homunculus/
├── identity.json             # Who you are, your journey
├── observations.jsonl        # Current session observations
├── observations.archive.jsonl # Processed observations
├── instincts/
│   ├── personal/             # Learned instincts (auto-approved)
│   └── inherited/            # Imported from others
└── evolved/
    ├── agents/               # Generated specialist agents
    ├── skills/               # Generated skills
    └── commands/             # Generated commands

Data Flow

Session Start
    ↓
session-memory skill activates
    ├→ Spawn observer agent (background, Haiku)
    ├→ Load identity + instincts
    └→ Greet with context
    ↓
Observer Agent (parallel, silent)
    ├→ Read observations.jsonl
    ├→ Find patterns
    ├→ Create instincts → personal/ (auto-approved)
    ├→ Check clustering → flag in identity.json
    └→ Archive observations
    ↓
User Works
    ↓
Hooks capture EVERYTHING
    ├→ UserPromptSubmit → observations.jsonl
    └→ PostToolUse → observations.jsonl
    ↓
Session End (Stop hook)
    └→ Session count increments
    ↓
Next Session
    └→ Observer processes new observations...

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

---

Commands

Command	What It Does
/homunculus:init	Birth or wake
/homunculus:status	Check in (includes journey)
/homunculus:evolve	Create capability from clustered instincts
/homunculus:export	Share instincts
/homunculus:import	Adopt instincts