npm install -g flowdeck

Human↔AI collaboration
via MARKDOWN files.

You write tasks. Claude does them. Git tracks the conversation. No plugins, no dashboards — just files and commits.

Get started View on GitHub
~/my-project
$npm install -g flowdeck
$flowdeck init
✓ templates — GitHub (7/7 templates)
✓ .flowdeck/ initialized
# add a task to .flowdeck/start/TODO.md, then:
$flowdeck send -m "add first task"
✓ Committed: "add first task"
⠹ TodoWrite(.flowdeck/start/TODO.md)
⠸ Bash(git commit -m "mark task done")
✓ done
How it works

A shared board, two inboxes.

Every folder under .flowdeck/ is a work area with its own TODO.md. Tasks for Claude go under ## BOT. Tasks that need you go under ## HUMAN.

.flowdeck/start/TODO.md BOT
## BOT
Add a README to this project
wrote README.md with install + usage
Set up CI with GitHub Actions
push to main should run tests
.flowdeck/start/TODO.md HUMAN
## HUMAN
Confirm the deploy target
AWS or Fly.io? affects the CI config
Add NPM_TOKEN to repo secrets
needed to publish the package
01

Init your project

Run flowdeck init inside any project directory. It creates .flowdeck/ with an AGENT.md protocol, a root TODO.md, a start/ work area, and a curated set of mdblu templates.

02

Write tasks for Claude

Open .flowdeck/start/TODO.md and add unchecked items under ## BOT. One task per line. Add a note below with > if context helps.

03

Hand off with flowdeck send

Run flowdeck send -m "what you just did". flowdeck commits your changes and invokes Claude Code with the diff and your AGENT.md. Claude picks up the tasks, does the work, marks them [x], and commits.

04

Review, repeat

Pull Claude's commit. Check ## HUMAN for anything it needs from you. Add more tasks. Run flowdeck send again. Git is the full history of the conversation.

Design

No new primitives.

flowdeck works with tools you already use.

📄

Plain Markdown

Tasks live in TODO.md files. Readable, diffable, git-friendly. No proprietary format.

🔀

Git is the log

Every human→Claude and Claude→human exchange is a commit. git log is your conversation history.

📋

AGENT.md protocol

Edit .flowdeck/AGENT.md to change how Claude behaves — focus, style, commit conventions.

📦

mdblu templates

Ships with SPEC, MISSION, ADR, and more. Run mdblu get --all to pull the full library.

Commands

Two commands.

That's the whole CLI.

flowdeck init
Create .flowdeck/ scaffold in the current directory. Fetches mdblu templates from GitHub or a local .mdblu/ if present.
flowdeck send [-m "message"]
Stage and commit (if -m is given), then hand off to Claude Code. Passes the diff and AGENT.md as the prompt.
Install

Get started in 30 seconds.

Requires Node.js ≥ 18 and Claude Code.

$npm install -g flowdeck
$cd your-project
$flowdeck init