Workban

Guide · Codex

Codex for teams: every task on the board, nothing to log by hand.

OpenAI's Codex works in the terminal on your machine. This guide shows how Codex writes its own tasks to a shared kanban board, so your team sees what it is working on, how long it takes and how many tokens it uses.

  • Codex
  • AGENTS.md
  • Hooks after a one-time approval
  • Updated October 30, 2026

The problem

Codex in the cloud or on your machine.

Codex comes in two forms. In the cloud, it works through a task you assign to it, such as an issue in Linear or GitHub, and comes back with a result. On your machine, it works with you in the terminal, step by step, in your repository.

The cloud has integrations with ticket systems. Work in the terminal leaves the team without an overview: which session is running for whom, what is it working on, what is done, what did it cost? That is what this guide is about.

Wiring

AGENTS.md for the workflow, hooks for the rest.

workban init writes the workflow into AGENTS.md, the file Codex reads in every repository. The hooks live in your Codex user settings.

AGENTS.md
The full workflow: when Codex creates a task, starts it, puts it on hold and closes it, with the CLI commands.
.workban.toml
Which Workban project the repository belongs to. This is how the hooks know they should work here.
~/.codex/hooks.json
The hooks: the gate before changes, the overview when a session starts, token usage after every turn and the line for the Live page.
Approval
Codex only runs hooks after you have reviewed and trusted them, through /hooks in Codex. It asks again only when an update brings new hooks. If the approval is missing, the agent tells you the next time it starts a task.

Several agents

From a concept to tasks, built by several sessions at once.

Codex can plan a whole project and put it in the backlog as tasks. Several sessions then work through them in parallel, and the board shows which one is on what.

  1. 01

    Write the concept

    Have Codex write a concept for the project and break it into tasks that can be built one by one.

  2. 02

    File the tasks

    Codex creates each task with a description in the backlog, without starting it.

    workban task create "Passkey button on the login page" --assignee me --json

  3. 03

    Start in parallel

    Start several sessions, ideally each in its own Git worktree so they do not get in each other's way, and tell each one which task to take: “do #31”.

    workban task start 31 --agent codex --json

  4. 04

    Follow it on the board

    Every session works under its own task, and the gate counts per session. The board shows live which task is already running, which is testing and which is waiting for you, and workban task list shows the next session what is already taken.

Set up

Connected in five steps.

Once per machine and once per repository. The setup page has the install command for your system.

  1. 01

    Create a workspace

    Sign up, no card needed, and give your team's space a name.

  2. 02

    Install the CLI

    One command in the terminal installs the Workban CLI, for macOS, Linux and Windows. You do not need Node.

  3. 03

    Create a token

    In Workban, open the user menu, go to Tokens and create a personal access key. You see it only once.

  4. 04

    Log in

    The CLI signs in on your behalf with the token, once per machine.

    workban auth login --token <token>

  5. 05

    Connect the repository

    Run this in your project's folder, then trust the hooks under /hooks in Codex. From then on, Codex creates its own tasks.

    workban init

Gate

No change without a task, in Codex too.

Once you have trusted the hooks, Workban holds back Codex's changes in the repository until a task of its own is running.

  • Applies to apply_patch and to shell commands as soon as they visibly write
  • Counts per session: a second session in the same repository needs its own task
  • Anything outside the repository, such as /tmp, stays open
  • If Workban cannot be reached, the gate lets everything through

Tokens

Usage comes from the log Codex writes anyway.

Codex keeps every session as a file under ~/.codex/sessions, with running token counts. After every turn, the Workban CLI reads what was added since the last reading and books it to the task that is In progress. Usage only counts while the task is there.

From that, Workban estimates the cost at OpenAI's list prices, per model. It does not account for a ChatGPT subscription, so the figure shows what the work would have cost at list prices.

Questions

What teams want to know first.

Does this work with Codex in the cloud?
No. Workban connects Codex on your machine, through the CLI and the hooks. A task that Codex works through in the cloud does not appear on the board by itself.
Can Codex and Claude Code work in the same team?
Yes. Every task on the board shows which agent worked on it, and the statistics show done tasks by people, Claude Code, Codex and other agents.
Does Workban read our code?
No. Workban only sees what Codex reports through the CLI: the title, description, comments, status and branch of a task, plus a short line for the Live view on what the session is doing.
What does it cost?
Workban is free, and you sign up without a card.
Does it work with my ChatGPT subscription, such as Pro?
Yes. Codex runs the way you signed it in, with a ChatGPT subscription such as Plus or Pro or with an API key. Workban needs no access to your OpenAI account and no API key.

Next

More on agents and cost.

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.