Agent Protocol
Overview
Section titled “Overview”This document defines how external Agents (AI CLI tools, custom scripts, cron jobs) read from and write to Mutsumi’s mutsumi.json.
Backward compatibility: Mutsumi also accepts
tasks.jsonas a fallback filename. However,mutsumi.jsonis the canonical name going forward.
Core principle: Mutsumi does not bind to any specific Agent. Any program that can correctly read and write JSON is a legitimate Controller.
Agent Skills (Recommended)
Section titled “Agent Skills (Recommended)”Mutsumi ships 5 bundled skills that follow the Agent Skills open standard. When installed, agents discover them automatically — no manual prompt pasting needed.
Installation
Section titled “Installation”mutsumi setup --agent claude-code # or codex-cli, gemini-cli, opencodeThis creates symlinks from ~/.mutsumi/skills/ (SSOT) into the agent’s skill directory.
Skill Reference
Section titled “Skill Reference”| Skill | Description | Trigger |
|---|---|---|
mutsumi-manage | Task CRUD — add, edit, done, remove via CLI or direct JSON | User asks to manage tasks |
mutsumi-track | Auto-update task progress as the agent works | Auto-triggered (user-invocable: false) |
mutsumi-plan | Decompose a complex goal into parent + subtasks | User asks to plan or break down work |
mutsumi-report | Generate a status summary grouped by scope | User asks for a report (disable-model-invocation: true) |
mutsumi-context | Load task board state at session start for priority awareness | Auto-triggered (user-invocable: false) |
SKILL.md Anatomy
Section titled “SKILL.md Anatomy”Each skill is a directory with a SKILL.md file:
mutsumi-manage/ SKILL.md ← YAML frontmatter + Markdown instructionsThe frontmatter follows the agentskills.io specification:
---name: mutsumi-managedescription: > Add, edit, complete, or remove tasks in mutsumi.json.---Key frontmatter fields:
name— lowercase + hyphens, max 64 charsdescription— when the agent should activate this skilluser-invocable: false— agent auto-triggers, user cannot invoke directlydisable-model-invocation: true— only activated when user explicitly asks
Architecture
Section titled “Architecture”Bundled in pip package SSOT (single copy) Agent skill dirsmutsumi/skills/ → ~/.mutsumi/skills/ → ~/.claude/skills/ mutsumi-manage/ mutsumi-manage/ mutsumi-manage/ (symlink) mutsumi-track/ mutsumi-track/ mutsumi-track/ (symlink) mutsumi-plan/ mutsumi-plan/ ... mutsumi-report/ mutsumi-report/ mutsumi-context/ mutsumi-context/ references/ references/Step 1: ensure_ssot() copies bundled skills → ~/.mutsumi/skills/.
Step 2: install_for_agent() creates symlinks from SSOT → agent directory.
This SSOT architecture ensures all agents share the same skill definitions. Updating Mutsumi (pip install --upgrade) automatically refreshes the SSOT on next mutsumi setup.
Supported Agents
Section titled “Supported Agents”| Agent | Type | Integration Level |
|---|---|---|
| Claude Code | AI CLI | Native (recommended) |
| Codex CLI | AI CLI | Native |
| Gemini CLI | AI CLI | Native |
| OpenCode | AI CLI | Native |
| Aider | AI CLI | Native |
| Shell scripts | Custom | Native |
| Cron jobs | System | Native |
“Native” means only JSON file read/write is needed. No SDK, no plugin, no driver.
Write Protocol (Agent to Mutsumi)
Section titled “Write Protocol (Agent to Mutsumi)”Workflow
Section titled “Workflow”- Read the current
mutsumi.json(full content) - Parse as JSON
- Modify the
tasksarray (add / update / delete) - Write the entire file back (no partial writes)
- Mutsumi’s watchdog detects the change and re-renders
| Rule | Description |
|---|---|
| Preserve unknown fields | Do not delete fields you don’t recognize. Keep them as-is. |
| Atomic write | Write to a temp file, then os.replace(). Prevents Mutsumi from reading a half-written state. |
| Valid JSON | The file must be valid JSON after writing. |
| Generate valid IDs | New task IDs should use UUIDv7. At minimum, ensure uniqueness. |
| Required fields | Every task must include id, title, status. |
| Enum compliance | status must be "pending" or "done". |
Code Example: Adding a Task (Python)
Section titled “Code Example: Adding a Task (Python)”import json, uuid, datetime, tempfile, os
# 1. Readwith open("mutsumi.json") as f: data = json.load(f)
# 2. Addnew_task = { "id": str(uuid.uuid7()), # or any unique string "title": "Fix login bug", "status": "pending", "scope": "day", "priority": "high", "tags": ["bugfix"], "created_at": datetime.datetime.now(datetime.UTC).isoformat(), "children": []}data["tasks"].append(new_task)
# 3. Write (atomic)tmp = tempfile.NamedTemporaryFile( mode='w', dir='.', suffix='.tmp', delete=False)json.dump(data, tmp, ensure_ascii=False, indent=2)tmp.close()os.replace(tmp.name, "mutsumi.json")Code Example: Completing a Task
Section titled “Code Example: Completing a Task”for task in data["tasks"]: if task["id"] == target_id: task["status"] = "done" task["completed_at"] = datetime.datetime.now(datetime.UTC).isoformat() breakCode Example: Shell (jq)
Section titled “Code Example: Shell (jq)”# Mark a task donejq '(.tasks[] | select(.id == "01JQ...")).status = "done"' mutsumi.json > tmp.jsonmv tmp.json mutsumi.jsonRead Protocol (Mutsumi to Agent)
Section titled “Read Protocol (Mutsumi to Agent)”Event Log
Section titled “Event Log”When a user operates in the TUI, Mutsumi appends events to events.jsonl (JSONL format, one event per line):
{"ts":"2026-03-21T10:00:00Z","event":"task_completed","task_id":"01JQ...","title":"Fix cache bug","source":"tui"}{"ts":"2026-03-21T10:01:22Z","event":"task_created","task_id":"01JQ...","title":"Write unit tests","source":"tui"}{"ts":"2026-03-21T10:05:00Z","event":"task_deleted","task_id":"01JQ...","title":"Outdated task","source":"tui"}{"ts":"2026-03-21T10:06:30Z","event":"task_updated","task_id":"01JQ...","changes":{"priority":"high->low"},"source":"tui"}Event Types
Section titled “Event Types”| Event | Fields | Description |
|---|---|---|
task_created | task_id, title | New task created |
task_completed | task_id, title | Task marked done |
task_deleted | task_id, title | Task deleted |
task_updated | task_id, changes | Task fields modified |
schema_error | file, message | JSON validation failed |
Agent Consumption
Section titled “Agent Consumption”# Real-time monitoringtail -f events.jsonl | jq .
# In agent prompt"Check events.jsonl for recent user actions on tasks"Schema Discovery
Section titled “Schema Discovery”Agents can retrieve the current JSON Schema via CLI:
# JSON Schema outputmutsumi schema
# Markdown field descriptionsmutsumi schema --format markdownError Handling
Section titled “Error Handling”When Agent Writes Bad Data
Section titled “When Agent Writes Bad Data”Agent writes invalid JSON | vMutsumi watchdog detects change | vParse fails -> TUI shows error banner | "mutsumi.json has errors, showing last valid state" vError logged to stderr + error.log | vEvent emitted: {"event":"schema_error","file":"mutsumi.json","message":"..."} | vAgent can read error.log or events.jsonl to self-correctSelf-Healing Prompt
Section titled “Self-Healing Prompt”Add to your agent’s system prompt:
After writing to mutsumi.json, check ~/.local/share/mutsumi/error.logfor any schema validation errors. If errors exist, fix and rewrite.Multi-Agent Coordination
Section titled “Multi-Agent Coordination”When multiple Agents operate on the same mutsumi.json simultaneously:
Recommendations
Section titled “Recommendations”- Read-before-write — Always read the latest version before writing
- Minimize write scope — Only modify the tasks you care about; don’t reorder others
- Idempotent operations — Marking complete should be idempotent (no error on repeat)
- Use unique IDs — UUIDv7 ensures IDs from different Agents never collide
Conflict Resolution
Section titled “Conflict Resolution”Mutsumi does not provide a locking mechanism. Strategy: Last Write Wins.
In practice, Agent writes are discrete (typically seconds to minutes apart), so the probability of conflict is extremely low.
Agent Prompt Template
Section titled “Agent Prompt Template”The recommended template for embedding in any agent’s system prompt:
## Task Management (Mutsumi Integration)
You have access to a local task file at `./mutsumi.json`.When the user asks you to manage tasks, read and write this file.
Schema:- Required fields: id (unique string), title (string), status ("pending" | "done")- Optional fields: scope ("day"|"week"|"month"|"inbox"), priority ("high"|"normal"|"low"), tags (string[]), children (Task[]), due_date (ISO date), description (string)- Preserve any fields you don't recognize -- do NOT delete them- Use atomic write (temp file + os.replace()) when possible- Generate UUIDv7 for new task IDs
Example task:{"id":"01JQ...","title":"Fix auth","status":"pending","scope":"day", "priority":"high","tags":["dev"],"children":[]}