Cvm: Stateful Programable Task Engine

CVM：Claude を体系的な処理エンジンに変える

壊れやすい AI スクリプトを書くのはやめましょう。Claude が一度に 1 つずつ思考を実行するプログラムを書きましょう。

CVM はデュアルライセンスです。 オープンソースでの利用には AGPL-3.0-or-later、プロプライエタリな統合には商用ライセンスが適用されます。詳細は COMMERCIAL.md をご覧ください。

重要

新機能：CVM Plan Protocol（CVM-PP）。 作業を構造化された Markdown プランとして記述すると、 CVM が AI エージェントをタスクごとに進行させます。CVM プログラムを手書きする必要は ありません。プランが CVM-PP 形式なら、CVM はその実行方法を把握しています。 → 概要と仕組み · プロトコル仕様

従来のスクリプト

🔘 グレー = スクリプトの操作

flowchart TD
    Start([Start]) --> Loop{More files?}
    Loop -->|Yes| Call[Call Claude API with process file prompt]
    Call --> Response[Get Response]
    Response --> Lost[❌ Context Lost]
    Lost --> Loop
    Loop -->|No| End([End])
    
    Response -.->|Crash| Restart[Start Over From Beginning]
    
    classDef script fill:#e0e0e0,stroke:#666,color:#000
    
    class Start,Loop,Call,Response,Lost,End,Restart script

CVM アーキテクチャ

🟢 緑 = CVM の操作 | 🔵 青 = Claude のアクション | 🟡 黄 = 人間による制御

flowchart TD
    Start([Start]) --> Loop{More files?}
    Loop -->|Yes| CC[CC: analyze file]
    CC --> Pause((⏸️ PAUSE))
    Pause --> Wait[Wait for Claude]
    Wait --> GetTask[Claude: getTask]
    GetTask --> Process[Claude analyze file]
    Process --> Submit[Claude: submitTask]
    Submit --> Save[✓ State saved]
    Save --> Loop
    Loop -->|No| End([End])
    
    Pause -.->|Can inspect| Status[Check Progress]
    Submit -.->|Crash| Resume[Resume from here, just going to start]
    
    classDef cvm fill:#d4ffd4,stroke:#090,color:#000
    classDef claude fill:#d4d4ff,stroke:#00d,color:#000
    classDef human fill:#ffffd4,stroke:#990,color:#000
    
    class Start,Loop,CC,Pause,Wait,Save,End cvm
    class GetTask,Process,Submit claude
    class Status,Resume human

実際の動作：壊れやすい仕組みから堅牢な仕組みへ

CVM を使わない場合、呼び出しを手動でつなぎます。クラッシュすると、状態が失われます。

// Fragile, stateless, and hard to inspect
const result1 = await claude.call("Step 1: Analyze this");
const result2 = await claude.call("Step 2: Based on '" + result1 + "', do this");
// If this fails, you have to start over from scratch

CVM を使う場合、シンプルなプログラムを書きます。VM が状態を管理します。

// Resilient, stateful, and observable
function main() {
  const step1 = CC("Step 1: Analyze this");
  const step2 = CC("Step 2: Based on '" + step1 + "', do this");
  return step2;
}

重要なのは、CVM が step2 に進む前に step1 を保存することです。いつでも停止して、状態を確認し、再開できます。

今すぐ試す

Node.js 22 以降が必要です。

次の内容を counter.ts として保存します。

function main() {
  var count = 0;
  while (count < 5) {
    var next = CC("Current number is " + count + ". What's the next number?");
    count = +next;
  }
  return count;
}

Claude に 「counter.ts を CVM で実行して」 と伝えます。

どうなるか：

1. CVM がプログラムを読み込み、実行を開始します
2. 各 CC() で CVM は一時停止して待機します
3. Claude が次のタスクを取得します：「現在の数値は 0 です。次の数値はいくつですか？」
4. Claude が「1」を送信します
5. CVM が count を更新し、ループを続行します
6. 完了するまで繰り返します

パラダイムシフト：CPU としての Claude

