{
  "markdown": "# agent-godmode\n\n<!-- mcp-name: io.github.mdvohra/agent-godmode -->\n\nWorkspace-scoped **MCP tools** for building Cursor-style agents: **read_file**, **write_file**, **edit_file**, **run_command**, **list_files**. Includes **strict, versioned system prompts** (`SYSTEM_PROMPT_V1`) and **OpenAI-style tool definitions** so your app can wire any LLM with one import.\n\nThe **LLM and API keys stay in your app**. This package provides tool execution, sandboxing, and prompts—not a hosted model.\n\n**OpenAI + in-process tools:** the **Tier B** section below is self-contained—copy the Python into a script, module, or REPL; no separate artifact is required.\n\n## Install\n\n```bash\npip install agent-godmode\n```\n\nEditable / dev:\n\n```bash\npip install -e \".[dev]\"\n```\n\n**Migrating from `mcp-agent-tools`:** uninstall the old package, install **`agent-godmode`**, change Python imports from `mcp_agent_tools` to **`agent_godmode`**, the CLI from `mcp-agent-tools` to **`agent-godmode`**, and environment variables from `MCP_AGENT_TOOLS_*` to **`AGENT_GODMODE_*`** (for example `AGENT_GODMODE_ROOT`).\n\n## Tools\n\nAll tools are scoped to a single **workspace root**. Paths are relative to that root (or absolute only if they resolve under it). The same operations are available over **MCP** (the `agent-godmode` server) and in-process via **`AgentWorkspace`** / **`WorkspaceTools`**.\n\n| Tool | Purpose |\n|------|---------|\n| **`read_file`** | Read a UTF-8 text file; optional line range and byte cap. |\n| **`write_file`** | Create or overwrite/append UTF-8 text; creates parent directories. |\n| **`edit_file`** | Search-and-replace in an existing UTF-8 file: non-empty `old_string`, optional `replace_all`. With `replace_all=false`, `old_string` must match **exactly once** (use surrounding context from `read_file` for uniqueness). Invalid UTF-8 returns an error instead of corrupting binary data. |\n| **`list_files`** | List directory entries with optional recursion, glob, depth cap, dotfile control. |\n| **`run_command`** | Run a subprocess from an **`argv` list only** (no shell); optional `cwd` under the root. |\n\nFor LLM integrations, tool shapes and descriptions are centralized in **`OPENAI_TOOL_DEFINITIONS`** and **`TOOL_DESCRIPTIONS`**; agent behavior is guided by **`SYSTEM_PROMPT_V1`**.\n\n## Tier A — Cursor (or any MCP client)\n\n**1.** Pick a workspace directory (only paths under this root are allowed).\n\n**2.** Add a server entry (stdio). Example for a global MCP config (paths use forward slashes on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-godmode\": {\n      \"command\": \"agent-godmode\",\n      \"args\": [],\n      \"env\": {\n        \"AGENT_GODMODE_ROOT\": \"D:/your/project\"\n      }\n    }\n  }\n}\n```\n\nOr with an explicit CLI root (overrides env for that process):\n\n```json\n{\n  \"mcpServers\": {\n    \"agent-godmode\": {\n      \"command\": \"agent-godmode\",\n      \"args\": [\"--root\", \"D:/your/project\"]\n    }\n  }\n}\n```\n\n**3.** Paste **`SYSTEM_PROMPT_V1`** (from `agent_godmode.prompts` or below) into your host’s system prompt if the client does not load server `instructions` automatically.\n\n### Environment variables\n\n\n| Variable                                   | Meaning                                                                                                                       |\n| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |\n| `AGENT_GODMODE_ROOT`                     | **Required** unless `--root` is passed. Absolute workspace root.                                                              |\n| `AGENT_GODMODE_MAX_READ_BYTES`           | Max bytes per read (default `512000`).                                                                                        |\n| `AGENT_GODMODE_COMMAND_TIMEOUT`          | Subprocess timeout in seconds (default `120`).                                                                                |\n| `AGENT_GODMODE_MAX_COMMAND_OUTPUT_BYTES` | Truncate stdout/stderr combined (default `256000`).                                                                           |\n| `AGENT_GODMODE_LIST_MAX_ENTRIES`         | Cap for list_files (default `2000`).                                                                                          |\n| `AGENT_GODMODE_ALLOWED_COMMANDS`         | Comma-separated **basenames** allowed as `argv[0]` (e.g. `python,uv,node`). If unset, all commands allowed under the sandbox. |\n\n\n## Tier B — Python app (in-process + OpenAI)\n\n**Design notes**\n\n- **Workspace root** — Examples use `D:\\Avi-assign` as a placeholder; point `WORK_DIR` at any directory you control.\n- **API key policy** — `OPENAI_API_KEY` is required **only** for Chat Completions. Imports set `client = OpenAI() if HAS_OPENAI_KEY else None`; workspace setup and **direct `edit_file`** run without a key.\n- **Model-authored I/O** — For `write_file`, persist **only** text returned by the model. For `edit_file`, the model must copy **`old_string`** exactly from **`read_file`** (see `SYSTEM_PROMPT_V1`).\n\n### 1. Install dependencies\n\nIn a shell or any interactive Python session:\n\n```bash\npip install -q openai\npip install -q -e \"D:/MCP\"   # editable checkout; or: pip install agent-godmode\n```\n\nIf your environment supports line magics (for example `%pip` in IPython), you can run the same installs there; do not place shell comments on the same line as `%pip`.\n\n### 2. Imports and API key handling\n\n```python\nimport os\nfrom pathlib import Path\n\n# OPENAI_API_KEY is required only for steps that call Chat Completions (LLM + agent loops).\n# Workspace + direct edit_file work without a key.\n# Set via OS env or e.g. %env OPENAI_API_KEY sk-... in IPython\n# Local-only optional override — never commit a real key:\n# os.environ[\"OPENAI_API_KEY\"] = \"sk-...\"\n\nfrom openai import OpenAI\n\nfrom agent_godmode import (\n    AgentWorkspace,\n    OPENAI_TOOL_DEFINITIONS,\n    SYSTEM_PROMPT_V1,\n    run_agent_loop,\n)\n\nHAS_OPENAI_KEY = bool(os.environ.get(\"OPENAI_API_KEY\"))\nclient = OpenAI() if HAS_OPENAI_KEY else None\nMODEL = \"gpt-4o-mini\"\n\nif not HAS_OPENAI_KEY:\n    print(\n        \"Note: OPENAI_API_KEY not set — Chat Completions examples will raise until you set it. \"\n        \"Workspace + direct edit_file still work.\"\n    )\n```\n\n### 3. Workspace bootstrap and seed file\n\n```python\n# Fixed workspace — all reads/writes/commands stay under this folder\nWORK_DIR = Path(r\"D:\\Avi-assign\")\nWORK_DIR.mkdir(parents=True, exist_ok=True)\nprint(\"Workspace:\", WORK_DIR.resolve())\n\nhello = WORK_DIR / \"hello.txt\"\nif not hello.exists():\n    hello.write_text(\"Hello from Avi-assign workspace.\\n\", encoding=\"utf-8\")\n\nws = AgentWorkspace(WORK_DIR)\nprint(ws.read_file(\"hello.txt\"))\nprint(\"--- list_files ---\")\nprint(ws.list_files(\".\", recursive=False))\n```\n\n### 4. LLM-authored file body (no tool calls)\n\n**Requires `OPENAI_API_KEY`.** Skip if you are only exercising tools without the API.\n\n```python\nif client is None:\n    raise ValueError(\n        \"Set OPENAI_API_KEY to run this block (e.g. export OPENAI_API_KEY=... or %env in IPython). \"\n        \"Skip if you only want workspace / edit_file demos.\"\n    )\n\n# 1) Context from disk (read-only)\ncontext = ws.read_file(\"hello.txt\")\n\n# 2) Ask the model to author the entire new file; no static template for the body\nuser_prompt = (\n    \"Here is the current contents of hello.txt in my workspace:\\n\\n\"\n    f\"---\\n{context}\\n---\\n\\n\"\n    \"Write ONLY the body of a new Markdown file (no preamble, no code fences) \"\n    \"with a title line and two bullet points explaining what this greeting is for.\"\n)\n\nresp = client.chat.completions.create(\n    model=MODEL,\n    messages=[\n        {\n            \"role\": \"system\",\n            \"content\": \"You output only the file body the user asked for. No extra commentary.\",\n        },\n        {\"role\": \"user\", \"content\": user_prompt},\n    ],\n)\n\ngenerated = (resp.choices[0].message.content or \"\").strip()\nif not generated:\n    raise RuntimeError(\"LLM returned empty content; nothing to write.\")\n\n# 3) Persist exactly what the LLM produced\nout_rel = \"llm_generated_notes.md\"\nws.write_file(out_rel, generated, mode=\"overwrite\")\nprint(f\"Wrote {out_rel!r} ({len(generated)} chars from model)\\n\")\nprint(ws.read_file(out_rel))\n```\n\n### 5. Direct `edit_file` (no Chat Completions)\n\n**No API key required.** The next lines create `ws` if you have not run the workspace section yet (same root).\n\n```python\n# Direct edit_file (no Chat Completions call).\n# If `ws` is not defined yet (e.g. you skipped §3), the next few lines create it (same WORK_DIR).\nfrom pathlib import Path\n\nfrom agent_godmode import AgentWorkspace\n\nif \"ws\" not in globals():\n    WORK_DIR = Path(r\"D:\\Avi-assign\")\n    WORK_DIR.mkdir(parents=True, exist_ok=True)\n    ws = AgentWorkspace(WORK_DIR)\n\ndemo_edit = \"edit_demo.txt\"\nws.write_file(\n    demo_edit,\n    \"version: 1\\nstatus: draft\\nfooter: end\\n\",\n    mode=\"overwrite\",\n)\nprint(\"--- before ---\")\nprint(ws.read_file(demo_edit), end=\"\")\nprint(ws.edit_file(demo_edit, old_string=\"status: draft\", new_string=\"status: ready\"))\nprint(\"--- after ---\")\nprint(ws.read_file(demo_edit), end=\"\")\n```\n\n### 6. Agent loop: model calls `write_file`\n\n**Requires `OPENAI_API_KEY`.**\n\n```python\nif client is None:\n    raise ValueError(\n        \"Set OPENAI_API_KEY to run this block. \"\n        \"Skip if you only need workspace or direct edit_file.\"\n    )\n\n\ndef complete(messages, tools):\n    \"\"\"One Chat Completions turn; return OpenAI-shaped dict for run_agent_loop.\"\"\"\n    resp = client.chat.completions.create(\n        model=MODEL,\n        messages=messages,\n        tools=tools,\n        tool_choice=\"auto\",\n    )\n    return resp.model_dump()\n\n\nanswer = run_agent_loop(\n    complete,\n    \"Use tools only. List the workspace root, read hello.txt, then call write_file on \"\n    \"agent_notes.txt. The `content` argument must be your own freshly written summary \"\n    \"(several sentences) based only on what you read—do not paste boilerplate.\",\n    ws,\n    system_prompt=SYSTEM_PROMPT_V1,\n    max_turns=12,\n)\nprint(\"--- final answer ---\")\nprint(answer)\nprint(\"--- agent_notes.txt (if created by tool write_file) ---\")\np = WORK_DIR / \"agent_notes.txt\"\nprint(p.read_text(encoding=\"utf-8\") if p.exists() else \"(missing)\")\n```\n\n### 7. Agent loop: model calls `edit_file`\n\n**Requires `OPENAI_API_KEY` and the `complete` function from §6.**\n\n```python\nfrom pathlib import Path\n\nfrom agent_godmode import AgentWorkspace\n\nif \"ws\" not in globals():\n    WORK_DIR = Path(r\"D:\\Avi-assign\")\n    WORK_DIR.mkdir(parents=True, exist_ok=True)\n    ws = AgentWorkspace(WORK_DIR)\nif \"complete\" not in globals():\n    raise NameError(\"Define `complete` in §6 (after imports) before running this block.\")\nif client is None:\n    raise ValueError(\n        \"Set OPENAI_API_KEY to run this block. \"\n        \"The direct edit_file example in §5 works without a key.\"\n    )\n\ntarget = \"edit_agent_target.txt\"\nws.write_file(\n    target,\n    \"# Demo\\nThere are three erorrs in this sentance.\\n\",\n    mode=\"overwrite\",\n)\nedit_answer = run_agent_loop(\n    complete,\n    (\n        f\"Use tools only. Read `{target}`. Then use edit_file (not write_file) to fix typos: \"\n        \"change erorrs to errors and sentance to sentence. \"\n        \"Copy old_string exactly from read_file; use two edit_file calls or replace_all where appropriate.\"\n    ),\n    ws,\n    system_prompt=SYSTEM_PROMPT_V1,\n    max_turns=14,\n)\nprint(\"--- agent (edit_file) answer ---\")\nprint(edit_answer)\nprint(\"--- file after agent ---\")\nprint(ws.read_file(target), end=\"\")\n```\n\n### 8. Optional: custom tool loop without `run_agent_loop`\n\nUse **`OPENAI_TOOL_DEFINITIONS`**, call the Chat Completions API with `tools=...`, parse **`tool_calls`**, and route each call through **`ws.dispatch(name, json.loads(arguments))`** (requires `import json`). For **`write_file`**, the **`content`** field should be whatever the **model** authored; for **`edit_file`**, pass **`old_string`**, **`new_string`**, and **`replace_all`** exactly as the model returned.\n\n### Optional limits on `AgentWorkspace`\n\n```python\nws = AgentWorkspace(\n    r\"D:\\Avi-assign\",\n    allowed_commands=frozenset({\"python\", \"uv\"}),\n    command_timeout_sec=60.0,\n)\n```\n\n### Lower-level (`WorkspaceTools` + `OPENAI_TOOL_DEFINITIONS`)\n\nSame sandbox without `AgentWorkspace`: use `config_from_root(...)` and `WorkspaceTools`. Pass **`OPENAI_TOOL_DEFINITIONS`** to your provider as `tools=` when you implement your own loop instead of `run_agent_loop`.\n\n```python\nfrom agent_godmode import WorkspaceTools, OPENAI_TOOL_DEFINITIONS, SYSTEM_PROMPT_V1\nfrom agent_godmode.config import config_from_root\n\ntools = WorkspaceTools(config_from_root(r\"D:\\Avi-assign\"))\nprint(tools.read_file(\"hello.txt\"))\n```\n\nCompose the system message:\n\n```python\nfinal_system = SYSTEM_PROMPT_V1 + \"\\n\\n\" + \"Your org rules here.\"\n```\n\n### Imports reference\n\n- `AgentWorkspace` — pass a directory path; use `read_file` / `write_file` / `edit_file` / `list_files` / `run_command` on that tree only\n- `SYSTEM_PROMPT_V1`, `SYSTEM_PROMPT_CHANGELOG`, `TOOL_DESCRIPTIONS`\n- `OPENAI_TOOL_DEFINITIONS` — same shapes as MCP tools (for `tools=` in chat completions)\n- `build_server(config)` — build a `FastMCP` app (stdio via `build_server(cfg).run()`)\n- `run_agent_loop` — minimal multi-turn executor with your `complete` callable (accepts `WorkspaceConfig` or `AgentWorkspace`)\n\n## Safety model\n\n- **Python:** all paths are resolved **under** the directory you passed to `AgentWorkspace(...)` or `config_from_root(...)`.\n- **MCP / CLI:** same rule via `AGENT_GODMODE_ROOT` or `--root` (no `..` escape).\n- `read_file`, `write_file`, and `edit_file` only touch UTF-8 text paths under that root; `edit_file` requires valid UTF-8 (strict decode).\n- `run_command` uses **`argv` only** (no shell). Optional allowlist via `AGENT_GODMODE_ALLOWED_COMMANDS`.\n- Subprocess inherits the current environment; avoid passing secrets you do not want child processes to see.\n\n## CLI\n\n```bash\nagent-godmode --root D:/your/project\n```\n\nRuns the MCP server on **stdio** (default for Cursor).\n\n## Agent loop (conceptual)\n\n1. System = `SYSTEM_PROMPT_V1` (+ optional suffix).\n2. User message + `OPENAI_TOOL_DEFINITIONS` → your LLM.\n3. For each `tool_call`, run `WorkspaceTools.dispatch` (or MCP `call_tool`) — including `read_file`, `write_file`, **`edit_file`**, `list_files`, and `run_command` as defined by the server.\n4. Append tool results; repeat until the model returns text without tools.\n\n`run_agent_loop` implements steps 2–4 given your `complete()` function.\n\n## License\n\nMIT\n\n[![MCP Badge](https://lobehub.com/badge/mcp/mdvohra-agent-godmode)](https://lobehub.com/mcp/mdvohra-agent-godmode)\n\n[![MCP Badge](https://lobehub.com/badge/mcp-full/mdvohra-agent-godmode?theme=light)](https://lobehub.com/mcp/mdvohra-agent-godmode)\n",
  "bytes": 14802,
  "sha": "771a5346f3309b02c81a0f6f56839818ee482b0ed9beaea8b596eebfe9cce87b",
  "repo_slug": "mdvohra/agent-godmode",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mdvohra_agent_godmode_2371b193/readme"
}