Docs

Set up Bento, connect a project, and run your work through it with Claude Code and Codex.

Setup

You need Python 3.9+ and git, plus Claude Code, Codex, or both. Bento is built and tested on macOS. Linux is untested. Windows won't work, because Bento relies on Unix file locks.

git clone https://github.com/ckoglmeier/bento.git ~/bento
mkdir -p ~/.local/bin
ln -s ~/bento/kb ~/.local/bin/kb
kb init ~/bento-data --owner yourname
kb install-agents

If your shell can't find kb, add that folder to your path and open a new terminal:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

The repo holds only code. Your board, docs, and plans live in the workspace folder on your machine. While it runs, Bento snapshots that folder to its own local git repo about once a minute, and kb history lists the snapshots. It never pushes them anywhere.

kb install-agents adds a short marked section to ~/.claude/CLAUDE.md and ~/.codex/AGENTS.md, and lets Codex's sandbox write to the workspace.

First five minutes

Connect a project and open the board:

kb connect ~/code/my-app --import-docs
kb open

In that project, ask Claude Code or Codex: "Read our backlog and add the next few epics to Bento." They land in Backlog.
On the board, drag the one you want first into Next.
Ask your agent "What's next?" It answers from the board and changes nothing. Tell it to pick the work up, and it claims the card and finishes into Review for you to check.

How it works

Every card is an epic: a meaningful group of work with one clear "done when". Small tasks go inside the epic's plan, not on the board.

The rules are short. Asking "what's next?" only reads. Agents claim a card before they start, finish into Review, and never move a card to Done. That call is yours. Agents put new work they notice in Backlog and don't start it. If one is stuck on a real decision, it blocks the card and tells you.

Agents get these rules from kb rules, which prints AGENTS.md. Claiming is atomic, so two agents can't take the same card.

The board

Every card is numbered within its project: the project's letters, then a number. B12 is the twelfth Bento card, and MA3 is the third card in my-app. Bento picks the letters from each project's name: one letter when it's free, the initials of a longer name like MA for my-app, or more of the name when those are taken. They never change once given, and kb projects lists them. Cards with no project use N. Moving a card to another project gives it the next number there. Its old number keeps working, and so do numbers from before projects had letters, like #36.

kb open opens the board at http://127.0.0.1:4747, and starts it in the background if it isn't running. You can also tell your agent "open bento". The board has five views:

Inbox: one ranked queue of everything waiting on you: blocked cards, work an agent started on your word, plans to approve, finished work to accept, done-whens an agent changed, Next cards missing a done-when, work that's gone quiet, epics assigned to you, milestones past their date, and Scratchpad notes. Each item links to what to check: the URL or doc an agent gave with kb review --link, the source doc, and the plan. Clear it from the keyboard. j and k move, a approves or accepts, r requests changes or sends work back, 1 to 9 pick an agent's offered option, and Enter opens the card. Sending work back asks why: it doesn't match the done-when, it doesn't work, you can't tell if it works, or something's missing. Copy briefing puts a summary of the board on your clipboard. Use Change order to pick which sections show and in what order, or run kb inbox --order blocked,review,plans.
Delivery: what to take up next, what each item still needs from you, and what is ready to verify.
Calendar: milestones across projects, and how the work feeding each one stands. Drag a milestone onto a date to move it.
Scratchpad: loose notes and ideas. Agents never pick these up, and any of them can become an epic. Say "note for bento" in Claude Code or Codex, and the agent saves a short summary of the discussion here.
Board: the kanban columns.

Column	Meaning	Who puts cards here
Backlog	Epics nobody has committed to	Anyone
Next	Committed work. The top card goes first.	You, or a handoff you asked for
Doing	Someone is working on it	Whoever claims it
Review	Finished, waiting for you to check	Whoever did the work
Done	You accepted it	You only

Agents claim from Next. The exception is work you ask an agent for directly, in conversation. The agent claims it straight from Backlog and quotes you: kb claim MA40 --as codex --asked "build the site directions". Your words go on the card, and the card waits under "Started on your word" in your Inbox. Click That's right to confirm it, or Stop it to send it back to Backlog. From the command line, that's kb confirm MA40 or kb confirm MA40 --stop.