graph LR
    subgraph "CVM System"
        PROGRAM["📜 Program<br/>(Instructions)"]-->|"loaded into"| CVM["🖥️ CVM<br/>(CPU + RAM)"]
        CVM-->|"executes until CC()<br/>then halts"| HALT["⏸️ Halted<br/>(Awaiting input)"]
        HALT-->|"getTask"| CLAUDE["🧠 Claude<br/>(Driver)"]
        CLAUDE-->|"submitTask"| CVM
        USER["👤 User<br/>(Observer)"]-."can interact<br/>with Claude".->CLAUDE
    end

従来のスクリプトでは、Claude をサービスとして扱います。CVM では、Claude が処理を進めます。

CVM が開発者にとって革新的な理由

独自のアーキテクチャによるメリット：

• 制御フローの反転：コードから AI API を呼び出す代わりに、VM は単に一時停止して待機します。Claude は準備ができると、自らタスクを取得します
• 状態の保持：VM はやり取りを通じてすべての状態を維持するため、長時間実行されるタスクでのコンテキスト喪失を防ぎます
• 集中した認知タスク：開発者が扱うのは特定の判断ポイントだけで、フロー全体を管理する必要はありません

開発者体験：

• シンプルな API：分かりやすい関数が 6 つあるだけです（load、start、getTask、submitTask、status など）
• TypeScript ネイティブ：使い慣れた TypeScript の構文でプログラムを記述できます
• 明確な分離：決定論的なロジックはコードで扱い、認知タスクは AI に委任します
• ファイルへの永続化：呼び出しの間の状態管理を自動で行います

開発者向けのユースケース：

• AI による推論が必要な、複雑で複数ステップのワークフロー
• 適切な判断ポイントを含むデータ処理パイプライン
• コンテキストに応じて適応する対話型開発ツール
• 創造的な入力が必要なテストシナリオ
• チェックポイントを含むコード生成ワークフロー

CVM の特長： Claude のドキュメントにある「GPS のたとえ」がぴったりです。開発者はルートを書きますが、複雑なフローで道に迷う心配はありません。VM が実行をステップごとに案内するため、通常なら AI のコンテキストウィンドウを圧迫するタスクに最適です。

プロンプトエンジニアリングや状態管理の複雑さに悩むことなく、AI を活用したツールを構築したい開発者にとって、特に洗練された仕組みです。

CC() は呼び出しではなく、一時停止です

CC(prompt) は「Claude を呼び出す」という意味ではありません。次の意味です。

stateDiagram-v2
    [*] --> Package: CC(analyze this)
    Package --> PAUSE: Create task
    PAUSE --> WAIT: Execution stops here
    WAIT --> PULL: Claude calls getTask
    PULL --> PROCESS: Claude processes
    PROCESS --> RESUME: Claude submits result
    RESUME --> [*]: Continue with result
    
    state Package {
        [*] --> p1: Package prompt
        p1 --> p2: Into task object
    }
    
    state PAUSE {
        [*] --> pause: ⏸️ Program paused
        pause --> save: State saved
    }
    
    state WAIT {
        [*] --> waiting: 🔄 Waiting for Claude
    }

Python の yield や JavaScript の await のようなものですが、認知タスク向けです。

実例

function main() {
  var files = fs.listFiles("./docs");
  var summaries = []; // State lives safely in CVM
  
  for (const file of files) {
    // PAUSE: Ask Claude to summarize this file
    var content = CC("Read and summarize: " + file);
    summaries.push({ filename: file, summary: content });
    // CVM automatically resumes here with content
  }
  
  // PAUSE: Ask Claude to create final report
  var report = CC("Create report from: " + JSON.stringify(summaries));
  return report;
}

