My Coding Agent

A small Python coding-agent that runs in an interactive terminal loop.\

The project is as a learning codebase for building coding agents from first principles.

Requirements

• Python 3.10+
• An OpenAI API key

Setup

Create and activate a virtual environment:

python -m venv venv
source venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Create a .env file in the project root:

OPENAI_API_KEY=your_api_key_here

The app loads environment variables with python-dotenv, so secrets should stay in .env and out of version control.

Run

Start the interactive agent:

python main.py

Type a request at the You: prompt. Exit with Ctrl-C or EOF.

How It Works

main.py builds a system prompt, sends the conversation to the OpenAI Responses API, and passes the registered tool schemas through the tools argument. When the model returns function calls, the agent:

1. Adds the assistant output to the conversation.
2. Runs PRE_TOOL_USE hooks.
3. Executes the requested local tool if it is allowed.
4. Appends a function_call_output message with the tool result.
5. Calls the model again until it returns final text.

When final text is produced, the agent prints it and logs the message through the hook system.

Tool Permissions

The permissions hook reads:

.my-coding-agent/tool-use-config.json

The file is created automatically if it does not exist. To disable a tool, add a tools object with the tool name and a deny status:

{
    "tools": {
        "run_shell_command": {
            "status": "deny"
        }
    }
}

When a tool is denied, the model receives a structured error instead of a tool result.

Adding A Tool

1. Add a new tool name in tools/types/tool_names.py.
2. Create an implementation in tools/implementations/.
3. Export a TOOL value using the Tool dataclass.
4. Register it in tools/tool_registry.py.

Each tool provides:

• name: a ToolName enum value.
• description: a short description passed to the model.
• parameters: JSON schema for the function call arguments.
• decode_params: argument normalization and defaults.
• exec: the Python function that performs the work.

Adding A Hook

1. Create a hook implementation in hooks/implementations/.
2. Export a Hook value.
3. Register it in _HOOK_REGISTRY in hooks/hook_registry.py.
4. Choose the appropriate event from hooks/types/hook_event.py.

Current hook events include:

• PRE_TOOL_USE
• POST_MESSAGE_SENT

Generated Files

Runtime state is written under:

.my-coding-agent/

This directory contains session logs and tool permission config. It is local runtime state and usually should not be committed.