Agents & CLI · For developers
The agent keeps its own task. You fill in nothing afterwards.
Workban talks to agents through a CLI in the terminal. workban init puts a rule, a skill and the hooks into the repository. From then on, Claude Code opens its task before the first change, moves it to testing and closes it with a comment.
$ workban task create "Fix the login redirect" --start --agent claude-code --json └ #42 created, In Progress$ workban task move 42 testing --json$ workban task done 42 --comment "Redirect fixed, PR linked" --json
- 25 commands
- 6 platforms, no Node
- Claude Code and Codex
- REST API, no MCP
Workflow
Four commands from the first line to done.
The rule in the repository tells the agent when to run which command. With --json, every command returns exactly one JSON object, so the agent can read the answer reliably.
- 01
Create and start
Before the agent changes a file. The CLI reads the branch from Git. If the branch already has an open task, the agent carries on with that one instead of creating a second.
- 02
Test
As soon as tests, lint or CI run. Until the task is back in progress, the gate blocks every change.
- 03
Wait
When the task waits for a person, an approval or an answer, the clock stands still. The comment says what for.
- 04
Close
After the commit, with the link to the pull request in the comment. The CLI has reported the token usage all along and does so one last time here.
Or the other way round: you create, the agent takes over.
Create the task on the board and tell your agent “do #28”. It reads the description, comments and attachments and starts the task before it begins.
workban init
One command sets up the repository.
Once per repository. The files live in the repository, so they apply to everyone working in it, person or agent.
- .workban.toml
- Which Workban project this repository is.
- .claude/rules/workban.md
- The binding workflow. Claude Code loads it at the start of every session.
- .claude/skills/workban/SKILL.md
- The CLI's commands. The agent loads them when it needs them.
- CLAUDE.md, AGENTS.md
- A pointer for Claude Code, the full workflow for Codex and other agents.
- .claude/settings.json
- The hooks: the gate before every change, at the start an overview of running tasks and backlog plus the update of CLI and files, after every turn the token usage, and all along whether the agent is working or waiting for you and which tool it is using, for the Live page.
- .codex/hooks.json
- The same hooks for Codex. Codex asks you once to trust them at its next start.
init adds to existing files instead of overwriting them. After a CLI update, the next session start brings everything up to date; by hand it is workban init --update.
Gate
No task, no change.
In Claude Code, a hook in the repository blocks every file change until the agent has started a task of its own. So even the small fix in between shows up on the board.
- Applies to Edit, Write and Bash, and to PowerShell on Windows
- For Bash, the gate reads the command itself: redirects into files,
sed -i,rm, package installs and scripts that write - It counts per session: a second agent in the same repository needs a task of its own
- Anything outside the repository, such as
/tmp, stays free - If Workban cannot be reached or nobody is logged in, the gate lets changes through. Workban never holds up work
Edit README.md
Workban: No running task. Start the task first, then make the change.
Workban Guard
Guardrails for your agents.
Workban knows what your agents are working on. Workban Guard watches what they do along the way: a plugin of its own for Claude Code and Codex that stops dangerous commands before they run.
- Before every command: a force push to main,
rm -rf ~,supabase db resetorcat .envgets stopped, even hidden in scripts and heredocs - After every edit it checks the new lines for
any, emptycatchblocks, SQL built from strings and secrets - The agent is only done when typecheck, lint and tests are green
- Access through your workspace: owners and admins request it in the app under Workban Guard, then every member installs Workban Guard with their Workban account
$ git push --force origin main └ Workban Guard blocked this action: a force push to "main" overwrites other people's commits. [git.force-push]$ git reset --hard └ Workban Guard asks for confirmation: this throws away uncommitted changes. [git.discard-changes]
Agents
Furthest with Claude Code, open to any agent with a shell.
All Workban needs from an agent is a terminal and a text instruction. How much happens on its own depends on what the agent can do.
- Claude Code
- Rule, skill and hooks. The gate applies, and after every turn a hook reports the tokens from the session file.
- Codex
- The full workflow sits in AGENTS.md, the hooks in .codex/hooks.json. Once you trust them in Codex, the gate applies there too, and a hook reports the tokens from the rollout log.
- Other agents
- Any agent with a shell can use the CLI. It reports its own usage with
--tokenswhen it closes a task. - People
- The same commands in the terminal, or the board in the browser.
CLI
One program, built for machines.
The CLI is a single program on your path, without Node and without a service that keeps running. It talks to Workban and nothing else.
- macOS, Linux and Windows, each for x64 and ARM64
- Installed with one command, logged in with a personal token, once per machine
--jsonon every command, stable exit codes, no prompts without a terminal- It installs new versions itself when a session starts, signed ones only.
workban doctorchecks the setup - No telemetry
Commands
- workban task
- create, start, move, done, comment, attach, show, list, current, claim, edit, delete
- workban project
- list, create
- workban board
- The board, compact, in the terminal
- workban auth
- login, status, logout
- workban init
- Connect a repository, with
--updatebring it up to the CLI's version - workban hook
- gate, session, usage and state, the hooks for Claude Code and Codex
- workban update, doctor
- Update and check the setup
No MCP
Why Workban has no MCP server.
A deliberate decision: a REST API and a CLI instead of an MCP server.
- One path for all
- Claude Code, Codex, scripts, dashboards and people in the terminal use the same API. Nothing works only through an agent channel.
- No process per session
- An MCP server runs per session, with its own configuration and its own failure points. The CLI is a program on your path.
- Testable with curl
- Every function can be checked without an agent, and errors can be reproduced.
- Independent of the agent
- A new agent only needs a shell and a text instruction.
- Less context
- An MCP server loads every tool into the agent's context. The skill loads only when it is needed.
Next
Setting up takes a few minutes.
Get started
Try it with your next task.
Workban is free. Your workspace is ready in a minute, and the first task appears as soon as your agent gets going. The app itself speaks German for now.