agent-godmode

agent-godmode

Ferramentas MCP com escopo de workspace para construir agentes estilo Cursor: read_file, write_file, edit_file, run_command, list_files. Inclui prompts de sistema estritos e versionados (SYSTEM_PROMPT_V1) e definições de ferramentas no estilo OpenAI para que seu aplicativo possa conectar qualquer LLM com uma única importação.

As chaves de LLM e API permanecem no seu aplicativo. Este pacote fornece execução de ferramentas, sandboxing e prompts—não um modelo hospedado.

OpenAI + ferramentas em processo: a seção Tier B abaixo é autocontida—copie o Python para um script, módulo ou REPL; nenhum artefato separado é necessário.

Instalação

pip install agent-godmode

Editável / desenvolvimento:

pip install -e ".[dev]"

Migrando de mcp-agent-tools: desinstale o pacote antigo, instale agent-godmode, altere as importações Python de mcp_agent_tools para agent_godmode, a CLI de mcp-agent-tools para agent-godmode e as variáveis de ambiente de MCP_AGENT_TOOLS_* para AGENT_GODMODE_* (por exemplo, AGENT_GODMODE_ROOT).

Ferramentas

Todas as ferramentas são limitadas a uma única raiz do workspace. Os caminhos são relativos a essa raiz (ou absolutos apenas se resolverem dentro dela). As mesmas operações estão disponíveis via MCP (o servidor agent-godmode) e em processo via AgentWorkspace / WorkspaceTools.

Ferramenta	Propósito
read_file	Lê um arquivo de texto UTF-8; intervalo de linhas e limite de bytes opcionais.
write_file	Cria ou sobrescreve/adiciona texto UTF-8; cria diretórios pais.
edit_file	Pesquisa e substitui em um arquivo UTF-8 existente: old_string não vazio, replace_all opcional. Com replace_all=false, old_string deve corresponder exatamente uma vez (use o contexto circundante de read_file para unicidade). UTF-8 inválido retorna um erro em vez de corromper dados binários.
list_files	Lista entradas de diretório com recursão opcional, glob, limite de profundidade, controle de dotfiles.
run_command	Executa um subprocesso a partir de uma lista argv apenas (sem shell); cwd opcional sob a raiz.

Para integrações com LLM, as formas e descrições das ferramentas são centralizadas em OPENAI_TOOL_DEFINITIONS e TOOL_DESCRIPTIONS; o comportamento do agente é guiado por SYSTEM_PROMPT_V1.

Tier A — Cursor (ou qualquer cliente MCP)

1. Escolha um diretório de workspace (apenas caminhos sob essa raiz são permitidos).

2. Adicione uma entrada de servidor (stdio). Exemplo para uma configuração MCP global (caminhos usam barras normais no Windows):

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

Ou com uma raiz CLI explícita (substitui o env para esse processo):

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

3. Cole SYSTEM_PROMPT_V1 (de agent_godmode.prompts ou abaixo) no prompt de sistema do seu host se o cliente não carregar o servidor instructions automaticamente.

Variáveis de ambiente

Variável	Significado
AGENT_GODMODE_ROOT	Obrigatória a menos que --root seja passado. Raiz absoluta do workspace.
AGENT_GODMODE_MAX_READ_BYTES	Máximo de bytes por leitura (padrão 512000).
AGENT_GODMODE_COMMAND_TIMEOUT	Tempo limite do subprocesso em segundos (padrão 120).
AGENT_GODMODE_MAX_COMMAND_OUTPUT_BYTES	Trunca stdout/stderr combinados (padrão 256000).
AGENT_GODMODE_LIST_MAX_ENTRIES	Limite para list_files (padrão 2000).
AGENT_GODMODE_ALLOWED_COMMANDS	Basenames separados por vírgula permitidos como argv[0] (ex.: python,uv,node). Se não definido, todos os comandos são permitidos no sandbox.

Tier B — Aplicativo Python (em processo + OpenAI)

Notas de design

