mutsumi-tui 0.5.0

A silent TUI task board that watches your JSON. Agent-agnostic. Layout-agnostic. Zero friction.

mutsumi ♪

中文版 | 日本語版

The silent task brain for the multi-threaded you.

A minimal TUI task board that watches your tasks.json and stays out of your way. Let your AI agent be the brain — Mutsumi is just the eyes.

┌─────────────────────────────────────────────────────┐
│  [Today] [Week] [Month] [Inbox]          mutsumi ♪  │
├─────────────────────────────────────────────────────┤
│                                                     │
│  ▼ HIGH ─────────────────────────────────────────   │
│  [ ] Refactor Auth module             dev,backend ★★★│
│  [x] Fix cache penetration bug        bugfix      ★★★│
│                                                     │
│  ▼ NORMAL ───────────────────────────────────────   │
│  [ ] Write weekly report              life        ★★ │
│  [ ] Review PR #42                    dev         ★★ │
│    └─ [ ] Check type safety           (1/2)          │
│    └─ [x] Run tests                                  │
│                                                     │
│  ▼ LOW ──────────────────────────────────────────   │
│  [ ] Update README                    docs        ★  │
│                                                     │
├─────────────────────────────────────────────────────┤
│  6 tasks · 2 done · 4 pending                       │
└─────────────────────────────────────────────────────┘

Why Mutsumi?

You're running Claude Code in one terminal, Codex CLI in another, browsing Reddit, chatting on Discord — all at the same time. You need a task board that:

• Summons in < 1 second — no loading, no login, no network
• Auto-refreshes when your AI agent writes to tasks.json
• Stays out of your way — no opinions, no workflow enforcement
• Works with any agent — Claude Code, Codex CLI, Gemini CLI, Aider, or a shell script

That's Mutsumi. She watches your JSON and re-renders instantly. That's it.

Install

# Beta install (from git)
uv tool install git+https://github.com/ywh555hhh/Mutsumi.git

No Python pre-install needed — uv manages everything.

# Alternative
pipx install mutsumi

# For hackers
git clone https://github.com/ywh555hhh/Mutsumi.git
cd Mutsumi && uv sync && uv run mutsumi

Quick Start

# Launch the TUI (watches tasks.json in current dir)
mutsumi

# Interactive setup (one screen, all options)
mutsumi init

# Setup agent integration
mutsumi setup --agent claude-code

How It Works

┌──────────────┐        ┌────────────┐        ┌──────────────┐
│  AI Agent    │───────▶│ tasks.json │◀───────│  You (TUI)   │
│  (Controller)│ write  │  (Model)   │ watch  │  (View)      │
└──────────────┘        └────────────┘        └──────────────┘

MVC separation: Agents write JSON. Mutsumi watches and renders. You click and it writes back. Simple.

Features

• Hot-reload: File changes re-render the TUI instantly (100ms debounce)
• Vim/Emacs/Arrow keybindings: Choose your style, or define custom keys
• 4 built-in themes: Monochrome Zen (default), Solarized, Nord, Dracula
• i18n: English, Chinese, Japanese out of the box
• Agent-agnostic: Any program that writes JSON is a valid controller
• Zero network: 100% local. No telemetry. No cloud. Your data stays yours.
• Hackable: TOML config, custom themes, custom keybindings — mod everything

Agent Integration

Your AI agent just needs to read/write tasks.json:

# One-liner: install + configure + integrate
uv tool install mutsumi && mutsumi init --defaults && mutsumi setup --agent claude-code

Supported agents: Claude Code, Codex CLI, Gemini CLI, OpenCode, Aider, or any custom script.

See Agent Protocol for details. Also see AGENT.md for a one-page cheat sheet.

Terminal Integration

tmux (recommended)

# One command: left shell + right Mutsumi split-pane
bash scripts/tmux-dev.sh

# Custom session name & width
MUTSUMI_WIDTH=40 bash scripts/tmux-dev.sh my-project

iTerm2

1. Cmd+D to split vertically
2. Right pane: mutsumi
3. Left pane: your agent / shell

Demo

# Run the demo script in the left pane to see live-reload in action
bash scripts/demo.sh

Documentation

Document	Description
RFC-001: Core Architecture	Product definition & architecture
RFC-002: Installation	Install & onboarding experience
RFC-003: i18n Strategy	Documentation internationalization
Data Contract	tasks.json schema specification
Agent Protocol	Agent integration protocol
TUI Spec	TUI interaction specification
Roadmap	Development roadmap
Brand	Brand identity

Contributing

See CONTRIBUTING.md.

License

MIT

---

mutsumi (若叶睦) — "harmony, closeness." She doesn't tell you what to do. She just waits there, quietly.