Decisions

An agent that needs you blocks its epic with a question, and can offer choices:

kb block MA12 "Which payment provider?" --option Stripe --option Paddle

You pick one in the Inbox, or type your own answer. Every answer is saved as a decision in DECISIONS.md, numbered D1, D2 and on. Mention other epics in it, such as "Stripe, and the same for MA13", and the decision is noted on them too. From the command line, kb answer MA12 Stripe --implies MA13,MA14 does the same, and kb decide "We launch in the US first" --implies MA12,MA13 records one you made in a conversation. Change your mind with kb decide "Paddle after all" --supersedes D3, and every epic D3 touched is told. kb why MA12 lists the decisions behind an epic, and the card shows them on the board.

Keeping the done-when honest

Once someone claims an epic, its done-when only changes with a reason: kb set MA12 "done when" "..." --reason "what the old one got wrong". The reason and the old wording go in the card's notes. When an agent makes the change, it shows in your Inbox until you keep it or put the old one back (kb bar MA12 keep or kb bar MA12 undo), so nobody can quietly lower the bar.

Tested before Review

An agent can't hand you work it hasn't tested. After claiming an epic, it writes the checks first with kb test-plan MA12. That adds a Testing plan section to the epic's plan doc, or starts a doc of its own when there's no plan. Each check says what to verify, how, and what to expect. Before Review, the agent runs every check and reports what it ran: kb review MA12 --as codex --tested "ran all four checks, all passed". Review refuses work with no testing plan or no report. If something can't be tested yet, the agent says why with --untested "no staging data yet", and the Inbox flags it next to the work. Your own cards skip the check. To turn it off, set { "review": { "require_tests": false } } in bento.json.

Health, briefings and resuming

kb health lists everything stuck: blocked epics, claimed work with no update for two days, work waiting in Review for two days, changed done-whens, late or at-risk milestones, and recurring reports that missed one and a half of their scheduled runs. Each line says since when, the next step, and who takes it. It exits 1 when something is stuck, so a scheduled job can alert on it. Change the thresholds in bento.json with { "health": { "quiet_days": 3, "review_days": 2 } }.

kb digest prints a short Markdown briefing: what's waiting on you, what's in progress, what's up next, milestones, what's stuck, recent decisions, and why work was sent back. API keys, tokens, and passwords are taken out, so you can paste it into a chat assistant. kb digest --out ~/briefing.md --watch keeps a file current.

An agent starting a session runs kb resume --as claude to see what it holds, what came back from you, the decisions on its epics, and what to do next.

Docs and plans

Connecting a project registers it in your workspace and adds nothing to its repo. Bento recognizes the project by its git remote, so every clone and worktree is connected automatically. --import-docs copies Markdown from docs/, plus root files like BACKLOG.md and ROADMAP.md, from the default branch into products/my-app/.

Imported docs are a copy. Decide which version is the real one: keep editing in the workspace and leave a pointer in the repo, or re-run kb import to refresh. A re-import overwrites workspace edits to those files.

Pull only what's worth doing soon onto the board. The --source flag points back to where the detail lives:

kb add "Saved searches" --source docs/BACKLOG.md#release-1 --release "Release 1" --done-when "..."

An epic can have one of four kinds of plan, which you can read, approve, or request changes on from the board:

Kind	Covers
`implementation`	Building something
`testing`	Verifying built epics as a group. It can't start until they reach Review.
`release`	Shipping a set of epics, with its exit gate and rollback
`writing`	A piece of writing, often timed to warm up an audience before a release

kb plan testing "Search" --epics MA14

On the board you can edit any doc in place, or start a Codex or Claude Code thread on it.

Handoffs

Iterate with one agent, then hand epics and a plan to another:

kb plan implementation "Search" --epics MA12 MA13
kb handoff MA12 MA13 --to claude --plan products/my-app/plans/implementation-search.md --as codex

The receiver runs kb claim MA12 MA13 --as claude, reads the plan, and follows it. Handing off doesn't start an agent. Someone still has to ask it to pick the work up.

Hearing back without polling

kb service install

This runs Bento in the background on macOS and starts it at login. An agent that pushes work hears back once when the whole set reaches Review, or right away if an epic gets blocked:

Codex: the service runs codex exec resume on the session that pushed.
Claude Code: the session runs kb wait MA12 MA13 as a background command, which sleeps on a kernel file event and wakes the session when it exits.

The web board updates live the same way. For your own alerts on a phone, Slack, or anything else, add a command to bento.json in your workspace. It receives the event as JSON on stdin, plus $BENTO_TITLE and $BENTO_MESSAGE:

{ "notify": { "command": "curl -s -d \"$BENTO_MESSAGE\" https://ntfy.sh/your-private-topic" } }

Milestones

Dates belong on milestones and releases, not on ordinary epics. A milestone is a named moment with one date, such as a launch or a publish date. Epics feed it through needs, and milestones in different projects can depend on each other.

kb add "Essay publishes" --kind milestone -p writing --target 2026-12-01 --needs MA12,MA13

Each one can have a doc with its theme, acceptance criteria, and release notes. Start one with kb plan milestone "Essay publishes" --epics MA14. When it ships, run kb ship MA14, or choose Ship it in the Inbox. Epics it needed that aren't finished or in Review move to the next milestone in the same project, or to the one you name with --next MA15. Use --keep to ship without moving them. A milestone is at risk if a dependency is blocked, a dependency is dated after it, or dependencies are open with 7 days or fewer left.

Recurring reports

kb report add "App daily usage" --thread <codex-thread-id> -p my-app --schedule "Daily at 2:00"

The Reports panel on the board links to each report's thread, filtered by project. A report job can also post a dated copy with kb report post "App daily usage" report.md, which keeps its history in products/my-app/reports/ where people and agents can read it.

Commands

kb --help lists everything. These are the ones you'll use most:

kb                               the board across projects (-p my-app, --kind testing, --all, --json; same as kb list)
kb next --as codex               best card for you, changes nothing
kb inbox                         what's waiting on you (--order blocked,review,plans to change it)
kb show MA12                     one card in full
kb claim --as codex              take the best card (or: kb claim MA12 MA13 --as codex)
kb claim MA12 --as codex --asked "..."   take a Backlog card you asked for, in your words
kb confirm MA12                  confirm work claimed on your word (--stop sends it back)
kb add "title" --done-when "..."  add an epic to Backlog
kb add "title" --to scratchpad   save a note or idea
kb plan testing "Search" --epics MA14
kb push MA12 MA13 --to claude    hand epics over, with or without a plan
kb wait MA12 MA13                sleep until they reach Review or get stuck
kb wake MA12 MA13                have this Codex session resumed when they finish
kb set MA12 needs "MA9"          change a field
kb note MA12 "text" --as codex   add a dated note
kb block MA12 "reason"           flag a card as stuck (kb unblock MA12 clears it)
kb block MA12 "Which?" --option A --option B   ask with choices
kb answer MA12 "text"            answer a blocked card; it becomes a decision (--implies MA13,MA14)
kb decide "text" --implies MA12  record a decision (--supersedes D3 replaces one)
kb why MA12                      the decisions behind a card
kb test-plan MA12                start the epic's testing plan, before you build
kb review MA12 --as codex --tested "what ran, what passed" --note "text" --link https://preview.example.com
kb send-back MA12 "text" --reason mismatch   send Review work back (broken, unclear, missing, other)
kb bar MA12 keep                 keep an agent's done-when change (or: undo)
kb ship MA14                     mark a milestone reached; unfinished epics move on
kb health                        everything stuck, since when, and who's next
kb digest                        a Markdown briefing, secrets removed (--out file --watch)
kb resume --as claude            start of a session: what you hold and what came back
kb move MA12 next --top          move or release a card
kb delete MA12                   move a card to TRASH.md (kb restore MA12 undoes it)
kb calendar                      milestones and their dependencies
kb docs                          product docs and plans
kb projects                      connected projects and their card letters
kb archive                       move Done cards to ARCHIVE.md
kb history                       local snapshots of your workspace
kb open                          open the web board, starting it if needed
kb serve                         run the web board in this terminal

Update or remove

cd ~/bento && git pull

kb uninstall-agents removes what kb install-agents added and leaves your workspace alone. kb service uninstall stops the background service if you turned it on.