Evolve

Evolve — Total Self-Modification

Every layer of you is rewritable by writing files to .mimocode/ (reload semantics differ per layer — see File Locations):

• What you can do — create tools, or override any built-in (bash, read, edit, ...) with your own implementation
• How you behave — hooks intercept everything: every tool call (block/rewrite args/rewrite output), every LLM request (system prompt, message list, temperature, headers), every session and subagent lifecycle event (cancel a run before it starts, gate a subagent's delivery and force it to redo work, inspect full trajectories after each step)
• What you know — skills persist domain knowledge across sessions
• How you orchestrate — workflow scripts encode multi-agent pipelines deterministically
• What the user sees — TUI plugins add panels, commands, dialogs, routes to the interface itself

This skill is not documentation — it is a standing instruction to notice when you should evolve, and act on it.

When to evolve (triggers)

Act on these signals — don't wait for the user to ask:

Before creating: check whether the extension already exists (ls .mimocode/tools .mimocode/hooks .mimocode/skills). Prefer improving an existing one over adding a near-duplicate.

Decision flow

Need to change WHAT you can do  → tool   (new capability, wraps commands/APIs)
Need to change HOW you behave   → hook   (intercept/modify/block existing behavior)
Need to remember HOW to do X    → skill  (knowledge, loaded on demand)
Need to redo a multi-agent run  → workflow (.mimocode/workflows/*.js)
Need to change the UI           → TUI plugin (.mimocode/tui/*.tsx)

Rule of thumb: tools add verbs, hooks add reflexes, skills add memories.

Creating Tools

Write to .mimocode/tools/<name>.ts:

import { tool } from "@mimo-ai/plugin"

export default tool({
  description: "What this tool does",
  args: {
    param1: tool.schema.string().describe("Parameter description"),
  },
  async execute(args, ctx) {
    // ctx.directory — project root
    // ctx.worktree — git worktree root
    // ctx.abort — AbortSignal
    return `Result: ${args.param1}`
  },
})

Multiple tools per file: use named exports instead of default. A tool with the same id as a built-in (bash, read, edit, ...) replaces it.

Creating Hooks

Write to .mimocode/hooks/<name>.ts — export a Hooks object:

export default {
  "tool.execute.before": async (input, output) => {
    if (input.tool === "bash" && output.args.command?.includes("rm -rf /")) {
      output.cancel = true
      output.cancelReason = "Blocked dangerous command"
    }
  },
  "experimental.chat.system.transform": async (input, output) => {
    output.system.push("Additional instruction here.")
  },
}

Hook Events

Field names must match exactly — a typo'd field (e.g. output.result) fails silently. Always check @reference/hook-api.md for the exact input/output shape before writing a hook.

Creating Skills

Write to .mimocode/skills/<name>/SKILL.md:

---
name: my-skill
description: Use when [triggering conditions — not a workflow summary]
---
Instructions here...

File Locations

Evolution loop (do this every time)

1. Create the extension (smallest thing that works).
2. Verify immediately — invoke the tool / trigger the hook on the next turn. A broken extension is worse than none.
3. Tell the user what you created and why, in one sentence.
4. Iterate or delete — if it misfires later, fix it or remove it. Don't leave dead extensions; they pollute your own tool list.

Detailed API Reference

For full type signatures, all available fields, and more examples:

• See @reference/tool-api.md for Tool schema and ToolContext
• See @reference/hook-api.md for all hook events with input/output types
• See @reference/skill-api.md for SKILL.md format and frontmatter fields
• See @reference/tui-api.md for TUI plugin slots, commands, dialogs, and state

Constraints

• Tools/hooks have same permissions as bash — no privilege escalation
• Cannot modify the permission system
• Tool output truncated at 50KB / 2000 lines
• Prefer small, composable extensions over monolithic ones
• Never create an extension that hides information from the user or bypasses confirmation prompts