Workflows
A phase state machine that runs agents automatically — from your terminal, or triggered by a labeled GitHub issue.
Overview
A workflow, defined at .claudin/workflows/<name>.md, is a linear phase state machine — backlog → development → code-review → test → done by default. Each phase runs one or more agents in parallel, referencing the same .claudin/agents/*.md definitions used by the plain Agent tool or a built-in. A main orchestrator agent decides, after each phase, whether to advance, refine the current phase, or handback to an earlier one. Because each agent definition sets its own model, a single workflow can mix a cheap model for one phase with a stronger one for another — across providers, not just within one.
The underlying tools — Workflow, ListWorkflows, WorkflowStatus — are available to the model directly, the same way Agent is.
The /workflows TUI
/workflows opens the same kind of interactive surface as /agents: a Library tab to create or edit .claudin/workflows/*.md definitions, and a way to watch a run in progress.
Running one locally
claudin workflow run <name> --task "<text>"| Flag | Default | Meaning |
|---|---|---|
--task <text> | required | The task seeding the workflow. |
--worktree | off | Run in an isolated git worktree instead of the working tree. |
--pr | off | On success: commit, push, and open a PR with gh. |
--base <branch> | remote default | PR base branch. |
--report <file> | temp file | Where to write the markdown run report. |
Exit codes: 0 reached done, 1 finished without reaching it (or threw), 2 unknown or invalid workflow (bad structure, or references an unknown agent), or worktree-creation failure.
Triggering from external events
claudin workflow watch polls a source and spawns a workflow run … --worktree --pr for each new trigger, one at a time, each in its own isolated worktree. This is outbound polling only — there's no inbound webhook server and no open port.
claudin workflow watch --workflow <name> [flags]| Flag | Default | Meaning |
|---|---|---|
--source <source> | github | github / url / command |
--label <label> | claudin | (github) issue label that triggers a run. |
--url <url> | — | (url) endpoint to poll. |
--command <cmd> | — | (command) local shell command to poll, reads stdout. |
--match <regex> | — | Only trigger when title+body matches. |
--interval <seconds> | 30 | Poll interval, floored at 5s. |
--base <branch> | remote default | Passed through to each run. |
| Source | Polls | Reports back |
|---|---|---|
github | gh issue list --label <label> --state open | Comments the PR URL on the issue. |
url | GET <url> | — |
command | Runs <cmd>, reads stdout | — |
GitHub auth goes through your local gh CLI — there's no separate token to configure, just make sure gh auth status is green. Dedup/processed-trigger state is written to .claudin/workflow-watch-state.json (gitignored), so restarting the watcher doesn't replay old triggers.
claudin workflow run dev-flow --task "Add a --json flag to the status command" --worktree --pr
claudin workflow watch --workflow dev-flow --label claudin --interval 30
claudin workflow watch --workflow dev-flow --source url --url https://example.com/queue.json
claudin workflow watch --workflow dev-flow --source command --command './scripts/next-task.sh' --match '^READY:'Scope
What's covered today: local polling across the three sources above, --match filtering, per-job worktree isolation, PR-out plus issue-comment report-back, deterministic exit codes, atomic dedup state. Deliberately out of scope: an inbound webhook server, parallel/multi-tenant jobs, non-GitHub forges with report-back, sandbox enforcement, and a committed GitHub Action template.
Differences from Claude Code
Claude Code's automation path here is GitHub Actions — a committed workflow YAML, a hosted runner, triggered by an @claude mention. Claudin's watcher runs entirely on a machine you control, with no YAML and no runner: claudin workflow watch is a local process polling a source you choose (GitHub issues by label, a URL, or a command), and every run it spawns is isolated to its own git worktree.