agent-godmode

agent-godmode

Cursor 風のエージェントを構築するための、ワークスペースに限定された MCP ツールです。read_file、write_file、edit_file、run_command、list_filesを利用できます。厳密にバージョン管理されたシステムプロンプト（SYSTEM_PROMPT_V1）とOpenAI 形式のツール定義を含み、1 回のインポートでアプリから任意の LLM を接続できます。

**LLM と API キーはアプリ内に保持されます。**このパッケージが提供するのはツールの実行、サンドボックス化、プロンプトであり、ホスト型モデルではありません。

OpenAI とインプロセスツール：以下のTier Bセクションは単体で動作します。Python コードをスクリプト、モジュール、または REPL にコピーすれば利用でき、別の成果物は必要ありません。

インストール

pip install agent-godmode

編集可能モード／開発用：

pip install -e ".[dev]"

mcp-agent-toolsからの移行：旧パッケージをアンインストールし、agent-godmodeをインストールしてください。Python のインポートをmcp_agent_toolsからagent_godmodeに、CLI をmcp-agent-toolsからagent-godmodeに、環境変数をMCP_AGENT_TOOLS_*からAGENT_GODMODE_*（例：AGENT_GODMODE_ROOT）に変更してください。

ツール

すべてのツールは、単一のワークスペースルートに限定されます。パスはそのルートからの相対パスです（または、ルート配下に解決される場合に限り絶対パスを使用できます）。同じ操作をMCP（agent-godmodeサーバー経由）と、インプロセスの**AgentWorkspace／WorkspaceTools**の両方で利用できます。

ツール	目的
read_file	UTF-8 テキストファイルを読み込みます。行範囲とバイト数の上限を任意で指定できます。
write_file	UTF-8 テキストを作成、上書き、または追記します。親ディレクトリも作成します。
edit_file	既存の UTF-8 ファイル内で検索と置換を行います。old_stringは空でない文字列とし、replace_allは任意です。replace_all=falseの場合、old_stringは完全に 1 回だけ一致する必要があります（唯一の一致となるよう、read_fileで周辺のコンテキストを確認してください）。無効な UTF-8 が含まれる場合、バイナリデータを破損させずにエラーを返します。
list_files	ディレクトリエントリを一覧表示します。再帰、glob、深さの上限、ドットファイルの表示を任意で指定できます。
run_command	argvリストのみを使ってサブプロセスを実行します（シェルは使用しません）。ルート配下のcwdを任意で指定できます。

LLM との連携では、ツールの形式と説明は**OPENAI_TOOL_DEFINITIONSおよびTOOL_DESCRIPTIONSに集約されています。エージェントの動作はSYSTEM_PROMPT_V1**によってガイドされます。

Tier A — Cursor（または任意の MCP クライアント）

1. ワークスペースディレクトリを選択します（このルート配下のパスのみ許可されます）。

2. サーバーエントリを追加します（stdio）。グローバル MCP 設定の例です（Windows ではパスにスラッシュを使用します）。

{
  "mcpServers": {
    "agent-godmode": {
      "command": "agent-godmode",
      "args": [],
      "env": {
        "AGENT_GODMODE_ROOT": "D:/your/project"
      }
    }
  }
}

または、CLI でルートを明示的に指定します（そのプロセスでは環境変数より優先されます）。

{
  "mcpServers": {
    "agent-godmode": {
      "command": "agent-godmode",
      "args": ["--root", "D:/your/project"]
    }
  }
}

3. クライアントがサーバーのinstructionsを自動的に読み込まない場合は、SYSTEM_PROMPT_V1（agent_godmode.promptsまたは以下から取得）をホストのシステムプロンプトに貼り付けます。

環境変数

