Homunculus plugin
A Claude Code plugin that records how you work, derives small instincts from it and grows them into commands, skills and agents
- 400 ★ on the repository
- Last commit
Broad access
Why this level
- Hooks run the `observe.sh` and `on_stop.sh` scripts on every prompt, tool call and session stop
- A background agent reads those records on its own, and the plugin creates new commands, skills and agents in the project
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/homunculusDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Hooks run the `observe.sh` and `on_stop.sh` scripts on every prompt, tool call and session stop
- A background agent reads those records on its own, and the plugin creates new commands, skills and agents in the project
This is third-party code. Review the repository files before installing.
What it does
Homunculus watches your work in Claude Code and learns from it. The `UserPromptSubmit` and `PostToolUse` hooks write every prompt and every tool call into an `observations.jsonl` file. At session start the session-memory skill launches a background observer agent on the Haiku model. It reads the records, finds repeated habits and turns them into instincts. An instinct is a small rule with a trigger, an action and a confidence from 0.3 to 0.9, for example "when writing new functions, prefer a functional style". Each instinct belongs to a domain: code style, testing, git, debugging, file organization, tooling or communication. When five or more instincts gather in one domain, the /homunculus:evolve command offers to grow them into a larger structure: a command, a skill or a specialist agent. Data lives in the project's `.claude/homunculus` folder: personal instincts, inherited ones, the `identity.json` file and the generated commands, skills and agents. Instincts can be exported as a `tar.gz` archive and shared with another person. On first launch the plugin asks how you work and adapts its tone to one of four types: technical, semi-technical, non-technical or chaotic.
Who it is for. For people who work in Claude Code on one project for long stretches and want repeated habits to become rules, commands and skills without writing them down by hand.
Good fit when
- You keep correcting the agent on the same things, such as code style or commit format, and want that captured automatically
- You want to gather repeated debugging or testing habits and turn them into a dedicated command
- A team wants to share worked-out rules: instincts export as an archive and import separately from personal ones
- You want to try the approach on your own project: the plugin installs from a marketplace and is removed with one command
- You need an overview of what the plugin has learned: the /homunculus:status command shows the state and the journey
Not a fit when
- Prompts and tool calls may hold secrets or personal data, and writing them into project files is not acceptable
- You need to avoid any background agents: the observer starts on its own at session start
- The project is shared and observation records must not be committed: the `.claude/homunculus` folder lives inside the repository
Example request
Show which instincts you have learned over the last sessions and propose growing a command from the testing onesLimitations
Version 2.0 is marked alpha: the author rewrote the plugin entirely. The hooks record observations reliably. The session-memory and instinct-apply skills depend on Claude's judgment and fire in about 50–80% of cases.
Evolution into a command, skill or agent starts by hand with /homunculus:evolve after five instincts gather in one domain. The other steps run automatically. The background observer runs on the Haiku model, so it spends tokens of your subscription or key.
The repository has no license in its GitHub metadata. The end of the README carries an MIT note.
How to disable. Remove the plugin with `/plugin uninstall homunculus@homunculus` and the hooks stop recording observations. Delete the `.claude/homunculus` folder in the project by hand: it keeps `observations.jsonl`, the instincts and the commands, skills and agents the plugin created.
FAQ
How do I install Homunculus in Claude Code?
Add the marketplace with `/plugin marketplace add humanplane/homunculus`, install the plugin with `/plugin install homunculus@homunculus` and run `/homunculus:init`. The init command creates the folders, asks about your working style and sets the tone of communication.
What is an instinct in Homunculus?
An atomic learned habit: one trigger, one action, a confidence from 0.3 to 0.9 and a domain. It is stored as a file with YAML metadata; it holds a heading, an action and evidence such as "observed five instances" inside. Automatically created instincts live in personal, those received from others in inherited.
How does version 2 differ from the first one?
Version 1 relied on skills to observe, and skills do not always fire. In version 2 hooks observe, analysis runs in a background Haiku agent, and the learning unit became the instinct. Sharing instincts through export and import was added.
How do I pass instincts to a colleague?
The /homunculus:export command creates an `instincts-TIMESTAMP.tar.gz` archive in `.claude/homunculus/exports`. The colleague imports it with /homunculus:import and the file path. Foreign instincts go to inherited and do not mix with personal ones, so the origin of each behavior stays visible.
What data does the plugin record?
The `UserPromptSubmit` hook writes your prompts and the `PostToolUse` hook writes tool calls, both into `observations.jsonl`. Processed records move to `observations.archive.jsonl`. The Stop hook only increments the session counter.
Discussion
No questions or reviews yet.
Related
PluginsA self-improvement plugin for Claude Code, Codex and OpenCode: turns corrections into rules the agent follows in later sessions
The author's personal Claude Code toolbox: meta-prompt and todo commands, skills to create skills, hooks and MCP servers, auditors and a Ralph loop
Workflows for Claude Code: /do, /omo, /bmad-pilot and more commands, with Codex, Gemini or OpenCode writing the code through codeagent-wrapper
Anthropic's coding agent for the terminal, IDE and GitHub: understands your codebase, runs tasks and handles git
AI Builder Club Skills
AI Builder Club — Skills
A Claude Code plugin marketplace to make a repo agent-ready and run compounding agent loops
A Claude Code plugin marketplace with ready sets of agents, slash commands, hooks and skills, plus a search site
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Homunculus (this entry) | no | 400 | |
| claude-smart | no | 789 | a self-improvement plugin for Claude Code, Codex and OpenCode that turns corrections into rules |
| Self-Improving Agent | no | 782 | a skill for OpenClaw that logs errors and corrections into .learnings files |
README in short
The move from version 1 to version 2, the observation, instinct, evolution path and the plugin file tree with hooks, an agent, two skills and five commands are covered in detail. Separate tables describe the reliability of each link, the instinct domains and the personality modes. Tests run with the test-homunculus.sh script, and a React and Tailwind landing page starts from the landing folder. It helps to see in advance which files the plugin will create in the project.