Homunculus — Development skill for Claude Code

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:

...