Beta Testing Guide

What You’re Testing

Two experiences — we call them aha moments — must feel magical before we ship v1.0.0. Your job is to try them and tell us if they land.

Aha 1: Out-of-the-Box

One command to install, 3-second onboarding, you’re in. Total time budget: under 60 seconds.

Aha 2: Agent Live Sync

Talk to your AI agent casually, Mutsumi updates in real time. Magic moment: under 30 seconds.

Aha 1: Out-of-the-Box

Goal: From zero to seeing your first task on screen — no docs, no config, no YAML.

Prerequisites

Requirement	How to check
macOS / Linux terminal	`uname`
Python 3.12+	`python3 --version`
`uv` or `pip`	`uv --version` or `pip --version`

Step 1: Install

uv tool install --prerelease allow mutsumi-tui

pip install --pre mutsumi-tui
# or pin the exact version:
pip install mutsumi-tui==1.0.0b1

pipx install mutsumi-tui --pip-args='--pre'

uv tool install git+https://github.com/ywh555hhh/Mutsumi.git

Verify:

mutsumi --version   # → mutsumi, version 1.0.0b1
mutsumi --help      # → shows subcommands

Step 2: First launch

cd ~/some-project
mutsumi

You should see a single-page onboarding screen:

┌─────────────────────────────────────────────────────────┐
│               Welcome to Mutsumi                        │
│                                                         │
│  Language       ● English  ○ 中文  ○ 日本語             │
│  Keybindings    ● Arrows  ○ Vim  ○ Emacs                │
│  Theme          ● Monochrome Zen  ○ Nord  ○ Dracula     │
│  Workspace      ● Personal + Project                    │
│  Agent          ○ Claude Code  ○ Codex CLI  ● Skip      │
│                                                         │
│           [Start Mutsumi]           [Skip]               │
└─────────────────────────────────────────────────────────┘

Step 3: Create your first task

After onboarding you land on an empty board. Click [+ New Task] or press n, type a title, and hit Create.

Checklist

#	What to check	Expected
1	Install command works	No compilation, pure Python
2	`mutsumi --version`	`1.0.0b1`
3	First launch shows onboarding	Single page, not multi-step wizard
4	All 5 settings visible at once	Language, Keybindings, Theme, Workspace, Agent
5	Select 中文 → Start	UI immediately shows Chinese
6	Select Nord → Start	Colors change instantly
7	Click Skip	Enters TUI with defaults, no crash
8	Second launch skips onboarding	Direct to TUI
9	Empty state has [+ New Task]	Clickable button
10	Press `?`	Shows help screen

Pass condition: Zero-to-first-task in under 60 seconds, no documentation needed.

Aha 2: Agent Live Sync

Goal: You talk to your AI agent, it writes JSON, Mutsumi updates before the agent finishes its response.

Setup: Split terminal

You need two panes side by side:

┌──────────────────────────┬──────────────────────────┐
│                          │                          │
│   AI Agent               │   Mutsumi TUI            │
│   (Claude Code, etc.)    │                          │
│                          │                          │
└──────────────────────────┴──────────────────────────┘

tmux new-session -d -s dev
tmux split-window -h -p 35 "mutsumi"
tmux select-pane -t 0
tmux attach -t dev

Press Cmd+D to split. Right pane: mutsumi. Left pane: your agent.

Split the terminal panel. Right: mutsumi. Left: your agent.

Skill injection

Tell your agent about Mutsumi’s JSON protocol:

mutsumi setup --agent claude-code    # or codex-cli, gemini-cli, opencode

The core loop: Talk → Write → See

Try these conversations with your agent:

Add a task casually
```
You: "帮我加个 todo，明天交周报"
```
Agent writes to mutsumi.json. Mutsumi detects the change and shows the new task — no restart, no flicker.

Batch add

You: "把这三个 bug 加进去：登录页白屏、支付超时、头像上传失败，都是 high priority"

All 3 tasks appear after a single re-render.

Mark done

You: "登录页白屏修好了，标记完成"

Checkbox updates, task grays out.

Edit fields

You: "把支付超时的优先级降到 normal，加个 tag 叫 backend"

Priority stars and tags update instantly.

Reverse direction

The sync is bidirectional. Toggle a checkbox in Mutsumi → mutsumi.json updates → agent can read the latest state.

Checklist

#	What to check	Expected
1	Agent adds 1 task	Appears within 1 second
2	Agent adds 3 tasks at once	All 3 appear, single re-render
3	Agent marks task done	Checkbox + strikethrough update
4	Agent edits priority	Stars change immediately
5	Agent writes invalid JSON	Error banner, no crash
6	Agent fixes JSON	Error clears, tasks reappear
7	No flicker during updates	Cursor position preserved
8	Toggle done in TUI	JSON file updates, agent can see it

Pass condition: Tasks appear on screen before the agent finishes printing its response. Your reaction: “that’s it?” (in a good way).

Reporting Feedback

Copy this template and send it to Wayne:

## Environment
- OS:
- Terminal:
- Python version:
- Install method: uv / pip / source
- Agent (if testing Aha 2):

## Aha 1 (Out-of-the-Box)
- Install time:
- Onboarding: smooth / had issues
- First task created: yes / no
- Overall feeling (1-5):
- Issues:

## Aha 2 (Agent Live Sync)
- Agent used:
- Split pane setup: tmux / iTerm2 / VS Code / other
- Add task via agent: worked / failed
- Hot-reload speed: instant / noticeable delay / broken
- Overall feeling (1-5):
- Issues:

## General
- Would you use this daily? yes / maybe / no
- What surprised you (good or bad)?
- What's missing?