AWR
GitHub
日本語
English中文Españolहिन्दीPortuguêsРусский日本語한국어DeutschFrançais

クイックスタート

GitHub でソースを見る

このウォークスルーでは、AWRの新規インストールから検証済みのセッションハンドオフまでを進めます。 CLIをインストールし、プロジェクトを初期化し、作業セッションを開始し、後続セッションが最初の セッションの続きから引き継げることを証明します。すべてコピー＆ペーストで実行できます。AWRは独自の SQLiteを同梱しています。

1. AWRをインストールする

AWRはnpmとPyPIでネイティブパッケージとして提供されます。どちらのチャネルも同じRust CLI（awr）と MCPサーバー（awr-mcp）をインストールします。別のJavaScriptやPythonのSDKはありません。

npmの場合（Node 22.14以降が必要）:

npm install -g @originoneai/agent-work-runtime@0.5.1

またはpipの場合、仮想環境内で（Python 3.9以降が必要）:

python -m pip install agent-work-runtime==0.5.1

両方の実行ファイルを確認します:

awr --version
awr-mcp --version

サポートされるプラットフォームは、macOS 15以降（arm64およびIntel x64）、glibc 2.39以降の Linux x64およびarm64（Ubuntu 24.04がベースライン）、Windows x64です。Linuxでは、まずglibcを 確認してください:

ldd --version | head -n 1

npmインストールでは、オプション依存関係を有効にしたままにしてください —— ランチャーがプラットフォーム ごとのネイティブパッケージを解決します。インストールスクリプトやネットワークダウンローダーはありません。 pipホイールはバイナリを埋め込んでいます。アプリケーション作者向けの第3のチャネルもあります。ホスト アプリが埋め込める、2つのバイナリの固定ネイティブペイロードで、そのユーザーは実行時にNode、Python、 Rustを一切必要としません。

2. プロジェクトを初期化する

初期化は2段階の操作です。プレビュー、そして明示的な承認です。--acceptを渡すまで何も書き込まれません。

AWR_PROJECT=/absolute/path/to/your/project
awr --project "$AWR_PROJECT" init

プレビューを読んでください。AWRが見つけたインベントリ —— 既存のMarkdownタスクレジャー、YAMLソース、 ゴール —— と、提案するソースマッピングが表示されます。既存のファイルが上書きされることはありません。 元のドキュメントが権威であり続けます。プレビューが正しければ、承認します:

awr --project "$AWR_PROJECT" init --accept

空のプロジェクトの場合は、目的を最初に明示します:

awr --project "$AWR_PROJECT" init --goal "Deliver a document portal" --accept

Markdownレジャーが非標準のステータス語を使っている場合は、初期化時にマッピングします:

awr --project "$AWR_PROJECT" init \
  --status-map pending=planned --status-map complete=completed --accept

次に、整理レポートを確認します:

awr --project "$AWR_PROJECT" intake inspect --json

レポートのorganization.stateが現状を示します。readyは、少なくとも1つのタスクにソースで宣言された ゴール、受け入れ基準、次のアクション、解決済みの前提条件があることを意味します。 needs_organizationは何かが欠けていることを意味します —— レポートの順序付きactionsが、ソース ファイルに追加すべき内容を教えてくれます。

3. 作業セッションを開始する

セッションはAWRにおける作業オーナーシップの単位です。以下のコマンドは小さなシェルヘルパーを使い、 すべての呼び出しにプロジェクトパスとJSON出力を付与します:

AWR_BIN=$(command -v awr)
AWR_WORK=INTAKE-001          # a task key from your intake report
AWR_AGENT=agent-primary      # a label for who is working
AWR_MODEL=your-current-model # a recorded label; AWR does not invoke the model
AWR_NOTES=$(mktemp -d "${TMPDIR:-/tmp}/awr-session.XXXXXX")
awrj() { "$AWR_BIN" --project "$AWR_PROJECT" --json "$@"; }

何が実行可能かを確認し、クレーム（作業アイテムのランタイムオーナーシップ）と現在のプロジェクト リビジョンを付けてセッションを開始します:

