Coding Agent

An autonomous coding agent that runs in a Docker container, connects to your LLM of choice, and delivers complete pull requests — from planning through testing.

Give it a task and a repository. It will clone the repo, create a branch, plan the changes, implement them, run tests, fix any failures, push, and open a PR with reviewers assigned.

How It Works

Task + Repo ──▶ Plan ──▶ Implement ──▶ Test ──╮
                                               │
                 PR ◀── Push ◀── Fix ◀─── Fail?┤
                                               │
                 PR ◀── Push ◀──────── Pass? ──╯

The agent loops through test/fix cycles (up to 5 attempts) until all checks pass, then pushes and creates a pull request.

Supported LLM Providers

Provider	Model Example	Env Variable
Ollama (local)	qwen2.5-coder:14b	OLLAMA_BASE_URL
Claude	claude-sonnet-4-20250514	ANTHROPIC_API_KEY
Gemini	gemini-2.5-pro	GEMINI_API_KEY
Codex / OpenAI	o3	OPENAI_API_KEY

Quick Start

1. Configure

Copy the example env file and add your credentials:

cp .env.example .env
# Edit .env with your GH_TOKEN and LLM API key

Copy the example config file and customize it for your repositories:

cp config.yaml.example config.yaml

Edit config.yaml to add your repositories:

repositories:
  # Public repo (or private using the default GH_TOKEN)
  - name: "my-backend"
    url: "https://github.com/yourorg/my-backend.git"
    default_branch: "main"
    language: "python"
    test_command: "pytest"
    lint_command: "ruff check ."
    setup_command: "uv sync --frozen"

  # Private repo with a dedicated token
  - name: "my-private-service"
    url: "https://github.com/yourorg/my-private-service.git"
    private: true
    auth_method: "token"
    token_env: "MY_PRIVATE_REPO_TOKEN"

  # Private repo via SSH
  - name: "my-private-infra"
    url: "git@github.com:yourorg/my-private-infra.git"
    private: true
    auth_method: "ssh"

See Private Repositories for full details on authentication methods.

2. Run

# With Claude
./scripts/run.sh my-backend "Add rate limiting to /api/users endpoint" claude

# With local Ollama
./scripts/run.sh my-backend "Fix bug #42" ollama

# With Gemini
./scripts/run.sh my-frontend "Add dark mode toggle" gemini

# With OpenAI
./scripts/run.sh my-backend "Refactor auth module" codex

Or use docker compose directly:

docker compose build agent
docker compose run --rm agent --repo my-backend --task "Add input validation" --verbose

Interactive TUI

A terminal UI lets you manage tasks interactively — select repos, pick PRs, start multiple tasks in parallel, and watch logs live:

uv run coding-agent-tui

See docs/TUI.md for details.

3. Result

The agent outputs a PR URL when finished. The PR includes an LLM-generated title and description with a summary of all changes.

Configuration Reference

See config.yaml.example for all options. Key sections:

• llm — provider selection and model configuration
• repositories — list of repos the agent can work on (name, URL, language, test/lint/setup commands, auth method for private repos)
• git — branch prefix, commit author, default branch, SSH key path
• agent — max fix attempts, auto-push, auto-PR, reviewer list
• sandbox — Docker resource limits and timeouts

Project Structure

├── config.yaml.example      # Agent and repository configuration template
├── docker-compose.yaml      # Agent + optional Ollama sidecar
├── Dockerfile               # Agent container image
├── pyproject.toml            # Python dependencies
├── scripts/
│   └── run.sh               # One-command launcher
├── src/
│   ├── main.py              # CLI entry point
│   ├── tui/
│   │   └── app.py           # Interactive terminal UI (Textual)
│   ├── agent/
│   │   ├── loop.py          # Core plan → implement → test → fix cycle
│   │   ├── executor.py      # Shell command runner (tests, lint)
│   │   └── prompts.py       # LLM prompt templates
│   ├── config/
│   │   └── settings.py      # YAML + env config loader
│   ├── docker_env/
│   │   └── sandbox.py       # Docker image build and container runner
│   ├── git_ops/
│   │   └── repo.py          # Clone, branch, commit, push, PR creation
│   └── llm/
│       ├── base.py          # Provider interface
│       ├── factory.py       # Provider factory
│       ├── ollama_provider.py
│       ├── claude_provider.py
│       ├── gemini_provider.py
│       └── codex_provider.py
├── tests/                   # Unit tests
└── docs/                    # Detailed documentation
    ├── architecture.md      # System design and component details
    └── research.md          # Survey of existing open-source agents

Documentation

• Architecture — system design, agent loop, component details, Docker setup, and extension points
• TUI — interactive terminal UI usage and keybindings
• Research — survey of 14 open-source coding agents, comparison matrix, and architectural patterns from the ecosystem

Development

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install dependencies
uv sync

# Run tests
uv run pytest

# Lint
uv run ruff check .

License

MIT