---

The Problem

Every vibe coder hits the same wall at project start:

Staring at a blank AGENT.md with no idea where to begin.

Writing these config files from scratch is slow, inconsistent, and easy to get wrong. Most people either skip them or write generic low-quality ones — and then their coding agent underperforms because of it.

AgentForge solves this. Give it a rough, even vague project description — it generates exactly the config bundle your project needs.

---

Why AgentForge?

Traditional Approach	AgentForge
Copy-paste generic templates	Dynamic — decides what you actually need
Wrong files for your project type	Only generates relevant files
Manual research & writing	AI does the heavy lifting
30+ minutes of setup	Under 30 seconds

---

Features

Intent Parsing

AI analyzes your vague description and understands:

• Project type (SaaS, CLI, library, etc.)
• Domain & goals
• Scale (solo, team, enterprise)
• Tech stack hints

Web Search

Grounds outputs in real best practices — fetches relevant docs, tutorials, and community configs for your specific project type.

Dynamic Generation

Not a fixed template. Generates exactly the files your project needs:

• Always: AGENT.md, RULES.md, STRUCTURE.md
• Conditional: STACK.md, SCHEMA.md, API.md, AUTH.md, PAYMENTS.md, COMMANDS.md, TESTING.md, DEPLOYMENT.md

Fallback Chain

Works even when AI APIs are unavailable:

Gemma 4 31B → Groq → OpenRouter → Jinja2 Templates → Keyword fallback

Stack Presets

Skip intent parsing and use a curated preset:

agentforge "my project" --preset nextjs-saas

Available presets: nextjs-saas, python-cli, fastapi-api, django-web, react-spa

Config Management

# View current config
agentforge config show

# Set preferences
agentforge config set --key model --value gemma-4-31B-it
agentforge config set --key output_dir --value ./output

# Clear search cache
agentforge config clear-cache

---

Quick Start

Option 1: Direct Python

# 1. Clone
git clone https://github.com/katariyaVivek/agentforge.git
cd agentforge

# 2. Setup environment
cp .env.example .env
# Edit .env with your API keys

# 3. Run
python agentforge.py "a twitter clone for developers"

Option 2: Global CLI (Recommended)

# 1. Install globally
pip install -e .

# 2. Setup environment
cp .env.example .env
# Edit .env with your API keys

# 3. Run from anywhere
agentforge "a twitter clone for developers"

Get Your Free API Keys

Service	Free Tier	Link
Gemini	15 RPM	aistudio.google.com
Groq	500K tokens/day	groq.com
Tavily	1,000 searches/month	tavily.com

---

CLI Options

# Basic usage
agentforge "your project idea"
ag "your project idea"                # shorthand alias

# Or with python (if not installed globally)
python agentforge.py "your project idea"

# Preview which files would be generated (no writing)
agentforge "..." --dry-run

# See detailed pipeline steps
agentforge "..." --verbose

# Skip web search (faster, lower quality)
agentforge "..." --no-search

# Custom output directory
agentforge "..." --out ./my-output

# Use a specific AI model
agentforge "..." --model gemini-2.5-flash

# Use a stack preset
agentforge "..." --preset nextjs-saas

# Show version
agentforge --version

---

Output Example

output/my-twitter-clone/
├── AGENT.md         # Project overview, goals, constraints
├── RULES.md         # Coding conventions
├── STRUCTURE.md     # Folder scaffold with purpose
├── STACK.md         # Tech decisions
├── SCHEMA.md        # Database models
├── AUTH.md          # User auth config
├── API.md           # REST API endpoints
└── PAYMENTS.md      # Stripe integration

---

Architecture

User Input (vague description or --preset)
         ↓
1. Intent Parser (Gemma 4 31B → Groq → fallback)
   → Extracts project type, domain, files needed
   → Optional: preset overrides merge with LLM-detected hints
         ↓
2. Search Layer (Tavily, cached)
   → Fetches relevant best practices
         ↓
3. Context Compression
   → Summarizes to ~400 words of signal
         ↓
4. File Generator (Gemma 4 31B → Groq → OpenRouter → Templates → Fallback)
   → Creates tailored config files
         ↓
Output: output/<project-slug>/

---

Tech Stack

Layer	Choice
Language	Python 3.10+
CLI	Typer
AI	Gemma 4 31B (primary), Groq (fallback), OpenRouter (fallback)
Search	Tavily (with caching)
Templating	Jinja2
Tests	111 passing

---

Project Structure

agentforge/
├── src/
│   ├── main.py                         # CLI orchestrator (Typer)
│   ├── pipeline/
│   │   ├── intent_parser.py            # LLM intent parsing + keyword fallback
│   │   ├── search.py                   # Tavily web search + caching
│   │   ├── cache.py                    # Search result cache (JSON)
│   │   └── compressor.py              # Context compression pipeline
│   └── agentforge/
│       ├── catalog/
│       │   ├── models.py               # Pydantic catalog models + CATALOG data
│       │   ├── registry.py             # File generation registry
│       │   ├── conditions.py           # Safe AST condition evaluator
│       │   └── presets.py             # Stack presets (nextjs-saas, etc.)
│       ├── cli/
│       │   ├── config_manager.py       # Config persistence (~/.agentforge/)
│       │   ├── errors.py               # Custom exception hierarchy
│       │   ├── exit_codes.py           # CLI exit codes
│       │   └── logging_config.py       # Logging setup
│       ├── generation/
│       │   ├── generator.py            # File generator (LLM + template + fallback)
│       │   ├── fallback.py             # LLM fallback chain
│       │   └── prompts/               # Jinja2 templates
│       ├── output/
│       │   └── writer.py               # File writer utility
│       └── utils/
│           └── text.py                 # Shared utilities (slugify)
├── tests/
│   ├── test_cli_flags.py
│   ├── test_compression.py
│   ├── test_conditions.py
│   ├── test_errors.py
│   ├── test_fallback.py
│   ├── test_generator.py
│   ├── test_intent_parser.py
│   ├── test_presets.py
│   ├── test_registry.py
│   ├── test_search.py
│   ├── test_template_rendering.py
│   └── test_writer.py
├── pyproject.toml
└── README.md

---

Contributing

1. Fork the repo
2. Create a feature branch
3. Submit a PR

---

License

MIT License — free for personal and commercial use.

---

_{Built for vibe coders, by vibe coders.}