使い方

1インストールと初回起動

1. DMG を開き、cmds.app を「アプリケーション」フォルダ（または ~/Applications）にドラッグして開きます。ソースからビルドする場合は README の手順を参照してください（Xcode、XcodeGen、Zig が必要）。
2. macOS のファイアウォールが有効な場合、受信接続の確認が出ます。iPhone/iPad コンパニオンを使うなら「許可」を選びます（ターミナル自体はどちらでも動きます）。
3. 通知も許可してください。cmds が背面にあるときに、入力待ちのペインを macOS の通知で知らせます。
4. ウィンドウを閉じても cmds とターミナル（エージェント）は動き続けます。Dock のアイコンか ⌘N でウィンドウが戻ります。エージェントの実行中に終了しようとすると確認が出ます。
5. アップデートは自動です（0.2.0 以降）。1 日 1 回確認し、新しい版をダウンロードして、cmds の終了時に入れ替えます。すぐに入れるには cmds › アップデートを確認…。cmds › 設定… › アップデート でオフにできます。
6. 任意：cmds › コマンドラインツールをインストール… で /usr/local/bin/cmds へのリンクを作ると、ほかのターミナルからも cmds を使えます（cmds の中のターミナルでは最初から使えます）。

起動すると、ホームディレクトリのターミナルを 1 つ持つワークスペースが開きます。

2ワークスペースと分割

• ⌘N で新しいワークスペース、⌘1…⌘9 で切り替え、⇧⌘R（またはダブルクリック）で名前を変更。行はドラッグで並べ替えられます。
• ⌘D で右に、⇧⌘D で下に分割。⌥⌘＋矢印でペイン間を移動、⇧⌘↩ でペインをズーム、⌘W で閉じます。
• サイドバーの各行には、Git ブランチ、ディレクトリ、待ち受けポート、エージェントの状態とタスク、最新の通知が表示されます。⌥⌘F で絞り込み、表示 › ワークスペースをプロジェクトでまとめる も使えます。
• 見ていないペインのプログラムが通知（OSC 9/777、ベル、cmds notify）を出すと、そのペインがオレンジのリングで光ります。⇧⌘U で最新の通知へジャンプ。

3タイル表示

複数のワークスペースを、それぞれ入力もできるライブタイルとして並べます。

• サイドバーで ⌘-クリック（追加・解除）や ⇧-クリック（範囲）で選ぶと、すぐにタイルになります。
• 表示 › すべてのワークスペースを並べて表示（⌃⌘T）で全部を並べ、もう一度押すと 1 つに戻ります。最大 9 枚。
• サイドバーの行をコンテンツ領域へドラッグしても並べられます（端に落とすと隣や上下へ、中央なら入れ替え）。タイルの見出しをドラッグして移動、サイドバーへ戻すと外れます。
• タイルの見出しに状態とタスクが出て、入力待ちのタイルはリングで光ります。⇧⌘↩ で 1 枚を大きく表示。
• Claude Code のサブエージェント（Task / Agent ツール）は、タイルの下にカードで表示されます。種類と説明、いま実行中の操作、経過時間、トークン数（サブエージェント用のフックが必要）。

4ブラウザとプレビュー

• ⇧⌘B でターミナルの右にブラウザを開きます。⌘L でアドレスバー、⌘R で再読み込み、⌘[ / ⌘] で戻る・進む。
• ⇧⌘O（ファイル › プレビューで開く…）、またはターミナルに表示されたパスの ⌘-クリックで、ファイルをプレビューペインに表示。画像、PDF、動画、Office、テキストは Quick Look、Markdown は整形表示、diff は色付きで表示します。
• ファイルが変更されると自動で再読み込みされます。エージェントが書いたレポートや画像をそのまま確認できます。

5cmds コマンド

cmds のターミナルは自分がどのペインかを知っている（CMDS_PANE_ID）ので、cmds は実行したペインを基準に動きます。

cmds ls                                   # ワークスペースとペインの一覧
cmds split down -- npm run dev            # 下に新しいペインを作って開発サーバーを起動
cmds browser open http://localhost:3000   # ブラウザペインで開く
cmds open README.md                       # ファイルをプレビュー
git diff | cmds open --diff -             # diff を色付きで表示
make test; cmds notify "tests done: $?"   # 終わったらこのペインを光らせる
cmds stats                                # ワークスペースごとと Mac 全体の CPU・メモリ