変数	意味
AGENT_GODMODE_ROOT	--root を指定しない場合は必須です。絶対パスで指定するワークスペースのルートです。
AGENT_GODMODE_MAX_READ_BYTES	1 回の読み取りあたりの最大バイト数（デフォルトは 512000）です。
AGENT_GODMODE_COMMAND_TIMEOUT	サブプロセスのタイムアウト秒数（デフォルトは 120）です。
AGENT_GODMODE_MAX_COMMAND_OUTPUT_BYTES	標準出力と標準エラー出力の合計を切り詰めるバイト数（デフォルトは 256000）です。
AGENT_GODMODE_LIST_MAX_ENTRIES	list_files の上限（デフォルトは 2000）です。
AGENT_GODMODE_ALLOWED_COMMANDS	argv[0] として許可するベース名をカンマ区切りで指定します（例：python,uv,node）。未設定の場合、サンドボックス内のすべてのコマンドが許可されます。

Tier B — Python アプリ（インプロセス + OpenAI）

設計上の注意

• ワークスペースのルート — 例では D:\Avi-assign をプレースホルダーとして使用しています。WORK_DIR を任意の管理下にあるディレクトリに設定してください。
• API キーのポリシー — OPENAI_API_KEY が必要なのは Chat Completions の場合のみです。インポート時に client = OpenAI() if HAS_OPENAI_KEY else None が設定されます。ワークスペースのセットアップと直接の edit_file はキーなしで実行できます。
• モデルが生成する I/O — write_file では、モデルから返されたテキストのみを保存してください。edit_file では、モデルが read_file から old_string を正確にコピーする必要があります（SYSTEM_PROMPT_V1 を参照）。

1. 依存関係のインストール

シェルまたは任意のインタラクティブな Python セッションで実行します。

pip install -q openai
pip install -q -e "D:/MCP"   # editable checkout; or: pip install agent-godmode

環境が行マジック（たとえば、IPython の %pip）に対応している場合は、同じインストールをそこで実行できます。%pip と同じ行にシェルコメントを記述しないでください。

2. インポートと API キーの処理

import os
from pathlib import Path

# OPENAI_API_KEY is required only for steps that call Chat Completions (LLM + agent loops).
# Workspace + direct edit_file work without a key.
# Set via OS env or e.g. %env OPENAI_API_KEY sk-... in IPython
# Local-only optional override — never commit a real key:
# os.environ["OPENAI_API_KEY"] = "sk-..."

from openai import OpenAI

from agent_godmode import (
    AgentWorkspace,
    OPENAI_TOOL_DEFINITIONS,
    SYSTEM_PROMPT_V1,
    run_agent_loop,
)

HAS_OPENAI_KEY = bool(os.environ.get("OPENAI_API_KEY"))
client = OpenAI() if HAS_OPENAI_KEY else None
MODEL = "gpt-4o-mini"

if not HAS_OPENAI_KEY:
    print(
        "Note: OPENAI_API_KEY not set — Chat Completions examples will raise until you set it. "
        "Workspace + direct edit_file still work."
    )

3. ワークスペースの初期化とシードファイル

# Fixed workspace — all reads/writes/commands stay under this folder
WORK_DIR = Path(r"D:\Avi-assign")
WORK_DIR.mkdir(parents=True, exist_ok=True)
print("Workspace:", WORK_DIR.resolve())

hello = WORK_DIR / "hello.txt"
if not hello.exists():
    hello.write_text("Hello from Avi-assign workspace.\n", encoding="utf-8")

ws = AgentWorkspace(WORK_DIR)
print(ws.read_file("hello.txt"))
print("--- list_files ---")
print(ws.list_files(".", recursive=False))

4. LLM が生成するファイル本文（ツール呼び出しなし）

OPENAI_API_KEY が必要です。 API を使わずにツールだけを試す場合はスキップしてください。

if client is None:
    raise ValueError(
        "Set OPENAI_API_KEY to run this block (e.g. export OPENAI_API_KEY=... or %env in IPython). "
        "Skip if you only want workspace / edit_file demos."
    )

# 1) Context from disk (read-only)
context = ws.read_file("hello.txt")

