Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 5 additions & 20 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@

<p align="center">
<a href="https://github.com/Tencent/LoopForge/actions/workflows/platform.yml"><img src="https://img.shields.io/github/actions/workflow/status/Tencent/LoopForge/platform.yml?branch=main&label=CI&style=flat-square" alt="CI"></a>
<a href="https://www.npmjs.com/package/loopforge-cli"><img src="https://img.shields.io/npm/v/loopforge-cli?label=loopforge-cli&color=7b61ff&style=flat-square" alt="npm loopforge-cli"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7b61ff?style=flat-square" alt="MIT License"></a>
<img src="https://img.shields.io/badge/self--hosted-Docker-526ce8?style=flat-square&logo=docker&logoColor=white" alt="Self-hosted with Docker">
<a href="https://github.com/Tencent/LoopForge/stargazers"><img src="https://img.shields.io/github/stars/Tencent/LoopForge?style=flat-square&color=f59e0b" alt="GitHub stars"></a>
Expand All @@ -26,7 +25,7 @@
<a href="#quick-start">Quick start</a> ·
<a href="#how-sops-work">SOPs</a> ·
<a href="#features">Features</a> ·
<a href="#loopforge-local">Local</a> ·
<a href="#loopforge-local">Local (Legacy)</a> ·
<a href="#faq">FAQ</a> ·
<a href="#documentation">Docs</a>
</p>
Expand Down Expand Up @@ -192,25 +191,11 @@ Each node declares its artifacts and dependencies, and the engine starts each st

## LoopForge Local

Don't want to run a server? **LoopForge Local** brings the built-in delivery workflows straight into the coding assistant you already use:
> **Legacy.** Previously published versions of LoopForge Local (`loopforge-cli`) remain available. The [Local guide](docs/local/usage.md) covers installing a fixed version and keeping existing workflows and artifacts.

```bash
# Run inside your target project, e.g. for Claude Code
npx -y loopforge-cli@latest install claude
```

Then run `/start-devflow "<your request>"` in Claude Code.

| Host | Supported |
| --- | --- |
| Claude Code · CodeBuddy · Codex · Cursor | Classic (default) and Portable editions |
| Pi | Portable edition |
| DeepSeek Harness | Portable edition |
| Hermes Agent | Portable edition |

