⚠️ Unofficial community project, not affiliated with or endorsed by Gentle AI. Report odd-board problems here, not to gentle-ai.
WORKS WITH ANY HARNESS THAT RUNS ODD
Claude Code · OpenCode · Codex · Pi · and others
read-only · no backend · no database · no account · nothing to install
Quickstart
npx odd-board # in a repository that uses ODD
npx odd-board --demo # temporary repo with simulated agents working in parallel
Add --open to open the board in your browser. The full list of options is in Usage.
Features
Columns from ODD stages — Never stored, always derived
ODD tracks substantial work in one feature document per feature (odd/tasks/<feature>.md) with objective, scope, a task checklist, evidence, progress and the next step. odd-board watches that folder and pushes every change to the browser over Server-Sent Events. Columns are derived from each document every time it changes, following the ODD stages that leave a trace on disk:
| Column | ODD stage | Rule |
|---|
| Tracked | Track | Document exists, no task done yet |
| Implementing | Implement | Some tasks done, some open |
| Verifying | Close (in progress) | All tasks done, but checks or review still pending |
| Closed | Close | All tasks done, no pending checks |
Blocked is a flag, not a column: the card stays in the stage where it stalled and is outlined in red.
Authorize, Explore, Resolve uncertainty and Classify happen inside the agent session and never reach the file system, so they are not columns. Small work never gets a feature document, so it never shows up. That is ODD working as designed.
Parallel agents — Read from git, never guessed
ODD records nothing about parallelism, so odd-board reads it from git, which knows it for certain:
git worktree list finds every checkout of the repository.- Each worktree is linked to a feature by its branch name.
feat/csv-export is the feature's primary worker; feat/csv-export-agent-2 (or any worktree nested inside the feature's worktree) is a subagent of the same feature.
- A worktree is active when it changed in the last 10 minutes (uncommitted files or a recent commit). Change the window with
--window <minutes>.
A card with active workers shows a pulsing "N agents working" line and lists its workers when expanded. The header counts active agents across the whole repository. A card in Implementing with no active worker is in progress but stalled. The Lanes view shows one row per worktree: branch, feature, current task, changed files and last activity. It is the quickest way to see what is running in parallel tonight.
The feature document is read from the feature's own branch when that worktree exists, then from the main checkout. File modification time alone is not trusted, because a worktree created later holds an older copy with a newer timestamp.
Deterministic where it can be — Honest where it cannot
ODD does not define a status field or a fixed document schema. So:
-
Deterministic: task counts and progress come from the state each task records. ODD only marks a task done with observed proof. Real gentle-ai documents record it in several ways, all supported:
- checkboxes:
- [ ] / - [x], anywhere in the document;
- inside a tasks section (
## Tasks, ## Tareas, ## Work units): a table with a Status column, - T1 | S1-S3 | ... | done | commit: <sha> items, 1. [done] ... items, and - T1 — ...; inline; done, commit <sha> items.
Status words are read in English and Spanish (done, complete, committed, hecho · pending, in progress, later, pendiente · blocked, bloqueado). dropped or superseded tasks stay on the card but count neither as done nor as remaining. Indented items under a task (acceptance criteria, evidence) and anything inside code blocks are not tasks.
-
Commits: a task's commit is a hash next to evidence/commit, in backticks, or in a Commit column. A bare hash must mix letters and digits, so numbers in the task text are not taken for commits, and hex IDs glued to a prefix (review-562ea3fd…, sha256:…) are not either.
-
Next step: a ## Next step section, else the last Next: / Next step: / Próximo paso: line.
-
Heuristic: "blocked" and "pending checks" are detected from wording in the Progress, Next step and Evidence sections and top-level Progress: lines (English and Spanish). An open task marked blocked also flags the card. Negations ("no longer blocked"), something else being blocked ("a blocked request"), waiting on CI, test summaries with zero failures ("42 passed, 0 failed"), the RED step of test-first work, and failures the document calls pre-existing, unrelated or flaky are ignored. Wording cannot tell an old failure from a current one; see the known misses in test/fixtures/gentle-ai-v4.3.1/README.md.
-
Optional override: if a document has frontmatter with status: planned | in-progress | verifying | blocked | done, it wins. This is a convention on top of ODD, not part of it.
Documents odd-board cannot understand are shown as unparsed. They are never dropped and never break the board.
Zero dependencies — Read-only by design
odd-board has zero runtime dependencies: package.json has no dependencies and no devDependencies, and there is no build step. The whole package is a CLI, a few modules and a single HTML page. The server listens on 127.0.0.1:4747 by default, only reads files and never writes to your odd/ folder. No database, no account, no API key, no network access.
Install
odd-board is published on npm as odd-board. You do not need to install it to try it:
npx odd-board --demo --open # no install, opens a demo board in your browser
Or install it once and run it anywhere:
npm install -g odd-board
odd-board ~/code/my-repo --open
From source (no npm install needed, there is nothing to install):
git clone https://github.com/claudiocebpaz/odd-board.git
cd odd-board
node bin/odd-board.js --demo --open
This is the beginning of the README. Read the rest at the original. Read the full README ↗