cmds --help と cmds <コマンド> --help で全コマンドを確認できます。すべて --json で JSON を出力します。

6Claude Code と Codex の設定

通知と状態（フック）

~/.claude/settings.json（またはプロジェクトの .claude/settings.json）に追加します。許可や入力を求めると「入力待ち」になってリングが光り、ターンが終わると「完了」、入力すると「作業中」に戻ります。SubagentStart / SubagentStop はサブエージェントのカードと、サイドバーの「サブ 3」のような数の表示に使います。

{
  "hooks": {
    "Notification": [
      { "hooks": [{ "type": "command", "command": "command -v cmds >/dev/null && cmds hook claude || true" }] }
    ],
    "Stop": [
      { "hooks": [{ "type": "command", "command": "command -v cmds >/dev/null && cmds hook claude || true" }] }
    ],
    "UserPromptSubmit": [
      { "hooks": [{ "type": "command", "command": "command -v cmds >/dev/null && cmds hook claude || true" }] }
    ],
    "SubagentStart": [
      { "hooks": [{ "type": "command", "command": "command -v cmds >/dev/null && cmds hook claude || true" }] }
    ],
    "SubagentStop": [
      { "hooks": [{ "type": "command", "command": "command -v cmds >/dev/null && cmds hook claude || true" }] }
    ]
  }
}

使用量と上限（ステータスライン）

ステータスラインのスクリプトが入力を読んだ（input=$(cat)）あとに 1 行追加します。モデル、コンテキスト、料金、5 時間・7 日間の上限がサイドバーに出ます。セッションの再開にもこの設定が必要です。

[ -n "$CMDS_PANE_ID" ] && command -v cmds >/dev/null 2>&1 && printf '%s' "$input" | cmds hook claude-status >/dev/null 2>&1

ステータスラインのスクリプトがなければ、"statusLine": {"type": "command", "command": "cmds hook claude-status"} だけでも動きます（表示は空になります）。

スキルと Codex

• MCP サーバー：claude mcp add --scope user cmds -- cmds mcp（Codex は ~/.codex/config.toml に [mcp_servers.cmds] command = "cmds" args = ["mcp"]）で登録すると、cmds のターミナルで動くエージェントが Chrome ではなく cmds のブラウザペインで Web ページを開き、スクリーンショットや JavaScript で確認します。ファイルのプレビューやサイドバーの状態表示も使えます。
• スキル：integrations/claude/skills/cmds/SKILL.md を ~/.claude/skills/cmds/（Claude Code）や ~/.codex/skills/cmds/（Codex）にコピーすると、エージェントがフォーカスを奪わずに補助ペインやプレビューを使い、Web ページを Chrome ではなく cmds のブラウザペインで開くようになります。
• Codex：使用量は設定不要です。通知は ~/.codex/config.toml の [tui] に notifications = true、notification_method = "osc9"、notification_condition = "always" を設定します。

7iPhone/iPad のペアリング

1. Mac で cmds › iPhone/iPadとペアリング… を選ぶと、QR コードと 6 桁のコードが表示されます（ウィンドウを開いている間だけ有効）。
2. iPhone/iPad のコンパニオンで「ペアリングコードをスキャン」をタップして QR コードを読み取ります。カメラを使わない場合は、Mac を選んで ID を照合し、6 桁のコードを入力します。
3. 接続すると、Mac のワークスペースの一覧が表示されます。ワークスペースを開くとターミナルの画面がライブで表示され、キーバーや入力欄から返答できます。キーバーの上のショートカットボタン（承認・考慮・別案・再確認・claude・codex）は、タップでその文字を送って改行し、長押しで改行せずに入力します。ボタンは ⋯ › 設定… で編集できます。

同じネットワークにいなくても、Wi‑Fi がなければ Bluetooth LE で、外出先では cmds › SSH経由のリモートアクセス… で設定したあなたの SSH サーバーを中継して接続します。どの経路でも、Mac の証明書にピン留めした同じ TLS 接続です。

iPhone・iPad のアプリ「cmds Companion」は App Store から無料で入手できます。

8SSH ワークスペース

