1. The Core Bottleneck

AI coding assistants perform admirably in single-file refactoring or toy demos, yet fail catastrophically during real-world, complex engineering delivery. When told to fix a bug, agents routinely bypass architecture design, omit unit tests, or self-review their way into fabricating false passes, halting mid-task without human notification. This black-box execution model cannot satisfy the rigorous standards of team collaboration and continuous deployment.

LoopForge abandons the hallucination-prone paradigm of pure chat interfaces by locking every interaction inside an isolated Docker sandbox. It decomposes tasks into trackable, auditable discrete steps. Whether handling routine hotfixes or cross-module feature iterations, the system dispatches requests via a Main Bot to dedicated project roles, enforcing mandatory human-in-the-loop approval gates at critical checkpoints, fundamentally curing the unruliness and non-reproducibility of AI coding.

💡 Architectural Insight: By fusing chat-driven exploration with Standard Operating Procedures (SOPs), LoopForge bounds unpredictable LLM outputs within deterministic state machine pipelines, endowing AI with true enterprise-grade delivery discipline.

2. Core Architecture and Data Flow

LoopForge centers its underlying architecture around self-hosted workspaces. When a client initiates a requirement, the gateway parser routes it to the MySQL persistence layer and the dynamic execution engine. The system integrates ten mainstream Coding Agent CLI tools as backend executors, including CodeBuddy, Codex, Claude Code, OpenCode, and Cursor CLI.

[ Client / CLI ] ---> [ Gateway / Parser ] ---> [ MySQL / State Storage ]
                                 │
                                 ▼
                     [ Dynamic Execution Engine ]
                                 │
         ┌───────────────────────┴───────────────────────┐
         ▼                                               ▼
[ Chat Workspace (Docker Sandbox) ]        [ SOP Engine (Multi-node Pipeline) ]
  - Subagents / Roles                        - Agent / Script / Human-gate Nodes
  - Git Repositories                         - Artifacts & Logs Traceability

Two parallel execution paths are provided: chatting with the Main Bot on-demand spawns conversation workspaces in Docker sandboxes containing target repositories, while executing an SOP runs a defined sequence of agent, script, human-gate, and sub-SOP nodes. Both paths link all modifications back to unified requirements, ensuring every code change, log trace, and resource cost is recorded and compiled into delivery metrics.

3. Technology Selection and Hardcore Benchmarks

Dimension LoopForge (This Project) Traditional Paradigms Typical SaaS Competitors Production Benefits
Execution Runtime Self-hosted Docker sandboxes + own servers Direct execution on host (High risk) Closed cloud SaaS (Data leakage risk) Zero data exposure, complete infrastructure ownership
Task Orchestration Configurable SOP state machines + gates Raw script automation (Rigid) Hardcoded rigid workflows (High custom cost) Complex tasks become pausable, retryable, and inspectable
Agent Ecosystem Native support for 10 major CLI tools Bound to single vendor APIs Proprietary agent runtimes Seamless model and toolchain swapping, zero lock-in
State Auditing Full-stack artifacts & node log tracking Terminal stdout or basic git commits Opaque or missing granular logs Troubleshooting time slashed by 70%, traceable per node

The design philosophy of LoopForge avoids reinventing foundational LLM training. Instead, it engineering-wraps existing high-performance coding CLI tools. By exposing GitHub, Skills, and MCP (Model Context Protocol) as standard tool interfaces, it preserves data sovereignty while maximizing architectural elasticity.

4. Hands-on Geek Guide: Zero-to-One Minimum Loop

Before deploying LoopForge, ensure Git, Docker, Docker Compose plugins, Python 3, and curl are installed. The following commands guide developers through local minimum viable deployment.

# Clone the official repository to local workspace
git clone https://github.com/Tencent/LoopForge.git
cd LoopForge

# Spin up services with an optional image mirror if network throttling occurs
MIRROR=ghcr.nju.edu.cn ./start.sh

The ./start.sh script automatically verifies system dependencies, pulls pinned GHCR release images defined in compose.yaml, initializes MySQL and platform backend services, and provisions secrets, built-in sandboxes, and starter SOPs. The service listens on 0.0.0.0:8090 by default. The first registered account gains administrator privileges. Configure model API keys and GitHub authorization in the dashboard, then begin dispatching coding tasks via chat or SOP engines.

5. Production Gotchas and Avoidance Strategies

When scaling multi-user access in production environments, proper resource allocation and network latency mitigation are critical due to heavy reliance on Docker sandboxes and external LLM APIs.

⚠️ Gotcha Warning [Image Pull Timeouts & Verification]: When direct ghcr.io pulls face connection resets in restricted networks, never blindly edit image tags in compose.yaml. Use the officially supported MIRROR=ghcr.nju.edu.cn ./start.sh variable injection, and verify SHA-256 digests via docker image inspect post-pull to guarantee supply chain integrity.

⚠️ Gotcha Warning [Sandbox Resource Isolation & Cleanup]: Chat workspaces and SOP executions dynamically spawn numerous isolated Docker container instances. Without periodic pruning during high-frequency iterations, host disk space and memory will be exhausted by orphaned volumes. Configure automated maintenance scripts running docker system prune and enforce strict CPU and memory limits per sandbox instance.