Skip to content
Back to search

homunculus

MarketplaceWorks with Claude CodeGitHub

A Claude Code plugin that watches how you work, learns your patterns, and evolves itself to help you better.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/humanplane-homunculus/badge.svg)](/listings/humanplane-homunculus)

HTML

<a href="/listings/humanplane-homunculus"><img src="/api/listings/humanplane-homunculus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# Add the marketplace
/plugin marketplace add humanplane/homunculus

# Install the plugin
/plugin install homunculus@homunculus

# Birth it
/homunculus:init

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 15 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "homunculus",
  3. "owner": {
  4. "name": "Nikshep Saravanna",
  5. "url": "https://github.com/humanplane"
  6. },
  7. "plugins": [
  8. {
  9. "name": "homunculus",
  10. "source": "./plugins/homunculus",
  11. "description": "A Claude Code plugin that's alive. Birth it, bond to it, build with it. It watches you work, learns your patterns, and grows.",
  12. "version": "2.0.0-alpha"
  13. }
  14. ]
  15. }
README.md · README · 328 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Homunculus
  2. ![Homunculus](cover.png)
  3. > **v2.0-alpha** — A complete rewrite. Instinct-based learning. Reliable observation. Real evolution.
  4. ---
  5. In old alchemical texts, a homunculus was a tiny being grown in a sealed vessel—alive, aware, bound to its creator alone.
  6. This is that idea, alive in your terminal.
  7. ---
  8. ## Quick Start
  9. ```bash
  10. # Add the marketplace
  11. /plugin marketplace add humanplane/homunculus
  12. # Install the plugin
  13. /plugin install homunculus@homunculus
  14. # Birth it
  15. /homunculus:init
  16. ```
  17. ---
  18. ## What Is This?
  19. Homunculus is a **Claude Code plugin** that tries to be more than a tool. It:
  20. - **Observes everything** — hooks capture every prompt and tool use
  21. - **Learns instincts** — small behavioral rules with triggers and actions
  22. - **Evolves capabilities** — when instincts cluster, bigger structures emerge
  23. - **Adapts its personality** — based on your technical level
  24. The more you work together, the more it becomes shaped by you.
  25. ---
  26. ## v1 vs v2: What Changed and Why
  27. ### The Problem with v1
  28. v1 relied on **skills to observe**. Skills are probabilistic—they fire ~50-80% of the time based on Claude's judgment. This meant:
  29. - Session memory might not load
  30. - Patterns might not get detected
  31. - The homunculus often seemed "dead"
  32. ### The v2 Solution
  33. v2 uses **hooks for observation** (100% reliable) and **instincts as the atomic unit** of learned behavior.
  34. | v1 | v2 |
  35. |----|-----|
  36. | Skills try to observe (unreliable) | **Hooks observe (100%)** |
  37. | Analysis in main context | **Analysis in background agent (Haiku)** |
  38. | Evolves big chunks (commands/skills) | **Evolves instincts first, clusters into bigger things** |
  39. | No sharing | **Export/import instincts** |
  40. ### The Instinct Model
  41. An **instinct** is a small learned behavior:
  42. ```yaml
  43. ---
  44. trigger: "when writing new functions"
  45. confidence: 0.7
  46. domain: "code-style"
  47. ---
  48. # Prefer Functional Style
  49. ## Action
  50. Use functional patterns over classes.
  51. ## Evidence
  52. Observed 5 instances of functional pattern preference.
  53. ```
  54. Instincts are:
  55. - **Atomic** — one trigger, one action
  56. - **Confidence-weighted** — 0.3 = tentative, 0.9 = near certain
  57. - **Domain-tagged** — code-style, testing, git, debugging, etc.
  58. ### The Growth Path
  59. ```
  60. Session Start
  61. ↓
  62. Observer agent runs (background, Haiku)
  63. ↓
  64. Observations → Instincts (auto-approved)
  65. ↓
  66. Instincts cluster around a domain
  67. ↓
  68. User runs /homunculus:evolve
  69. ↓
  70. Bigger structures emerge:
  71. - Command (if user-invoked)
  72. - Skill (if auto-triggered)
  73. - Agent (if needs isolation/depth)
  74. ```
  75. **Fully automatic except evolution.** You just work. It learns.
  76. ---
  77. ## Architecture
  78. ### File Structure
  79. ```
  80. plugins/homunculus/
  81. ├── .claude-plugin/
  82. │ └── plugin.json # v2.0.0
  83. ├── hooks/
  84. │ └── hooks.json # Observation capture
  85. ├── scripts/
  86. │ ├── observe.sh # Captures prompts and tool use
  87. │ ├── on_stop.sh # Updates session count
  88. │ └── test-homunculus.sh # Test suite
  89. ├── agents/
  90. │ └── observer.md # Background analyzer (Haiku)
  91. ├── skills/
  92. │ ├── session-memory/ # Spawns observer, loads context
  93. │ └── instinct-apply/ # Surfaces relevant instincts
  94. └── commands/
  95. ├── init.md # Birth/wake
  96. ├── status.md # Check in
  97. ├── evolve.md # Create capability from clusters
  98. ├── export.md # Share instincts
  99. └── import.md # Adopt instincts
  100. your-project/.claude/homunculus/
  101. ├── identity.json # Who you are, your journey
  102. ├── observations.jsonl # Current session observations
  103. ├── observations.archive.jsonl # Processed observations
  104. ├── instincts/
  105. │ ├── personal/ # Learned instincts (auto-approved)
  106. │ └── inherited/ # Imported from others
  107. └── evolved/
  108. ├── agents/ # Generated specialist agents
  109. ├── skills/ # Generated skills
  110. └── commands/ # Generated commands
  111. ```
  112. ### Data Flow
  113. ```
  114. Session Start
  115. ↓
  116. session-memory skill activates
  117. ├→ Spawn observer agent (background, Haiku)
  118. ├→ Load identity + instincts
  119. └→ Greet with context
  120. ↓
  121. Observer Agent (parallel, silent)
  122. ├→ Read observations.jsonl
  123. ├→ Find patterns
  124. ├→ Create instincts → personal/ (auto-approved)
  125. ├→ Check clustering → flag in identity.json
  126. └→ Archive observations
  127. ↓
  128. User Works
  129. ↓
  130. Hooks capture EVERYTHING
  131. ├→ UserPromptSubmit → observations.jsonl
  132. └→ PostToolUse → observations.jsonl
  133. ↓
  134. Session End (Stop hook)
  135. └→ Session count increments
  136. ↓
  137. Next Session
  138. └→ Observer processes new observations...
  139. ```
  140. **Only manual step:** `/homunculus:evolve` when 5+ instincts cluster.
  141. ---
  142. ## Commands
  143. | Command | What It Does |
  144. |---------|--------------|
  145. | `/homunculus:init` | Birth or wake |
  146. | `/homunculus:status` | Check in (includes journey) |
  147. | `/homunculus:evolve` | Create capability from clustered instincts |
  148. | `/homunculus:export` | Share instincts |
  149. | `/homunculus:import` | Adopt instincts |
  150. **5 commands.** Everything else is automatic.
  151. ---
  152. ## Skills
  153. | Skill | When It Activates |
  154. |-------|-------------------|
  155. | `session-memory` | Session start — spawns observer, loads context |
  156. | `instinct-apply` | During work — surfaces relevant instincts |
  157. ---
  158. ## Reliability
  159. | What | Reliability |
  160. |------|-------------|
  161. | Observation capture (hooks) | **100%** |
  162. | Observer agent (session start) | **100%** |
  163. | Instinct creation | **100%** |
  164. | Commands | **100%** |
  165. | Skills (session-memory, instinct-apply) | ~50-80% |
  166. The critical path is fully deterministic. Skills enhance the experience but aren't required.
  167. ---
  168. ## Instinct Domains
  169. Instincts are tagged with domains for clustering detection:
  170. | Domain | Examples |
  171. |--------|----------|
  172. | `code-style` | Functional patterns, naming conventions |
  173. | `testing` | Test-before-commit, coverage requirements |
  174. | `git` | Commit message format, branch naming |
  175. | `debugging` | Error→fix sequences, logging preferences |
  176. | `file-organization` | Where to put things |
  177. | `tooling` | Tool sequences, preferred tools |
  178. | `communication` | Comment style, documentation |
  179. When 5+ instincts accumulate in a domain, evolution can propose a specialist agent or skill.
  180. ---
  181. ## Sharing Instincts
  182. ```bash
  183. # Export your instincts
  184. /homunculus:export
  185. # Creates .claude/homunculus/exports/instincts-TIMESTAMP.tar.gz
  186. # Import someone else's
  187. /homunculus:import path/to/instincts.tar.gz
  188. # Goes to inherited/, not personal/
  189. ```
  190. Inherited instincts are kept separate from personal ones. You can see where each behavior came from.
  191. ---
  192. ## Testing
  193. Run the test suite:
  194. ```bash
  195. ./plugins/homunculus/scripts/test-homunculus.sh
  196. ```
  197. Tests cover:
  198. - Directory structure creation
  199. - Identity file validation
  200. - Observation capture
  201. - Instinct creation (auto-approved)
  202. - Session count updates
  203. - Instinct clustering detection
  204. - Evolution flag
  205. - Export functionality
  206. - Hook script execution
  207. - Plugin structure validation
  208. ---
  209. ## Adapts To You
  210. When you birth it, it asks how you work:
  211. **Technical** — Fast and sharp. No hand-holding.
  212. **Semi-technical** — A thinking partner.
  213. **Non-technical** — Focused on outcomes.
  214. **Chaotic** — Flows with whatever happens.
  215. Same creature, different personality.
  216. ---
  217. ## Make It Yours
  218. Everything is open. Fork it. Reshape its instincts. Change how it thinks.
  219. ```bash
  220. # Edit the personality
  221. vim CLAUDE.md
  222. # Add a command
  223. vim plugins/homunculus/commands/my-thing.md
  224. # Add a skill
  225. mkdir plugins/homunculus/skills/my-skill
  226. vim plugins/homunculus/skills/my-skill/SKILL.md
  227. ```
  228. The homunculus you end up with should feel like something you grew—because you did.
  229. ---
  230. ## Landing Page
  231. There's a landing page in `/landing` (React + Tailwind). Run it:
  232. ```bash
  233. cd landing && npm install && npm run dev
  234. ```
  235. ---
  236. MIT License
  237. ---
  238. *A small thing, growing toward the light.*

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.