How to Build a Coding Agent

You need to have NodeJS installed. Follow the installation guide here.

Set up the project and install dependencies with these commands

mkdir tiny-code
cd tiny-code
npm init -y
tsc --init
npm install openai @types/node dotenv

Replace content of tsconfig.json with this

{
	"compilerOptions": {
		"target": "ES2022",
		"module": "NodeNext",
		"moduleResolution": "NodeNext",
		"outDir": "dist",
		"rootDir": "src",
		"strict": true
	}
}

Replace content of package.json with this

{
	"name": "tiny-code",	
	"version": "0.1.0",
	"type": "module",
	"bin": {
		"tiny-code": "./dist/agent.js"
	},
	"scripts": {
		"build": "tsc",
		"postbuild": "chmod +x dist/agent.js",
		"prepare": "npm run build",
		"start": "node dist/agent.js",
		"dev": "node --env-file=.env --watch src/agent.js"
	},
	"dependencies": {
		"@types/node": "^25.3.2",
		"dotenv": "^17.3.1",
		"openai": "^6.27.0"
	}
}

Project structure:

|__tiny-code/
	|__src/
		|__functions.ts
		|__tools.ts
		|__agent.ts

Install uv We will be using uv as the package manager for our project. You can find guidance for installing uv here.

Set up the project and install dependenices with these commands:

mkdir tiny-code
cd tiny-code
uv init
uv venv .venv
source .venv/bin/activate
touch .env
uv add openai python-dotenv

Project structure:

|__tiny-code/
	|__src/
		|____init.py__
		|__functions.py
		|__tools.py
		|__agent.py

import fs from "node:fs/promises"

export interface ToolResult {
	ok: boolean;
	message: string;
}

export async function readFile({path}: {path: string}): Promise<ToolResult> {
	const content = await fs.readFile(path, "utf-8");
	return { ok: true, message: content }
}

First, we create a ToolResult interface to represent the function’s return value: an object containing a status message and the tool result. This implementation wraps the the readFile()method in Node’s filesystem API, fs, and we return the content, which is the result of readFile() in utf-8 format.

from pathlib import Path
def read_file(path: str) -> dict:
	file_path = Path(path)
	content = file_path.read_text()
	return { "ok": True, "content": content }

This implementation uses the read_text() method on the Path subclass in Python. We take the path string, convert it to a Path object and assign it to a new variable, file_path. Then we call read_text() on file_path to get the file content. We return the content in a dict alongside a status message. This lets the model know if the function handled the tool call successfully.

import { access } from "node:fs/promises";

export async function createFile({path, content}: {path: string, content: string}): Promise<ToolResult> {
	try {
		await access(path);
		return {ok: false, message: `${path} already exists.`}
		} catch {
		await fs.writeFile(path, content);
		return { ok: true, message: `created new file at ${path}`};
	}
}

Similar to the read_file() function above, this function uses a method from Node’s fs module, the writeFile() method. This function accepts two arguments: path and content, representing the location of the file we want to create and content to add to it. We don’t want to overwrite existing files accidentally, so, we only call the writeFile() function if the file doesn’t already exists. To overwrite an existing file, it would be better to use the edit_file() function.

def create_file(path: str, content: Optional[str] = None):
	file_path = Path(path)
	file_path.parent.mkdir(parents=True, exist_ok=True)
	if file_path.exists():
		return {"ok": False, "message": f"{path} already exists."}
	file_path.write_text(content or "")
	return {"ok": True, "message": f"created {file_path} successfully."}

Here again, we are using a method from Python’s Path subclass. First, we create a parent directory for the file if it doesn’t exist, and we check whether the file already exists, so, we don’t overwrite an existing file mistakenly. Then, we use the write_text() method to write the content to the file. If we are creating an empty file, the function can take an empty string.

export async function editFile({path, oldContent, newContent}: {path: string, oldContent: string, newContent: string}): Promise<ToolResult> {
	let content = await fs.readFile(path, "utf-8");
	content = content.replace(oldContent, newContent);
	await fs.writeFile(path, content);
	return {ok: true, message: `edith ${path}, replaced all occurences of ${oldContent} with ${newContent}`};
}

def edit_file(path: str, old_content: str, new_content: str):
	
	def write_to_file(path: str, content):
		file_path = Path(path)
		with open(file_path, "w") as f:
			f.write(content)
		return {"ok": True, "message": f"written {content} to {file_path}"}

	file_path = Path(path)
	existing_content = file_path.read_text()
	new_file_content = existing_content.replace(old_content, new_content)
	write_to_file(path, new_file_content)
	return {"ok": True, "message": f"edited {path} successfully."}

