English | 简体中文
LoopForge Local runs development workflows inside an existing coding assistant without starting the platform. It currently supports the built-in Classic and Portable workflows. Importing and independently executing platform SOP exports is not implemented yet. See deployment for the platform.
Requires Node.js 20+ and Python 3.8+. The commands below install the default Classic Edition; choose it if you are unsure.
| Agent | Install | Start a workflow |
|---|---|---|
| CodeBuddy | npx -y loopforge-cli@latest install codebuddy |
/start-devflow "<request>" |
| Codex | npx -y loopforge-cli@latest install codex |
$devflow-codex "<request>" |
| Cursor | npx -y loopforge-cli@latest install cursor |
/start-devflow "<request>" |
| Claude Code | npx -y loopforge-cli@latest install claude |
/start-devflow "<request>" |
For example, with Claude Code:
npx -y loopforge-cli@latest install claude
npx -y loopforge-cli@latest status claude/start-devflow "add status filtering to the order list and cover the API with tests"
Check any installation with npx -y loopforge-cli@latest status <agent>. If installation or execution fails, diagnose the environment:
npx -y loopforge-cli@latest doctorPi is supported through the Portable Edition.
- Understand the problem first: the agent inspects the project and clarifies the goal, scope, and acceptance criteria instead of immediately writing code.
- Confirm the boundaries before implementation: medium and large tasks move into design and implementation only after you confirm the goal, scope, exclusions, key decisions, and acceptance criteria.
- Separate responsibilities: design, implementation, review, and testing are handled stage by stage by roles with independent responsibilities, which reduces self-review bias in a single context.
- Show evidence, not just a diff: requirements, plans, changes, review findings, and test results are saved for inspection, handoff, and retrospectives.
- Continue after interruption: workflow state is persisted so the next session can resume at the unfinished stage instead of starting over.
LoopForge picks the path by task complexity. Small changes take a streamlined single-role path; the full role-based workflow is reserved for medium and large tasks that benefit from it.
Your request
│
├─ Small change ───────> Understand → implement → verify → deliver
│
└─ Medium/large task ──> Clarify and confirm → design → implement
→ independent review → test → deliver
│
└── State and artifacts are saved throughout
| Agent | Classic Edition (default) | Portable Edition |
|---|---|---|
| CodeBuddy | ✓ | ✓ |
| Codex | ✓ | ✓ |
| Cursor | ✓ | ✓ |
| Claude Code | ✓ | ✓ |
| Pi | — | ✓ |
LoopForge enables only one edition per coding agent in each project. See Edition selection for the differences and directory layout.
At the end of a task, you get the code changes together with the confirmed requirement, technical design, independent review findings, test results, and delivery summary. LoopForge saves this history under artifacts/{task_slug}/ by default for inspection, handoff, and retrospectives.
View the default artifact layout
Some directory names differ between editions.
01-requirement/ Confirmed goals, scope, and acceptance criteria
02-design/ Technical design and execution plan
03-code/ Code changes and independent review report
04-e2e/ Test results
05-knowledge/ Reusable project knowledge
workflow-summary.md
Resume an interrupted Classic workflow with /resume-devflow {task_slug} on CodeBuddy, Cursor, or Claude Code, and with $devflow-codex resume {task_slug} on Codex. Each installed host bundle documents its status, abort, and individual-stage commands.
The Classic Edition for CodeBuddy includes a local observability dashboard. It turns the workflow evidence into a view of session activity, Token and cost trends, Skill/Rule usage, role dispatch, and Devflow stage attribution—useful for finding expensive runs, checking whether automation is actually being used, and reviewing how work moved between roles.
Dashboard example using synthetic demonstration data.
The dashboard is generated and served locally; it does not require an external telemetry service. Runtime logs can contain tool arguments and output excerpts, so LoopForge excludes them from Git by default and they should not be shared without review.
Open the local dashboard
After running at least one CodeBuddy session from the project root:
python3 .codebuddy/skills/agent-observability/scripts/build_dashboard_data.py --project-root .
python3 -m http.server 8765 --directory .codebuddy/skills/agent-observability/scripts/dashboardOpen http://localhost:8765. See the observability quickstart for data sources, custom pricing, and troubleshooting.
LoopForge is especially useful when:
- the request is still ambiguous and the goal or boundaries need clarification;
- a change crosses multiple modules and should be designed before implementation;
- implementation, review, and testing should be performed by separate roles;
- work may span multiple sessions and needs resumable state;
- the team wants an inspectable delivery record for handoff or retrospectives.
For one-off code completion or a tiny, fully specified edit, using a coding agent directly is often enough. Simple tasks that do enter LoopForge use its streamlined path.
The Classic Edition from the quick start is the right choice for most users. If you only want the portable Agent Skills workflow, use the Portable Edition. To prevent one coding agent from loading two workflows and mixing their state or artifacts, LoopForge enables only one edition per coding agent in each project. To switch editions, run the new install command with --force.
| Agent | Install | Start a workflow |
|---|---|---|
| CodeBuddy | npx -y loopforge-cli@latest skills install codebuddy |
/devflow "<request>" |
| Codex | npx -y loopforge-cli@latest skills install codex |
$devflow "<request>" |
| Cursor | npx -y loopforge-cli@latest skills install cursor |
/devflow "<request>" |
| Claude Code | npx -y loopforge-cli@latest skills install claude |
/devflow "<request>" |
| Pi | npx -y loopforge-cli@latest skills install pi, then pi install npm:pi-subagents |
/skill:devflow "<request>" |
See Edition selection for the complete boundaries and directory layout.
For ongoing use, install the CLI globally:
npm install --global loopforge-cliThen maintain an installation with the same agent names as above (codebuddy, codex, cursor, claude, and pi for the Portable Edition):
# Classic Edition
loopforge update <agent>
loopforge status <agent>
loopforge uninstall <agent>
# Portable Edition
loopforge skills update <agent>
loopforge skills status <agent>
loopforge skills uninstall <agent>Installation state is stored in .devflow/install-state.json. An update stops instead of overwriting user-modified or conflicting files. Use --force only when you intend to replace conflicts or switch editions, preferably after inspecting loopforge plan.
If you have cloned this repository, install the LoopForge CLI from the current source tree by running this in the repository root:
pipx install ./localtools/tcmcp is a Tencent Cloud read-only MCP Initializr (Redis, CDB, TDSQL-C, TKE, CLS, COS). It is not part of loopforge install or the npm CLI package. From a clone:
cd local/tools/tcmcpThen follow tools/tcmcp/README.md. Cloud API keys are not written into generated zips or the container image; they stay on the machine that lists resources or installs the MCP client. LoopForge vX.Y.Z releases publish ghcr.io/tencent/loopforge-tcmcp:<version>.
Some Classic host configurations enable automatic execution or high-permission agent modes. Use LoopForge only in trusted projects. Before installation, inspect planned files with loopforge plan codebuddy, loopforge plan codex, loopforge plan cursor, or loopforge plan claude. Do not put credentials, private endpoints, or production operations configuration in workflow templates.
See Security policy and report vulnerabilities privately through GitHub Security Advisories.