Skip to main content
command CX Codex

evolve — Claude Code command: what it does, how to install

The evolve command turns related instincts into commands, skills, or agents. Use it when repeated patterns in your Claude Code work need a clearer structure.

MIT ★ 880 updated 2026-09-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/evolve.md
Open on GitHub

What evolve does

evolve reads instincts from ~/.claude/homunculus/instincts/ and groups them by domain, matching triggers, and related action sequences. Each cluster is classified as a user-invoked command, an automatic skill, or an agent for a deeper multi-step workflow.

The command previews the proposed changes by default. With --execute, it writes generated files under ~/.claude/homunculus/evolved/{commands,skills,agents}/ and links them back to the source instincts. You can narrow the run by domain or type, or set a minimum cluster size. Its implementation calls python3, so Python 3 is required for the analysis to run.

What it helps with

  • group related instincts by domain and trigger
  • turn repeated actions into a slash command
  • combine automatic behavior rules into a skill
  • separate a multi-step workflow into an agent
  • preview generated structures before writing files

Example prompts for the agent

  • Run /evolve to analyze all stored instincts.
  • Limit the analysis to testing with /evolve --domain testing.
  • Preview the proposed files with /evolve --dry-run.

How to install evolve

Manually: put the files in place

.claude/commands/evolve.md

Call it with /evolve. For all projects use ~/.claude/commands/

Questions about evolve

How do I install evolve in Claude Code?

Save the command file at .claude/commands/evolve.md. Claude Code can then run it with /evolve.

What does evolve do?

It analyzes stored instincts and clusters related ones into commands, skills, or agents. You can review the result first and create the files with --execute.

Can I limit what evolve analyzes?

Yes. Use --domain <name> for one domain, --type <command|skill|agent> for one output type, or --threshold <n> to set the minimum cluster size.

Source text

evolve.md · MIT
---
name: evolve
description: Cluster related instincts into skills, commands, or agents
command: /evolve
implementation: python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve
---

# Evolve Command

## Implementation

```bash
python3 ~/.claude/skills/continuous-learning-v2/scripts/instinct-cli.py evolve [--generate]
```

Analyzes instincts and clusters related ones into higher-level structures:
- **Commands**: When instincts describe user-invoked actions
- **Skills**: When instincts describe auto-triggered behaviors
- **Agents**: When instincts describe complex, multi-step processes

## Usage

```
/evolve                    # Analyze all instincts and suggest evolutions
/evolve --domain testing   # Only evolve instincts in testing domain
/evolve --dry-run          # Show what would be created without creating
/evolve --threshold 5      # Require 5+ related instincts to cluster
```

## Evolution Rules

### → Command (User-Invoked)
When instincts describe actions a user would explicitly request:
- Multiple instincts about "when user asks to..."
- Instincts with triggers like "when creating a new X"
- Instincts that follow a repeatable sequence

Example:
- `new-table-step1`: "when adding a database table, create migration"
- `new-table-step2`: "when adding a database table, update schema"
- `new-table-step3`: "when adding a database table, regenerate types"

→ Creates: `/new-table` command

### → Skill (Auto-Triggered)
When instincts describe behaviors that should happen automatically:
- Pattern-matching triggers
- Error handling responses
- Code style enforcement

Example:
- `prefer-functional`: "when writing functions, prefer functional style"
- `use-immutable`: "when modifying state, use immutable patterns"
- `avoid-classes`: "when designing modules, avoid class-based design"

→ Creates: `functional-patterns` skill

### → Agent (Needs Depth/Isolation)
When instincts describe complex, multi-step processes that benefit from isolation:
- Debugging workflows
- Refactoring sequences
- Research tasks

Example:
- `debug-step1`: "when debugging, first check logs"
- `debug-step2`: "when debugging, isolate the failing component"
- `debug-step3`: "when debugging, create minimal reproduction"
- `debug-step4`: "when debugging, verify fix with test"

→ Creates: `debugger` agent

## What to Do

1. Read all instincts from `~/.claude/homunculus/instincts/`
2. Group instincts by:
   - Domain similarity
   - Trigger pattern overlap
   - Action sequence relationship
