vichu-flow

README

VichuFlow

An installable, verifiable agentic workflow for your coding assistant.

VichuFlow installs into the coding agent you already use (Claude Code today) and turns a natural-language request into a verified run — a persistent state machine over your repository. You talk to your agent; VichuFlow orchestrates, delegating the coding to native subagents and deciding every stage transition from evidence it verifies itself — running your tests, lint, and typecheck — never from the agent's own say-so. The vichu binary is the kernel/verifier; you drive it from inside your agent (or headless with vichu exec for CI).

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 run only completes when VichuFlow runs your tests itself and the verify gate passes; intermediate stages advance only on kernel-validated evidence — a mutation audit, an artifact's provenance, a structured review verdict — never the agent's say-so. An agent that claims success without that evidence is blocked, with the proof on disk.
• It survives crashes. A run is plain files (state.json + events.ndjson). Kill it, reboot, and resume from where it stopped: vichu run resume <id> reopens and re-validates the run so your host keeps driving it, or vichu exec resume <id> continues it headless.
• It won't wreck your work. Workspace snapshots (Git or filesystem), per-worker mutation tracking, and automatic rollback if a check touches your files. When VichuFlow runs commands itself (gates, shell workers, the headless claude-code/codex adapters), a command policy blocks rm -rf/git push/installs before they run. In host-first native mode the host (Claude Code) runs its own subagents, so preventive control belongs to the host; the kernel's guarantee is that it audits every mutation and blocks the run from advancing on a violation — disallowed changes can't move the run forward.
• It won't burn your budget. Hard limits on agent invocations and wall-clock always apply; cost and token caps apply per dimension whenever the agent reports it — claude-code reports both, codex reports tokens but not USD cost, shell reports neither, and a native host reports whatever it exposes. Together they stop runaway loops and surprise bills (see the usage matrix in configuration.md).
• 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 is a view today, with a TUI and web dashboard planned on the same data. 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:

• Host packs (vichu init --host claude-code): install the orchestrator skill + native subagents into your coding agent, then drive verified runs by talking to it. The kernel owns state and gates; the host runs the agents.
• Host-first kernel commands the pack drives: run start · worker start/complete · review complete · stage close · run resume · status --json · observe — transactional, idempotent (--op-id), single-writer.
• vichu init [--template], new, doctor, exec (headless fallback), status [--watch], 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
• Workflows: sdd (explore → propose → plan → implement → review → (approved: verify, needs_fixes: fix → review), with allowlisted proposal/plan artifacts and TDD-intent enforcement), review (adversarial review → auto-fix loop), and quick
• 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

Install the host pack and talk to your agent. VichuFlow installs into the coding agent you already use (Claude Code today); you describe the task in natural language and it orchestrates a verified run — the kernel owns the state, runs the gates, and decides every transition.

cd your-project                       # a Git repo, or any folder — Git is optional
vichu init --host claude-code         # install the orchestrator skill + subagents
# then, inside Claude Code:
#   "implement password reset using sdd"
#   "fix the failing login test"
#   "continue the run"

The orchestrator drives the run through the kernel's transactional commands — delegating the coding to native subagents and letting the kernel verify every stage against your real tests/lint/typecheck. The workflow sdd (explore → propose → plan → implement → review → (approved: verify, needs_fixes: fix → review)) is spec-driven; quick (explore → implement → verify) is for small changes; review adds an adversarial review → auto-fix loop on top of quick. Observe any run with vichu status <id> or vichu observe <id>.

Starting from nothing? Scaffold a runnable project (source + a real gate) so the first run completes with no manual config:

vichu new my-app --template go        # or: empty | node | python | rust
cd my-app && vichu init --host claude-code

Headless / CI (fallback). Without a host pack, run a whole workflow from the terminal with vichu exec:

vichu exec "add a sum function"       # → completed (gate: go test ./...)

vichu exec runs the agent headless and gates its work against your tests. (vichu run "task" is a deprecated alias for vichu exec.) A fresh project uses the fake adapter, so exec works with no agent CLI installed; a run reaches completed only when a verification gate passes. 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.