export async function deleteFile({path}: {path: string}): Promise<ToolResult>{
	await fs.rm(path);
	return {ok: true, message: `successfully deleted ${path}`};
} 

import os

def delete_file(path: str):
	file_path = Path(path)
	os.remove(file_path)
	return {"ok": True, "message": f"deleted {path} successfully."}

Node’s subprocess module has multiple methods for creating new processes programatically. For example, spawn() lets you create a new process without creating a shell. The output from your command, stdout and stderr arrives in chunks as the process produces it . exec() creates a shell and collects the process output into memory and returns the complete result in a callback. exec() is recommended when you need to run a command and get the entire output at once but has a buffer size limit of 1MB so if you get a very large output from a command, it will throw an error. spawn() is recommended when you have a long running process or expect a very large output from your process because it streams output directly and does not need to store anything. For this tutorial, we will be using exec.

So how does this function work?

import { exec } from "node:child_process";

interface CommandResult {
	stdout: string;
	stderr: string;
	exitCode: number;
}

export function runCommandWithExec({ command}: { command: string }): Promise<CommandResult> {
	return new Promise((resolve, reject) => {
		exec(command, (error, stdout, stderr) => {
			if (error && typeof error.code !== "number") {
				reject(error);
				return;
			}
		
			resolve({
				stdout: stdout.trim(),
				stderr: stderr.trim(),
				exitCode: error ? Number(error.code) : 0
			});
		});
	});
}

We pass our command into the exec function alongside a callback function with error, stdout and stderr as arguments. Inside the callback, we handle any errors arising from outside the process itself . exec() itself is wrapped inside a Promise with resolve and reject as callback arguments. Inside the reject() method we pass any runtime errors and return control to the Promise() method. We also pass the outputs from the process, stdout and stderr, and any runtime errors, error, if the Promise() fails to resolve() as an object literal.

import subprocess

def run_command(cmd: str) -> dict:
	args = cmd.split()
	result = subprocess.run(	
		args,
		shell=False,
		capture_output=True,
		text=True,
		check=True
	)
	return {"ok": True, "result": result.stdout}

In Python, we have one method, run(), for creating child processes through the subprocess module. Shell configuration and output streaming are handled as parameters that we pass to the run() method. Let’s go over the code line by line. We pass our command as a string and we want this function to return a dict with status message and the output of the process. At line 2 we change our command from a string data type to a list of strings using the split() method on the Python string object. This means that each part of our command is passed as a separate literal argument, reducing errors that arise when Python is trying to figure out where the command starts and ends. In the subprocess.run() call, we pass the args, shell=False means that we are not passing our commands through a shell to the os but creating the process directly. We set capture_output to True so that we can receive the output being streamed from the process. The output from the process will be in byte format so we set text=True so that we can convert it into readable text. check=True lets us know when there is an error in the process. It will raise an error automatically if the command fails.

import { Tool } from "openai/resources/responses/responses";

export const tools: Tool[] = [
	
	{
		type: "function",
		name: "read_file",
		description: "Returns the contents of a file given the path. Use it to read file contents.",
		parameters: {
			type: "object",
			properties: {
				path: {
				type: "string",
				description: "The path to the file"
				}
			},
			required: ["path"],
			additionalProperties: false			
		},
			strict: true
	},
	{
		type: "function",
		name: "create_file",
		description: "Create a file and add some content to it. Eg create a file hello.txt with content 'hello' inside it.",
		
		parameters: {
			type: "object",
			properties: {
				path: {
					type: "string",
					description: "The path to the file to create."
				},
				content: {
					type: "string",
					description: "The content or data to write to the created file."				
					}
				},
			required: ["path", "content"],
			additionalProperties: false,
		},
		strict: true
	},

	{
		type: "function",
		name: "edit_file",
		description: "Edit a file by writing new content to it. eg, edit a file hell.txt with content 'Hello world' to 'Hello planet' by replacing 'world' with 'planet'",
		parameters: {
			type: "object",
			properties: {
				path: {
					type: "string",
					description: "Path to the file to edit"
				},
				oldContent: {
					type: "string",
					description: "The content to replace"
				},
				newContent: {
					type: "string",
					description: "The new content to replace the old content with."
				},
			},
			required: ["path", "oldContent", "newContent"],
			additionalProperties: false
		},
		strict: true
	},
	{
		type: "function",
		name: "delete_file",
		description: "Delete a file",
		parameters: {
		type: "object",
		properties: {
			path: {
				type: "string",
				description: "path to the file to delete"
			}
		},
		required: ["path"],
		additionalProperties: false
		},
		strict: true,
			
	},
	{
		type: "function",
		name: "run_command_with_exec",
		description: "Run commands using Node's exec() child process method. Creates a new shell to run the commands in. Only use for short commands that don't return large outputs. Eg pwd, ls -lh",
		parameters: {
			type: "object",
			properties: {
				command: {
					type: "string",
					description: "The command to run. eg 'ls -lh', 'pwd' "
				}
			},
			required: ["command"],
			additionalProperties: false
		},
		strict: true
	},
]

