The monoban guide

## 00 · the big picture

Start here

monoban is a kanban board you drive with the keyboard, from the browser or your terminal, and that coding agents work on too. This guide goes through each part in the order you'll meet it and shows how they connect. You can try most of it in the live demo as you read: nothing there is saved.

browserch. 01 · 02monoban.devPlan and organise with the keyboard.

terminalch. 03$ monobanAdd, start and finish tasks from your repository.

agentsch. 04 · 05your coding agentsTurn plans into tasks, and tasks into pull requests.

your boardone set of projects and tasks, saved as you go

Six words to know

project: A board of its own, with a short key like SHOP. Every task in it is named after it.
column: A stage the work goes through. New projects get Backlog, To do, In progress and Done.
task: A title and a Markdown description, named like SHOP-14. Tags, links, a day, comments.
tag: A label like bug or phase-1, kept to one project or shared by all of them.
runner: monoban runner, running in a terminal on your machine: it takes the tasks you hand to agents.
run: One go of an agent at a task: its steps, what it's doing now, and the pull request it opens.

Where to start

I want a calm board for my workRead 01 and 02. Ten minutes, and the live demo to try it in. →
I live in the terminal03 sets up the CLI and shows the everyday loop. →
I work with coding agents04 and 05: agents that plan on the board, and agents that do the tasks. →

next01 · The board →

## 01 · projects, columns, tasks

The board

A project is a board: columns left to right, tasks top to bottom. That's the whole model. Every action on it is one key away, and every change saves in the background while you keep going.

Your first board in a minute

