AI に構成を作ってもらうためのガイド

RetainProcess の構成を作る AI へのガイド

このガイドは、RetainProcess を初めて扱う AI アシスタント向けです。利用者の代わりに、RetainProcess に登録する「構成」を書くための書式と規則をまとめています。これは RetainProcess 1.0 の仕様です（出典: https://foo-tec.com/retainprocess/）。

1. RetainProcess とは

• macOS のメニューバーに常駐するアプリ。開発で使う、長く動き続けるコマンド（開発サーバー、ワーカー、ローカル LLM など）を「構成」として登録し、ワンクリックで起動（Run）・停止（Stop）する。
• 動かしている間、CPU・メモリ（プロセスグループの合算）と stdout / stderr のログを表示する。ログはファイルにも保存し、古い世代を指定フォルダへ退避する。
• 停止はプロセスグループ単位: SIGTERM を送り、猶予秒数を過ぎてもグループが残っていれば SIGKILL。
• RetainProcess を終了しても、動かしているコマンドは止まらない。
• CLI retain-process があるが、CLI では構成を追加・編集できない。構成の追加は「取り込み（Import）」か、スタックのファイル（retainprocess.yml）で行う。

2. 出力の選び方（JSON か YAML か）

3. 利用者に確かめること

次の項目が会話から分からなければ、推測せずに質問する。プロジェクトのフォルダを示されたら、先に IDE の起動構成を読む（4 章）と、多くはそこで分かる。

1. 動かすコマンドそのもの（ターミナルで打っているとおりに）
2. どのディレクトリで動かすか（絶対パスか ~/ から）
3. 必要な環境変数、または読む .env ファイル
4. 落ちたときに自動で起動し直したいか（no / on-failure / always）
5. 複数のサービスに依存関係があるか。あるなら、準備完了をポートか HTTP で判定できるか
6. （任意）案件ごとにまとめる名前（ワークスペース）

4. IDE の起動構成から作る（IntelliJ・VS Code・Cursor など）

利用者がプロジェクトのフォルダを示したら、そこにある IDE の起動構成（Run Configuration / launch.json / tasks.json）を読み、RetainProcess の構成に変換できる。コマンド・引数・作業ディレクトリ・環境変数を聞き直さずに済む。

• フォルダを読める AI（Claude Code、Cursor のエージェント、Codex など）なら、フォルダのパスだけで始められる。
• ファイルを読めないチャットの AI なら、下の表のファイルの中身を貼り付けてもらう。
• RetainProcess 自体に IDE の構成を読む機能は無い。変換するのは AI で、結果は通常どおり取り込み用の JSON（または retainprocess.yml）として出す。

探す場所

選び方

• 変換するのは動き続けるものだけ: 開発サーバー、API、ワーカー、ウォッチ（dev・serve・watch・start など）。
• すぐ終わるもの（ビルド、テスト、lint、マイグレーション、コード生成）、デバッガのアタッチ（"request": "attach"）、GUI アプリやシミュレータの起動（Xcode・AppleRunConfiguration・open）は変換しない。
• 見つけた起動構成の一覧と、変換する / しないの判断を先に利用者に見せ、確認を取ってから出力する。
• name は元の起動構成の名前を使う。workspace にプロジェクトのフォルダ名を入れると、まとめて絞り込める。
• 依存関係がある複数の起動構成（VS Code の compounds、tasks の dependsOn、「API を起動してからフロントを起動する」などの手順）は、retainprocess.yml のスタックにするのも提案する。

変数の置き換え

JetBrains の起動構成の読み方（type ごと）

VS Code・Cursor の読み方

• launch.json（"request": "launch" のもの）:
  • node / pwa-node: runtimeExecutable（無ければ node）+ runtimeArgs + program + args。runtimeExecutable が npm なら npm run-script dev のようになる
  • python / debugpy: python の指定（無ければ .venv/bin/python を探す）+ -m module または program + args
  • go: go run <program> + args
  • lldb / cppdbg: program + args（ビルド済みの実行ファイル。preLaunchTask のビルドは含めない）
  • 共通: cwd → working_dir、env → env_text、envFile → env_files。デバッガ専用の設定（console・stopOnEntry・sourceMaps など）は捨てる