# 2) Ask the model to author the entire new file; no static template for the body
user_prompt = (
    "Here is the current contents of hello.txt in my workspace:\n\n"
    f"---\n{context}\n---\n\n"
    "Write ONLY the body of a new Markdown file (no preamble, no code fences) "
    "with a title line and two bullet points explaining what this greeting is for."
)

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {
            "role": "system",
            "content": "You output only the file body the user asked for. No extra commentary.",
        },
        {"role": "user", "content": user_prompt},
    ],
)

generated = (resp.choices[0].message.content or "").strip()
if not generated:
    raise RuntimeError("LLM returned empty content; nothing to write.")

# 3) Persist exactly what the LLM produced
out_rel = "llm_generated_notes.md"
ws.write_file(out_rel, generated, mode="overwrite")
print(f"Wrote {out_rel!r} ({len(generated)} chars from model)\n")
print(ws.read_file(out_rel))

5. 直接の edit_file（Chat Completions なし）

API キーは不要です。 次の行は、まだワークスペースのセクションを実行していない場合に ws を作成します（ルートは同じです）。

# Direct edit_file (no Chat Completions call).
# If `ws` is not defined yet (e.g. you skipped §3), the next few lines create it (same WORK_DIR).
from pathlib import Path

from agent_godmode import AgentWorkspace

if "ws" not in globals():
    WORK_DIR = Path(r"D:\Avi-assign")
    WORK_DIR.mkdir(parents=True, exist_ok=True)
    ws = AgentWorkspace(WORK_DIR)

demo_edit = "edit_demo.txt"
ws.write_file(
    demo_edit,
    "version: 1\nstatus: draft\nfooter: end\n",
    mode="overwrite",
)
print("--- before ---")
print(ws.read_file(demo_edit), end="")
print(ws.edit_file(demo_edit, old_string="status: draft", new_string="status: ready"))
print("--- after ---")
print(ws.read_file(demo_edit), end="")

6. エージェントのループ：モデルが write_file を呼び出す

OPENAI_API_KEY が必要です。

if client is None:
    raise ValueError(
        "Set OPENAI_API_KEY to run this block. "
        "Skip if you only need workspace or direct edit_file."
    )


def complete(messages, tools):
    """One Chat Completions turn; return OpenAI-shaped dict for run_agent_loop."""
    resp = client.chat.completions.create(
        model=MODEL,
        messages=messages,
        tools=tools,
        tool_choice="auto",
    )
    return resp.model_dump()


answer = run_agent_loop(
    complete,
    "Use tools only. List the workspace root, read hello.txt, then call write_file on "
    "agent_notes.txt. The `content` argument must be your own freshly written summary "
    "(several sentences) based only on what you read—do not paste boilerplate.",
    ws,
    system_prompt=SYSTEM_PROMPT_V1,
    max_turns=12,
)
print("--- final answer ---")
print(answer)
print("--- agent_notes.txt (if created by tool write_file) ---")
p = WORK_DIR / "agent_notes.txt"
print(p.read_text(encoding="utf-8") if p.exists() else "(missing)")

7. エージェントのループ：モデルが edit_file を呼び出す

OPENAI_API_KEY と §6 の complete 関数が必要です。

from pathlib import Path

from agent_godmode import AgentWorkspace

if "ws" not in globals():
    WORK_DIR = Path(r"D:\Avi-assign")
    WORK_DIR.mkdir(parents=True, exist_ok=True)
    ws = AgentWorkspace(WORK_DIR)
if "complete" not in globals():
    raise NameError("Define `complete` in §6 (after imports) before running this block.")
if client is None:
    raise ValueError(
        "Set OPENAI_API_KEY to run this block. "
        "The direct edit_file example in §5 works without a key."
    )

target = "edit_agent_target.txt"
ws.write_file(
    target,
    "# Demo\nThere are three erorrs in this sentance.\n",
    mode="overwrite",
)
edit_answer = run_agent_loop(
    complete,
    (
        f"Use tools only. Read `{target}`. Then use edit_file (not write_file) to fix typos: "
        "change erorrs to errors and sentance to sentence. "
        "Copy old_string exactly from read_file; use two edit_file calls or replace_all where appropriate."
    ),
    ws,
    system_prompt=SYSTEM_PROMPT_V1,
    max_turns=14,
)
print("--- agent (edit_file) answer ---")
print(edit_answer)
print("--- file after agent ---")
print(ws.read_file(target), end="")