flowchart TD
    START([Start]) --> LIST[fs.listFiles]
    LIST --> INIT[summaries = empty array]
    INIT --> LOOP{For each file}
    
    LOOP -->|Has files| CC1[CC: Read and summarize file]
    CC1 --> PAUSE1[⏸️ CVM Pauses]
    PAUSE1 --> CLAUDE1[Claude pulls task]
    CLAUDE1 --> SUMMARY[Claude returns summary]
    SUMMARY --> SAVE[Push to summaries array]
    SAVE --> LOOP
    
    LOOP -->|No more files| CC2[CC: Create final report]
    CC2 --> PAUSE2[⏸️ CVM Pauses]
    PAUSE2 --> CLAUDE2[Claude creates report]
    CLAUDE2 --> RETURN[Return report]
    RETURN --> END([End])
    
    CRASH{{If crash at file 500}} -.-> STATE[(CVM State:<br/>499 summaries<br/>preserved)]
    STATE -.-> RESUME[Can resume<br/>from file 500]
    

CVM はこれを堅牢なワークフローに変えます。1000 個のファイルのうち 500 個目で失敗しても、最初の 499 個の要約は CVM の状態に安全に保存されています。

Python スクリプトを書くだけではだめなのですか？

graph LR
    subgraph YourScript["Your Script"]
        S1[❌ Stateless]
        S2[❌ Fragile]
        S3[❌ Opaque]
        S4[❌ Rigid]
        
        S1 --> API1[API Call 1]
        API1 --> S2
        S2 --> API2[API Call 2]
        API2 --> S3
        S3 --> CRASH[💥 Crash = Start Over]
    end
    
    subgraph CVMArch["CVM"]
        C1[✅ Stateful]
        C2[✅ Resilient]
        C3[✅ Observable]
        C4[✅ Flexible]
        
        C1 --> TASK1[Task 1]
        TASK1 --> STATE1[(State Preserved)]
        STATE1 --> TASK2[Task 2]
        TASK2 --> STATE2[(State Updated)]
        STATE2 --> PAUSE[⏸️ Can Pause/Resume]
    end
    

スクリプト	CVM
❌ ステートレス： API 呼び出しのたびに最初から開始します	✅ ステートフル： すべての変数が自動的に保持されます
❌ 脆弱： クラッシュすると最初からやり直しです	✅ 高い回復性： 状態が維持され、いつでも再開できます
❌ 不透明： 進行状況を確認できません	✅ 可観測： いつでも状態を確認できます
❌ 柔軟性がない： 途中で介入できません	✅ 柔軟： 各 CC() でデフォルトで一時停止します

内部の仕組み

CVM はパッシブな MCP サーバーです。Claude が実行を能動的に進めます。

sequenceDiagram
    participant Claude
    participant CVM
    participant State as CVM State
    
    Claude->>CVM: load("counter", "...program code...")
    CVM->>State: Store program
    
    Claude->>CVM: start("counter", "exec-123")
    CVM->>State: Initialize count = 0
    
    loop While count < 5
        Claude->>CVM: getTask("exec-123")
        CVM-->>Claude: "Current number is 0. What's the next number?"
        Claude->>Claude: Process task
        Claude->>CVM: submitTask("exec-123", "1")
        CVM->>State: count = 1
        Note over CVM: Continue loop execution
    end
    
    Claude->>CVM: getTask("exec-123")
    CVM-->>Claude: "Execution completed with result: 5"

CVM は完全にパッシブで、何かを自ら開始することはありません。すべてを Claude が進めます。

MCP（Model Context Protocol）上に構築

上記の getTask／submitTask のやり取りは、Claude の Model Context Protocol（MCP） に準拠しています。MCP は、Claude が操作できるステートフルで回復性の高いツールを構築するための仕様です。CVM は MCP サーバーとして動作し、これによって Claude が実行を能動的に進められます。CVM を使ううえで MCP を理解する必要はありませんが、CVM がこの標準に基づいて構築されていると知っておくと、その独自のパッシブなアーキテクチャを理解しやすくなります。

CVM の仕組み：インタープリター

TypeScript の while ループを実行途中で一時停止できるのはなぜだろう、と疑問に思うかもしれません。その答えは、CVM が Node.js や ts-node でコードを実行しているわけではないということです。代わりに、CVM は独自のインタープリターを使い、次の処理を行います。

