Skip to content

README.md

Latest commit

 

History

History
217 lines (152 loc) · 9.05 KB

README.md

File metadata and controls

217 lines (152 loc) · 9.05 KB
Raw

AgentFlow Logo

AgentFlow

Let your AI agents work 12 hours straight — then quietly blow everyone away

License: MIT AgentFlow Hub

中文 | English

Orchestrate complex, long-running tasks — module migrations, AI automation, deep code cleanup — using Cursor / OpenCode / Claude Code / Codex as swappable backends.

AgentFlow Projects

Pipeline Editor

Running Status

The Problem

Coding agents like Cursor, Claude Code, and Codex are great — until the task gets long.

1. Context window is a hard ceiling. A 10-minute task fits comfortably. A 10-hour migration? The model starts forgetting earlier steps, repeating work, or silently drifting off course. Context compression helps, but it's lossy — the agent no longer has the full picture.

2. Process reliability degrades with length. You tell the agent: "after step 1, ask me to confirm; after step 2, run tests." It works the first few times. Three hours in, the confirmation step gets compressed away and the agent just... skips it. This is the same class of problem that caused an AI to delete a user's emails — not malice, just lost context.

3. Markdown checklists aren't control flow. You can write a numbered plan in a prompt, but you can't express "loop until compilation passes" or "if tests fail, go back to step 3." Real workflows need real branches and loops — not a flat list that the model interprets however it wants.

AgentFlow fixes this by moving orchestration out of the context window. Workflows are defined as node graphs with explicit edges, loops, and conditionals. Each node runs in a fresh agent session with only its own inputs — no context to degrade. State is persisted to disk between nodes, so a 10-hour workflow is just a sequence of focused 10-minute tasks.

Features

  • Reuse your AI subscriptions — Cursor Pro, OpenCode (Alibaba Cloud, etc.), Claude Code, Codex; no need to purchase LLM API keys
  • Visual editor + AI Composer — drag-and-drop nodes or describe workflows in natural language
  • Persistent state — every node's I/O cached to disk (like Gradle task caching); resume from any failure point
  • Loop / branch / parallel — control_if, control_anyOne, control_toBool for real control flow
  • CI/CD ready — deterministic graphs, long-running, --machine-readable JSON event stream

Quick Start

Requirements: Node >= 18, one of: Cursor CLI (agent), OpenCode CLI, Claude Code, or Codex CLI

# Install
npm install -g @fieldwangai/agentflow

# Launch Web UI (port 8765)
agentflow ui

# Or run a flow directly
agentflow apply <FlowName>

From source: git clone → npm install → npm link.

AgentFlow Hub

Browse, download and share community-built workflows at agentflow-hub.com.

# Browse flows from the command line
agentflow list-remote

# Download a flow
agentflow download <slug>

# Publish your flow to the Hub
agentflow login
agentflow publish <FlowName> --tags "migration,review"

Creating Flows

Option A: Visual Editor

In the Web UI — create pipeline → drag nodes from palette → connect edges → save.

Option B: AI Composer (recommended)

Open the right-side Composer panel and describe what you need:

Create a code review flow:
1. Scan the codebase for issues
2. Auto-fix issues
3. Re-check
4. Loop until all pass

Composer auto-detects loop patterns and generates the correct control-flow nodes. Complex flows are built in three phases: topology → node details → wiring & validation (auto-repairs up to 5 times).

Running & Recovery

# Execute
agentflow apply <FlowName>

# Check status
agentflow run-status <FlowName> <uuid>

# Resume from failure
agentflow resume <FlowName> <uuid>

# Retry one node
agentflow replay <FlowName> <uuid> <instanceId>

# View agent reasoning
agentflow extract-thinking <FlowName> <uuid>

Skills

AgentFlow provides specialized skills for common operations:

Skill Description
agentflow-flow-add-instances Add new nodes to flow.yaml with proper YAML structure, connection design, and positioning
agentflow-flow-edit-node-fields Edit allowed fields in existing nodes (label, body, role, input/output values) without breaking topology
agentflow-flow-sync-ui Sync flow.yaml changes to Web UI canvas after saving to disk
nestjs-route-order-debug Debug NestJS route conflicts between parameter routes (:id) and concrete routes

Skills are automatically loaded when relevant tasks are detected, providing domain-specific instructions and workflows.

Tutorials

CLI Reference

Command Description
list List all pipelines
ui Start Web UI
apply Execute flow
validate Validate flow structure
resume Resume from breakpoint
replay Retry a single node
run-status View execution status
extract-thinking Extract agent thinking process

Options

Flag Description
--workspace-root <path> Workspace root directory
--dry-run Preview ready nodes without execution
--model <name> Override model. Use prefixes such as opencode:<model>, claude-code:<model>, codex:<model>, or api:<provider>/<model> to switch backends
--parallel Parallel execution for independent nodes
--machine-readable JSON event stream (for UI/CI integration)
--lang <code> Language (zh / en)

Environment Variables

Variable Default Description
CURSOR_AGENT_CMD agent Cursor CLI command
CURSOR_AGENT_MODEL — Default model
OPENCODE_CMD opencode OpenCode CLI command
CLAUDE_CODE_CMD claude Claude Code CLI command
AGENTFLOW_CLAUDE_CODE_BYPASS_PERMISSIONS 1 Pass --dangerously-skip-permissions to Claude Code; set 0 for interactive approval
AGENTFLOW_CLAUDE_CODE_STDERR_INHERIT 0 Forward Claude Code stderr directly to terminal for debugging
CODEX_CMD codex Codex CLI command
CODEX_MODEL — Default Codex model when no explicit codex:<model> is set
AGENTFLOW_CODEX_SANDBOX workspace-write Codex sandbox mode passed to codex exec
AGENTFLOW_CODEX_APPROVAL never Codex approval policy passed before exec
AGENTFLOW_CODEX_DANGER 0 Set 1 to pass --dangerously-bypass-approvals-and-sandbox to Codex
AGENTFLOW_CODEX_SKIP_GIT_CHECK auto Skip Codex git-repo check automatically when the execution directory has no .git ancestor; set 1/0 to force
AGENTFLOW_CODEX_IGNORE_USER_CONFIG 1 Run Codex with --ignore-user-config so AgentFlow jobs only use the MCP/config overrides AgentFlow passes in; set 0 to also load the user's Codex config
AGENTFLOW_CODEX_STDERR_INHERIT 0 Forward Codex stderr directly to terminal for debugging
AGENTFLOW_HOME ~/agentflow User data directory

Codex Backend

Use --model codex:<model> or select a Codex model in the Web UI to run Composer or agent nodes through codex exec. Run codex login first, then refresh model lists with agentflow update-model-lists so the UI can show Codex models.

Composer reuses the MCP servers managed in AgentFlow's MCP page by translating Cursor MCP config into Codex -c mcp_servers... overrides for the current process. Stdio MCP private env values are passed through the Codex child process environment; HTTP Authorization: Bearer ... headers are converted to bearer_token_env_var.

The MCP page shows a backend compatibility matrix for each server. Codex is marked partial when a server relies on features Codex cannot express exactly, such as arbitrary HTTP headers or URL-level env values.

Directory Layout

~/agentflow/                          # User data (pipelines, agents, config)
<workspace>/.workspace/agentflow/
  ├── pipelines/<flowId>/             # Project-local pipeline copies
  ├── nodes/                          # Custom node definitions
  └── runBuild/<flowId>/<uuid>/       # Run artifacts & per-node status

i18n

  • CLI: --lang flag or LANG env
  • Web UI: auto-detects browser language
  • Agent prompts: agents/<lang>/ directory

Supported: zh (中文), en (English)

Contributing

See CONTRIBUTING.en.md.

License

MIT