Self-hosted workflows for coding-agent delivery. Orchestrate CodeBuddy, Codex and Claude Code with scripts and human approval gates. Includes Local workflows for coding assistants.
LoopForge Local usage
English | 简体中文
Legacy. LoopForge Local runs built-in Classic and Portable workflows inside your coding assistant without a LoopForge server. You can keep using a published version for existing projects.
Connect to LoopForge with MCP
Use CodeBuddy with a running LoopForge instance to access projects, SOPs, and runs on that instance. If you need an instance, see the deployment guide.
- Sign in to LoopForge and open Access (接入方式). Create a personal access token and select CodeBuddy for its MCP setup instructions.
- Apply the user-level configuration in CodeBuddy and confirm that the
agentflowserver is connected in the MCP settings. Ask CodeBuddy to list your LoopForge projects to verify access.
See the MCP API reference for the endpoint and available operations.
Quick start
Requires Node.js 20+ and Python 3.8+. Replace X.Y.Z in the commands below with the published version you use for your agent and edition. You can list published versions with npm view loopforge-cli versions --json. Host support depends on the version you install.
| Agent | Install | Start a workflow |
|---|---|---|
| CodeBuddy | npx -y [email protected] install codebuddy |
/start-devflow "<request>" |
| Codex | npx -y [email protected] install codex |
$devflow-codex "<request>" |
| Cursor | npx -y [email protected] install cursor |
/start-devflow "<request>" |
| Claude Code | npx -y [email protected] install claude |
/start-devflow "<request>" |
| DeepSeek Harness | npx -y [email protected] skills install dsh |
/devflow "<request>" |
| Hermes Agent | npx -y [email protected] skills install hermes then hermes skills trust . |
/devflow "<request>" |
For example, with Claude Code:
npx -y [email protected] install claude
npx -y [email protected] status claude
/start-devflow "add status filtering to the order list and cover the API with tests"
Check any installation with npx -y [email protected] status <agent>. If installation or execution fails, diagnose the environment:
npx -y [email protected] doctor
Pi, DeepSeek Harness and Hermes Agent are supported through the Portable Edition. DSH has an optional plugin for task controls, status, artifacts and approval gates. Hermes uses its project-local Agent Skills discovery and delegate_task tool; it does not modify ~/.hermes/config.yaml. Hermes users can optionally install the native Hermes plugin for the same /loopforge status, /loopforge result and /loopforge approve controls.
How it works
- 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
Supported agents
| Agent | Classic Edition (default) | Portable Edition |
|---|---|---|
| CodeBuddy | ✓ | ✓ |
| Codex | ✓ | ✓ |
| Cursor | ✓ | ✓ |
| Claude Code | ✓ | ✓ |
| Pi | — | ✓ |
| DeepSeek Harness | — | ✓ |
| Hermes Agent | — | ✓ |
LoopForge enables only one edition per coding agent in each project. See Edition selection for the differences and directory layout.
What you get
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.
See how agents work
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/dashboard
Open http://localhost:8765. See the observability quickstart for data sources, custom pricing, and troubleshooting.
When LoopForge is useful
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.
Portable Edition
Use the Portable Edition for the portable Agent Skills workflow. 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 [email protected] skills install codebuddy |
/devflow "<request>" |
| Codex | npx -y [email protected] skills install codex |
$devflow "<request>" |
| Cursor | npx -y [email protected] skills install cursor |
/devflow "<request>" |
| Claude Code | npx -y [email protected] skills install claude |
/devflow "<request>" |
| Pi | npx -y [email protected] skills install pi, then pi install npm:pi-subagents |
/skill:devflow "<request>" |
| DeepSeek Harness | npx -y [email protected] skills install dsh |
/devflow "<request>" |
| Hermes Agent | npx -y [email protected] skills install hermes, then hermes skills trust . |
/devflow "<request>" (optional plugin: /loopforge) |
See Edition selection for the complete boundaries and directory layout.
Update and uninstall
Before switching to platform MCP or uninstalling Local, back up your project's artifacts/, .devflow/, and any customized skills and agent configuration. Keep these files as the record of your Local runs. Use the same Local version to finish or resume any runs still in progress.
To manage an existing Local installation, you can install the same CLI version globally.
npm install --global [email protected]
Then maintain an installation with the same agent names as above (codebuddy, codex, cursor, claude, pi, dsh, and hermes 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.
To install from the source of a published release, check out its tag and run the following from the repository root.
pipx install ./local
Optional tools
tools/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/tcmcp
Then 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 Local local-vX.Y.Z releases publish ghcr.io/tencent/loopforge-tcmcp:<version>.
Permissions and security
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.