See the [local guide](docs/local/usage.md) for each host's entry point and [editions](docs/local/editions.md) for the differences. Source lives in [`local/`](local/). Local runs the built-in workflows today; exporting a platform SOP for standalone local execution is planned.
To use platform projects and SOPs from a coding assistant, [connect CodeBuddy to your LoopForge instance over MCP](docs/local/usage.md#connect-to-loopforge-with-mcp). Local continues to run its built-in workflows inside the coding assistant without a LoopForge server.

| | Platform | Local |
| | Platform | Local (Legacy) |
| --- | --- | --- |
| Best for | Teams sharing chat workspaces, SOPs, approvals and history | One developer inside an IDE or CLI |
| Needs | Docker + Python 3 | Node.js 20+, Python 3.8+ and a coding assistant |
Expand Down Expand Up @@ -243,7 +228,7 @@ New installations listen on all interfaces and target a trusted team. Read the [
| --- | --- |
| Deploy, manage accounts, connect execution machines | [Deployment](docs/deployment.md) |
| Understand chat workspaces, scheduled AI tasks and token pricing | [Conversation workspaces](docs/conversation-workspaces.md) · [AI scheduled tasks](docs/ai-scheduled-task-capabilities.md) · [Token pricing](docs/token-pricing.md) |
| Install local workflows or choose an edition | [LoopForge Local](docs/local/usage.md) · [Editions](docs/local/editions.md) |
| Maintain an existing Local installation | [LoopForge Local](docs/local/usage.md) · [Editions](docs/local/editions.md) |
| Extend the platform or use the HTTP / MCP API | [Architecture](docs/architecture.md) · [API reference](docs/api/README.md) · [Shared schedules API](docs/api/shared-schedules.md) |
| Contribute to the UI | [Frontend design conventions](design.md) (Chinese) |
| Check functional coverage and release readiness | [Validation record](docs/validation.md) · [Acceptance matrix](docs/testing/acceptance-matrix.md) · [Release review](docs/release-readiness.md) |
Expand Down
23 changes: 5 additions & 18 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,6 @@

<p align="center">
<a href="https://github.com/Tencent/LoopForge/actions/workflows/platform.yml"><img src="https://img.shields.io/github/actions/workflow/status/Tencent/LoopForge/platform.yml?branch=main&label=CI&style=flat-square" alt="CI"></a>
<a href="https://www.npmjs.com/package/loopforge-cli"><img src="https://img.shields.io/npm/v/loopforge-cli?label=loopforge-cli&color=7b61ff&style=flat-square" alt="npm loopforge-cli"></a>
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7b61ff?style=flat-square" alt="MIT License"></a>
<img src="https://img.shields.io/badge/自主部署-Docker-526ce8?style=flat-square&logo=docker&logoColor=white" alt="Docker 自主部署">
<a href="https://github.com/Tencent/LoopForge/stargazers"><img src="https://img.shields.io/github/stars/Tencent/LoopForge?style=flat-square&color=f59e0b" alt="GitHub stars"></a>
Expand All @@ -26,7 +25,7 @@
<a href="#快速开始">快速开始</a> ·
<a href="#sop-如何运行">SOP</a> ·
<a href="#功能一览">功能</a> ·
<a href="#loopforge-local">本地版</a> ·
<a href="#loopforge-local">本地版(旧版)</a> ·
<a href="#常见问题">FAQ</a> ·
<a href="#文档">文档</a>
</p>
Expand Down Expand Up @@ -192,23 +191,11 @@ GitLab、Gitea、Gogs 等托管可[配置 Git SSH](docs/deployment.md#git-reposi

## LoopForge Local

不想部署服务端?**LoopForge Local** 把内置交付工作流直接带进你正在用的编程助手:
> **旧版(Legacy)。** 已发布的 LoopForge Local(`loopforge-cli`)版本仍可安装。[Local 使用指南](docs/local/usage.zh-CN.md)介绍如何安装固定版本、继续使用既有工作流并保留产物。

```bash
# 在目标项目目录中执行,例如安装到 Claude Code
npx -y loopforge-cli@latest install claude
```

然后在 Claude Code 中运行 `/start-devflow "<你的需求>"`。

| 宿主 | 支持情况 |
| --- | --- |
| Claude Code · CodeBuddy · Codex · Cursor | Classic(默认)与 Portable 版 |
| Pi | Portable 版 |

各宿主的入口见[本地使用指南](docs/local/usage.zh-CN.md),版本差异见[版本说明](docs/local/editions.md),源码位于 [`local/`](local/)。Local 目前运行内置工作流;平台 SOP 导出后在本地独立执行是后续方向,尚未实现。
要在编码 Agent 中使用平台项目和 SOP,请[通过 MCP 将 CodeBuddy 接入 LoopForge 实例](docs/local/usage.zh-CN.md#通过-mcp-连接-loopforge)。Local 仍可在编码 Agent 中独立运行内置工作流,无需启动 LoopForge 服务端。

| | 平台版 | Local |
| | 平台版 | Local(旧版) |
| --- | --- | --- |
| 适合 | 团队共享对话工作区、SOP、审批与运行记录 | 个人开发者在 IDE / CLI 中使用 |
| 依赖 | Docker + Python 3 | Node.js 20+、Python 3.8+ 和一个编程助手 |
Expand Down Expand Up @@ -241,7 +228,7 @@ LoopForge 不替代它们,而是编排它们。每个 Agent 步骤和每轮对
| --- | --- |
| 部署、账号、执行机器与凭据 | [部署指南](docs/deployment.md) |
| 对话工作区、AI 定时任务与 Token 成本口径 | [对话工作区](docs/conversation-workspaces.md) · [AI 定时任务](docs/ai-scheduled-task-capabilities.md) · [Token 成本统计](docs/token-pricing.md) |
| 本地工作流的安装、使用与版本选择 | [LoopForge Local](docs/local/usage.zh-CN.md) · [版本差异](docs/local/editions.md) |
| 继续使用 Local 旧版工作流 | [LoopForge Local](docs/local/usage.zh-CN.md) · [版本差异](docs/local/editions.md) |
| 扩展平台或接入 HTTP / MCP API | [架构](docs/architecture.md) · [API 参考](docs/api/README.md) · [共享定时任务 API](docs/api/shared-schedules.md) |
| 参与前端开发 | [前端设计约定](design.md) |
| 功能覆盖与发布就绪情况 | [实测记录](docs/validation.md) · [验收矩阵](docs/testing/acceptance-matrix.md) · [发布评审](docs/release-readiness.md) |
Expand Down
57 changes: 34 additions & 23 deletions docs/local/usage.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,36 +2,45 @@

English | [简体中文](usage.zh-CN.md)

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](../deployment.md) for the platform.
> **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](../deployment.md).

1. Sign in to LoopForge and open **Access** (接入方式). Create a personal access token and select **CodeBuddy** for its MCP setup instructions.
2. Apply the user-level configuration in CodeBuddy and confirm that the `agentflow` server is connected in the MCP settings. Ask CodeBuddy to list your LoopForge projects to verify access.

See the [MCP API reference](../api/README.md#公共能力发现与-mcp) for the endpoint and available operations.

## Quick start

Requires Node.js 20+ and Python 3.8+. The commands below install the default Classic Edition; choose it if you are unsure.
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 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>"` |
| DeepSeek Harness | `npx -y loopforge-cli@latest skills install dsh` | `/devflow "<request>"` |
| Hermes Agent | `npx -y loopforge-cli@latest skills install hermes` then `hermes skills trust .` | `/devflow "<request>"` |
| CodeBuddy | `npx -y loopforge-cli@X.Y.Z install codebuddy` | `/start-devflow "<request>"` |
| Codex | `npx -y loopforge-cli@X.Y.Z install codex` | `$devflow-codex "<request>"` |
| Cursor | `npx -y loopforge-cli@X.Y.Z install cursor` | `/start-devflow "<request>"` |
| Claude Code | `npx -y loopforge-cli@X.Y.Z install claude` | `/start-devflow "<request>"` |
| DeepSeek Harness | `npx -y loopforge-cli@X.Y.Z skills install dsh` | `/devflow "<request>"` |
| Hermes Agent | `npx -y loopforge-cli@X.Y.Z skills install hermes` then `hermes skills trust .` | `/devflow "<request>"` |

For example, with Claude Code:

```bash
npx -y loopforge-cli@latest install claude
npx -y loopforge-cli@latest status claude
npx -y loopforge-cli@X.Y.Z install claude
npx -y loopforge-cli@X.Y.Z status claude
```

```text
/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:
Check any installation with `npx -y loopforge-cli@X.Y.Z status <agent>`. If installation or execution fails, diagnose the environment:

```bash
npx -y loopforge-cli@latest doctor
npx -y loopforge-cli@X.Y.Z doctor
```

Pi, DeepSeek Harness and Hermes Agent are supported through the [Portable Edition](#portable-edition). DSH has an optional [plugin](../../local/dsh-plugin/README.md) 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](../../local/hermes-plugin/README.md) for the same `/loopforge status`, `/loopforge result` and `/loopforge approve` controls.
Expand Down Expand Up @@ -131,26 +140,28 @@ For one-off code completion or a tiny, fully specified edit, using a coding agen

## Portable Edition

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`.
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 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>"` |
| DeepSeek Harness | `npx -y loopforge-cli@latest skills install dsh` | `/devflow "<request>"` |
| Hermes Agent | `npx -y loopforge-cli@latest skills install hermes`, then `hermes skills trust .` | `/devflow "<request>"` (optional plugin: `/loopforge`) |
| CodeBuddy | `npx -y loopforge-cli@X.Y.Z skills install codebuddy` | `/devflow "<request>"` |
| Codex | `npx -y loopforge-cli@X.Y.Z skills install codex` | `$devflow "<request>"` |
| Cursor | `npx -y loopforge-cli@X.Y.Z skills install cursor` | `/devflow "<request>"` |
| Claude Code | `npx -y loopforge-cli@X.Y.Z skills install claude` | `/devflow "<request>"` |
| Pi | `npx -y loopforge-cli@X.Y.Z skills install pi`, then `pi install npm:pi-subagents` | `/skill:devflow "<request>"` |
| DeepSeek Harness | `npx -y loopforge-cli@X.Y.Z skills install dsh` | `/devflow "<request>"` |
| Hermes Agent | `npx -y loopforge-cli@X.Y.Z skills install hermes`, then `hermes skills trust .` | `/devflow "<request>"` (optional plugin: `/loopforge`) |

See [Edition selection](editions.md) for the complete boundaries and directory layout.

## Update and uninstall

For ongoing use, install the CLI globally:
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.

```bash
npm install --global loopforge-cli
npm install --global loopforge-cli@X.Y.Z
```

Then maintain an installation with the same agent names as above (`codebuddy`, `codex`, `cursor`, `claude`, `pi`, `dsh`, and `hermes` for the Portable Edition):
Expand All @@ -169,7 +180,7 @@ 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:
To install from the source of a published release, check out its tag and run the following from the repository root.

```bash
pipx install ./local
Expand Down
Loading
Loading