3. For each cluster of 3+ related instincts:
   - Determine evolution type (command/skill/agent)
   - Generate the appropriate file
   - Save to `~/.claude/homunculus/evolved/{commands,skills,agents}/`
4. Link evolved structure back to source instincts

## Output Format

```
🧬 Evolve Analysis
==================

Found 3 clusters ready for evolution:

## Cluster 1: Database Migration Workflow
Instincts: new-table-migration, update-schema, regenerate-types
Type: Command
Confidence: 85% (based on 12 observations)

Would create: /new-table command
Files:
  - ~/.claude/homunculus/evolved/commands/new-table.md

## Cluster 2: Functional Code Style
Instincts: prefer-functional, use-immutable, avoid-classes, pure-functions
Type: Skill
Confidence: 78% (based on 8 observations)

Would create: functional-patterns skill
Files:
  - ~/.claude/homunculus/evolved/skills/functional-patterns.md

## Cluster 3: Debugging Process
Instincts: debug-check-logs, debug-isolate, debug-reproduce, debug-verify
Type: Agent
Confidence: 72% (based on 6 observations)

Would create: debugger agent
Files:
  - ~/.claude/homunculus/evolved/agents/debugger.md

---
Run `/evolve --execute` to create these files.
```

## Flags

- `--execute`: Actually create the evolved structures (default is preview)
- `--dry-run`: Preview without creating
- `--domain <name>`: Only evolve instincts in specified domain
- `--threshold <n>`: Minimum instincts required to form cluster (default: 3)
- `--type <command|skill|agent>`: Only create specified type

## Generated File Format

### Command
```markdown
---
name: new-table
description: Create a new database table with migration, schema update, and type generation
command: /new-table
evolved_from:
  - new-table-migration
  - update-schema
  - regenerate-types
---

# New Table Command

[Generated content based on clustered instincts]

## Steps
1. ...
2. ...
```

### Skill
```markdown
---
name: functional-patterns
description: Enforce functional programming patterns
evolved_from:
  - prefer-functional
  - use-immutable
  - avoid-classes
---

# Functional Patterns Skill

[Generated content based on clustered instincts]
```

### Agent
```markdown
---
name: debugger
description: Systematic debugging agent
model: sonnet
evolved_from:
  - debug-check-logs
  - debug-isolate
  - debug-reproduce
---

# Debugger Agent

[Generated content based on clustered instincts]
```

© sangrokjung · MIT · sangrokjung/claude-forge

Similar slash commands

All slash commands for Agent setup: memory, context, orchestration →

From the same set44

The whole set →
instinct-import instinct-import pulls instincts from a file or URL, checks them against the ones you already have, and files the keepers with a note of where they came from. CX Codex +1 ★ 880repo stars database-reviewer database-reviewer — a Claude Code subagent for reviewing SQL migrations, schema types, and RLS policies in PostgreSQL and Supabase projects. It spots N+1 queries and runs EXPLAIN ANALYZE. CX Codex ★ 880repo stars observer observer — a background subagent that mines session observations for repeating patterns and saves each one as a short instinct rule with a confidence score. CX Codex ★ 880repo stars verify-agent verify-agent runs a fresh-context validation pipeline in Claude Code. It executes typecheck, lint, build, and test steps while safely auto-fixing trivial errors. CX Codex ★ 880repo stars systematic-debugger systematic-debugger turns a reproducible bug into a bounded search: failing test, bisect, falsifiable hypotheses, verified fix. Built for the case where the cause is still a mystery. CX Codex ★ 880repo stars humanize-korean The humanize-korean skill edits awkward, translation-shaped Korean and formulaic AI phrasing while leaving facts, numbers, names, and quotations intact. It works in one pass. CX Codex +1 ★ 880repo stars workflow-classify The workflow-classify command grades a task from S to XL and recommends a workflow. Run it before implementation to get a plan matched to the change’s scope and risk. CX Codex +1 ★ 880repo stars build-error-resolver build-error-resolver turns a failing build green with the smallest possible diff: type errors, compile failures, imports, dependencies. Refactoring and architecture work are ruled out. CX Codex ★ 880repo stars

Project sponsors

Companies that keep this analytics open