8. オプション：run_agent_loop を使用しないカスタムツールループ

OPENAI_TOOL_DEFINITIONS を使用し、tools=... を指定して Chat Completions API を呼び出し、tool_calls を解析して、各呼び出しを ws.dispatch(name, json.loads(arguments)) に渡します（import json が必要です）。write_file では、content フィールドにモデルが生成した内容を指定してください。edit_file では、モデルから返された old_string、new_string、replace_all をそのまま渡してください。

AgentWorkspace のオプションの制限

ws = AgentWorkspace(
    r"D:\Avi-assign",
    allowed_commands=frozenset({"python", "uv"}),
    command_timeout_sec=60.0,
)

低レベル（WorkspaceTools + OPENAI_TOOL_DEFINITIONS）

AgentWorkspace を使わずに同じサンドボックスを使用するには、config_from_root(...) と WorkspaceTools を使用します。run_agent_loop の代わりに独自のループを実装する場合は、プロバイダーに OPENAI_TOOL_DEFINITIONS を tools= として渡してください。

from agent_godmode import WorkspaceTools, OPENAI_TOOL_DEFINITIONS, SYSTEM_PROMPT_V1
from agent_godmode.config import config_from_root

tools = WorkspaceTools(config_from_root(r"D:\Avi-assign"))
print(tools.read_file("hello.txt"))

システムメッセージを構成します。

final_system = SYSTEM_PROMPT_V1 + "\n\n" + "Your org rules here."

インポートのリファレンス

• AgentWorkspace — ディレクトリパスを渡します。そのツリー内でのみ read_file / write_file / edit_file / list_files / run_command を使用します
• SYSTEM_PROMPT_V1、SYSTEM_PROMPT_CHANGELOG、TOOL_DESCRIPTIONS
• OPENAI_TOOL_DEFINITIONS — MCP ツールと同じ形式です（チャット補完の tools= 用）
• build_server(config) — FastMCP アプリを構築します（stdio 経由の場合は build_server(cfg).run()）
• run_agent_loop — complete 呼び出し可能オブジェクトを使った最小限の複数ターン実行機能です（WorkspaceConfig または AgentWorkspace を受け付けます）

安全性モデル

• Python： すべてのパスは、AgentWorkspace(...) または config_from_root(...) に渡したディレクトリの配下に解決されます。
• MCP / CLI： AGENT_GODMODE_ROOT または --root を使って同じルールが適用されます（.. による外部への移動はできません）。
• read_file、write_file、edit_file は、そのルート配下にある UTF-8 テキストパスのみを扱います。edit_file には有効な UTF-8（厳密なデコード）が必要です。
• run_command は argv のみを使用します（シェルは使用しません）。AGENT_GODMODE_ALLOWED_COMMANDS で許可リストを任意に設定できます。
• サブプロセスは現在の環境を継承します。子プロセスに見せたくないシークレットを渡さないようにしてください。

CLI

agent-godmode --root D:/your/project

MCP サーバーを stdio で実行します（Cursor のデフォルト）。

エージェントループ（概念）

1. システム = SYSTEM_PROMPT_V1（＋任意のサフィックス）。
2. ユーザーメッセージ + OPENAI_TOOL_DEFINITIONS → LLM。
3. 各 tool_call について、WorkspaceTools.dispatch（または MCP の call_tool）を実行します。これには、サーバーで定義されている read_file、write_file、edit_file、list_files、run_command が含まれます。
4. ツールの結果を追加し、モデルがツールを使わずにテキストを返すまで繰り返します。

run_agent_loop は、complete() 関数を指定して手順 2〜4 を実行します。

ライセンス

MIT