Coding Agent

This recipe builds a coding agent that explores a project, reads and writes files, and executes code to verify its work. It uses OpenAI as the model provider and opentine's filesystem and Python execution tools.

What It Does

  • Explores project structure with ls
  • Reads existing files to understand the codebase with read
  • Writes new files and edits existing ones with write
  • Executes Python code to test changes with a policy-enabled wrapper
  • Saves the run graph so you can fork and retry if something goes wrong

Prerequisites

Terminal
export OPENAI_API_KEY="sk-..."

Full Example

coder.py
1from opentine import Agent
2from opentine.core import PythonPolicy
3from opentine.models.openai import OpenAI
4from opentine.tools.fs import read, write, ls
5from opentine.tools.python import execute as _execute
6
7def execute_python(code: str) -> str:
8    """Execute Python code in an isolated subprocess."""
9    return _execute(code, policy=PythonPolicy(enabled=True))
10
11agent = Agent(
12    model=OpenAI("gpt-4o"),
13    tools=[read, write, ls, execute_python],
14    system="""You are a senior Python developer. Given a task:
151. Explore the project structure with ls
162. Read relevant files to understand the codebase
173. Write or edit files to implement the solution
184. Execute Python snippets to verify your changes work
19Use subprocess from Python when you need to run tests.""",
20    max_steps=50,
21)
22
23run = agent.run_sync("Add input validation to the user registration endpoint")
24print(f"Completed in {run.total_duration:.1f}s, cost {run.total_cost:.4f}")
25run.save("validation_feature.tine")

How It Works

The agent gets four tools: read, write, ls, and a policy-enabled Python execution wrapper. The system prompt establishes a workflow — explore first, understand the code, make changes, then verify. The max_steps=50 limit gives it room for complex tasks while preventing runaway execution.

This pattern mirrors how a developer works: look at the project, read the relevant files, make changes, and run the tests.

Running It

Terminal
python coder.py

Example Run Output

Terminal
Run: validation_feature
Status: completed | Steps: 18 | Cost: $0.0523 | Duration: 34.2s

[think]  Understanding the task — need to add input validation...
[tool]   ls(".")
[tool]   ls("src/")
[tool]   read("src/routes/auth.py")
[tool]   read("src/models/user.py")
[model]  Found the registration endpoint, planning validation...
[tool]   write("src/validators/user.py")
[tool]   read("src/routes/auth.py")
[tool]   write("src/routes/auth.py")
[tool]   execute_python("import subprocess, sys; subprocess.run([sys.executable, '-m', 'pytest', 'tests/test_auth.py', '-v'], check=True)")
[done]   Validation added and tests passing

Forking to Fix a Failed Approach

If the agent's first approach didn't work — say the tests failed or the validation logic was wrong — fork from before the problematic step and try a different strategy. All the exploration and reading steps are reused.

fork_coder.py
1from opentine import Run, Agent
2from opentine.core import PythonPolicy
3from opentine.models.openai import OpenAI
4from opentine.tools.fs import read, write, ls
5from opentine.tools.python import execute as _execute
6
7def execute_python(code: str) -> str:
8    """Execute Python code in an isolated subprocess."""
9    return _execute(code, policy=PythonPolicy(enabled=True))
10
11# Load the run where tests failed
12run = Run.load("validation_feature.tine")
13
14# Fork from the inspected step just before the write to try a different approach.
15fork_point = run.steps[5].id
16forked = run.fork(from_step_id=fork_point)
17
18agent = Agent(
19    model=OpenAI("gpt-4o"),
20    tools=[read, write, ls, execute_python],
21    system="Use pydantic for validation instead of manual checks.",
22)
23
24fixed = agent.resume_sync(
25    forked,
26    prompt="Continue from the fork point using pydantic validation.",
27)
28fixed.save("validation_feature_v2.tine")

Adding Shell Access

For tasks that need shell commands (installing packages, running build tools, git operations), add a wrapper around run with an explicit ShellPolicy alongside the filesystem tools.

coder_with_shell.py
1from opentine import Agent
2from opentine.core import PythonPolicy, ShellPolicy
3from opentine.models.openai import OpenAI
4from opentine.tools.fs import read, write, edit, ls
5from opentine.tools.shell import run as _run
6from opentine.tools.python import execute as _execute
7
8def shell(command: str) -> str:
9    """Run approved shell commands."""
10    return _run(command, policy=ShellPolicy(enabled=True, executables=("git", "python", "pytest")))
11
12def execute_python(code: str) -> str:
13    """Execute Python code in an isolated subprocess."""
14    return _execute(code, policy=PythonPolicy(enabled=True))
15
16agent = Agent(
17    model=OpenAI("gpt-4o"),
18    tools=[read, write, edit, ls, shell, execute_python],
19    system="You are a coding assistant with shell access.",
20)
21
22result = agent.run_sync("Set up a new FastAPI project with a health endpoint")

Next Steps