tools: list[ToolParam] = [
	{
	"type": "function",
	"name": "run_command",
	"description": "run a command",
	"parameters": {
		"type": "object",
		"properties": {
			"cmd": {
				"type": "string",
				"description": "The command(s) to run"
			}
		},
		"required": ["cmd"],
		"additionalProperties": False
	},
	"strict": True
	},
	{
		"type": "function",
		"name": "read_file",
		"description": "Read the contents of a file.",
		"parameters": {
		"type": "object",
		"properties": {
			"path": {
			"type": "string",
			"description": "Path to the file to read"
			}
		},
		"required": ["path"],
		"additionalProperties": False,
		},
		"strict": True
	},

	{
		"type": "function",
		"name": "write_to_file",
		"description": "Add content to an existing file.",
		"parameters": {
			"type": "object",
			"properties": {
				"path": {
					"type": "string",
					"description": "The path to the file you want to write to"
				},
				"content": {
					"type": "string",
					"description": "The content you want to write"
				}
			},
			"required": ["path", "content"],
			"additionalProperties": False,
			},
		"strict": True,
	},
	{
		"type": "function",
		"name": "create_file",
		"description": "Create a new file.",
		"parameters": {
			"type": "object",
			"properties": {
				"path": {
					"type": "string",
					"description": "The path to the file to create"	
				},
				"content": {
					"type": "string",
					"description": "Content you want to write to the file"
				}
		
			},
		"required": ["path", "content"],
		"additionalProperties": False,
		},
		"strict": True,
	},
	{
		"type": "function",
		"name": "edit_file",
		"description": "Edit a file by writing new content to it",
		"parameters": {
			"type": "object",
			"properties": {
				"path": {
					"type": "string",
					"description": "The path to the file to edit"
				},
				"old_content": {
					"type": "string",
					"description": "The text to be replaced"
				},
				"new_content": {
					"type": "string",
					"description": "The text to replace old_content with."
				}
			},
			"required": ["path", "old_content", "new_content"],
			"additionalProperties": False,
		},
		"strict": True,
	},
]

export const toolHandlers: Record<string, (args: any) => Promise<any>> = {
	read_file: readFile,
	create_file: createFile,
	edit_file: editFile,
	delete_file: deleteFile,
	run_command_with_exec: runCommandWithExec
}

from tools import read_file, edit_file, create_file, run_command, write_to_file

TOOLS = {
	"run_command": run_command,
	"read_file": read_file,
	"create_file": create_file,
	"edit_file": edit_file
}

#!/usr/bin/env node

import OpenAI from "openai";
import { tools, toolHandlers } from "./tools/toolSchemas.js";
import { ResponseInput } from "openai/resources/responses/responses";
import * as rl from "node:readline";
import { stdin as input, stdout as output } from "node:process";
import "dotenv/config";

const client = new OpenAI({
	apiKey: process.env.OPENAI_API_KEY,
});

async function runAgentTurn(conversationHistory: ResponseInput, userInput: string){

	conversationHistory.push({ role: "user", content: userInput });
	while (true) {
		const response = await client.responses.create({
		model: "gpt-5.4",
		input: conversationHistory,
		tools,
		tool_choice: "auto"
	});

	conversationHistory.push(...(response.output as ResponseInput ));

	const toolCalls = response.output.filter((output) => output.type === "function_call");

	if ( toolCalls.length === 0) {
		console.log(`\nAssistant: ${response.output_text}\n`);
		return;
	}

  
	for (const call of toolCalls) {
		const toolName = call.name;
		const handler = toolHandlers[toolName];
		if (!handler){
			conversationHistory.push({
				type: "function_call_output",
				call_id: call.call_id,
				output: JSON.stringify({ error: `Unknown tool: ${toolName}`})
			});
		continue;
	}

	let result: any;

	try {
		const args = JSON.parse(call.arguments || "{}");
		result = await handler(args);
	} catch (err: any) {
	
		result = { error: {
			type: "tool_runtime_error",
			message: err instanceof Error ? err.message : String(err)
			}
		};
	}

	conversationHistory.push({
		type: "function_call_output",
		call_id: call.call_id,
		output: JSON.stringify(result)
	});
	}
	}
}


