ワークフロー SOP

ゴール

ホットキーひとつでコマンドセンターを起動。左ペインは AI Agent、右ペインはリアルタイムタスクボード。Agent がタスクを書き込み、ボードが即座に更新される。コンテキストスイッチなし。

 Win+~  /  Ctrl+~  (ドロップダウンターミナル)
┌──────────────────────────────┬──────────────────┐
│                              │                  │
│  AI Agent (opencode/claude)  │   Mutsumi TUI    │
│                              │                  │
│  > "auth リファクタリングの  │  ┌─────────────┐ │
│     タスクを3つ追加して"     │  │ [* Main]     │ │
│                              │  │ * ログイン修正│ │
│  mutsumi.json に書き込み中...│  │ * OAuth 追加 │ │
│                              │  │ * テスト作成 │ │
│                              │  └─────────────┘ │
└──────────────────────────────┴──────────────────┘

前提条件

ツール	用途	インストール
ターミナルエミュレータ	ドロップダウン（Quake）モード	Windows Terminal / iTerm2 / Yakuake
tmux（任意）	ペイン分割、セッション永続化	`apt install tmux` / `brew install tmux`（Windows は Terminal の内蔵分割を使用）
uv	Python パッケージマネージャ	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
Mutsumi	タスクボード TUI	`uv tool install git+https://github.com/ywh555hhh/Mutsumi`
AI Agent	`mutsumi.json` にタスクを書き込む	opencode / Claude Code / aider / Codex CLI

プラットフォーム別セットアップ

ステップ 1：Windows Terminal + Quake モード

Windows Terminal には「Quake モード」が内蔵されています。グローバルホットキーを押すと、ゲーム Quake のように画面上部からターミナルがドロップダウンします。

Microsoft Store から Windows Terminal をインストール
設定 → アクション → 追加：

{ "command": { "action": "quakeMode" }, "keys": "win+`" }

これで Win+` でドロップダウンターミナルをグローバルに切り替えられます。

ステップ 2：ツールのインストール

Mutsumi は Windows でネイティブに動作します。WSL は不要です。

# uv（Python マネージャ）
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

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

# AI Agent（いずれかを選択）
uv tool install opencode    # または：npm install -g @anthropic-ai/claude-code

ステップ 3：ペイン分割

Windows Terminal にはペイン分割が内蔵されています。tmux は不要です：

Alt+Shift+D — 自動分割（現在のペインを複製）
Alt+Shift+= — 垂直分割
Alt+Shift+- — 水平分割
Alt+矢印キー — ペイン間の切り替え

ワークフロー：

プロジェクトディレクトリを開く
Alt+Shift+= で垂直分割
右ペインで mutsumi と入力
Alt+← で左ペインに戻り、Agent を起動

以上です！初回の mutsumi 起動時、内蔵のオンボーディングウィザードが言語、キーバインド、テーマ、ワークスペースモード、Agent 統合の設定をガイドします — 手動の init や setup は不要です。

ステップ 1：iTerm2 ホットキーウィンドウ

iTerm2 をインストール
Preferences → Keys → Hotkey → “Show/hide all windows with a system-wide hotkey” をチェック
ホットキーを Ctrl+` に設定

代替案：Ghostty の quick-terminal-hotkey 設定。

ステップ 2：tmux

brew install tmux

ステップ 3：ツールのインストール

# uv
curl -LsSf https://astral.sh/uv/install.sh | sh

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

# AI Agent
uv tool install opencode    # または：npm install -g @anthropic-ai/claude-code

初回の mutsumi 起動時、オンボーディングウィザードが自動的に実行されます — 手動の init や setup は不要です。

ステップ 1：ドロップダウンターミナル

主要な Linux デスクトップにはドロップダウンターミナルのオプションがあります：

デスクトップ	ツール	ホットキー
KDE	Yakuake	`F12`
GNOME	ddterm	`F12`
汎用	Guake	`F12`
汎用	Tilix（Quake モード）	設定可能

ステップ 2：tmux

sudo apt install tmux    # Debian/Ubuntu
sudo pacman -S tmux      # Arch
sudo dnf install tmux    # Fedora

ステップ 3：ツールのインストール

curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install git+https://github.com/ywh555hhh/Mutsumi
uv tool install opencode

初回の mutsumi 起動時、オンボーディングウィザードが自動的に実行されます — 手動の init や setup は不要です。

ワンクリック起動スクリプト

~/.local/bin/mu（または $PATH 上の任意の場所）に保存：

#!/usr/bin/env bash
# mu — Mutsumi 開発環境を起動
# 使い方：mu [プロジェクトディレクトリ] [agent コマンド]
#   mu                          → カレントディレクトリ、デフォルト agent
#   mu ~/projects/saas-app      → 指定プロジェクト
#   mu . claude                 → カレントディレクトリ、Claude Code

set -euo pipefail

PROJECT_DIR="${1:-.}"
AGENT_CMD="${2:-opencode}"
SESSION="mu-$(basename "$PROJECT_DIR")"
MUTSUMI_WIDTH="${MUTSUMI_WIDTH:-35}"