• tasks.json: "isBackground": true のものや、名前・コマンドが dev / watch / serve のものが候補。"type": "process" は command を実行ファイル、args を引数に。"type": "shell" はシェルの構文を含みうるので /bin/zsh -lc '…' に。options.cwd / options.env も読む

例

JetBrains の .idea/runConfigurations/dev.xml:

<configuration default="false" name="dev" type="js.build_tools.npm">
  <package-json value="$PROJECT_DIR$/package.json" />
  <command value="run" />
  <scripts><script value="dev" /></scripts>
  <package-manager value="/opt/homebrew/bin/pnpm" />
  <envs><env name="PORT" value="3000" /></envs>
</configuration>

VS Code の .vscode/launch.json:

{
  "configurations": [
    {
      "name": "API",
      "type": "debugpy",
      "request": "launch",
      "module": "uvicorn",
      "args": ["app.main:app", "--reload"],
      "cwd": "${workspaceFolder}/api",
      "envFile": "${workspaceFolder}/api/.env"
    }
  ]
}

プロジェクトのフォルダが ~/src/shop なら、変換結果は次のとおり。

[
  {
    "name": "dev",
    "executable_path": "pnpm",
    "args": "run dev",
    "working_dir": "~/src/shop",
    "env_text": "PORT=3000\n",
    "workspace": "shop"
  },
  {
    "name": "API",
    "executable_path": ".venv/bin/python",
    "args": "-m uvicorn app.main:app --reload",
    "working_dir": "~/src/shop/api",
    "env_text": "PYTHONUNBUFFERED=1\n",
    "env_files": [".env"],
    "workspace": "shop"
  }
]

補足: pnpm は名前で書けば、ログインシェルの PATH で見つかる（元の構成の /opt/homebrew/bin/pnpm のような絶対パスでもよい）。Python の仮想環境の場所（.venv）が構成に書かれていなければ、フォルダの中を確かめるか利用者に聞く。

5. 構成の JSON の書式

取り込みは次の 3 つの形を受け付ける。形 1（構成の配列）を使うこと。

1. 構成の配列 [ {…}, {…} ]（推奨）
2. 構成 1 件のオブジェクト { "name": …, … }
3. config.json 全体（{"version": 1, "configs": [ … ]}。settings は取り込まれない）

すべてのフィールドに既定値があり、省略してよい。既定値と同じなら書かないほうが読みやすい。id は書かない（取り込み時に必ず新しく採番される）。

全項目を書いた例（実際の構成）

RetainProcess で使っている Ollama の構成を、全項目のまま載せる。省略した項目は表の既定値になるので、普段はここまで書かなくてよい。

{
  "id": "8e01a5a9-2f9c-4b4f-a977-5b90bfa5e6dd",
  "name": "Ollama",
  "executable_path": "ollama",
  "args": "serve",
  "working_dir": "",
  "env_text": "# OLLAMA_HOST=127.0.0.1:11434\n# OLLAMA_MODELS=~/.ollama/models\n",
  "env_files": [],
  "workspace": "AI",
  "stop_grace_secs": 10,
  "log_enabled": true,
  "log_max_size_mb": 5,
  "log_max_files": 3,
  "log_file_per_run": false,
  "archive_dir": null,
  "restart": "no",
  "tty": false
}

• id は取り込み時に必ず採番し直されるので、書いてあっても使われない（新しく作るときは書かない）。
• working_dir が空なのでホームで動く。env_text の 2 行は # で始まるコメントで、使うときに外す。
• archive_dir は null（未設定）。アプリ全体の退避先（Log Archive Home）があればそこの Ollama フォルダへ、無ければあふれたログは削除される。空文字列 "" ではなく null にするか、項目ごと省く。

環境変数は次の順に重ね、後のものが勝つ: ログインシェルの環境 → env_files（書いた順）→ env_text。子プロセスには RETAIN_PROCESS=1 も渡る。

6. コマンドの起動のされ方（つまずきやすい点）