async function main() {
	const terminalChat = rl.createInterface({ input, output });
	console.log(`\nHello! I am your tiny-agent ready to help you with your coding.`);
	const conversationHistory: any[] = [
		{
			role: "developer",
			content: "You are a coding agent. Use the provided tools to answer the user's questions."
	
		}
	];

	const terminalInput = (userInput: string) => new Promise<string>((resolve) => terminalChat.question(userInput, resolve));

	while (true) {
		const newInputFromUser = (await terminalInput("You: ")).trim();
		if (!newInputFromUser) continue;
		if (newInputFromUser === "exit()") break;
		await runAgentTurn(conversationHistory, newInputFromUser);
	}
	terminalChat.close();
}

main().catch((err) => {
	console.error(err);
	process.exit(1);
});

Let’s break down the code and see what each line is doing:

import OpenAI from "openai";
import { tools, toolHandlers } from "./tools/toolSchemas.js";
import { ResponseInput } from "openai/resources/responses/responses";
import * as rl from "node:readline";
import { stdin as input, stdout as output } from "node:process";
import "dotenv/config";

We import the OpenAI client class which we will use to send requests to the API. We import the tools and tool handlers, these will go into the OpenAI API create() method that we use to receive a response from the model. We import the ResponseInput type which our prompts will take. We also import the node:readline and stdin, stdout modules so we can communicate with the agent through a terminal. Lastly, we import dontenv/config to load our OPENAI_API_KEY as an environment variable.

const client = new OpenAI({
	apiKey: process.env.OPENAI_API_KEY,
});

We define the OpenAI client.

async function runAgentTurn(conversationHistory: ResponseInput, userInput: string){

	conversationHistory.push({ role: "user", content: userInput });
	
	while (true) {
		const response = await client.responses.create({
			model: "gpt-5.4",
			input: conversationHistory,
			tools,
			tool_choice: "auto"
		});
	
		conversationHistory.push(...response.output);

		const toolCalls = response.output.filter((output) => output.type === "function_call");

		if ( toolCalls.length === 0) {
			console.log(`\nAssistant: ${response.output_text}\n`);
			return;	
			}

  
		for (const call of toolCalls) {
			const toolName = call.name;
			const handler = toolHandlers[toolName];
			if (!handler){
				conversationHistory.push({
					type: "function_call_output",
					call_id: call.call_id,
					output: JSON.stringify({ error: `Unknown tool: ${toolName}`})
				});
			continue;
		}

			let result: any;
	
			try {
				const args = JSON.parse(call.arguments || "{}");
				result = await handler(args);
			} catch (err: any) {
				result = { error: {
								type: "tool_runtime_error",
								message: err instanceof Error ? err.message : String(err)
							}
						}
					}
	
			conversationHistory.push({
				type: "function_call_output",
				call_id: call.call_id,
				output: JSON.stringify(result)
			});
		}
	}
}

We define a runAgentTurn() function which handles the core part of the inference work. It takes in conversationHistory and userInput as arguments. The conversation history is running list of all our back and forth messages with the model. userInput is the message we send from the terminal. When runAgentTurn() is called, the first thing it does is push userInput into conversationHistory. The OpenAI chat format uses roles to differentiate between different kinds of messages during inference. Messages sent by an end user take the role user, messages sent by the model take the role assistant and messages defined by a developer to control the way a model interacts take the role developer.

Next, we set up the inference loop. We use while (True) so that the loop continues to run until we directly terminate it. Inside the loop, we set up the OpenAI client by assigning the create() method to a response variable. The parameters we set in this method are the kernel of the agent. We define the model we are using for inference as gpt-5.4, we also set the input to the model as our conversationHistory list. We pass our tool schemas to the model and finally we set tool_choice to auto meaning that the model can choose to call any tool from the list we have provided.

The create() method on the OpenAI Responses API returns an object with output as one of its properties. We push that output to the end of our conversationHistory list. This means that when we send the next message, the model will have full context of all our previous messages and its previous responses.

Next we filter out all tool calls from the model’s output and if there is no tool call, we print response.output_text, the model’s final text response, to the terminal. This handles cases where you send a prompt that does not require a tool call, like, “How are you?” or after a series of tool calls, the model is sending a summary of the work it has done. For instance, you ask, “How many .md files are there in this project?” The model uses its tools to do the count and sends you a final response with the actual number. We end the current iteration of the loop with a return statement until there is a new userInput. Then, we get to handling tool calls.

