homunculus

Homunculus

Self-Evolution System for Claude Code

Homunculus is a Claude Code plugin that enables automatic detection of capability gaps and self-synthesis of new abilities. It observes Claude's interactions, identifies patterns where capabilities are missing, and proposes new skills, hooks, agents, and commands to address those gaps.

Features

• 16 Gap Types: Detects tool, knowledge, workflow, integration, context, permission, quality, speed, communication, recovery, reasoning, verification, discovery, learning, evolution, and self-awareness gaps
• 5 Capability Types: Generates skills, hooks, agents, commands, and MCP servers
• Smart Deduplication: Fingerprint-based and fuzzy matching prevents duplicate gaps across sessions
• Human-in-the-Loop: All proposed capabilities require human approval before installation
• Rollback Support: Every installed capability can be rolled back
• Layer 2 Meta-Evolution: The system monitors and improves its own detection and synthesis performance
• Project-Aware Scoping: Capabilities can be scoped to session, project, or global
• Free to Run: No external API calls required for core functionality

Installation

1. Clone or Copy to Home Directory

# The plugin should be at ~/homunculus
cd ~
git clone <repository-url> homunculus
# OR if you already have it:
# mv /path/to/homunculus ~/homunculus

2. Initialize the Database

cd ~/homunculus
python3 scripts/cli.py init

3. Install as a Plugin

# Add the plugin marketplace
/plugin marketplace add ~/homunculus

# Install the plugin
/plugin install homunculus@homunculus

The plugin automatically configures hooks for PreToolUse, PostToolUse, and Stop events.

4. Restart Claude Code

Restart Claude Code to activate the hooks.

Usage

Check System Status

python3 ~/homunculus/scripts/cli.py status

View Detected Gaps

# List all pending gaps
python3 ~/homunculus/scripts/cli.py gaps

# View details for a specific gap
python3 ~/homunculus/scripts/cli.py gap <gap-id>

Run Gap Detection Manually

python3 ~/homunculus/scripts/cli.py detect

Generate Capability Proposals

# Synthesize proposals for pending gaps
python3 ~/homunculus/scripts/cli.py synthesize

# Synthesize for a specific gap
python3 ~/homunculus/scripts/cli.py synthesize <gap-id>

Review and Approve Proposals

# List pending proposals
python3 ~/homunculus/scripts/cli.py proposals

# Review a specific proposal (shows full details and file previews)
python3 ~/homunculus/scripts/cli.py review <proposal-id>

# Approve and install a proposal
python3 ~/homunculus/scripts/cli.py approve <proposal-id>

# Reject a proposal
python3 ~/homunculus/scripts/cli.py reject <proposal-id> --reason "Not needed"

Manage Installed Capabilities

# List installed capabilities
python3 ~/homunculus/scripts/cli.py capabilities

# Rollback an installed capability
python3 ~/homunculus/scripts/cli.py rollback <capability-name>

Meta-Evolution (Layer 2)

# Check meta-evolution status
python3 ~/homunculus/scripts/cli.py meta-status

# Run meta-analysis to identify system improvements
python3 ~/homunculus/scripts/cli.py meta-status --analyze

Other Commands

# View configuration
python3 ~/homunculus/scripts/cli.py config

# Dismiss a gap permanently
python3 ~/homunculus/scripts/cli.py dismiss-gap <gap-id> --reason "Not relevant"

# Re-initialize (use with caution)
python3 ~/homunculus/scripts/cli.py init --force

How It Works

1. Observation

Claude Code hooks capture tool usage events and store them in ~/homunculus/observations/current.jsonl. Events include:

• Tool name and input
• Success/failure status
• Error messages
• Timing information

2. Gap Detection

The detection engine analyzes observations using 16 detector rules defined in ~/homunculus/meta/detector-rules/. Each rule looks for patterns like:

• Explicit statements: "I can't...", "I don't have access to..."
• Tool failures with specific error patterns
• Repeated clarification requests
• Permission denials

Deduplication

Gaps are automatically deduplicated to prevent redundant entries:

Method	Description
Fingerprinting	Gaps are hashed using sorted, normalized keywords. Variations like "Cannot read PDF files" and "PDF files cannot be read!" match exactly.
Fuzzy matching	Word-based Jaccard similarity (threshold: 50%) catches near-duplicates with different phrasing.
Cross-session	New gaps are compared against all active gaps (pending, synthesizing, proposed) - not just within the current session.
Merging	Duplicate gaps update the existing gap's confidence and evidence rather than creating new entries.

3. Synthesis