1. TypeScript に似たコードを抽象構文木（AST）に解析します
2. このツリーを順にたどり、各命令を実行します
3. CC() に遭遇すると、完全な実行状態を保存して一時停止します
4. Claude が結果を送信すると、まったく同じ位置から再開します

これが、CVM がどこでも一時停止できる理由です。ネイティブの JavaScript を実行するのではなく、コードを命令ごとに慎重に解釈しているのです。

CVM 自身を使った開発

CVM 自体の開発は、CVM プログラムで管理されています。これは単に自分たちで試しているだけではなく、CVM が複雑で実際の開発ワークフローにも対応できることの証明です。

🔧 機能の進化プログラム

• RegExp の実装 - TDD でパターンマッチングを追加
• String と Array のメソッド - 15 個のメソッドを体系的に実装
• Object Keys と For ループ - 言語機能を強化

🏗️ アーキテクチャのリファクタリング

• CVM Evolution Executor - 重大なアーキテクチャ上の欠陥を修正
• テストカバレッジの分析 - テストを体系的に改善

これらのプログラムは、Claude による何百もの連携した変更を導きます。

• まず失敗するテストを書く（TDD）
• 機能を段階的に実装する
• 変更のたびにテストスイートを実行する
• 進捗を体系的にコミットする
• ドキュメントを自動的に更新する

各プログラムは複雑なタスクを認知チェックポイントに分解します。CVM がワークフロー全体を通じて状態を完全に維持するなか、各チェックポイントで Claude が実装を行い、コードをレビューし、問題を修正して、正しさを検証します。

CVM Plan Protocol（CVM-PP）：エージェントが自ら計画を進めるようにする

タスクごとに CVM プログラムを手作業で書く必要はありません。CVM は CVM Plan Protocol（CVM-PP） に対応しています。作業を構造化された Markdown の 計画 （ミッション＋順序付けされたアトミックブロックのリスト）として記述すれば、 計画が CVM-PP 形式である限り、CVM はその実行方法を認識します。AI エージェントは、 一度に 1 つずつタスクを進めて、自ら計画を遂行します。

CVM は作業そのものを実行するのではなく、順序を決めます。計画をチェックポイントの ストリームに変換し、エージェントに一度に 1 つのタスクを渡します（失敗するテストを書く → 実装する → 各基準を検証する → コミットする）。ループ／再試行／再開／進行状況の状態は すべて CVM が保持します。エージェントは実際の作業を行って結果を報告し、CVM が次へ 進みます。これは CC() と同じガイドロープの考え方を開発計画全体に適用したもので、 エージェントは計画全体をコンテキストに保持しなくても、長い計画に沿って作業できます。

flowchart LR
    PLAN["📄 Markdown plan<br/>(mission + blocks)"] -->|parsePlan| UPLAN["🧩 uplan.json<br/>(validated + compiled)"]
    UPLAN -->|planexecutor| SEQ["🔁 One task at a time<br/>RED → GREEN → VERIFY → COMMIT"]
    SEQ -->|CC checkpoint| AGENT["🧠 AI agent<br/>does the work, reports back"]
    AGENT -->|done| SEQ

2 つの要素：

• parsePlan — 計画を文法に照らして検証し、.cvm/uplan.json にコンパイルします。 違反があると、正確な line N: message エラーを出して失敗します。
• planexecutor — ブロックを順に処理し、エージェントに一度に 1 つのフェーズタスクを 出力して、完了の報告を受けるたびに次へ進みます。完了したブロックは .cvm/uplan-progress.json にチェックポイントとして保存されるため、中断した実行を 中断箇所から再開できます。

計画には 2 種類あります。tddab（テスト駆動ブロック、RED → GREEN → VERIFY → CROSS-CHECK → COMMIT）と step（アクションブロック、EXECUTE → VERIFY → COMMIT） で、単一ファイルにも、インデックスファイルと複数のサブファイルにも対応できます。