We loop through each tool_call in output. First, we access the tool name we defined in the function schema and pass that name as a key to our tool handler map/dict to retrieve the corresponding function. We also handle the failure case of when a model calls a tool that we don’t have. This is referred to as hallucination, a situation where the model is literally making things up. We add this information to the conversationHistory so the model can see the error and correct it in its next response.

Next, we create a result variable that we will assign the result of function execution on any tool calls that the agent makes. We set up a try-catch block and inside it we handle the tool calls. Next, we parse the arguments from the function call that is returned in the model’s output, the args variable is optionally initialized to an empty dict/map if there are no arguments. The result = await handler(args) is the actual function execution. So if the handler is read_file() and args is "/hello.txt" await handler(args) would be await read_file("/hello.txt").

We catch any errors from the tool execution, for instance, in the case of read_file() the path already exists. These errors are added to the conversation history too and passed to the model so it is aware of them and can fix them in the next turn. Finally, we add the output of the function execution to the conversation history.

async function main() {
	const terminalChat = rl.createInterface({ input, output });
	console.log(`\nHello! I am your tiny-agent ready to help you with your coding.`);
	const conversationHistory: any[] = [
		{
			role: "developer",
			content: "You are a coding agent. Use the provided tools to answer the user's questions."
	
		}
	];

	const terminalInput = (userInput: string) => new Promise<string>((resolve) => terminalChat.question(userInput, resolve));

	while (true) {
		const newInputFromUser = (await terminalInput("You: ")).trim();
		if (!newInputFromUser) continue;
		if (newInputFromUser === "exit()") break;
		await runAgentTurn(conversationHistory, newInputFromUser);
	}
	terminalChat.close();
}

main().catch((err) => {
	console.error(err);
	process.exit(1);
});

Finally, we set up our main() function, which will be the entry point to the agent. Here, we initilalize the conversationHistory with a system prompt directing the model on how to behave. This is a very minimal prompt, in a production setting, your prompt would be more elaborate with examples and more detailed guidance. We set up a loop to retrieve userInput from the terminal and pass it to runAgentTurn(). Finally, we call the main() function.

And that’s our coding agent fully set up!

You can find the Python version of inference loop below. The code explanations I provided on the TypeScript version also apply here, the only difference is syntax.

from openai import OpenAI
from dotenv import load_dotenv
from tools.tool_handlers import tools, TOOLS
import json
import os
from logging import Logger

load_dotenv()

def run_agent_turn(conversation_history, user_input):
	conversation_history.append({"role": "user", "content": user_input})
	print(conversation_history)

	while True:
		client = OpenAI(
			api_key = os.environ["OPENAI_API_KEY"]
		)

		response = client.responses.create(
			model="gpt-5.4",
			input=conversation_history,
			tools=tools
		)

		'''
		
		We extend conversation_history += response.output because response.output is a list of output items not a single item
		
		If we appended using conversation_history.append(response.output), on the next api call, input=conversation_history would
		
		likely be malformed and raise a type/validation error like "expected an input item/object, got array/list"
		
		+= is equivalent to extending the list, so, conversation_history.extend(response.output) would also work here.
		
		'''

		conversation_history += response.output
		print(conversation_history)
		tool_calls = [o for o in response.output if o.type == "function_call"]
		print(f"\n{tool_calls}") 
	
		if len(tool_calls) == 0:
			print(f"\nAssistant: {response.output_text}")
		return
	
		for call in tool_calls:
			function_name = call.name
			tool_handler = TOOLS[function_name]
			args = call.arguments
			print(f"\ncalling {function_name} with {args}")

			'''
			Why we use json.loads()
			
			the model gives function arguments as text,
			
			but the tool handler needs real values like dicts, lists, strings, numbers, and booleans.
			
			'''

		try:
			tool_result = tool_handler(**json.loads(args))
		except Exception as e:
			print(e)
			tool_result = {"ok": False, "message": f"{type(e).__name__}: {e}"}
		print(f"\n{tool_result}")
	
		conversation_history.append({
			"type": "function_call_output",
			"call_id": call.call_id,
			"output": json.dumps({
			"tool_result": tool_result
			})
		})

def main():
	print("Hi! I'm tiny, your minimal coding agent. Give me a task to do!")
	conversation_history = []
	system_prompt = '''
		You are an advanced coding agent.
		Use the provided tools to answer the user's questions accurately.
	'''

	conversation_history.append({
		"role": "developer",
		"content": system_prompt
	})

	while True:
		user_input = input("\nUser: ")
		if user_input is None:
			continue

		if user_input == "exit()":
			print("Goodbye! See you another time!")
			break
		run_agent_turn(conversation_history, user_input)

if __name__ == "__main__":

main()