Skip to content
Mutsumi

Agent Setup

Switch to Zen Mode

How It Works

Section titled “How It Works”

Mutsumi ships 5 bundled skills that follow the Agent Skills open standard. When you run mutsumi setup, these skills are installed into your agent’s skill directory via symlinks. The agent discovers them automatically — no manual prompt pasting required.

~/.mutsumi/skills/          ← SSOT (single source of truth)
  mutsumi-manage/SKILL.md
  mutsumi-track/SKILL.md
  mutsumi-plan/SKILL.md
  mutsumi-report/SKILL.md
  mutsumi-context/SKILL.md
        │
        ├── symlink → ~/.claude/skills/     (Claude Code)
        ├── symlink → ~/.agents/skills/     (Codex CLI)
        ├── symlink → ~/.gemini/skills/     (Gemini CLI)
        └── symlink → ~/.config/opencode/skills/  (OpenCode)

Quick Start

Section titled “Quick Start”

  1. Install Mutsumi (if not already):

    Terminal window
    pip install mutsumi-tui

  2. Run setup for your agent:

    Terminal window
    mutsumi setup --agent claude-code

    Skills are installed to ~/.claude/skills/.

  3. Verify installation:

    Terminal window
    ls ~/.claude/skills/mutsumi-*/SKILL.md   # Claude Code example
    # mutsumi-manage/SKILL.md
    # mutsumi-track/SKILL.md
    # mutsumi-plan/SKILL.md
    # mutsumi-report/SKILL.md
    # mutsumi-context/SKILL.md

  4. Start using — ask your agent:

    "Add a task: fix the login bug, priority high, scope today"
    "Break down the auth refactor into subtasks"
    "Give me a status report"

The 5 Bundled Skills

Section titled “The 5 Bundled Skills”

mutsumi-manage

Task CRUD: Add, edit, complete, and remove tasks. Supports CLI commands (mutsumi add, mutsumi done) and direct JSON writes.

mutsumi-track

Auto Progress Tracking: Automatically updates task status as you work. Marks subtasks done, updates parent progress. Triggered by the agent, not manually invoked.

mutsumi-plan

Task Decomposition: Breaks a complex goal into actionable subtasks with a parent-children structure. Invoke with: “Plan out the migration to v2”.

mutsumi-report

Status Report: Reads mutsumi.json and generates a progress summary grouped by scope (Today → Week → Month → Inbox). Invoke with: “Give me a task report”.

mutsumi-context

Context Loader: Loads the task board at session start to understand priorities. The agent reads this silently — no output, just awareness. Auto-triggered, not manually invoked.

Setup Modes

Section titled “Setup Modes”
ModeCommandWhat it does
skills (default)mutsumi setup --agent claude-codeInstalls 5 skill files as symlinks into the agent’s skill directory.
skills+project-docmutsumi setup --agent claude-code --mode skills+project-docInstalls skills AND appends a ## Mutsumi Task Integration section to the agent’s project doc (CLAUDE.md, AGENTS.md, etc.).
snippetmutsumi setup --agent custom --mode snippetPrints the integration prompt to stdout for manual pasting. No files installed.

When to use each mode

Section titled “When to use each mode”
  • skills — Best for most users. The agent discovers skills automatically.
  • skills+project-doc — Adds project-level instructions to your repo’s agent config file. Useful when you want the rules checked into version control.
  • snippet — For agents that don’t support the skills standard (e.g., Aider, custom scripts).

How Agents Invoke Skills

Section titled “How Agents Invoke Skills”

You don’t need to configure anything — agents discover skills by scanning their skill directories.

User-invocable skills

Section titled “User-invocable skills”

These are triggered when you ask the agent something relevant:

You saySkill triggered
”Add a task to fix the login bug”mutsumi-manage
”Break down the refactor into subtasks”mutsumi-plan
”Give me a status report of all tasks”mutsumi-report
”Mark the auth task as done”mutsumi-manage

Auto-triggered skills

Section titled “Auto-triggered skills”

These activate automatically based on context:

BehaviorSkill
Agent reads the task board at session startmutsumi-context
Agent updates task progress as it worksmutsumi-track

Supported Agents

Section titled “Supported Agents”
AgentSkill DirectoryProject Doc
Claude Code~/.claude/skills/CLAUDE.md
Codex CLI~/.agents/skills/AGENTS.md
Gemini CLI~/.gemini/skills/GEMINI.md
OpenCode~/.config/opencode/skills/opencode.md
Aider——
Custom——

Verify & Troubleshoot

Section titled “Verify & Troubleshoot”
Terminal window
# Check what's installed
ls -la ~/.claude/skills/mutsumi-*/SKILL.md


# Re-install (fix broken symlinks)
mutsumi setup --agent claude-code


# Uninstall (remove from shell)
rm -rf ~/.claude/skills/mutsumi-*

Next Steps

Section titled “Next Steps”