• シェルを通さない。 args は分割して直接 execve に渡す。パイプ |、&&、リダイレクト >、$VAR の展開、グロブ *、args の中の ~ はどれも効かない。必要なら executable_path を /bin/zsh、args を -lc 'cd sub && exec npm run dev' のようにする（最後のコマンドは exec で置き換えると、停止と監視が素直になる）。
• 前景で動き続けるコマンドにする。 自分でバックグラウンドに回るもの（docker compose up -d、&、nohup、--daemon、brew services start）は、すぐ終わったように見えて管理できない。-d などを外した前景版を使う。
• 入力は送れない。 パスワードの入力や確認（y/n）を待つコマンドは止まったままになる。sudo は使わない。
• PATH はログインシェルの環境（$SHELL -lic で取得）。nvm・pyenv・Homebrew などで入れたコマンドは、ターミナルと同じように名前で見つかる。仮想環境の Python は executable_path に .venv/bin/python のような作業ディレクトリからのパスを書くと確実。
• 出力のバッファ。 パイプにつながると出力をためて遅れて出すツールがある（Python など）。PYTHONUNBUFFERED=1 を足すか、"tty": true にする。
• 色。 端末でないと色を出さないツールが多い。色が欲しければ "tty": true、または FORCE_COLOR=1 / CLICOLOR_FORCE=1。
• 停止に時間がかかるもの（DB、docker compose up、JVM など）は stop_grace_secs を 15〜30 に増やす。
• ポートの衝突。 同じポートを使うものが既に動いていると、Run は失敗する。
• 引き取り。 同じ実行ファイル・同じ引数のプロセスが RetainProcess の外で既に動いていると、それを引き取って監視・停止の対象にする（その場合、出力は表示できない）。
• 秘密。 env_text の値は設定ファイルに平文で保存される。トークンなどは .env ファイルに置き、env_files で参照するほうがよい。

7. JSON の例

次の配列をそのまま取り込める（1 件だけでも配列にする）。

[
  {
    "name": "Blog Dev",
    "executable_path": "npm",
    "args": "run dev -- --port 4321",
    "working_dir": "~/src/blog",
    "env_text": "NODE_ENV=development\nFORCE_COLOR=1\n",
    "workspace": "Blog"
  },
  {
    "name": "API (uvicorn)",
    "executable_path": ".venv/bin/python",
    "args": "-m uvicorn app.main:app --reload --port 8000",
    "working_dir": "~/src/shop/api",
    "env_text": "PYTHONUNBUFFERED=1\n",
    "env_files": [".env"],
    "restart": "on-failure"
  },
  {
    "name": "Ollama",
    "executable_path": "ollama",
    "args": "serve",
    "env_text": "OLLAMA_HOST=127.0.0.1:11434\n",
    "stop_grace_secs": 10
  },
  {
    "name": "Docker Stack",
    "executable_path": "docker",
    "args": "compose up",
    "working_dir": "~/src/shop",
    "stop_grace_secs": 30
  },
  {
    "name": "Worker (shell)",
    "executable_path": "/bin/zsh",
    "args": "-lc 'source ./env.sh && exec bundle exec sidekiq'",
    "working_dir": "~/src/shop/backend",
    "tty": true,
    "restart": "always"
  }
]

補足: docker compose up の場合、CPU・メモリに出るのは docker の CLI の分だけで、コンテナ自体（Docker の VM の中）は含まれない。

8. スタック（retainprocess.yml）の書式

docker compose のファイルの部分集合。プロジェクトのディレクトリに retainprocess.yml（.yaml も可）として置く。ファイルが正で、アプリ側では編集しない（変えたらファイルを直す）。

トップレベル

• name: スタック名（省略時はディレクトリ名）
• services: サービス名をキーにしたマップ。サービス名は [a-zA-Z0-9][a-zA-Z0-9_.-]*

サービスのキー（これ以外は読み飛ばされ、警告が出る）

• 時間は 500ms / 10s / 1m30s / 2h、または数だけ（秒）。
• image・ports・volumes・build・profiles などは使えない（読み飛ばされる）。コンテナが要るものは、docker compose up を 1 つのサービスの command にする。
• ${VAR} は展開しない。
• : や # を含む値、数字だけの値（ポート番号など）を command の配列や environment に書くときは "…" でくくる。
• 依存の循環、存在しないサービスへの依存、空の command はエラーになり、そのスタックは操作できない。

例

