🤖 Agent Smith

"Never send a human to do a machine's job."
— Agent Smith, The Matrix

Table of Contents

• 🤖 Agent Smith
  • Table of Contents
  • Description
  • Features
  • Installation
    • Requirements
    • Clone the repository
    • Install the project
    • Configure the API key
  • Usage
    • Display help
    • Run the agent
    • Verbose output
    • Working directory
  • Testing
  • Known limitations
  • License

Description

Agent Smith is an educational command-line coding agent based on Boot.dev’s Build an AI Agent in Python course. Inspired by tools such as Claude Code, it uses free models from OpenRouter through the official OpenAI Python SDK to inspect files, execute Python code, and make changes within a working directory.

Warning

This project does not include all the security and safety protections expected from a production AI agent. It is a toy implementation intended strictly for learning and experimentation.

Features

• Uses an LLM to plan and complete coding tasks through an iterative agent loop.
• Lists files and directories within the working directory.
• Reads file contents with configurable truncation for large files.
• Creates and overwrites files, including files in new subdirectories.
• Executes Python files with optional command-line arguments.
• Captures standard output, standard error, and process exit codes.
• Prevents ordinary path traversal outside the configured working directory.
• Provides optional verbose output, including tool calls and token usage.

Installation

Requirements

• Python 3.13 or newer
• uv
• An OpenRouter API key

Clone the repository

git clone https://github.com/ilkkavv/agent-smith
cd agent-smith

Install the project

Use uv to create the virtual environment and install the project with its dependencies:

uv sync

Configure the API key

Copy the provided environment template:

cp .env.example .env

Open .env and replace the placeholder with your OpenRouter API key:

OPENROUTER_API_KEY=your_openrouter_api_key

The .env file is excluded from version control. Never commit an API key or share it publicly.

Verify the installation without making an API request:

uv run agent-smith --help

Usage

Display help

uv run agent-smith --help

Run the agent

uv run agent-smith "Describe the task you want the agent to complete"

Verbose output

uv run agent-smith --verbose "Describe the task you want the agent to complete"

Agent Smith can also be run as a Python module:

uv run python -m agent_smith "Describe the task you want the agent to complete"

Working directory

The current development setup runs Agent Smith from the repository root. Because its permitted working directory is configured as ./, its file and execution tools operate on this repository.

Running Agent Smith against another project is possible, but requires making the agent-smith command available outside this repository. For example, by activating its virtual environment, installing it as a command-line tool, or telling uv where to find the Agent Smith project.

A future version could provide a dedicated --working-dir option to make selecting another project explicit.

Caution

Agent Smith can read, overwrite, and execute files in its working directory. Commit your changes before running it, and do not use it in a directory containing sensitive or irreplaceable files.

Testing

The project uses pytest for automated testing. The tests use temporary directories and do not operate on the actual repository files.

Run the complete test suite:

uv run pytest

Display each test name and result:

uv run pytest -v

Run a single test module:

uv run pytest tests/test_get_file_content.py -v

The current test suite covers:

• Listing files and directories
• Reading normal, nested, missing, and oversized files
• Creating and overwriting files
• Rejecting ordinary paths outside the working directory
• Running Python scripts with arguments
• Capturing standard output, standard error, and exit codes

The tests do not make requests to OpenRouter, so an API key is not required to run them.

Known limitations

Agent Smith is an educational project and is not a secure sandbox or production-ready coding agent.

Known limitations include:

• Path validation prevents ordinary ../ traversal but does not fully protect against symbolic-link escapes.
• Python scripts executed inside the working directory are not isolated from the rest of the system.
• Executed scripts inherit the permissions and environment variables of the Agent Smith process.
• The agent can create, overwrite, and execute files without asking for confirmation.
• There is no automatic backup, rollback, approval flow, or dry-run mode.
• The permitted working directory is currently fixed to ./.
• The standard development workflow therefore operates on the Agent Smith repository itself.
• Selecting another target project requires launching the installed command from that directory or otherwise making the CLI available there.
• The agent depends on an external model provided through OpenRouter, so availability and responses may vary.
• Automated tests cover the filesystem tools but not real LLM responses or the complete OpenRouter integration.

License

This project is licensed under the GNU General Public License version 3 or any later version (GPL-3.0-or-later).

See the LICENSE file for the complete license terms.