Martin

An experimental, autonomous coding agent intended to explore how useful a minimal code assistant can be.

Basic tools and a Ralph loop.

Quickstart

python -m venv .venv
source .venv/bin/activate
pip install -e .
cp .env.example .env  # then set OPENAI_API_KEY (and optional OPENAI_BASE_URL/OPENAI_MODEL)

Run the agent

agent

Example

$ agent
Agent ready. Describe a task, or 'quit' to exit.

>>> The current working directory is your code. Update your code. Add whatever tools or powers you desire.

list: . (100 files)
file_read: AGENTS.md - not found
Tool call failed.
list: . (100 files)
list: src (55 files)
file_read: README.md:1-66 (66 lines)
file_read: src/agent/tools/registry.py:1-52 (52 lines)
file_read: pyproject.toml:1-33 (33 lines)
file_read: src/agent/tools/__init__.py:1-14 (14 lines)
file_read: src/agent/tools/list.py:1-99 (99 lines)
file_read: src/agent/tools/common.py:1-108 (108 lines)
file_read: src/agent/tools/file_read.py:1-94 (94 lines)
list: . (0 files)
file_read: src/agent/agent.py:1-111 (111 lines)
file_read: src/agent/tools/__init__.py:1-14 (14 lines)
file_read: src/agent/tools/file_write.py:1-68 (68 lines)
file_read: src/agent/tools/git.py:1-96 (96 lines)
file_read: src/agent/config.py:1-55 (55 lines)
file_read: src/agent/llm.py:1-92 (92 lines)
file_read: src/agent/tools/grep.py:1-108 (108 lines)
file_read: src/agent/tools/run.py - not found
Tool call failed.
grep: "class RunTool|def run|run\.py" (0 matches)
file_read: src/agent/tools/stop.py:1-65 (65 lines)
file_read: src/agent/tools/__main__.py - not found
Tool call failed.
file_read: src/agent/tools/file_delete.py:1-94 (94 lines)
file_read: src/agent/tools/dir_create.py:1-59 (59 lines)
file_read: src/agent/tools/dir_delete.py:1-85 (85 lines)
file_read: src/agent/tools/run.py - not found
Tool call failed.
file_read: src/agent/tools/ask.py:1-63 (63 lines)
file_read: src/agent/tools/think.py:1-49 (49 lines)
file_read: src/agent/__main__.py:1-22 (22 lines)
file_read: src/agent/tools/registry.py:1-52 (52 lines)
file_read: src/agent/ui.py:1-61 (61 lines)
file_write: src/agent/tools/run.py (3736 chars)
file_read: src/agent/tools/run.py:1-113 (113 lines)
file_read: src/agent/tools/registry.py:1-52 (52 lines)
file_read: src/agent/tools/registry.py:1-52 (52 lines)
file_read: src/agent/tools/registry.py:1-52 (52 lines)
file_write: src/agent/tools/registry.py (1435 chars)
Updated your codebase by adding a new run tool that lets the agent execute a small allowlisted set of commands safely inside the project working
directory.

                      What changed

 • Added: src/agent/tools/run.py
    • Implements RunTool
    • Uses subprocess.run(shell=False) with shlex.split
    • Runs only allowlisted executables: python, python3, pip, pip3, pytest, ruff, git
    • Enforces cwd=WORKING_DIR and a configurable timeout (COMMAND_TIMEOUT)
 • Updated: src/agent/tools/registry.py
    • Registers the new RunTool so it becomes available to the LLM via tool calling

If you want, I can expand the allowlist (e.g., make, node, npm) or add higher-level “powers” like tests (auto-run + summarize), lint (ruff
wrapper), or patch (apply unified diffs safely).

>>>