name: shop
services:
  db:
    command: postgres -D ./data -p 5432
    working_dir: backend
    healthcheck:
      port: 5432
      timeout: 1m30s
    stop_grace_period: 15s
  api:
    command: [.venv/bin/python, -m, uvicorn, "app.main:app", --port, "8000"]
    working_dir: api
    env_file: api/.env
    environment:
      PYTHONUNBUFFERED: "1"
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      http: http://localhost:8000/health
    restart: on-failure
  web:
    command: npm run dev
    working_dir: web
    tty: true
    depends_on: [api]
    x-retainprocess:
      workspace: Shop

Up は依存の順に起動し（service_healthy なら準備完了を待つ）、Down は逆順に止める。

9. Mac に最初から入っているもので試す例

利用者が「まず試したい」「何を登録すればよいか分からない」ときは、インストール不要の macOS 標準のコマンドで例を作る。どれも前景で動き続け、Stop で止まる。

JSON の例

[
  {
    "name": "Keep Awake",
    "executable_path": "/usr/bin/caffeinate",
    "args": "-d -i",
    "log_enabled": false
  },
  {
    "name": "Finder Log",
    "executable_path": "/usr/bin/log",
    "args": "stream --style compact --predicate 'process == \"Finder\"'",
    "log_max_size_mb": 2,
    "log_max_files": 2
  },
  {
    "name": "Ping Watch",
    "executable_path": "/sbin/ping",
    "args": "-i 10 www.apple.com"
  },
  {
    "name": "Memory Stats",
    "executable_path": "/usr/bin/vm_stat",
    "args": "60",
    "workspace": "Monitor"
  },
  {
    "name": "Port 9000",
    "executable_path": "/usr/bin/nc",
    "args": "-lk 127.0.0.1 9000"
  },
  {
    "name": "Clock",
    "executable_path": "/bin/zsh",
    "args": "-c 'while true; do date; sleep 60; done'"
  }
]

スタックの例（依存と準備完了を試す）

listener がポート 9000 で待ち受けてから、sender が 5 秒ごとに時刻を送る。retain-process up で順に起動し、listener の Logs に時刻が流れる。

name: mac-demo
services:
  listener:
    command: /usr/bin/nc -lk 127.0.0.1 9000
    healthcheck:
      port: 9000
  sender:
    command: [/bin/zsh, -c, "while true; do date | /usr/bin/nc -w 1 127.0.0.1 9000; sleep 5; done"]
    depends_on:
      listener:
        condition: service_healthy
    restart: on-failure

log は zsh の組み込みコマンドと名前が重なる。RetainProcess はシェルを通さないので log でも /usr/bin/log が動くが、例では絶対パスで書くと誤解が無い。

10. 出す前のチェックリスト

• JSON は構成の配列で、構文として正しい（末尾のカンマなし、env_text の改行は \n）。
• 各構成に name と executable_path がある。id は書いていない。
• args にパイプ・&&・$VAR・~ が無い（あれば /bin/zsh -lc '…' に）。
• 前景で動き続けるコマンドになっている（-d や & が無い）。入力を待たない。sudo が無い。
• env_text の値を引用符でくくっていない。秘密は env_files 側にある。
• 既定値と同じフィールドを省いている。archive_dir を勝手に決めていない。
• YAML なら、使えないキー（image など）を使っていない。依存が循環していない。
• 推測で埋めた値（パス、ポート）があれば、その旨を利用者に伝えている。

11. 利用者に伝える反映のしかた

JSON の場合

1. JSON をコピーする。
2. メニューバーの RetainProcess のアイコンをクリックし、ポップアップの左ペインの ⤓ → Import from Clipboard。ファイルに保存したなら Import from File…。
3. 構成は一覧の末尾に追加される（既存の構成は変わらない。同じものを 2 回取り込むと 2 件になる）。自動では起動しないので、選んで ▶ Run。
4. 直すときは Configuration タブで編集する（自動で保存される。動いている間の変更は次の Run から効く）。

YAML の場合

1. retainprocess.yml をプロジェクトのディレクトリに保存する。
2. そのディレクトリで retain-process up（初回はスタックの登録も行う）。状態は retain-process ps、停止は retain-process down。
3. ファイルを直したら、もう一度 retain-process up（または、ポップアップのスタックの表示で Reload）。

CLI の retain-process は、アプリが起動していないと終了コード 2 で「RetainProcess is not running」と返す。その場合は open -a RetainProcess で起動してもらう。