• Raiz do workspace — Os exemplos usam D:\Avi-assign como espaço reservado; aponte WORK_DIR para qualquer diretório que você controla.
• Política de chave de API — OPENAI_API_KEY é necessária apenas para Chat Completions. As importações definem client = OpenAI() if HAS_OPENAI_KEY else None; a configuração do workspace e edit_file direto são executados sem chave.
• I/O de autoria do modelo — Para write_file, persista apenas o texto retornado pelo modelo. Para edit_file, o modelo deve copiar old_string exatamente de read_file (veja SYSTEM_PROMPT_V1).

1. Instalar dependências

Em um shell ou qualquer sessão interativa Python:

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

Se o seu ambiente suporta line magics (por exemplo, %pip no IPython), você pode executar as mesmas instalações lá; não coloque comentários de shell na mesma linha que %pip.

2. Importações e manipulação de chave de 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. Bootstrap do workspace e arquivo de semente

# 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. Corpo de arquivo de autoria do LLM (sem chamadas de ferramenta)

Requer OPENAI_API_KEY. Pule se você estiver apenas exercitando ferramentas sem a 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 direto (sem Chat Completions)

Nenhuma chave de API necessária. As próximas linhas criam ws se você ainda não executou a seção do workspace (mesma raiz).

# 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. Loop do agente: modelo chama write_file

Requer 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. Loop do agente: modelo chama edit_file

Requer OPENAI_API_KEY e a função complete da §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. Opcional: loop de ferramenta personalizado sem run_agent_loop

Use OPENAI_TOOL_DEFINITIONS, chame a API de Chat Completions com tools=..., analise tool_calls e roteie cada chamada através de ws.dispatch(name, json.loads(arguments)) (requer import json). Para write_file, o campo content deve ser o que o modelo criou; para edit_file, passe old_string, new_string e replace_all exatamente como o modelo retornou.

Limites opcionais em AgentWorkspace

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

Nível inferior (WorkspaceTools + OPENAI_TOOL_DEFINITIONS)

Mesmo sandbox sem AgentWorkspace: use config_from_root(...) e WorkspaceTools. Passe OPENAI_TOOL_DEFINITIONS para seu provedor como tools= quando você implementar seu próprio loop em vez de run_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"))

Componha a mensagem do sistema:

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

Referência de importações

• AgentWorkspace — passe um caminho de diretório; use read_file / write_file / edit_file / list_files / run_command apenas nessa árvore
• SYSTEM_PROMPT_V1, SYSTEM_PROMPT_CHANGELOG, TOOL_DESCRIPTIONS
• OPENAI_TOOL_DEFINITIONS — mesmas formas que as ferramentas MCP (para tools= em chat completions)
• build_server(config) — construa um aplicativo FastMCP (stdio via build_server(cfg).run())
• run_agent_loop — executor multi-turno mínimo com seu callable complete (aceita WorkspaceConfig ou AgentWorkspace)

Modelo de segurança

• Python: todos os caminhos são resolvidos sob o diretório que você passou para AgentWorkspace(...) ou config_from_root(...).
• MCP / CLI: mesma regra via AGENT_GODMODE_ROOT ou --root (sem escape de ..).
• read_file, write_file e edit_file tocam apenas caminhos de texto UTF-8 sob essa raiz; edit_file requer UTF-8 válido (decodificação estrita).
• run_command usa apenas argv (sem shell). Lista de permissões opcional via AGENT_GODMODE_ALLOWED_COMMANDS.
• O subprocesso herda o ambiente atual; evite passar segredos que você não quer que processos filhos vejam.

CLI

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

Executa o servidor MCP em stdio (padrão para Cursor).

Loop do agente (conceitual)

1. Sistema = SYSTEM_PROMPT_V1 (+ sufixo opcional).
2. Mensagem do usuário + OPENAI_TOOL_DEFINITIONS → seu LLM.
3. Para cada tool_call, execute WorkspaceTools.dispatch (ou MCP call_tool) — incluindo read_file, write_file, edit_file, list_files e run_command conforme definido pelo servidor.
4. Acrescente os resultados das ferramentas; repita até que o modelo retorne texto sem ferramentas.

run_agent_loop implementa as etapas 2–4 dada a sua função complete().

Licença

MIT