awrj ready
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session start --work "$AWR_WORK" --agent "$AWR_AGENT" \
  --provider generic --model "$AWR_MODEL" --claim --ttl-ms 3600000 \
  --expected-revision "$AWR_REV" > "$AWR_NOTES/start.json"
AWR_SESSION=$(jq -er '.session.id' "$AWR_NOTES/start.json")

作業コンテキストをコンパイルします —— ゴール、受け入れ基準、記録された事実、履歴を境界付きの パケットに組み立てます:

awrj context compile --work "$AWR_WORK" --session "$AWR_SESSION" \
  --budget 5000 > "$AWR_NOTES/context.json"
jq -e '.completeness.complete and (.work_context != null)' "$AWR_NOTES/context.json"

ブール値だけでなく、パケットそのものを読んでください。BudgetExceededの場合は--budgetを広げ、 SourceStaleの場合はawrj source reindexを実行してから再度コンパイルします。

4. チェックポイントで進捗を記録する

離席する前 —— あるいは長いホスト会話がコンパクトされる前 —— に、実際に使ったコンテキストハッシュ、 正直なダイジェスト、正確な次のアクション、すべての未解決ループを含むチェックポイントを保存します:

AWR_CONTEXT_HASH=$(jq -er '.work_context.context_hash' "$AWR_NOTES/context.json")
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session checkpoint --session "$AWR_SESSION" --agent "$AWR_AGENT" \
  --context-hash "$AWR_CONTEXT_HASH" \
  --digest "Record the work actually done; do not invent a passing review." \
  --next-action "State the exact next operator or agent action." \
  --open-loop "List every unresolved loop." \
  --expected-project-revision "$AWR_REV" > "$AWR_NOTES/checkpoint.json"

チェックポイントは未完了の作業を記録できます。テストの合格や受け入れ基準の完了を証明するものでは ありません。

5. 新しいセッションで作業を続ける

継続が機能することを証明するために、最初のセッションを終了し、そこから再開します —— 新しい エージェント、マシン、ホスト会話が使うのと同じ引き継ぎ経路です。終了はクレームを解放します。 ソースの作業を完了としてマークするものではありません:

AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session end --session "$AWR_SESSION" --outcome incomplete \
  --expected-revision "$AWR_REV"

では再開します。任意のエージェント —— 別のエージェントでも、同じエージェントの後の実行でも —— が 前任セッションから後続セッションを作成します:

AWR_PREDECESSOR="$AWR_SESSION"
awrj session show "$AWR_PREDECESSOR"
AWR_REV=$(awrj status | jq -er '.project_revision')
awrj session resume --from-session "$AWR_PREDECESSOR" \
  --agent successor --provider generic --model "$AWR_MODEL" \
  --budget 5000 --expected-revision "$AWR_REV" > "$AWR_NOTES/resume.json"
jq -e '.context_ready' "$AWR_NOTES/resume.json"
AWR_SESSION=$(jq -er '.resumed.session.id' "$AWR_NOTES/resume.json")

2つのチェックでハンドオフが機能したことが確認できます:

  • jq -e '.context_ready'が0で終了する: 後続者が、最後に成功したチェックポイントを含む前任者の 記録済みコンテキストを受け取った。
  • 再開されたセッションには新しいIDがある —— resumeは古いセッションを変更するのではなく、新しい AWRセッションを作成します。

いつでもリカバリー状態を読み取り専用で確認できます:

awrj recovery inspect --session "$AWR_SESSION"

コーディングエージェントのチャット内で作業していますか? ホスト会話をAWRセッションにバインドすれば、 ホストのコンパクションを越えてチェックポイントが生き残ります:

awrj client bind --client generic --external-session "myhost:$HOST_CONVERSATION_ID" \
  --work "$AWR_WORK" --session "$AWR_SESSION"

AWRはホストのプロセスメモリを転送したり、任意の既存プロセスを引き継いだりしません —— 継続性は 明示的に記録されたものから生まれます。

次に読むべきもの