Zing Forum

Reading

VichuFlow: An Observable and Verifiable Workflow Orchestration Engine for Agents

VichuFlow is an open-source cross-platform runtime that runs workflows as persistent state machines, coordinates external coding agents, and decides phase transitions based on self-verified evidence, never blindly trusting agents' self-reports.

agentic workflowobservableverifiableorchestrationcoding agentstate machinecross-platform
Published 2026-06-14 09:15Recent activity 2026-06-14 09:23Estimated read 5 min
VichuFlow: An Observable and Verifiable Workflow Orchestration Engine for Agents
1

Section 01

Introduction / Main Floor: VichuFlow: An Observable and Verifiable Workflow Orchestration Engine for Agents

VichuFlow is an open-source cross-platform runtime that runs workflows as persistent state machines, coordinates external coding agents, and decides phase transitions based on self-verified evidence, never blindly trusting agents' self-reports.

2

Section 02

Original Author and Source


3

Section 03

Background: Trust Crisis of Coding Agents

Current AI coding assistants and agents perform well in code generation, but their code correctness verification is worrying. They often claim "Done ✅" and move to the next task, but fail to provide reliable evidence that the code actually works.

Existing tools face a dilemma: either let agents run inside the editor (no external records, can't recover after crashes) or start multiple agents in parallel to show differences (no workflow concept, no verification checkpoints). VichuFlow was born to solve this pain point—it's an external runtime that doesn't trust agents.


4

Section 04

1. External Observable Runtime

Each run of VichuFlow is pure text files on disk (state.json + events.ndjson). CLI, TUI, and Web interfaces are just views of these files. This design brings key advantages:

  • Crash Recovery: Runs can survive crashes and resume from breakpoints via the vichu resume command
  • Full Auditability: All events and state changes are recorded for post-hoc analysis
  • Tool Agnostic: Not tied to any specific editor or IDE, usable in any environment
5

Section 05

2. Verification-Driven Evidence

VichuFlow runs commands like tests, code checks, type checks itself, captures exit codes and outputs—only these verification results can authorize phase transitions. If an agent claims success but fails the verification checkpoint, it can't proceed. This "show, don't tell" philosophy ensures code quality.

6

Section 06

3. Cross-Vendor Design

VichuFlow isn't tied to a single agent provider. You can implement features with one agent, review with another—or not use agents at all, just ordinary shell commands. Currently supported adapters include:

  • claude-code: Anthropic Claude Code CLI
  • codex: OpenAI Codex CLI
  • shell: Ordinary shell commands
  • fake: Deterministic simulation (for CI testing)

7

Section 07

Anti-Deception Mechanisms

VichuFlow prevents agents from "lying" through the following means:

  • Phases can only progress after VichuFlow runs tests itself and sees them pass
  • Agents that claim success but fail the green checkpoints are blocked, with evidence saved on disk
  • Verification commands (test/lint/typecheck) are executed by the project's own toolchain; VichuFlow only handles coordination
8

Section 08

Workspace Protection

To prevent agents from damaging work results, VichuFlow provides multi-layer protection:

  • Workspace Snapshots: Based on Git or file system, create snapshots before each run
  • Change Tracking: Track file changes by worker to identify unexpected modifications
  • Command Policies: Intercept dangerous operations like rm -rf, git push, installation commands before execution
  • Automatic Rollback: If verification checks touch your files, automatically roll back to a safe state