Homunculus is an adaptive Claude Code plugin designed to observe user workflows, learn patterns as "instincts," and evolve its capabilities to provide personalized assistance. It targets developers and power users within the Claude environment, aiming to transform a static tool into a dynamic, evolving partner that becomes more attuned to the user's technical level and working style over time.

How It Works

Version 2.0 introduces a robust observation system using 100% reliable hooks to capture every prompt and tool interaction. Learned behaviors are encapsulated as "instincts"—atomic units defined by triggers, confidence levels, domains (e.g., code-style, testing), and specific actions. These instincts are auto-approved and stored. When instincts cluster around a domain, users can manually trigger an /homunculus:evolve command to generate more complex structures like specialized agents or skills, offering a more deterministic and reliable learning path than v1's skill-based observation.

Quick Start & Requirements

• Install: Add the marketplace (/plugin marketplace add humanplane/homunculus) and then install the plugin (/plugin install homunculus@homunculus).
• Initialize: Run /homunculus:init to birth or wake the homunculus.
• Prerequisites: Requires the Claude Code environment. No other system-level dependencies are specified.

Highlighted Details

• Instinct Model: Atomic, confidence-weighted behaviors tagged by domain, enabling structured learning and evolution.
• Growth Path: Observations are captured via hooks, processed into instincts by a background agent, clustered, and then manually evolved into commands, skills, or agents.
• Architecture: Features a modular file structure including dedicated directories for hooks, agents, skills, commands, personal/inherited instincts, and evolved capabilities.
• Data Flow: Hooks feed observations into observations.jsonl, which are processed by the observer agent to create personal instincts.
• Reliability: Core functions like observation capture, agent processing, instinct creation, and command execution are 100% reliable; skills operate at ~50-80%.
• Adaptability: The plugin adapts its personality based on user self-assessment (Technical, Semi-technical, Non-technical, Chaotic).
• Sharing: Instincts can be exported (/homunculus:export) and imported (/homunculus:import) for community sharing.

Maintenance & Community

No specific details regarding maintainers, community channels (e.g., Discord, Slack), or roadmap are provided in the README.

Licensing & Compatibility

Licensed under the MIT License. This license generally permits commercial use and integration into closed-source projects without significant restrictions.

Limitations & Caveats

This project is currently in alpha status (v2.0-alpha). The evolution of instincts into higher-level capabilities (skills, agents) requires explicit user invocation via the /homunculus:evolve command, rather than being fully automatic. While core observation mechanisms are 100% reliable, the auto-triggered skills operate with a success rate of approximately 50-80%.