Auto Repo Forge

An AI agent that autonomously develops, commits, and ships GitHub projects from ideas and research.

Give it an idea. It scaffolds the project, writes the code, creates a GitHub repo, commits, and pushes — all without manual intervention.

How It Works

Idea → AI Planning → Code Generation → GitHub Repo → Commit & Push

1. Ideation — You provide a project idea (or feed it from a research pipeline)
2. Planning — Claude analyzes the idea, decides on tech stack, file structure, and architecture
3. Generation — Code is written file-by-file with context awareness between files
4. Publishing — A GitHub repo is created, code is committed with a meaningful message, and pushed

Quick Start

# Clone
git clone https://github.com/KyleBuildsAI/auto-repo-forge.git
cd auto-repo-forge

# Install dependencies
pip install -r requirements.txt

# Set your API key
export ANTHROPIC_API_KEY="sk-ant-..."

# Forge a project
python -m forge "Build a CLI tool that monitors disk usage and sends alerts"

Usage

Basic — forge from an idea

python -m forge "A Python FastAPI service that converts markdown to styled PDFs"

With options

python -m forge \
  --owner KyleBuildsAI \
  --visibility public \
  --model claude-sonnet-4-20250514 \
  "A real-time crypto price dashboard with WebSocket updates"

From a spec file

python -m forge --spec project-spec.yaml

Dry run (plan only, no repo creation)

python -m forge --dry-run "A browser extension that summarizes any webpage"

Spec File Format

For more complex projects, use a YAML spec:

name: my-awesome-project
description: A tool that does X, Y, and Z
language: python
visibility: public
features:
  - REST API with FastAPI
  - SQLite database
  - CLI interface
  - Docker support

Configuration

Env Variable	Description	Default
ANTHROPIC_API_KEY	Claude API key (required)	—
GITHUB_OWNER	GitHub username for repo creation	From gh auth
FORGE_MODEL	Claude model to use	claude-sonnet-4-20250514
FORGE_WORKSPACE	Where to create projects locally	./workspace

Architecture

auto-repo-forge/
├── forge/
│   ├── __init__.py
│   ├── __main__.py      # CLI entry point
│   ├── agent.py          # Core AI agent (planning + code generation)
│   ├── github.py         # GitHub repo creation and git operations
│   ├── planner.py        # Project planning and architecture decisions
│   ├── generator.py      # File-by-file code generation
│   └── config.py         # Configuration management
├── templates/
│   └── spec_example.yaml # Example spec file
├── requirements.txt
├── .env.example
└── README.md

Requirements

• Python 3.10+
• GitHub CLI (gh) — authenticated
• Anthropic API key

License

MIT