cd "$PROJECT_DIR"

# セッションが既にあればアタッチ
if tmux has-session -t "$SESSION" 2>/dev/null; then
  tmux attach -t "$SESSION"
  exit 0
fi

# 新セッション：左に agent、右に mutsumi
tmux new-session -d -s "$SESSION" -c "$PROJECT_DIR"
tmux split-window -h -p "$MUTSUMI_WIDTH" -t "$SESSION" "mutsumi"
tmux select-pane -t "$SESSION:0.0"

# 左ペインで agent を起動
if [ "$AGENT_CMD" != "shell" ]; then
  tmux send-keys -t "$SESSION:0.0" "$AGENT_CMD" Enter
fi

tmux attach -t "$SESSION"

#!/usr/bin/env fish
# mu — Mutsumi 開発環境を起動

set PROJECT_DIR (realpath (test -n "$argv[1]"; and echo $argv[1]; or echo .))
set AGENT_CMD (test -n "$argv[2]"; and echo $argv[2]; or echo opencode)
set SESSION "mu-"(basename $PROJECT_DIR)
set MUTSUMI_WIDTH (test -n "$MUTSUMI_WIDTH"; and echo $MUTSUMI_WIDTH; or echo 35)

cd $PROJECT_DIR

if tmux has-session -t $SESSION 2>/dev/null
  tmux attach -t $SESSION
  exit 0
end

tmux new-session -d -s $SESSION -c $PROJECT_DIR
tmux split-window -h -p $MUTSUMI_WIDTH -t $SESSION "mutsumi"
tmux select-pane -t "$SESSION:0.0"

if test "$AGENT_CMD" != shell
  tmux send-keys -t "$SESSION:0.0" $AGENT_CMD Enter
end

tmux attach -t $SESSION

# mu.ps1 — Windows ネイティブ起動スクリプト
# PATH に配置するかスタートメニューにピン留め

param(
  [string]$ProjectDir = ".",
  [string]$Agent = "opencode"
)

Push-Location (Resolve-Path $ProjectDir).Path

# Windows Terminal で右ペインに mutsumi を分割起動
wt -w 0 sp -V --size 0.35 mutsumi

# 左ペインで agent を起動
if ($Agent -ne "shell") {
  & $Agent
}

実行権限を付与：

chmod +x ~/.local/bin/mu

日常の使い方

ホットキーを押す — Win+</kbd> / <kbd>Ctrl+ / F12 — ターミナルがドロップダウン
起動 — プロジェクトディレクトリで mu と入力（または mu ~/projects/my-app）
作業 — 左ペインで AI Agent と会話、右ペインでタスクがリアルタイム更新
タスク完了 — Mutsumi でチェックボックスをクリックするか x キーで完了マーク
プロジェクト切替 — mu ~/projects/other-app で新しい tmux セッションを開き、Ctrl-b s でセッション間を切り替え
デタッチ — Ctrl-b d でセッションをデタッチ。バックグラウンドで動き続けます。mu でいつでも復帰
非表示 — ホットキーをもう一度押してターミナルを非表示

マルチプロジェクトレイアウト

パワーユーザー向け — 複数プロジェクトの同時管理：

 tmux セッション：
  mu-saas-app     →  opencode  |  mutsumi (saas-app/mutsumi.json)
  mu-oshigrid     →  claude    |  mutsumi (oshigrid/mutsumi.json)
  mu-personal     →  shell     |  mutsumi (~/.mutsumi/mutsumi.json)

 Ctrl-b s → セッションピッカー → 瞬時切替

Multi-Source Hub を使えば、Main ダッシュボードで全プロジェクトを一覧できます。

Agent 互換性

起動スクリプトはすべてのターミナル AI Agent と互換：

mu . opencode     # OpenCode
mu . claude       # Claude Code
mu . aider        # Aider
mu . codex        # Codex CLI
mu . shell        # Agent なし、シェルのみ

すべての Agent は同じプロトコルを使用：mutsumi.json を読み込み → タスクを変更 → 書き戻し。プロンプトテンプレートは Agent セットアップを参照。

上級テクニック：mu をシェルの起動スクリプトに追加するか、tmux キーバインドに割り当て：

# ~/.tmux.conf — Ctrl-b M でプロジェクトピッカーを開く
bind M command-prompt -p "Project:" "run-shell '~/.local/bin/mu %1'"

トラブルシューティング

問題	解決方法
`mu: command not found`	`~/.local/bin` を `$PATH` に追加
tmux ペインが狭すぎる	`export MUTSUMI_WIDTH=40` または `Ctrl-b →` でリサイズ
Agent が `mutsumi.json` に書き込まない	`mutsumi setup --agent <name>` でプロンプトを注入、または `mutsumi init` でオンボーディングを再実行
Quake モードが動作しない	ターミナルのホットキー設定を確認。DE がキーを横取りしている可能性