agent-godmode

Workspace-scopedMCP toolsfor building Cursor-style agents:read_file,write_file,edit_file,run_command,list_files. Includesstrict, versioned system prompts(SYSTEM_PROMPT_V1) andOpenAI-style tool definitionsso your app can wire any LLM with one import.

TheLLM and API keys stay in your app. This package provides tool execution, sandboxing, and prompts—not a hosted model.

OpenAI + in-process tools:theTier Bsection below is self-contained—copy the Python into a script, module, or REPL; no separate artifact is required.

Migrating frommcp-agent-tools:uninstall the old package, installagent-godmode, change Python imports frommcp_agent_toolstoagent_godmode, the CLI frommcp-agent-toolstoagent-godmode, and environment variables fromMCP_AGENT_TOOLS_toAGENT_GODMODE_(for exampleAGENT_GODMODE_ROOT).

All tools are scoped to a singleworkspace root. Paths are relative to that root (or absolute only if they resolve under it). The same operations are available overMCP(theagent-godmodeserver) and in-process viaAgentWorkspace/WorkspaceTools.

For LLM integrations, tool shapes and descriptions are centralized inOPENAI_TOOL_DEFINITIONSandTOOL_DESCRIPTIONS; agent behavior is guided bySYSTEM_PROMPT_V1.

1.Pick a workspace directory (only paths under this root are allowed).

2.Add a server entry (stdio). Example for a global MCP config (paths use forward slashes on Windows):

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

Or with an explicit CLI root (overrides env for that process):

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

3.PasteSYSTEM_PROMPT_V1(fromagent_godmode.promptsor below) into your host’s system prompt if the client does not load serverinstructionsautomatically.

Tier B — Python app (in-process + OpenAI)

- Workspace root— Examples useD:\Avi-assignas a placeholder; pointWORK_DIRat any directory you control.
- API key policy—OPENAI_API_KEYis requiredonlyfor Chat Completions. Imports setclient = OpenAI() if HAS_OPENAI_KEY else None; workspace setup anddirectedit_filerun without a key.
- Model-authored I/O— Forwrite_file, persistonlytext returned by the model. Foredit_file, the model must copyold_stringexactly fromread_file(seeSYSTEM_PROMPT_V1).

In a shell or any interactive Python session:

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

If your environment supports line magics (for example%pipin IPython), you can run the same installs there; do not place shell comments on the same line as%pip.

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." )

# 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-authored file body (no tool calls)

RequiresOPENAI_API_KEY.Skip if you are only exercising tools without the 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. Directedit_file(no Chat Completions)

No API key required.The next lines createwsif you have not run the workspace section yet (same root).

# 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="")

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)")

RequiresOPENAI_API_KEYand thecompletefunction from §6.

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. Optional: custom tool loop withoutrun_agent_loop

UseOPENAI_TOOL_DEFINITIONS, call the Chat Completions API withtools=..., parsetool_calls, and route each call throughws.dispatch(name, json.loads(arguments))(requiresimport json). Forwrite_file, thecontentfield should be whatever themodelauthored; foredit_file, passold_string,new_string, andreplace_allexactly as the model returned.

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

Lower-level (WorkspaceTools+OPENAI_TOOL_DEFINITIONS)

Same sandbox withoutAgentWorkspace: useconfig_from_root(...)andWorkspaceTools. PassOPENAI_TOOL_DEFINITIONSto your provider astools=when you implement your own loop instead ofrun_agent_loop.

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— pass a directory path; useread_file/write_file/edit_file/list_files/run_commandon that tree only
- SYSTEM_PROMPT_V1,SYSTEM_PROMPT_CHANGELOG,TOOL_DESCRIPTIONS
- OPENAI_TOOL_DEFINITIONS— same shapes as MCP tools (fortools=in chat completions)
- build_server(config)— build aFastMCPapp (stdio viabuild_server(cfg).run())
- run_agent_loop— minimal multi-turn executor with yourcompletecallable (acceptsWorkspaceConfigorAgentWorkspace)

- Python:all paths are resolvedunderthe directory you passed toAgentWorkspace(...)orconfig_from_root(...).
- MCP / CLI:same rule viaAGENT_GODMODE_ROOTor--root(no..escape).
- read_file,write_file, andedit_fileonly touch UTF-8 text paths under that root;edit_filerequires valid UTF-8 (strict decode).
- run_commandusesargvonly(no shell). Optional allowlist viaAGENT_GODMODE_ALLOWED_COMMANDS.
- Subprocess inherits the current environment; avoid passing secrets you do not want child processes to see.

Runs the MCP server onstdio(default for Cursor).
- System =SYSTEM_PROMPT_V1(+ optional suffix).
- User message +OPENAI_TOOL_DEFINITIONS→ your LLM.
- For eachtool_call, runWorkspaceTools.dispatch(or MCPcall_tool) — includingread_file,write_file,edit_file,list_files, andrun_commandas defined by the server.
- Append tool results; repeat until the model returns text without tools.

run_agent_loopimplements steps 2–4 given yourcomplete()function.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

next-devtools-mcp is a MCP server that provides Next.js development tools and utilities for AI coding assistants like Claude and Cursor.

Word search, crossword, and sudoku generator MCP server with printable PDF worksheets, themed word banks, and verifiable LLM evals. Local-first, from the makers of puzzletide.com.

A demonstration server for ActionKit, providing access to Slack actions via Claude Desktop.

MCP server that lets Claude Code agents delegate tasks to agents in other project directories, with parallel dispatch, sessions, and async jobs.

Statistical regression testing for LLM agents: p-value, effect size, and CI on behavior change.

Integrates with Google AI Studio/Gemini API for PDF to Markdown conversion and content generation.

Anchor Browser (https://anchorbrowser.io) is secure infrastructure for computer-use agents — stealth cloud browsers, authentication, captcha bypass, and a hosted MCP server for Cursor, Claude, and Windsurf.

Open-source Claude Code plugin replacing Read/Grep/Edit/Bash with token-efficient versions. Independently benchmarked at 57% token reduction on real codebases. 40 MCP tools.