Sign in
With Google, with your email and password, or ask for a one-time link by email instead. Google works for an account with the same address. No password yet? forgot it? on the sign-in page emails you a link to choose one, and Settings › Sign-in changes it. A new password doesn't sign out the CLI or end personal tokens, so if any are left you're asked whether to keep or revoke them.
Make a project
Give it a name. It starts with Backlog, To do, In progress and Done, and you can rename, reorder or add columns later. Its key (SHOP) names every task in it: SHOP-1, SHOP-2…
Add tasks with n
Type a title and press ↵. The input stays open for the next one, so you can empty your head in one go. esc when you're done.
Move around, move tasks
j k select a task, h l change column (arrows work too). Add ⇧ to carry the task with you: ⇧→ moves it to the next column, ⇧↑ reorders it, and ⌘⇧↑ sends it to the top of its column (⌘⇧↓: the bottom; the task's panel has a button too). Dragging works as well.
Open one with ↵
It opens beside the board, like a tab in your editor. j and k keep walking through tasks with it open, z widens it, esc closes it.

Inside a task

The description is Markdown. Lines starting with - [ ] are a checklist, and the card shows how far along it is ([2/5]). ⇥ indents the lines you select and ⇧⇥ takes the indent back off, here and in the notes. Around it, a key each:

key	what it does
`t`	tag it: type to find a tag, or a new name to make one
`d`	plan it for a day (next chapter)
`a`	attach a link: a pull request, an issue, any page
`p`	open its pull request
`P`	mark its pull request open, draft, merged or closed by hand (the CLI reads it from GitHub)
`y`	its history: what changed, when, and whether from the web or the CLI
`s`	its comments
`R`	hand it to a coding agent (chapter 05)

Keep it tidy

`/`	filter the board; `#bug` shows only one tag
`#`	the tags next to the filter: tick some to show only the tasks with all of them
`xu`	delete, and undo. No “are you sure?”: undo is one key away
`e`	archive a done task. Done tasks archive themselves after the days you set in the project's settings
`A`	the project's archive: what's done and what won't be, the last archived first, by month. Search it, open a task with `↵`, put it back where it was with `r`. A column's `3 archived` opens it too
`E`	won't do: archive a task that isn't done, saying why. The archive shows why, and so does its history
`spacem`	mark tasks (or `⇧`-click them), then move them all to another project; `esc` unmarks. One task moves from `⌘K`: “move to project”
`r`	rename the column. A column can have a limit, and goes amber past it
`N`	the project's notes: one scratch file for links, decisions, commands. B goes back

next02 · Plan your days →

## 02 · dates and Today

Plan your days

A board tells you where everything stands. Today tells you what you meant to do now, across every project, so nothing planned slips through.

Give a task a day with d
Pick today or tomorrow, or type one: fri, +3, oct 12. The card shows the day, and turns amber when it's gone by and the task isn't done.
Open Today with T
Late tasks first, then today's, from every project. It's also where the app opens. [ and ] step through the days; the palette shows the next 7.
Work through it
↵ opens a task, c marks it done, d moves it to another day. Nothing to reschedule by hand: what you didn't finish waits for you at the top.

next03 · The terminal →

## 03 · the monoban CLI

The terminal

The monoban command works on the same board as the browser. Use it from the repository you're in: note the bug you just found, start a task on its own branch, close it when the pull request lands. It's also how coding agents read and write your board.

Install it

brew install thiagodmont/tap/monoban

npm install -g monoban

Homebrew installs a standalone binary for macOS and Linux, completions included (no Node needed). npm needs Node 22.12 or newer.

Set it up once

monoban login
It opens your browser to approve the sign-in. Over SSH, monoban login --device gives you a code to type instead. Each new sign-in is emailed to you, and Settings signs out any computer.
monoban link SHOP
Run it in your clone. From then on, commands there use project SHOP, and the project knows its GitHub repository. Elsewhere, -p SHOP picks the project.
monoban doctor
Checks this machine: your version, the sign-in, git and gh, and the coding agents. Whatever is missing, it says how to fix.

The everyday loop

zsh — ~/code/shop

$ monoban add "Fix the flaky checkout test" -t bug  # SHOP-14, at the end of the first column$ monoban list  # the board, column by column$ monoban start SHOP-14  # checks out shop-14-fix-the-flaky-checkout-test, moves it to In progress# …work, commit, gh pr create…$ monoban attach --pr  # this branch's pull request, on the card$ monoban done SHOP-14  # and it's in Done

More you can do

command	what it does
`show SHOP-14`	one task in full
`today`	what's planned, in every project, late first
`schedule SHOP-14 fri`	plan it for a day
`search login bug`	find a task in any project
`log SHOP-14`	what happened to it, and from where
`comment SHOP-14 "…"`	comment in Markdown
`notes add "…"`	add lines to the project's notes
`open SHOP-14`	open it in the browser

Add --help to any command for the rest.

Scripts and CI

Every command takes --json. Results go to stdout and messages to stderr, and the exit code says what happened: 0 ok, 1 error, 2 usage, 4 not signed in, 5 not found. In CI, sign in with a personal access token from Settings (read-only, or read and write) in MONOBAN_TOKEN.

next04 · Plan with your agent →

## 04 · Claude Code, Codex

Plan with your agent

Coding agents are good at breaking work down. Teach yours the board, and its plans become tasks you can see, reorder and hand out, instead of a list that scrolls away with the chat.

Teach it the board, once
monoban setup claude
Or monoban setup codex. It installs a skill, the instructions an agent reads when they're useful: in ~/.claude/skills/monoban (Codex: ~/.agents/skills/monoban). With --project it goes in the repository instead, to commit for everyone working on it.
Ask it to plan something
“Let's plan invoices for the account page.” It reads the board first, so it reuses your tasks and tags instead of adding duplicates, then proposes tasks grouped by phase, and asks before it writes anything.
Say yes, or change the plan
Drop, rename or reorder tasks first if you like. It adds them tagged phase-1, phase-2…, each with why it matters and a checklist of what done means.
Let it keep them current
It asks once. Then, as it works, it starts each task (its branch, and In progress), ticks its checklist, comments on decisions, attaches the pull request, and moves it to Done when it's done by your standard.

claude — ~/code/shop

> let's plan invoices for the account page⏺ I read the board first (monoban list --json). Add these 4 tasks to SHOP?phase-1 Add the invoices table and its API routephase-1 Show invoices on the account pagephase-2 Email a receipt when an invoice is paidphase-3 Remove the old billing page> yes, and drop the last one for now⏺ monoban add "Add the invoices table and its API route" -t phase-1 -d -Added SHOP-21 to To do⏺ Added SHOP-21…SHOP-23. Shall I keep them current as I go?>

next05 · Hand a task to an agent →

## 05 · the runner

Hand a task to an agent

When a task is clear enough to hand off, press R. An agent works on it on your machine, in your clone and on the task's own branch, and comes back with a pull request. You see every step on the task while you get on with something else.

runner: monoban runner in a terminal on the machine with your code. It asks monoban.dev for work every few seconds and runs the agents there.
agent: Claude Code, Codex or agentpipe: whichever of them is installed where the runner runs.
run: One go of an agent at one task. A task can have many; one at a time.
run tab: w on a task: its runs, their steps, what the agent is doing now, the pull request.

How a run travels

1youPress R. Pick the runner, the agent and the folder of your clone. The run is queued.
2runnerPicked up. Within a minute: it checks in once a minute while idle. It checks the folder is a clone of the task's project, with nothing uncommitted.
3prepareA branch. Fetches the default branch, checks out shop-14-fix-the-flaky-checkout-test, moves the task to In progress.
4codeThe agent works. It gets the task: title, description and latest comments. The run tab shows what it's doing now.
5commit · push · prA pull request. What it left is committed and pushed, and gh opens the pull request (a draft, unless you said ready).
6reportBack on the task. The pull request is attached to the task, with a comment saying what was done.

That's Claude Code and Codex: the runner does the git work around them, and they only write the code. agentpipe does its own: it plans, implements and verifies in steps of its own, and moves and comments on the task as it goes.

Your first run

Install an agent where the code is
agentpipe monoban agentpipe install
Claude Code npm install -g @anthropic-ai/claude-code
Codex npm install -g @openai/codex
For pull requests the runner uses GitHub's gh, signed in (gh auth login). monoban doctor tells you what's missing.
Start the runner, and leave it running
monoban runner
The status bar's runner light turns green, and Settings lists it. It offers the agents it finds, and notices one you install later within a minute.
Have a clean clone of the project
A run works only in a checkout of the task's project: its origin is the project's linked repository, or you ran monoban link there. For Claude Code and Codex it must have no uncommitted changes.

Press R on a task

Runner	the machine; online ones come first
Agent	the ones that runner has; the dialog says how to install the others
Folder on the runner	your clone's absolute path, remembered for the project on this device
Pull request	draft (the default), ready for review, or none: just the branch
Budget	the most it may spend, in US dollars (agentpipe, Claude Code)
Model	which model, as the agent names it (Claude Code, Codex)
Access	Codex only: its sandbox, the sandbox with the network, or no sandbox

Watch it with w
The run tab updates every couple of seconds. Cancel stops it, and what it did so far is kept.

SHOP-14 — Fix the flaky checkout test

How a run ends

the run tab says	what it means
✓ done	the pull request is on the task: review it like any other
? needs you	the agent was blocked, or changed nothing. Its question is on the task as a comment
✗ failed	it says why on the task, and which branch has the work so far
■ cancelled	you stopped it from the run tab, or with Ctrl-C in the runner
lost	the runner stopped answering: start it again

From the terminal

zsh

$ monoban run SHOP-14 --agent claude --follow  # queue it here, print its steps until it ends$ monoban runs SHOP-14  # its runs, newest first

You stay in control

It only asks	the runner polls for work: no open ports, no tunnels, nothing reaches into your machine
`--allow ~/code`	runs only in folders you name, and below them
`--confirm`	asks in the terminal before each run starts
Claude Code	runs in auto mode: a classifier reviews each action, and nothing waits on a prompt
Codex	stays in its sandbox, offline unless the run asks. No sandbox only on a runner started with `--allow-full-access`

next06 · When the network drops →

## 06 · offline and sync

When the network drops

A train tunnel, a flaky café network, a flight: monoban keeps working. What you do is kept on this device and sent when the network is back, in the order you did it. The status bar always says where things stand.

What keeps working

offline	what happens
Tasks, columns, tags	Add, edit, move, plan and delete as usual. Each change is kept here at once, so closing the tab doesn't lose it, and goes out when the network is back.
Notes	Never kept on this device, so they can't be edited offline: if they're on screen they stay, read-only. A line you add is kept, and goes at the end of the notes once you're back. Online, a save waits in memory only, so the browser asks before you close the tab while one is on its way.
Opening the app	Boards you've opened on this device in the last 7 days open with no network, as you left them plus your changes since. Online too, they show at once while the latest comes from the server.
Today and the palette's search (`⌘K`)	Answer from the boards you've opened here, and say so. Connect for everything.
Runs, comments, history, projects	Starting a run, loading comments or history, creating or deleting a project, the settings and signing out need a connection. They say so instead of failing, and what was loading goes on by itself once you're back.

Read the status bar

synced: Everything you did is on the server.
saving…: A change is on its way.
offline · 3 changes: No connection. Three changes wait on this device and go out, in order, once it's back.
1 change not applied: Refused: changed or deleted elsewhere meanwhile. Click it to see why, copy what you wrote, or discard it.

Click it, or press O, for a card with where things stand: offline since when, what waits, and how many boards and page copies this browser keeps. It opens offline too.

A task you add offline shows its reference faint and slanted, as a guess: until the server gives it its number, the CLI or another device may take that one first.

When something changed elsewhere

You worked offline while the CLI, an agent's run or your other laptop changed the same task. When your change goes out, monoban merges it field by field: what only you changed goes in, and what only they changed stays. Where you both changed something, theirs stays, and your words are never lost: your description is kept with theirs below it, and your title goes into the description, under a line saying it changed elsewhere at the same time. A toast says what happened.

A change to a task deleted elsewhere can't go in. It waits in not applied (the status bar, or ⌘K › changes not applied), where you can copy what you wrote, or discard it.

Two tabs, or more

Every tab sends its own changes. If you close one before its changes went out, another open tab sends them right away, and a change saved in one tab shows in the others without a reload.

What this browser keeps

Settings › This browser lists it: the boards you opened here (each dropped 7 days after you last open it), the changes waiting, the copies of pages that open with no network, and your preferences. Never a token, a password or your notes: offline, only the lines you add to them wait here.

Remove what's kept deletes it and keeps you signed in; the boards come back as you open them, and your preferences stay. With changes not sent yet, it asks first: they go with the rest.

next07 · Putting it together →

## 07 · a day with monoban

Putting it together

Each part works on its own. Together they make a loop: plan, hand out, review, close. Whichever way a change comes in, the board is where you see it.

09:00
See what's onbrowser
The app opens on Today: two tasks planned, one late from yesterday.
09:10
Plan the next featureagent
In Claude Code: “let's plan invoices”. You agree to three tasks, SHOP-21…SHOP-23, tagged phase-1 and phase-2.
09:20
Hand one offbrowser
R on SHOP-21: Claude Code, on the runner in your other terminal. It starts on its own branch.
09:25
Do the urgent one yourselfterminal
monoban start SHOP-14, fix the flaky test, gh pr create, monoban attach --pr.
10:05
Reviewbrowser
SHOP-21's run is done and its draft pull request is on the card. p opens it.
11:30
Close the loopterminal
Both merged: monoban done SHOP-14, monoban done SHOP-21. d plans SHOP-22 for tomorrow.

Every one of those changes is in the task's history (y): what changed, when, and whether it came from the web or the CLI.

next08 · Cheat sheet →

## 08 · keys and commands

Cheat sheet

Everything above, on one screen. In the app, ? shows every key and ⌘K finds any action; in the terminal, add --help to any command.

On the board

`jk`	select a task
`hl`	change column
`⇧→⇧←`	move it across
`⇧↑⇧↓`	reorder it
`⌘⇧↑⌘⇧↓`	to the top, the bottom
`n`	new task
`↵`	open it
`/#`	filter, by tag
`xu`	delete, undo
`eE`	archive; won't do, with why
`spacem`	mark; move the marked to a project
`T`	Today
`NAB`	notes, archive, board

On a task

`t`	tags
`d`	plan for a day
`a`	attach a link
`p`	open the pull request
`y`	history
`s`	comments
`R`	run with an agent
`w`	its runs
`z`	widen the panel
`⌘S`	save now (it saves as you type anyway)
`esc`	close it (so does back, on a phone too)

In the terminal

`login · link · doctor`	set up this machine and this clone
`add · list · show · move · done`	the board
`start · attach --pr`	a task's branch, and its pull request on the card
`today · schedule · search`	across every project
`setup claude · setup codex`	teach your agent the board
`runner · run · runs`	hand tasks to agents
`agentpipe install`	install agentpipe for the runner

agentpipe	`monoban agentpipe install`
Claude Code	`npm install -g @anthropic-ai/claude-code`
Codex	`npm install -g @openai/codex`