ClankPipe

ClankPipe is a Bun CLI for collecting work from GitHub Issues, Jira Cloud, or QMD collections, then running Actions for each matching Item.

Define a Workspace that selects only the work you care about—for example, open GitHub Issues assigned to you with a ready-for-agent label. ClankPipe stores local copies, then runs the Actions you configured. The built-in Actions create Git worktrees and run shell commands.

ClankPipe provides the queue and action pipeline. It does not include an agent runtime.

Sources -> local Store -> configured Actions

Install

ClankPipe publishes platform archives in component releases named clankpipe-v<VERSION>.

ubi

Install a pinned release and select the clankpipe executable from its archive:

ubi --project zenobi-us/clankpipe \
  --tag clankpipe-v0.1.0-next.53.1 \
  --exe clankpipe

See ubi installation if ubi is not installed.

mise

Add the GitHub backend to mise.toml. The version prefix prevents latest from selecting releases for other components in this repository.

[tools]
"github:zenobi-us/clankpipe" = { version = "latest", version_prefix = "clankpipe-v" }

Then install it:

mise install

GitHub Issues quickstart

Authenticate GitHub CLI first. ClankPipe uses it as a credential helper:

gh auth login
clankpipe workspace init ./work.toml
clankpipe workspace edit ./work.toml # opens $EDITOR

Configure the Workspace:

[[sources]]
id = "github-assigned"

[sources.source]
uses = "@clankpipe/source-github"
mode = "issue"
query = "repo:OWNER/REPO is:open assignee:@me label:ready-for-agent"
limit = 50
status_map = { ready-for-agent = "ready" }

[sources.source.credentials]
helper = "gh auth token"

[[sources.actions]]
uses = "@clankpipe/action-run-cmd"

[sources.actions.with]
cmd = "echo 'launch your agent for {{ item.url }}'"

Replace OWNER/REPO with the repository to watch. The example Action is deliberately harmless: replace the echo command with your agent launcher when the dry run shows the expected Issues. ClankPipe runs that command through sh -c for each matching Item.

clankpipe doctor ./work.toml
clankpipe run ./work.toml --dry-run
clankpipe run ./work.toml --watch --interval 60s

A dry run collects and renders pending Actions without executing them or writing to the Store. run --watch repeats the Run until you stop it with Ctrl-C.

How ClankPipe fits together

• Workspace — TOML file containing Sources and their Actions.
• Source — GitHub Issues, Jira Cloud, or QMD collections selected by a query.
• Item — normalized local copy of one task-like record, including its raw source payload.
• Store — local append-only JSONL history of Item observations and Action attempts.
• Action — configured side effect, currently a shell command or Git worktree creation.
• Run — one pass that collects Items, updates the Store, and executes pending Actions.
• Watch Mode — repeated Runs for one Workspace.

The upstream tracker remains the source of truth. Successful Actions are recorded locally and skipped on later Runs unless their rendered inputs change.

Documentation

• CLI commands
• Workspaces and schema
• Sources, including GitHub Issues, Jira Cloud, and QMD
• Actions, including run command and create worktree
• Store layout and retry state
• Contributing and development setup