nakedagent

A coding agent with no third-party Python runtime dependencies. The agent uses Python 3.10+ and its standard library. Live coding sessions also need a model service, such as Ollama.

Try it offline

From a clone of this repository, run:

python -m examples.replay_demo

This synthetic demo writes a temporary event log, verifies it, changes one record, and shows that replay rejects the change. It needs no model, API key, network connection, or plugins, and removes its temporary files on exit. It demonstrates log consistency, not authentication or proof that external actions occurred. For a live coding session, see Quick start below.

With a model service running, the interactive session looks like this:

$ python -m nakedagent
nakedagent -- workspace: /home/you/myproject -- model: qwen2.5-coder:7b
Ctrl-D to exit.

> add a .gitignore for a Python project

Why

nakedagent keeps the Python dependency surface small: urllib + json + subprocess + re, all from the standard library, drive the tool-use loop. You can read the implementation and replay recorded transitions without installing provider SDKs. Python, the model service, and any tools or plugins you enable still have their own security and maintenance requirements.

What you get for that

• Tools: shell, read, write, patch (search/replace edits, aider's simplest edit format). That's the whole foundation tool surface. shell is confirmation-first in interactive mode and requires --allow-shell in non-interactive mode, with optional command filtering via --shell-allowlist.
• Model backend: Ollama by default — local-first, no API key required to try it. For models too large to run locally, --api openai speaks the OpenAI-compatible format that hosted APIs, vLLM/LM Studio and gateways share (see below).
• Tool-call format: the model writes a fenced code block whose language tag is the tool name; nakedagent parses it out of the response text after each turn. Works with any model that can write a code fence — no dependency on a provider's native function-calling API.
• Plugins: drop a .py file in .nakedagent/plugins/ (repo-local, requires --trust-workspace-plugins) or ~/.nakedagent/plugins/ (user-global, always loaded) that defines a TOOLS dict (add or override tools) and/or a DISABLE list (remove tools entirely). A read-only configuration of the built-in tools disables shell, write, and patch. Each tool carries a .usage attribute that controls its prompt example, so a plugin replacing a tool replaces its syntax too. No registration, no framework — see DOCTRINE.md for the omakase framing. Repo-local plugins are off by default because they execute with your privileges — only pass the flag in workspaces you trust.

See docs/architecture/architecture.md for how the loop and tool parser work, including what was learned from reading gptme's and aider's actual source before writing this.

Quick start

git clone https://github.com/hummbl-io/nakedagent.git
cd nakedagent
ollama pull qwen2.5-coder:7b   # or any model you like
python -m nakedagent           # interactive
python -m nakedagent "explain what this repo does"   # one-shot

Larger models

Small local models get the loop running; bigger models make it good. Point nakedagent at any OpenAI-compatible server. The key comes from an environment variable (--api-key-env, default OPENAI_API_KEY), never a flag:

# hosted API
OPENAI_API_KEY=... python -m nakedagent --api openai --host https://api.openai.com/v1 -m <model>

# self-hosted (vLLM, LM Studio) — no key needed
python -m nakedagent --api openai --host http://localhost:8000/v1 -m <model>

Shell safety for automation

For one-shot runs and other non-interactive use-cases, the shell tool is denied unless explicit shell allowances are provided:

python -m nakedagent "run project checks" --allow-shell --shell-allowlist "git status" --shell-allowlist "ls"

--shell-allowlist is prefix-based. If you pass --allow-shell with an empty allowlist, all non-interactive shell commands are blocked.

No pip install step. That's not an oversight — nakedagent/ only imports the standard library, so running it in place works.

Provable execution: event log + replay

One-shot runs can go through the functional lane — the agent is a pure Mealy machine (functional.agent_reducer: (state, event) -> (state, actions)), and a thin driver (driver.py) performs the actual model/tool IO while appending every event to a JSONL log:

python -m nakedagent "add a .gitignore" --event-log run.jsonl

Each logged event carries the Merkle state hash after that transition, so the trace is a tamper-evident receipt. Replay reconstructs the run with zero model calls and verifies the whole chain:

python -m nakedagent.replay run.jsonl
# PASS run.jsonl: verified 5 events (1 tool results); final hash 6d1e0965…

Status

MVP. Two wire formats (Ollama native + OpenAI-compatible), four foundation tools, no streaming. The plugin seam is the one extension surface — see DOCTRINE.md. Went through two independent peer reviews (headless GLM-5.2, and a separately-running devin session, both 2026-09-09) before this first push — between them they found five real bugs, all fixed with regression tests, documented in docs/architecture/architecture.md alongside what's still genuinely not here and why.

Research & Citation

If you use nakedagent in academic research or want to study its architecture, please cite our research paper:

Reuben Bowlby, "NakedAgent: A Zero-Dependency Coding Agent Architecture via Standard-Library Primitives and Provable Replay", HUMMBL Research, Zenodo Preprint, 2026.

Preprint PDF and LaTeX sources are available under paper/. For machine-readable citation metadata, see CITATION.cff.

License

MIT. See LICENSE.