vichu-flow

README

VichuFlow

Observable, verifiable agentic workflow orchestration for real software tasks.

VichuFlow is an open-source, cross-platform runtime that runs workflows as persistent state machines over any repository. It coordinates existing coding agents from the outside, and decides stage transitions from evidence it verifies itself — running your tests, lint, and typecheck — never from the agent's own say-so.

Adapter status: VichuFlow ships the claude-code, codex, shell, and fake adapters. More agents (OpenCode, Gemini CLI) are planned through the same contract.

Why VichuFlow?

Coding agents are great at writing code and terrible at proving it works. They say "all done ✅" and move on. Other tools either run agents inside the editor (no external record, no resume after a crash) or fan out parallel agents with a diff UI (no workflow, no verified gates). VichuFlow is the missing piece: an external runtime that doesn't trust the agent.

• It can't lie to you. A stage only advances when VichuFlow runs your tests itself and sees them pass. An agent that claims success without a green gate is blocked, with the evidence on disk.
• It survives crashes. A run is plain files (state.json + events.ndjson). Kill it, reboot, vichu resume — it picks up where it stopped.
• It won't wreck your work. Workspace snapshots (Git or filesystem), per-worker mutation tracking, a command policy that blocks rm -rf/git push/installs before they run, and automatic rollback if a check touches your files.
• It won't burn your budget. Hard limits on wall-clock, cost, and tokens (summed across every agent) stop runaway loops and surprise bills.
• It's vendor-neutral. Implement with one agent, review with another — or none, using plain shell commands.

VichuFlow coordinates agents; it does not replace them or write code itself.

Three ideas hold it together:

1. External, observable runtime. Every run is flat files on disk (state.json + events.ndjson); the CLI, TUI, and web are just views. A run survives a crash, resumes, and is fully auditable.
2. Verified evidence. VichuFlow runs your test/lint/typecheck commands itself, captures exit code and output, and only that verdict authorizes a transition. An agent that claims success without passing the gate does not advance.
3. Cross-vendor by design. Implement with one agent and review with another (or just one). The adapter contract is the heart of the architecture.

Status

The latest release is shown by the Release badge above; the version is tracked by git tags and CHANGELOG.md, not hardcoded here. The current build ships:

• vichu init [--template], new, doctor, run, status [--watch], resume, cancel, adapters, config
• Project templates (vichu new <name> --template go|node|python|rust|empty, or vichu init --template): scaffold a runnable project with a real gate, so the first run completes from scratch — Git optional
• Persistent runtime: atomic state.json, append-only events.ndjson, heartbeat locks with orphan reclaim, cooperative cancel
• quick workflow (explore → implement → verify) and review workflow (an adversarial review → auto-fix loop that branches on a structured, persisted verdict)
• Adapters: claude-code and codex (headless, streamed events, session resume), shell, and fake (deterministic, for CI)
• Workspace providers — git or filesystem (workspace.provider: auto), so runs work with or without a VCS (see below)
• Verified gates, workspace snapshots with content fingerprints, per-worker mutation tracking, and enforced mutation policy (sensitive files block, read-only stages enforced)

Works with or without Git (v0.3). workspace.provider: auto | git | filesystem (default auto): on a Git repo VichuFlow uses Git as the baseline; in any other folder it snapshots the tree under .vichu/ — so change detection, mutation tracking, and rollback work the same way, no VCS required. Git stays the recommended path for Git repos; it is no longer a requirement of the runtime.

The architecture is documented in Concepts and the runtime format.

Install

VichuFlow is a single self-contained binary — you do not need Go (or any runtime) to use it. It works on any project: Node, Python, Rust, Go, mixed.

1. Download a prebuilt binary for your OS/arch (macOS, Linux, Windows) from the Releases page, unpack it, and put vichu on your PATH. That's it.

2. Package managers (Homebrew / Scoop / winget) are planned — see the roadmap.

3. For Go developers, you can also install or build from source:

go install github.com/corteshvictor/vichu-flow/cmd/vichu@latest   # Go 1.26+
# or:  git clone … && cd vichu-flow && go build -o vichu ./cmd/vichu

VichuFlow itself needs no runtime — no Go, no Git. Git is recommended (the git provider is efficient and ties into your history) but optional: in a non-Git folder the filesystem provider gives the same undo guarantees. The verification commands you configure (test/lint/typecheck) do run with your project's own toolchain: a Python gate needs Python, a Node gate needs Node, cargo test needs Rust, and so on. VichuFlow runs your commands; it doesn't bundle the toolchains they call.

Quick start

New project — scaffold runnable source plus a real gate, then run:

vichu new my-app --template go     # or: empty | node | python | rust
cd my-app
vichu run "add a sum function"     # → completed (gate: go test ./...)
vichu status                       # inspect the latest run

Existing project — initialize in place:

cd your-project                    # a Git repo, or any folder — Git is optional
vichu init                         # detect stack, write vichu.yaml, ignore .vichu/
vichu run "add a hello function"   # (or `vichu init --template node` to seed one)

Each template seeds minimal source plus a real gate using the stack's built-in test runner (no package install), so the very first run completes — with or without Git. By default a fresh project uses the fake adapter, so vichu run works with no agent CLI installed.

A run reaches completed only when a verification gate passes: vichu init wires up the gates it detects for your stack (go test, npm test, …). An empty folder has no gate, so the run honestly blocks at verify instead of faking success — which is exactly why vichu new / --template seed one.

To use a real agent, install the Claude Code CLI and set the agents block in vichu.yaml:

agents:
  default:
    provider: claude-code
    model: sonnet

Then vichu run "your task" runs the agent headless and gates its work against your tests. Full walkthrough: Getting started.

Cost: VichuFlow itself is free and open source (MIT) and collects no telemetry. The agents it coordinates are billed by their own providers (e.g. Anthropic for Claude Code) — VichuFlow's per-run cost and token budgets help you cap that spend. The shell and fake adapters cost nothing.

Documentation

• Getting started
• Concepts
• Configuration
• Runtime format

Development

Run all commands below from the project root (the directory containing go.mod). The ./... suffix means "this module and every package under it".

These need only the Go toolchain:

gofmt -l .           # formatting check (no output = clean)
go vet ./...         # suspicious-construct check
go test -race ./...  # test suite with the race detector (as CI does)
go mod verify        # dependency integrity

Linting and vulnerability scanning run with pinned versions via go run — nothing needs to be installed as a binary or be on your PATH (the first run may download the tool's modules into the module cache):

go run github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2 run
go run golang.org/x/vuln/cmd/govulncheck@v1.3.0 ./...

Or run the whole gate at once with Task:

task check   # gofmt + vet + test -race + lint + vuln

Installing the tools as binaries is faster than go run. After go install ...@version, they land in $(go env GOPATH)/bin — make sure that directory is on your PATH (e.g. add export PATH="$PATH:$(go env GOPATH)/bin" to your shell profile), or call them by full path.

Contributing

Issues and PRs are welcome. We use Conventional Commits (they drive automated versioning and the changelog) — see CONTRIBUTING.md. Releases are automated: how that works is in RELEASING.md, and shipped changes are tracked in CHANGELOG.md.

License

MIT — see LICENSE.