データとバックアップ

Agent Boardのデータは、すべて手元のマシンの一つのフォルダに保存されます。このページでは、ファイルの場所、プロジェクトとフォルダの登録、エージェントにフォルダへのアクセスを許可する方法、バックアップの取り方を示します。

データの保存先

既定のデータフォルダは、ホームフォルダ直下の.agent-board/です。

OS	既定のフォルダ
macOS	`~/.agent-board/`
Windows	`%USERPROFILE%\.agent-board\`

別のデータフォルダを使うにはAGBOARD_HOMEを設定します。空の値は未設定として扱います。ボードを共有するには、CLI、サーバー、Hook、agboard setupが同じフォルダを使う必要があります。

text

.agent-board/
  bindings.json          フォルダの登録(マシン固有)
  serve.json             CLIが起動中のagboard serveを見つける情報
  .internal/
    preferences.json     言語とカラーテーマ（アプリが書き込む）
  shared/
    workspace.json
    projects/<project-id>/
      README.md
      project.json
      docs/
        README.md
      tasks/<task-id>/
        task.json
        TASK.md
        assets/
      epics/<EPIC-ID>/
        epic.json
        EPIC.md
        assets/

ファイルはプレーンなMarkdownとJSONです。各ファイルに必要な内容はMarkdownファイルの形式に説明があります。formatVersionが1でないファイルは未対応で、アプリは問題として報告し、ファイルを変更しません。移行、旧形式へのフォールバック、旧データの削除・初期化は行いません。

.internal/フォルダには、アプリ自身の設定が入ります。preferences.jsonには、設定で選んだ言語とカラーテーマを保存します。この設定は、このPCのすべてのブラウザとモバイルモニターに適用されます。ファイルはアプリが書き込むので、手で編集しないでください。shared/の外にあるため、プロジェクトのファイルには含まれません。

各プロジェクトのdocs/には、自分のMarkdown文書を置きます。ボードのヘッダーのドキュメントから読んだり編集したりできます。フォルダは短いREADME.mdとともにAgent Boardが作りますが、中のファイルはボードのデータとして扱いません。変更してもボードは変わりません。詳しくはプロジェクトのドキュメントを参照してください。

プロジェクトとフォルダ

ほとんどのコマンドは、--project NAMEでプロジェクトを指定します。プロジェクトは、名前を変えてもIDを保つので、フォルダの登録・タスク・履歴は新しい名前に追従します。

agboard project create "My project"
agboard project ls --json
agboard --project "My project" project rename "Website launch"

--projectを明示しているコマンドでは、名前を更新してください。フォルダに基づく進行表とHookは、同じプロジェクトを引き続き解決します。project rmは、指定したプロジェクトと、そのタスクとdocs/を削除します。人の確認を求め、エージェントは使えません。

フォルダを登録する

--projectを渡さないとき、agboard progressとHookは、最も近い登録済みのプロジェクトのフォルダを使います。project createは、現在の作業フォルダも登録します。別の既存のフォルダには--folderを、既存のプロジェクトにはproject bindを使います。

agboard project create "Website launch" --folder ./website
agboard project bind "My project"
agboard project bind "My project" --folder ./docs

一つのフォルダは一つのプロジェクトに属し、複数のフォルダが同じプロジェクトに属することもできます。サブフォルダでコマンドを実行した場合は、親フォルダをたどり、最も近い登録先のプロジェクトを選びます。登録がない、または壊れているときは、別のプロジェクトを推測せずにエラーを返します。ほかのコマンドも、ブラウザやほかのエージェントからプロジェクトを推測しません。

登録は、データフォルダのbindings.jsonに別に保存され、マシン固有のパスを含みます。同じマシンのバックアップには、このファイルを残してかまいません。別のマシンでは、project bindで正しいフォルダを登録します。コミットしたり、共有のプロジェクトファイルの中に置いたりしないでください。

共有フォルダをセットアップする

agboard setupは、CodexとClaude Codeのためにデータフォルダを準備します。プロジェクトは不要で、次を行います。

データフォルダと、その中のshared/フォルダを作成します。
Codexのconfig.tomlにあるsandbox_workspace_write.writable_rootsへ、データフォルダを追加します。対象は$CODEX_HOME、なければ~/.codexです。
Claude Codeのsettings.jsonにあるpermissions.additionalDirectoriesへ、データフォルダを追加します。対象は$CLAUDE_CONFIG_DIR、なければ~/.claudeです。

agboard setup --dry-run
agboard setup

--agent codex|claude|allで更新する設定を選びます。既定はallです。--dry-runは変更内容を表示するだけで、何も変更しません。--jsonは同じ結果をJSON形式で表示します。ドライランの出力は次のようになります(<home>はホームフォルダを表します)。

text

Dry run: no files, folders, or backups were created.
Data directory: <home>/.agent-board
Shared folder: <home>/.agent-board/shared
Codex: planned <home>/.codex/config.toml
  - add "<home>/.agent-board" to sandbox_workspace_write.writable_roots
Claude Code: planned <home>/.claude/settings.json
  - add "<home>/.agent-board" to permissions.additionalDirectories

セットアップは既存の設定をすべて残し、上の配列だけを変更します。既存の設定ファイルを変更する前に、同じフォルダへ<file>.agboard-backup-<id>という名前のバックアップを作成します。もう一度実行しても何も変更されず、各ファイルはunchangedと表示されます。

Codexの設定を更新できるのは、sandbox_modeが"workspace-write"の場合だけです。権限プロファイル（default_permissions、permissions、profile、profiles）には対応していません。セットアップがsandbox_modeを変更することもありません。

設定の更新が拒否された場合は、config.tomlにsandbox_mode = "workspace-write"を自分で設定してから、再実行してください。拒否された実行では、ファイルは変更されません。既定の--agent allでは、Codexの設定を更新できなければClaude Codeの設定も変更しません。Codexを使わない場合は、agboard setup --agent claudeでClaude Codeだけを対象にできます。

Hookとエージェントのスキルは、セットアップとは別に手動で登録します。手順はエージェントとの連携を参照してください。

セットアップは、利用者自身が一度だけ実行する手順です。通常の作業中にエージェントへ実行させないでください。プロジェクトや組織の設定によってアクセスが制限される場合もあるため、セットアップ後は新しいセッションで共有フォルダを読み書きできることを確認してください。

EPIC.mdへの移行

以前のバージョンは、エピックの詳細をPLAN.mdに保存していました。このバージョンではEPIC.mdに保存します。移行は自動で行われ、以前のバージョンはEPIC.mdを読めません。

初めて実行する前に、agboard serve、エージェント、エディターを止め、shared/フォルダ全体をバックアップしてください（次の節の手順を参照）。

プロジェクトを初めて読み込むと、Agent Boardは各エピックのPLAN.mdを、同じフォルダ内でEPIC.mdに名前変更します。ファイルの中身は変わらないので、frontmatter・priority・本文・画像・添付・タスクの所属はそのまま残ります。名前変更はプロジェクトの書き込みロックの中で行うため、途中で止まっても次の読み込みで完了します。すでにEPIC.mdがあるエピックは変更しません。

次の二つの場合は確認が必要です。

両方のファイルがある。 Agent Boardはどちらのファイルも変更しません。そのプロジェクトの読み込みはすべてfile_invalidで失敗し、エラーはエピックと両方のパスを示します。二つを比べて、残す内容をEPIC.mdにし、もう一方のファイルを手で削除してください。
どちらのファイルもない。 エピックは一覧に出ますが、詳細は空になります。snapshotは、そのファイルをproblemsに報告します。バックアップから戻してください。

以前のバージョンに戻すには、移行前に取ったバックアップを復元します。以前のバージョンは、移行後にEPIC.mdへ書かれた詳細を読めません。PLAN.mdが残ったバックアップを、この版で読み込むと、再び移行されます。

連携先（スクリプトやHook）の名前も変わります。

以前	現在
`epic edit --plan`	`epic edit --document`
`epic edit --plan-file`	`epic edit --document-file`
エピックJSONの`plan`	`document`
Hook・進行表・waitの`planPath`	`documentPath`
`PLAN.md`	`EPIC.md`

以前の名前は受け付けず、出力もしません。Hookのスクリプト、エージェントへの指示、これらの項目を読むスクリプトを更新してください。

バックアップと復元

バックアップや復元の前に、agboard serve、エージェント、ファイルへ書き込むエディターを止めてください。すべてのプロジェクトをワークスペースの管理情報とともに保存するには、shared/フォルダ全体をコピーします。1つのプロジェクトだけなら、workspace --jsonのfolderの値を使って、そのフォルダ全体をコピーします。サーバーとエージェントを再起動する前に、コピーを同じ場所へ戻してください。

shared/をコピーしても.internal/は含まれないため、プロジェクトのバックアップには言語とカラーテーマが残りません。それらも残すには、preferences.jsonもあわせてコピーしてください。

次に読む

エージェントとの連携: エージェントをこのフォルダにつなぎます。
トラブルシューティング: プロジェクトやフォルダが見つからない。

データとバックアップ ​

データの保存先 ​

プロジェクトとフォルダ ​

フォルダを登録する ​

共有フォルダをセットアップする ​

EPIC.mdへの移行 ​

バックアップと復元 ​

次に読む ​