• ⇧⌘N（ファイル › 新規SSHワークスペース…）でホストを入力します。~/.ssh/config のホストが補完され、鍵やジャンプホストもいつも通り使われます。
• cmds は制限付きのソケットを同じ SSH 接続でサーバーへ転送します。ペイン › リモートヘルパーをインストール… を一度実行すると、サーバー上でも cmds notify や Claude Code のフックが動き、通知と使用量が手元のサイドバーに届きます。
• 接続が切れるとペインに「切断されました」と表示され、⌘R か「再接続」で同じコマンドを再実行します。

9ファイル一覧ペイン

Mac や SSH ホストのフォルダを、ターミナルの隣に一覧で表示するペインです。2 つ並べると 2 画面のファイルマネージャーになります。

• ⇧⌘E（ファイル › 新規ファイル一覧ペイン）で、フォーカス中のターミナルのディレクトリを右に開きます。ターミナルからは cmds files [PATH]。
• ↩ で開く、Space でプレビューペインに表示。Git のリポジトリでは変更の状態（M・A・? など）の列が出ます。「ターミナルに追従」をオンにすると、ターミナルで cd した先へ一緒に移動します。
• F5 / F6 でもう一方のペインにコピー・移動。ドラッグ＆ドロップ、Finder との間、⌘C / ⌘V も使えます。同じ名前があるときは「両方とも残す」「置き換える」「スキップ」から選べます。
• F2 で名前を変更、F7 で新規フォルダ、⌘⌫ でゴミ箱に入れる。完全に削除することはありません。
• ファイルをターミナルにドロップすると、シェル用にクォートされたパスが入力されます。

SSH ホストのフォルダ

• ⌥⇧⌘E（ファイル › 新規リモートファイル一覧ペイン…）でホストとフォルダを指定します。SSH ペインで ⇧⌘E を押すと、そのペインのリモートのディレクトリが開きます。ターミナルからは cmds files HOST:PATH。サーバーには何もインストールしません（SFTP）。
• 接続にはいつもの ssh（~/.ssh/config、鍵、エージェント、ジャンプホスト）を使います。cmds はパスワードを尋ねたり保存したりせず、ホスト鍵も追加しません。パスワードだけのホストや、known_hosts にない・変わったホスト鍵は、対処方法を添えて断ります。
• 開く・プレビューはダウンロードしたコピー（読み取り専用）で行います。ゴミ箱に入れると、サーバー側のゴミ箱（~/.local/share/Trash）へ移すだけで削除はしません。

転送

• Mac とホストの間、ホスト同士のコピー・移動は転送キューでバックグラウンドで実行されます。進み具合はペインと ウインドウ › 転送（⌥⌘T）で確認でき、一時停止・キャンセル・再試行・ログの表示ができます。cmds transfers でも同じ情報を表示します。
• ファイルは一時的な名前で書き込み、最後まで届いてから本来の名前になります。キャンセルしても、その転送が書いたもの以外は消しません。

10スケジュール

ウインドウ › スケジュール… または cmds schedule で、あとで実行する作業を登録します。cmds の起動中に実行されます。

• いつ：1 回だけ、曜日と時刻、Claude のアカウントや Codex の利用上限がリセットされたとき（「リセットのたびに」で毎回）。
• 何を：ワークスペースをバックグラウンドで開始（フォルダ、アカウント、最初のコマンドや Claude Code への最初のプロンプト）、Claude Code / Codex のセッションを続ける、既存のペインに入力する（空のシェルへのコマンド、待機中のエージェントへのプロンプト）。
• 安全に：作業中や確認待ちのエージェント、別のプログラムが動いているペインには入力しません。同じ実行を 2 回することもなく、実行できないときはスキップして履歴に理由を残します。
• 実行の 1 分前に通知が出て、スキップできます。次回の実行はサイドバーの下に表示されます。Mac がスリープしていた・cmds が起動していなかった場合は、許容範囲内なら 1 回だけ実行します。
• 利用上限に達してほかのアカウントも使えないときは、ペインのバーの「15:01 に続ける」で、リセット後に continue を入力するスケジュールを作れます。

# アカウント work の上限がリセットされたら、このペインのセッションを続ける
cmds schedule add --name "リセット後に続ける" --after-limit work --continue

# 平日 9:00 に ~/src/app で Claude Code を起動して作業を渡す
cmds schedule add --name "朝のテスト" --every weekdays --time 09:00 \
  --start ~/src/app --account auto --prompt "テストを実行して失敗をまとめて" -- claude

cmds schedule list      # 一覧
cmds schedule history   # 実行履歴

11キーボードショートカット