ClankerFlow

clankerflow is a Rust CLI, drop-in OpenCode framework that allows you to run deterministic AI workflows in your repository using readable TypeScript. Get the full power of OpenCode with the full power of a programming language. Workflows can be containerized for yolo mode or run directly on your machine.

Workflows are authored in TypeScript and executed by a managed Node runtime, while Rust owns orchestration, state, and OpenCode lifecycle calls.

Warning: clankerflow is currently in beta. Expect rough edges, breaking changes, and fast iteration.

Example Workflows

See more example workflows in our example document here

What it does

• Initializes a project-local workflow scaffold under .agents/.
• Runs workflows on host or in a containment container.
• Persists workflow runs/events in SQLite.
• Integrates with OpenCode sessions from Rust (run/messages/events/cancel/command).
• Opens the OpenCode web UI for the current project when you start a workflow.

Requirements

• Rust toolchain (edition 2024 compatible).
• Node + npm (used during clankerflow init to install runtime dependencies).
• Docker (only if you use containment mode).
• OpenCode CLI (opencode) installed and on PATH (workflow runs auto-start opencode serve on 127.0.0.1:4096).

Install and build

As Crate from crates.io:

cargo install clankerflow

From source:

cargo install --git https://github.com/AlextheYounga/clankerflow.git clankerflow

After build, the CLI binary is named clankerflow.

Quick start

From the repository you want to automate:

clankerflow init

Then run a workflow:

# Run the duos.js workflow
clankerflow work duos

clankerflow work also opens the OpenCode manage URL in your browser automatically.

Workflows stay user-editable in .agents/workflows/*.ts and import the runtime surface as a normal module:

import type { WorkflowMeta, WorkflowContext, WorkflowTools } from "clankerflow";

CLI commands

• clankerflow init - initialize or refresh .agents scaffold.
• clankerflow work <name> - run workflow .agents/workflows/<name>.ts.
  • --env host|container
  • --yolo
  • --containment (shorthand for container + yolo)
• clankerflow manage - open OpenCode sessions UI for current project.
• clankerflow make ticket - create a new ticket markdown file.
• clankerflow make worktree <branch> - create a git worktree under .agents/.worktrees/<branch>.
• clankerflow containment up|down - start/stop containment container.

Containment mode

Containment runs workflows inside a Docker container so agents can operate with full autonomy (--yolo) without touching your host filesystem directly.

# Start the container (idempotent — builds on first run)
clankerflow containment up

# Run a workflow inside the container with safety checks disabled
clankerflow work duos --containment

# Or use the flags separately
clankerflow work duos --env container --yolo

# Stop and remove the container when done
clankerflow containment down

Each project gets its own persistent container named agent-{codebase_id}, derived from your project path. The container:

• Bind-mounts your project root as /workspace (read-write).
• Mounts ~/.config/opencode read-only so the agent can reach your OpenCode server.
• Rewrites 127.0.0.1 URLs to host.docker.internal automatically.
• Ships with git, build-essential, gitleaks, and the OpenCode CLI pre-installed.
• Stays alive between runs (restart: unless-stopped) so subsequent workflows start instantly.

The Dockerfile and compose file are scaffolded into .agents/.clankerflow/docker/ during init. Since .agents/.clankerflow/ is gitignored, treat these as local runtime overrides.

Workflows can check their environment at runtime via ctx.runtimeEnv and ctx.yolo:

async function careful(ctx, { agent }) {
  await agent.run({
    title: ctx.yolo ? "Cowboy" : "Engineer",
    prompt: ctx.yolo
      ? "You have full autonomy. Ship it."
      : "Proceed carefully and explain each step.",
  });
}

Workflow runtime notes

• Workflow files live at .agents/workflows/*.ts.
• Runtime helpers and package metadata are scaffolded under .agents/.clankerflow/lib.
• clankerflow init runs npm install inside .agents/.clankerflow/lib.
• .agents/.clankerflow/ is gitignored and treated as local runtime state.
• Rust and Node communicate over structured JSON IPC.
• Run monitoring is done in the OpenCode web UI.

More short examples live in docs/examples.md.

Agent API (workflow side)

Current workflow agent tool surface includes:

• agent.run(...)
• agent.command(...)
• agent.messages(sessionId)
• agent.events(sessionId)
• agent.cancel(sessionId)

Example:

const started = await agent.run({ prompt: "Draft implementation plan" });

if (started.session_id) {
  await agent.command({
    session_id: started.session_id,
    command: "/review",
  });
}

Development

The embedded scaffold now comes directly from kit/. Update files there when you want to change what clankerflow init writes into .agents/.

Key source-of-truth paths:

• kit/ mirrors the emitted .agents/ scaffold.
• kit/.clankerflow/lib/ is the hidden runtime package installed during init.
• runtime/ still exists for runtime-focused development and tests, but kit/ is what gets embedded into the binary.

Run Rust tests:

cargo test

Run runtime tests:

cd kit/.clankerflow/lib
npm test