# oh-my-kimi (OMK)

<p align="center">
  <img src="https://raw.githubusercontent.com/wang-h/oh-my-kimi/main/docs/shared/omk-character-spark-initiative.jpg" alt="oh-my-kimi character" width="280">
  <br>
  <em>あなたのcodexは一人じゃない。</em>
</p>

[![npm version](https://img.shields.io/npm/v/oh-my-kimi)](https://www.npmjs.com/package/oh-my-kimi)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js](https://img.shields.io/badge/node-%3E%3D20-brightgreen)](https://nodejs.org)
[![Discord](https://img.shields.io/discord/1452487457085063218?color=5865F2&logo=discord&logoColor=white&label=Discord)](https://discord.gg/PUwSMR9XNk)

> **[Website](https://github.com/wang-h/oh-my-kimi)** | **[Documentation](https://github.com/wang-h/oh-my-kimi#readme)** | **[CLI Reference](https://github.com/wang-h/oh-my-kimi#command-reference)** | **[Workflows](https://github.com/wang-h/oh-my-kimi#recommended-workflows)** | **[OpenClaw 統合ガイド](./docs/openclaw-integration.ja.md)** | **[GitHub](https://github.com/wang-h/oh-my-kimi)** | **[npm](https://www.npmjs.com/package/oh-my-kimi)**

[Kimi Code CLI](https://moonshotai.github.io/kimi-cli/en/)のためのマルチエージェントオーケストレーションレイヤー。

## v0.9.0 の新機能 — Spark Initiative

Spark Initiative は、OMK のネイティブ探索・検査経路を強化するリリースです。

- **`omk explore` ネイティブハーネス** — 読み取り専用のリポジトリ探索を Rust ベースのハーネスで高速かつ厳格に実行します。
- **`omk sparkshell`** — 長い出力の要約と tmux pane キャプチャを行う、オペレーター向けのネイティブ検査サーフェスです。
- **クロスプラットフォームのネイティブリリース資産** — `omk-explore-harness`、`omk-sparkshell`、`native-release-manifest.json` を中心とした hydration 経路がリリースパイプラインに組み込まれました。
- **強化された CI/CD** — `build` ジョブでの明示的な Rust toolchain セットアップ、`cargo fmt --check`、`cargo clippy -- -D warnings` を追加しました。

詳細は [v0.9.0 リリースノート](./docs/release-notes-0.9.0.md) と [リリース本文](./docs/release-body-0.9.0.md) を参照してください。

## 最初のセッション

Codex内部で：

```text
$deep-interview "clarify the auth change"
$ralplan "approve the auth plan and review tradeoffs"
$ralph "carry the approved plan to completion"
$team 3:executor "execute the approved plan in parallel"
```

ターミナルから：

```bash
omk team 4:executor "parallelize a multi-module refactor"
omk team status <team-name>
omk team shutdown <team-name>
```

## 推奨ワークフロー

1. `$deep-interview` — スコープや境界がまだ曖昧なときに明確化するために使います。
2. `$ralplan` — 明確になった内容を、承認可能なアーキテクチャ/実装計画に落とし込みます。
3. `$team` または `$ralph` — 承認済みプランを並列で進めるなら `$team`、1 人の担当者が完了と検証まで粘り強く進めるなら `$ralph` を使います。

## コアモデル

OMXは以下のレイヤーをインストールして接続します：

```text
User
  -> Kimi Code CLI
    -> AGENTS.md (オーケストレーションブレイン)
    -> ~/.codex/prompts/*.md (エージェントプロンプトカタログ)
    -> ~/.codex/skills/*/SKILL.md (スキルカタログ)
    -> ~/.codex/config.toml (機能、通知、MCP)
    -> .omk/ (ランタイム状態、メモリ、計画、ログ)
```

## 主要コマンド

```bash
omk                # Codexを起動（tmuxでHUD付き）
omk setup          # スコープ別にプロンプト/スキル/設定をインストール + プロジェクト .omk + スコープ別 AGENTS.md
omk doctor         # インストール/ランタイム診断
omk doctor --team  # Team/swarm診断
omk team ...       # tmuxチームワーカーの開始/ステータス/再開/シャットダウン
omk status         # アクティブなモードを表示
omk cancel         # アクティブな実行モードをキャンセル
omk reasoning <mode> # low|medium|high|xhigh
omk tmux-hook ...  # init|status|validate|test
omk hooks ...      # init|status|validate|test（プラグイン拡張ワークフロー）
omk hud ...        # --watch|--json|--preset
omk help
```

## Hooks拡張（追加サーフェス）

OMXにはプラグインのスキャフォールディングとバリデーション用の`omk hooks`が含まれるようになりました。

- `omk tmux-hook`は引き続きサポートされ、変更されていません。
- `omk hooks`は追加的であり、tmux-hookワークフローを置き換えません。
- プラグインファイルは`.omk/hooks/*.mjs`に配置されます。
- プラグインはデフォルトで無効です；`OMK_HOOK_PLUGINS=1`で有効にします。

完全な拡張ワークフローとイベントモデルについては`docs/hooks-extension.md`を参照してください。

## 起動フラグ

```bash
--yolo
--high
--xhigh
--madmax
--force
--dry-run
--verbose
--scope <user|project>  # setupのみ
```

`--madmax`はCodexの`--dangerously-bypass-approvals-and-sandbox`にマッピングされます。
信頼された/外部のサンドボックス環境でのみ使用してください。

### MCP workingDirectoryポリシー（オプションの強化）

デフォルトでは、MCP state/memory/traceツールは呼び出し元が提供する`workingDirectory`を受け入れます。
これを制限するには、許可されたルートのリストを設定します：

```bash
export OMK_MCP_WORKDIR_ROOTS="/path/to/project:/path/to/another-root"
```

設定すると、これらのルート外の`workingDirectory`値は拒否されます。

## Codex-Firstプロンプト制御

デフォルトでは、OMXは以下を注入します：

```text
-c model_instructions_file="<cwd>/AGENTS.md"
```

これは`CODEX_HOME`の`AGENTS.md`とプロジェクトの`AGENTS.md`（存在する場合）を結合し、その上にランタイムオーバーレイを追加します。
Codexの動作を拡張しますが、Codexのコアシステムポリシーを置き換えたりバイパスしたりしません。

制御：

```bash
OMK_BYPASS_DEFAULT_SYSTEM_PROMPT=0 omk     # AGENTS.md注入を無効化
OMK_MODEL_INSTRUCTIONS_FILE=/path/to/instructions.md omk
```

## チームモード

並列ワーカーが有利な大規模作業にはチームモードを使用します。

ライフサイクル：

```text
start -> assign scoped lanes -> monitor -> verify terminal tasks -> shutdown
```

運用コマンド：

```bash
omk team <args>
omk team status <team-name>
omk team resume <team-name>
omk team shutdown <team-name>
```

重要なルール：中断する場合を除き、タスクが`in_progress`状態の間はシャットダウンしないでください。

### Team shutdown policy

Use `omk team shutdown <team-name>` after the team reaches a terminal state.
Team cleanup now follows one standalone path; legacy linked-Ralph shutdown handling is no longer a separate public workflow.

チームワーカー用のWorker CLI選択：

```bash
OMK_TEAM_WORKER_CLI=auto    # デフォルト；worker --modelに"claude"が含まれる場合claudeを使用
OMK_TEAM_WORKER_CLI=codex   # Kimi Code CLIワーカーを強制
OMK_TEAM_WORKER_CLI=claude  # Claude CLIワーカーを強制
OMK_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude  # ワーカーごとのCLIミックス（長さ=1またはワーカー数）
OMK_TEAM_AUTO_INTERRUPT_RETRY=0  # オプション：適応型queue->resendフォールバックを無効化
```

注意：
- ワーカー起動引数は引き続き`OMK_TEAM_WORKER_LAUNCH_ARGS`を通じて共有されます。
- `OMK_TEAM_WORKER_CLI_MAP`はワーカーごとの選択で`OMK_TEAM_WORKER_CLI`をオーバーライドします。
- トリガー送信はデフォルトで適応型リトライを使用します（queue/submit、必要に応じて安全なclear-line+resendフォールバック）。
- Claude workerモードでは、OMXはワーカーをプレーンな`claude`として起動し（追加の起動引数なし）、明示的な`--model` / `--config` / `--effort`オーバーライドを無視して、Claudeがデフォルトの`settings.json`を使用します。

## `omk setup`が書き込む内容

- `.omk/setup-scope.json`（永続化されたセットアップスコープ）
- スコープ依存のインストール：
  - `user`：`~/.codex/prompts/`、`~/.codex/skills/`、`~/.codex/config.toml`、`~/.omk/agents/`、`~/.codex/AGENTS.md`
  - `project`：`./.codex/prompts/`、`./.codex/skills/`、`./.codex/config.toml`、`./.omk/agents/`、`./AGENTS.md`
- 起動動作：永続化されたスコープが`project`の場合、`omk`起動時に自動的に`CODEX_HOME=./.codex`を使用（`CODEX_HOME`が既に設定されている場合を除く）。
- 起動命令は`~/.codex/AGENTS.md`（または上書きされた`CODEX_HOME/AGENTS.md`）とプロジェクトの`./AGENTS.md`を結合し、その後ランタイムオーバーレイを追加して使用します。
- 既存の`AGENTS.md`は黙って上書きされません。インタラクティブTTYでは置き換え前に確認し、非インタラクティブ実行では`--force`がない限り置き換えをスキップします（アクティブセッションの安全チェックは引き続き適用されます）。
- `config.toml`の更新（両スコープ共通）：
  - `notify = ["node", "..."]`
  - `model_reasoning_effort = "high"`
  - `developer_instructions = "..."`
  - `[features] multi_agent = true, child_agents_md = true`
  - MCPサーバーエントリ（`omx_state`、`omx_memory`、`omx_code_intel`、`omx_trace`）
  - `[tui] status_line`
- スコープ別`AGENTS.md`
- `.omk/`ランタイムディレクトリとHUD設定

## エージェントとスキル

- プロンプト：`prompts/*.md`（`user`は`~/.codex/prompts/`に、`project`は`./.codex/prompts/`にインストール）
- スキル：`skills/*/SKILL.md`（`user`は`~/.codex/skills/`に、`project`は`./.codex/skills/`にインストール）

例：
- エージェント：`architect`、`planner`、`executor`、`debugger`、`verifier`、`security-reviewer`
- スキル：`deep-interview`、`ralplan`、`team`、`ralph`、`plan`、`cancel`

## プロジェクト構成

```text
oh-my-kimi/
  bin/omk.js
  src/
    cli/
    team/
    mcp/
    hooks/
    hud/
    config/
    modes/
    notifications/
    verification/
  prompts/
  skills/
  templates/
  scripts/
```

## 開発

```bash
git clone https://github.com/wang-h/oh-my-kimi.git
cd oh-my-kimi
npm install
npm run build
npm test
```

## ドキュメント

- **[完全なドキュメント](https://github.com/wang-h/oh-my-kimi#readme)** — 完全ガイド
- **[CLIリファレンス](https://github.com/wang-h/oh-my-kimi#command-reference)** — すべての`omk`コマンド、フラグ、ツール
- **[通知ガイド](https://github.com/wang-h/oh-my-kimi#notifications)** — Discord、Telegram、Slack、webhookの設定
- **[推奨ワークフロー](https://github.com/wang-h/oh-my-kimi#recommended-workflows)** — 一般的なタスクのための実戦で検証されたスキルチェーン
- **[リリースノート](https://github.com/wang-h/oh-my-kimi#release-notes)** — 各バージョンの新機能

## 備考

- 完全な変更ログ：`CHANGELOG.md`
- 移行ガイド（v0.4.4以降のmainline）：`docs/migration-mainline-post-v0.4.4.md`
- カバレッジとパリティノート：`COVERAGE.md`
- Hook拡張ワークフロー：`docs/hooks-extension.md`
- セットアップと貢献の詳細：`CONTRIBUTING.md`

## 謝辞

[oh-my-claudecode](https://github.com/Yeachan-Heo/oh-my-claudecode)にインスパイアされ、Kimi Code CLI向けに適応されました。

## ライセンス

MIT