A self-correcting test-driven development (TDD) sandbox that enforces writing a failing reproduction test first (RED), modifying source code via buffer updates, and verifying test completion (GREEN) inside an isolated execution environment.
v2 closes four gaps from the v1 baseline: real VS Code extension, tested Docker path, 5 diverse examples, and explicit mode control (no silent mock fallback).
codexforge_mvp_v2/
├── DESIGN.md # High-level system design
├── PLAN.md # Phased build plan with acceptance criteria
├── ARCHITECTURE.png # System architecture diagram
├── README.md # This file
├── requirements.txt # Python dependencies
├── sandbox/
│ ├── Dockerfile # Python 3.11 sandbox with pytest + ruff
│ ├── docker-compose.yml # Container orchestration with healthcheck
│ └── workspace/ # Volume-mounted workspace for test execution
├── acp/
│ ├── package.json # Real VS Code extension manifest
│ ├── extension.js # VS Code extension (commands + TCP JSON-RPC)
│ ├── acp_client.py # Python ACP server (port 9120) + client API
│ └── diff_solver.py # Three-way merge (Diff3) conflict resolver
├── engine/
│ ├── tdd_orchestrator.py # Core RED→GREEN TDD loop orchestrator
│ └── run_example.py # CLI entry point with argparse
├── router/
│ └── llm_client.py # LLM API client (Anthropic/OpenAI/OpenRouter)
├── tests/
│ ├── buggy_divide.py # Example 1: Division by zero
│ ├── buggy_parser.py # Example 2: CSV parser with quoted fields
│ ├── buggy_dedup.py # Example 3: List dedup with order preservation
│ ├── buggy_retry.py # Example 4: Exception handling (retry)
│ ├── buggy_flatten.py # Example 5: Recursive nested list flattening
│ ├── test_llm_client.py # Unit tests for LLM client (12 tests)
│ ├── test_diff_solver.py # Unit tests for Diff3 solver (8 tests)
│ └── test_acp_client.py # Unit tests for ACP client (6 tests)
└── .github/workflows/
└── ci.yml # Full CI: syntax, unit tests, mock examples, Docker, VS Code
--mode=live only)pip install -r requirements.txt
cd codexforge_mvp_v2
# Run any of the 5 built-in examples
python3 engine/run_example.py --example 1 --mode mock # Division by zero
python3 engine/run_example.py --example 2 --mode mock # CSV parser
python3 engine/run_example.py --example 3 --mode mock # List deduplication
python3 engine/run_example.py --example 4 --mode mock # Exception handling (retry)
python3 engine/run_example.py --example 5 --mode mock # Nested list flattening
Each example demonstrates the full RED→GREEN TDD loop:
cd codexforge_mvp_v2/sandbox
# Build and start the sandbox container
docker compose up -d
# Verify it's healthy
docker compose ps
cd ..
# Now run examples — they'll automatically use Docker
python3 engine/run_example.py --example 1 --mode mock
The orchestrator auto-detects a running Docker container and routes test execution through docker compose exec instead of local subprocess.
Three providers are supported — the client auto-detects which key you’ve set:
# Option A: Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."
python3 engine/run_example.py --example 1 --mode live
# Option B: OpenAI
export OPENAI_API_KEY="sk-..."
python3 engine/run_example.py --example 1 --mode live
# Option C: OpenRouter (100+ models, pay-per-token)
export OPENROUTER_API_KEY="sk-or-..."
python3 engine/run_example.py --example 1 --mode live
# Override the default model for any provider
export CODEXFORGE_MODEL="google/gemini-2.5-flash" # OpenRouter
export CODEXFORGE_MODEL="claude-3-5-sonnet-20241022" # Anthropic
export CODEXFORGE_MODEL="gpt-4o" # OpenAI
Important: Running with --mode=live without an API key will produce a clear error message — it will NOT silently fall back to mock mode. This is intentional.
Fix your own buggy code — no need to add it to the built-in examples:
python3 engine/run_example.py \
--target path/to/your/buggy_file.py \
--task "Fix the function so it handles edge case X" \
--mode live
# Run all 26 unit tests
python3 -m pytest tests/test_llm_client.py tests/test_diff_solver.py tests/test_acp_client.py -v
The acp/ directory contains a real VS Code extension:
cd codexforge_mvp_v2/acp
code --extensionDevelopmentPath=.
python3 acp/acp_client.py
This starts a TCP server on localhost:9120 that receives JSON-RPC payloads from the VS Code extension.
textDocument/didChange payload.In VS Code settings:
codexforge.agentHost — ACP server hostname (default: localhost)codexforge.agentPort — ACP server port (default: 9120)| # | Name | Bug | Fix |
|---|---|---|---|
| 1 | Division by Zero | return a / b raises ZeroDivisionError |
Guard if b == 0: return 0 |
| 2 | CSV Parser | Splits on ALL commas, ignoring quotes | Track in_quotes state |
| 3 | List Dedup | sorted(set()) loses insertion order |
seen = set() + ordered loop |
| 4 | Exception Handling | except BaseException swallows KeyboardInterrupt |
except Exception only |
| 5 | Nested Flatten | Only one level deep: result.extend(item) |
Recursive: result.extend(flatten(item)) |
The GitHub Actions CI runs on every push and PR:
| Job | Tests |
|---|---|
| Syntax Check | Compiles all Python files |
| Unit Tests | 26 module-level tests |
| Mock Examples (1–5) | 5 parallel TDD loops |
| Docker Sandbox | All 5 examples in container |
| VS Code Extension | package.json + extension.js validation |
| Area | v1 | v2 |
|---|---|---|
| ACP Extension | Stub package.json only |
Real extension.js with activation events, commands, TCP client |
| Docker Sandbox | Untested volume mount | Fixed mount, healthcheck, verified exec path |
| Examples | 1 hardcoded divide() |
5 diverse examples (divide, CSV, dedup, retry, flatten) |
| Mode Control | Silent mock fallback | Explicit --mode flag; hard error without API key in live mode |
| Providers | Anthropic + OpenAI only | + OpenRouter (100+ models) |
| Model Config | Hardcoded model names | Configurable via CODEXFORGE_MODEL env var |
| CLI | No CLI interface | Full argparse with --example, --mode, --target, --task |
| Tests | None | 26 unit tests + CI pipeline |
| Live Verified | Mock only | Gemini 2.5 Flash via OpenRouter — 5/5 GREEN |
Built by Nagarjuna Reddy Kamireddy (Nagarjuna Kamireddy / Nagarjuna K) — Lead AI Architect, GenAI & Agentic AI Lead, and Corporate AI Trainer (20+ years across Enterprise Data, SAP HANA & Production AI; AWS Certified Solutions Architect – Professional & NVIDIA-Certified Professional: Agentic AI).
llms-full.txt · LinkedIn