CVM-PP は、文書化された安定した仕様です。 AI（または任意のツール）がプロトコルに 準拠した計画を生成すれば、変換なしですぐに実行できます。仕様の全文（文法、検証規則、 例、作成チェックリスト）は docs/PLAN_FORMAT.md に記載されて おり、外部の計画生成ツールとの相互運用を目的としています。

ユニバーサルスキル：任意の AI エージェントで CVM を単独利用する

CVM には 3 つの ユニバーサルスキルが含まれています。自己完結した Markdown ガイドで、 保守担当者独自のエージェント設定を使わずに、任意の AI エージェントが CVM-PP 計画を 作成、レビュー、実行できます。各スキルでは、フォーマットの唯一の信頼できる情報源として docs/PLAN_FORMAT.md を参照しています。

• skills/cvm-plan-create/SKILL.md — 有効な CVM-PP 計画 （ミッション＋アトミックブロック）を作成し、parsePlan で検証します。
• skills/cvm-plan-review/SKILL.md — 実行前に計画を レビューします。parsePlan による機械的な検証を行い、その後、意味的な品質を確認します。
• skills/cvm-plan-execute/SKILL.md — 検証済みの計画を parsePlan → start → getTask/submitTask のループを通じて、最初から最後まで実行します。

インストール（Claude Code）

各スキルディレクトリを、プロジェクトの .claude/skills/ フォルダーにコピーします。

mkdir -p .claude/skills
cp -r skills/cvm-plan-create  .claude/skills/
cp -r skills/cvm-plan-review  .claude/skills/
cp -r skills/cvm-plan-execute .claude/skills/

またはシンボリックリンクを作成すると、このリポジトリの更新が反映されます。

mkdir -p .claude/skills
ln -s "$(pwd)/skills/cvm-plan-create"  .claude/skills/cvm-plan-create
ln -s "$(pwd)/skills/cvm-plan-review"  .claude/skills/cvm-plan-review
ln -s "$(pwd)/skills/cvm-plan-execute" .claude/skills/cvm-plan-execute

スキルは YAML フロントマター付きのプレーンな Markdown で、エージェントに依存しません。 他のエージェントフレームワークも同じ SKILL.md ファイルをそのまま取り込めます。 上記のインストールパスを除き、Claude Code 固有の要素はありません。

言語機能と制限事項

CVM はカスタムインタープリターを使用するため、信頼性と安全性を重視して設計された TypeScript のようなサブセットをサポートしています。

✅ サポートされる機能

