CLIによる監視と保守

Komugi には、サーバー管理者および AI コーディングエージェントが稼働状況を把握・調査するための 2 つの強力な CLI サブコマンドが組み込まれています。

1. ステータス確認 CLI (`komugi status`)

稼働中の Komugi プロセスと UNIX ドメインソケット経由で安全に通信し、接続中プレイヤー一覧やリアルタイム統計を即座に取得・表示します。

# 接続中プレイヤーと状態を 1 回表示
komugi status

# 1 秒ごとに画面を自動更新 (top コマンド風)
komugi status --watch

# 更新間隔を 2 秒に指定
komugi status -w -i 2s

表示例 (テキスト形式)

=== Komugi Status (稼働時間: 1h 23m 45s | 接続中: 2/10) ===
リレー: 0.0.0.0:19132 → 接続先: mc.example.com:19132 [バックエンド: UP]

NAME      XUID              SERVER    PING (D/U/合計)    TPS (5s/1m)  接続時間  状態    端末
Steve     2535412345678901  lobby     12ms/8ms/20ms      20.0/20.0    15m 22s   Active  Windows
Alex      2535987654321098  survival  45ms/12ms/57ms     19.8/19.9    1h 04m    Limbo   iOS (iPhone14,2)

機械可読・エージェント連携 (`--format json / jsonl`)

外部監視スクリプトや AI エージェントとの連携には、JSON または JSONL 形式を指定します:

komugi status --format json

{
  "started_at": "2026-10-01T07:00:00Z",
  "uptime_seconds": 5025,
  "relay_addr": "0.0.0.0:19132",
  "target_addr": "mc.example.com:19132",
  "backend_status": "UP",
  "player_count": 2,
  "max_players": 10,
  "players": [
    {
      "name": "Steve",
      "xuid": "2535412345678901",
      "server_name": "lobby",
      "down_latency_ms": 12,
      "up_latency_ms": 8,
      "total_latency_ms": 20,
      "tps_5s": 20.0,
      "device_os": "Windows"
    }
  ]
}

2. ログ検索 CLI (`komugi logs`)

LOG_OUTPUT=sqlite で蓄積された SQLite ログ (komugi-logs.db) を安全に検索・集計します。データベースを読み取り専用 (Read-Only) で開くため、稼働中のリレープロセスに一切悪影響を与えません。

主なサブコマンド

komugi logs info

総レコード数、記録開始〜終了日時、ログレベル別の内訳をサマリー表示します。

# 直近のエラーログ 20 件を表示
komugi logs tail -n 20 --level error

# 直近 30 分間のログを取得
komugi logs tail --since 30m

# 特定プレイヤーの切断記録を直近 24 時間から検索 (AND 検索)
komugi logs search Steve 切断 --since 24h

# ノイズログを除外
komugi logs search Steve --exclude 統計 --since 24h

# 直近 1 時間のパケット種類別内訳
komugi logs stats --by packet --since 1h

# 日別のログ件数推移
komugi logs stats --by day

# 30 日以上前のログおよび空の統計ログを確認 (dry-run: 削除しません)
komugi logs prune --empty-stats --older-than 30d

# 実際に削除を実行し、DB 容量を解放
komugi logs prune --empty-stats --older-than 30d --apply --vacuum

3. エージェントフレンドリー設計 (AI エージェント連携)

Komugi の CLI は、AI コーディングエージェント（Antigravity, Codex, OpenCode, Claude Code 等）が直接呼び出して診断できるように設計されています。

1行1オブジェクト (`--format jsonl`)

--format jsonl オプションを使用すると、ログやステータスが 1 行ごとの独立した JSON 文字列として出力されます。これにより、大規模なログでもメモリを消費せずにパイプやストリーミング処理で安全にパースできます。

komugi logs search Steve 切断 --format jsonl

エージェント向け Skill 定義

リポジトリ直下の .agents/skills/komugi-logs/SKILL.md にエージェント向け Skill 仕様が定義されています。エージェントツールとしてこのスキルを登録することで、AI が自然言語のプロンプト（「Steve の昨日の切断ログを調べて原因を教えて」）から自動的に最適な komugi logs コマンドを組み立てて実行できます。

CLIによる監視と保守

1. ステータス確認 CLI (komugi status)