機能	例
変数	var name = "CVM"; var version = 1;
基本型	文字列、数値、真偽値、null、undefined
配列	[1, 2, 3]、items.push(4)、items[0]
オブジェクト	{name: "Claude", age: 2}、obj.name
ループ	while (i < 5)、for (const item of array)
条件分岐	if (x > 10) { ... } else { ... }
演算子	+、-、*、/、===、!==、&&、`

❌ サポート対象外

• import／require 文
• async／await（代わりに CC() を使用してください）
• クラスと new キーワード
• try...catch ブロック（下記のエラー処理を参照）
• アロー関数 () => {}
• スプレッド演算子 ...
• 分割代入 const {a, b} = obj
• テンプレートリテラル `Hello ${name}`

📦 組み込み関数

関数	説明
CC(prompt: string): string	Claude がタスクを処理するために実行を一時停止します
console.log(...args)	CVM コンソールに出力します
fs.listFiles(path, options?)	ディレクトリ内のファイルを一覧表示します（サンドボックス内に制限）
JSON.stringify(obj)	オブジェクトを JSON 文字列に変換します
JSON.parse(str)	JSON 文字列をオブジェクトに解析します

セキュリティとサンドボックス

CVM はコードを安全で隔離された環境で実行します。

• ネットワークアクセスなし：スクリプトから HTTP リクエストを送信したり、インターネットにアクセスしたりすることはできません
• ファイルシステムの制限：fs.listFiles() は CVM の作業ディレクトリ内に制限されます
• システムアクセスなし：シェルコマンドの実行や環境変数へのアクセスはできません
• メモリ制限：スクリプトには適切なメモリ制限が設けられています
• 実行タイムアウト：長時間実行される処理は自動的に終了します

セキュリティをさらに高めるため、機密データを処理する際は CVM を Docker コンテナ内で実行することをおすすめします。

実践的な使い方

try...catch を使わないエラー処理

CVM は try...catch をサポートしていないため、Claude の応答を防御的に検証する必要があります。

// ❌ Fragile - assumes Claude returns a number
function fragileCounter() {
  var count = 0;
  while (count < 5) {
    var next = CC("Current number is " + count + ". What's next?");
    count = +next;  // Fails if Claude returns "four" instead of "4"
  }
}

// ✅ Robust - validates the response
function robustCounter() {
  var count = 0;
  while (count < 5) {
    var result = CC("Current number is " + count + ". What's next?");
    var nextNum = parseInt(result, 10);
    
    if (isNaN(nextNum)) {
      console.log("Invalid response: '" + result + "'. Retrying...");
      // Loop continues without incrementing, effectively retrying
    } else {
      count = nextNum;
    }
  }
  return count;
}

実行状態の確認

status ツールを使って、実行中の処理の状態を確認できます。

// Claude can check status at any time:
const status = await cvm.status("exec-123");
console.log(status);
// {
//   "executionId": "exec-123",
//   "status": "PAUSED",
//   "currentTask": "Analyzing file 247 of 1000",
//   "state": {
//     "filesProcessed": 246,
//     "summaries": [...]
//   }
// }

これにより、長時間実行されるタスクを監視し、実行を中断せずに進捗を確認できます。

クイックリファレンス

Claude が使用する MCP ツール：

• load(programId, source) - プログラムを読み込みます
• start(programId, executionId) - 実行を開始します
• getTask(executionId) - 次のタスクを取得します
• submitTask(executionId, result) - 結果を送信します
• status(executionId) - いつでも状態を確認します
• parsePlan(filePath) - CVM-PP プランを検証し、.cvm/uplan.json にコンパイルします（CVM Plan Protocol を参照）

CVM が保持するもの：

• すべての変数とその値
• 現在の実行位置
• ループカウンターと条件
• 一時停止中も保持されるプログラムの完全な状態

インストール

Claude の MCP 設定に追加します。

{
  "mcpServers": {
    "cvm": {
      "command": "npx",
      "args": ["cvm-server@latest"]
    }
  }
}

使用例

Claude が多くの項目を体系的に処理する必要がある、あらゆるワークフローに最適です。

• ドキュメント分析パイプライン
• 複数のソースからのデータ抽出
• 複数の入力を使ったレポート生成
• 多数のファイルにわたるコードのリファクタリング
• AI による処理を伴うループが必要なあらゆるタスク

→ API ドキュメント全文 → CVM Plan Protocol（CVM-PP）仕様

重要なポイント

CVM は Claude を賢くするものではありません。Claude が体系的に作業できるようにします。

CVM なし：優秀ですが、まとまりがありません CVM あり：優秀さに加え、完璧な記憶力とチェックリストを備えています

---

ライセンス

CVM はデュアルライセンスです。

• AGPL-3.0-or-later — オープンソース、個人利用、研究利用、および AGPL のネットワーク条項（第 13 条）に準拠した社内利用は無料です。
• 商用ライセンス — プロプライエタリな統合、クローズドソースでの再配布、または AGPL-3.0 と両立しないあらゆる用途で必要です。

CVM を商用製品に統合したい企業、クローズドソースのツールに組み込みたい企業、または自社のコードを AGPL のもとで公開せずにホスト型サービスの一部として提供したい企業は、COMMERCIAL.md をご覧ください。

以前のバージョンに関する注意： バージョン 0.16.0-next.8 までのすべてのリリースは Apache-2.0 のもとでライセンスされており、引き続きその条件で利用できます。バージョン 1.0.0 以降、CVM は上記のとおりデュアルライセンスとなっています。

---

Copyright (C) 2025-2026 Ladislav Sopko.