omatty
A real engineering workspace for Claude Code. In your terminal.
You already run Claude Code in parallel. Everything you need to judge the
work lives somewhere else: panes in tmux, files in an editor, the diff in a
git client, the tests in one more terminal per worktree, the pull request in
a browser tab. omatty puts the whole loop in one window.

Real omatty and real Claude Code, in two Go repositories: both sessions
work at once, the file tree marks what changed, the gate lands on each card,
and a review comment goes back and stays on its line while Claude edits. The
keys and the two prompts are scripted; the rest is not. Long waits are
shortened. More at omatty.com.
brew install WilsonSousajr/tap/omatty
- Live panes. Each session is the real
claude binary in a pane you type
into, in a worktree of its own, several side by side across your
repositories. The sidebar says which is working, which is waiting for you
and which is done, from Claude's hooks, never from the screen.
- A file tree that follows each session.
ctrl+o f shows the worktree of
the session you are on and moves with you to the next. When a turn ends it
re-lists itself and marks what Claude added, changed or deleted.
- A diff you can answer. Syntax-highlighted, with the lines no test
covers marked. Comments anchor to a line's content, so they stay on the
right code while Claude keeps editing, and go back as one message.
- Your gate on every session. Your own
fmt/vet/lint/test/coverage
line runs in each session's worktree, with a verdict per step on its card.
A step passes if and only if it exits 0; one key sends the failures back.
- Ship it or take it back.
ctrl+o p pushes, opens the pull request, or
merges when your gate and the forge's checks are both green. ctrl+o u
puts the worktree back to where the last turn began. ctrl+o i shows the
project's issues and pull requests in the same column.
- Nothing leaves your machine. No telemetry, no account. omatty never
writes your
~/.claude/settings.json; its hooks go on each session's
command line. One Go binary, MIT, for macOS and Linux.
docs/comparison.md is the fair version of how this compares to herdr,
claude-squad, Orca, claude agents and the rest, including where they are
ahead.
What omatty is
There are a great many tools for running coding agents in parallel, and they
almost all optimise the same thing: how much agent-work you can have in flight
at once. Fleets, coordinators, queues, boards.
omatty optimises the other thing: how quickly you can tell whether what came
back is any good.
So a project here is not a container for delegated tasks. It is a repository
and the sessions running against it. omatty starts the real claude binary —
it does not reimplement Claude's interface — and shows you what each session
changed, with your comments anchored to the content of the lines rather than
their numbers, sent back as one message.
A project also carries its gate: the fmt/vet/lint/test/coverage
line that decides whether the work is sound. omatty runs it in the session's
own directory, shows the result on the session's card, and sends the failures
back into the session that caused them — one keystroke, or on its own when a
turn ends, if you ask for that.
It does not delegate, plan, schedule, or decide on your behalf. You are not a
bottleneck in the loop; you are the part of it that catches things. omatty's job
is to get you to the point of catching them sooner.
docs/ROADMAP.md lists what that rules out, and why.
docs/comparison.md says how it compares to everything else in the field.
Status
v0.11.0, 2026-10-05 — Codex, any agent, and a review that follows
claude. Codex runs beside claude as a first-class agent (#152), a session can
run any command you declare as an agent, and omatty shows only what that agent
lets it know (#525, #526). The review column follows claude
into the worktree it moved to (#659), the file tree opens closed (#593), and
the tracker stays in sync, with ]/[ and tab to reach its pull requests
(#658, #662, #663).
v0.10.0, 2026-10-01 — the architecture. The code is rebuilt in the shape
of ADR 0001, with nothing you see changed:
omatty no longer waits on git or the disk while it draws, every git call has
a deadline, and omatty sessions --json and omatty status --json hand a
script what the sidebar shows.
v0.9.0, 2026-09-29 — your forge, whichever it is. The card's pull request
and CI, the tracker, the browser and ctrl+o p work on GitLab, Gitea, Forgejo
and Codeberg, Bitbucket and Azure DevOps as they did on GitHub, through each
forge's own CLI or its REST API with a token omatty borrows and never stores.
ctrl+o p now merges only the commit the card showed green, and only into the
branch the session came from (#598, #599). The Forges table says
which forges a real run has shown.
v0.8.2, 2026-09-27 — curl -fsSL https://omatty.com/install.sh | sh
installs omatty on any macOS or Linux machine, checking the release archive
against its checksum and handing off to Homebrew when it is there (#517).
brew install stops warning you to report a bug in our tap (#369). A project
reached through a symlink finds its transcript again (#564). And scrollback
survives a reattach, because it is Claude Code's own (#336).
v0.8.1, the same day — the recording above is real Claude Code, showing
the whole workspace (#556).
v0.8.0, the same day — ctrl+o tab folds a project's sessions behind its
sidebar header, showing how many it hides and the loudest status among them
(#505). And this page opens on what omatty is (#549), with a comparison
corrected against each tool's own source (#515, #548).
v0.7.0, 2026-09-26 — two pieces of polish you feel on every frame: the
session list answers the mouse wheel, and neither column starts hard against its
own edge any more (#497, #498).
v0.6.0, the same day — the review column starts remembering things. v marks
a file read and says ~ when its diff changes under you; the files nobody wrote
are folded away; a line takes more than one comment, and C comments on part of
one. ctrl+o u puts a session back to the start of its last turn, and ctrl+o p
ships a green one — push, open the pull request, and merge it when your gate and
the forge's checks are both already green. omatty gate <project> --stats is
the only thing omatty measures about itself: lead time, and how often the gate
passes first time. And the review column is made worth living in: every face
moves and marks state the same way, the diff is syntax-highlighted with its
changed words picked out, and ctrl+o z zooms the column when a view needs the
room. Install with curl -fsSL https://omatty.com/install.sh | sh or
brew install WilsonSousajr/tap/omatty; CHANGELOG.md has the whole list.
| Milestone |
Delivers |
| M1 Skeleton |
Projects and sessions registered, worktrees created on demand, the real claude binary running inside an embedded terminal pane, and modal key routing. |
| M2 Status |
Live per-session glyphs, age and token usage in the sidebar, from Claude Code hooks and each session's transcript — never scraped from the screen. |
| M3 Review |
A diff pane over everything a session changed, with comments anchored to line content, sent back as one message. |
| M4 Lifecycle |
Rename, archive, jump by name, and discover the projects claude already knows you use. |
| M5 File tree |
The session's worktree beside its diff, with change markers and syntax-highlighted previews. |
| M6 Persistence |
With dtach, quitting detaches rather than ends; relaunching reattaches. Sessions claude already has can be adopted. |
| M7 Reach |
A config file, mouse support, the agent seam, and a visual identity. |
| M8 Surface |
The frame, colour rule, cards, header, footer and diffstat that the panes are drawn in. |
| M9 The Gate |
A project carries the check line that says whether work in it is sound. omatty runs it per session, shows the verdict on the card, and sends the failures back into the session. |
| M10 Coverage on the diff |
Of the lines a session added, the ones no test covers, marked in the diff with a count per file — and a word on the title when a change brought no tests with it. |
| M11 The Harness |
Nothing an operator sees: invariant 4's import boundaries, module hygiene, per-function C.R.A.P. and the package dependency structure become steps of this repository's gate that fail. |
| M12 The Field |
What the rest of the field ships and why omatty declines most of it, researched at code level; then everything that came out of it — review scoped to the last turn and to what you have read, generated files folded away, several comments on a line, a session put back to where its turn began, and a green one shipped from its card. |
| M13 Memory and idle CPU |
Idle CPU cut by about 55%, and a per-session leak on archive fixed. |
| M14 The Tracker |
A project's open issues and pull requests in the review column, read through your own gh and never written to: counts on every header, one item's body and comments on enter, and a worktree session named after the issue you picked. |
| M15 The Polish |
The review column made worth living in: one list window and one state vocabulary across every face, chrome that names the face you are on, and ctrl+o z to zoom it; a gate that reads like a CI check page, a compact tree, a tracker with review state and a preview, a syntax-highlighted diff with file and hunk navigation, and help that opens where you are. |
| M16 The Forges |
The card's pull request and CI, the tracker, browse and ctrl+o p on GitLab, Gitea/Forgejo/Codeberg, Bitbucket and Azure DevOps as on GitHub, through each forge's own CLI or its REST API with a token stored nowhere; ctrl+o p merging only the commit that was green, into the branch the session came from. The Forges table says which a real run has shown. |
Pre-1.0 deliberately: the embedded terminal library underneath is itself
pre-1.0, and the key table, config.toml keys and state.json schema are
not yet frozen. docs/ROADMAP.md has the reasoning and what was cut;
CHANGELOG.md has what each release changed.
Install
On macOS or Linux, in one line:
curl -fsSL https://omatty.com/install.sh | sh
With brew on your PATH it hands off to the Homebrew tap, so upgrades stay in
one place. Otherwise it downloads the release archive for your platform
(darwin or linux, amd64 or arm64), refuses it unless it matches the release's
checksums.txt, and puts omatty in ~/.local/bin, without sudo.
OMATTY_VERSION=vX.Y.Z picks a release and OMATTY_INSTALL_DIR another
directory. Running it again upgrades. It is
scripts/install.sh; read it before you pipe it into a
shell.
With Homebrew directly:
brew install WilsonSousajr/tap/omatty
Or by hand: take the archive for your platform from the
latest release,
check it against checksums.txt, and put omatty on your PATH. No Go needed
any of these ways.
From source, with Go 1.26:
go install github.com/WilsonSousajr/omatty/cmd/omatty@latest
Or @vX.Y.Z for a given release rather than the tip of main; from a clone,
go install ./cmd/omatty does the same thing, with $(go env GOPATH)/bin on
your PATH.
Every way needs git and claude on your PATH. omatty --version says which
build you ended up with.
Optionally, dtach:
brew install dtach # or: apt install dtach
With it, quitting omatty detaches from your sessions instead of ending them,
and relaunching reattaches to the same running claude — a turn in flight
keeps going while omatty is closed, and pgup still reaches the whole
conversation afterwards, because the history is Claude Code's own. Without it omatty works exactly as before
and says so once at startup; quitting ends each session, and relaunching
resumes the conversation from its transcript rather than the turn.
Install rather than go build -o omatty: a binary left in the working tree
goes stale the moment you rebuild anywhere else, and ./omatty will happily
run last week's code while the tests pass on this week's.
Use
omatty discover # pick from the repos claude already knows
omatty adopt my-app # pick from the claude sessions already in it
omatty add ~/Projects/my-app # or register one by hand
omatty rm my-app # forget a project (the repository stays)
omatty new my-app main # a session on the main checkout
omatty new my-app parser-fix parser-fix # a session on a fresh worktree
omatty gate my-app # show the gate, or propose one and confirm
omatty gate my-app --detect # print the proposal, write nothing
omatty carry my-app .env certs # files every new worktree of it carries
omatty carry my-app # show that list
omatty sessions --json # every session, for a script
omatty status --json # each session's status and tokens, read from its transcript
omatty # run the TUI
omatty --version # which build is this
omatty carry is what makes a fresh worktree able to run the project. A
worktree is a clean checkout, so nothing git ignores is in it: .env, local
certificates, generated config. Name those paths once per project and every
worktree omatty creates afterwards gets a copy, before Claude starts in it —
so a gate step fails because the code is wrong, not because .env was
missing. Paths are relative to the main checkout; directories are copied
recursively, modes are preserved, symlinks are copied as links, a file the
worktree already has is left alone, and a path that is not there yet is
skipped with a note rather than treated as an error. The list lives in
~/.omatty/state.json, per project, not in the repository — a clone does not
get to choose which of your files are copied.
omatty discover reads Claude Code's own transcript store and offers the
repositories you have actually used it in, most recent first — the ones still
on disk, that are still git repositories, with worktrees folded into the
repository they came from. On a well-used machine that is 34 directories in
the store collapsing to 6 worth listing. It only ever proposes: nothing is
registered until you pick it.
omatty gate <project> --stats is the only thing omatty measures about itself:
the mean time from a session being registered to its pull request merging, and
the share of the gate runs that followed a turn which passed. Two numbers, local
only, nothing leaves the machine. A project that has measured nothing says so
rather than reporting 0% - a rate over no runs is not a rate.
the numbers for omatty:
lead time 3h30m (mean over 4 merged session(s))
first-pass gate 75% (8 run(s) after a turn)
omatty gate reads the repository and proposes the check line it already
uses — gofmt, go vet, golangci-lint, go test -race, a coverage script;
cargo fmt --check, cargo clippy, cargo test; ruff and pytest; or the
lint and test scripts a package.json defines. Like discover, it only
proposes: nothing is written, and nothing is ever run, until you confirm it.
A coverage step also declares the profile it writes, and the listing you
confirm says so:
cov $ ./scripts/check-coverage.sh [coverage] -> cover.out
That path is read out of the session's own directory when its gate finishes,
and it is what puts the uncovered markers on the diff. Go profiles and lcov are
both understood, told apart by content rather than by file name. A project that
writes its profile somewhere else names it in ~/.omatty/state.json; a project
that declares none simply gets no overlay.
A step can be anything your shell runs, including a hostile review by a model:
docs/llm-audit-gate.md is the recipe, with a working script, and it is honest
about the three things that makes awkward - it is not deterministic, it costs
money on every run, and the diff it reads is untrusted input.
Inside the TUI every keystroke goes to Claude except the ctrl+o leader:
| Key |
Action |
ctrl+o j / ctrl+o k |
move between sessions |
ctrl+o ] / ctrl+o [ |
move between projects, including one with no sessions yet |
ctrl+o tab |
fold or unfold the project the cursor is in; a click on its header does the same |
ctrl+o n |
new session on the main checkout; with two or more agents installed, it then asks which one runs it |
ctrl+o N |
new session on a fresh worktree |
ctrl+o d |
open or close the diff pane |
ctrl+o f |
open or close the file tree |
ctrl+o g |
open or close the gate pane, and run the gate |
ctrl+o i |
open or close this project's issues and pull requests |
ctrl+o z |
zoom the review column over the session pane, or back; esc also brings the split back |
ctrl+o m |
hand the mouse back to your terminal, or take it back |
ctrl+o r |
restart a crashed session |
ctrl+o s |
stop the selected session's claude, keeping the session; enter resumes it |
ctrl+o u |
put the session's worktree back to the start of its last turn, after a confirmation |
ctrl+o p |
ship a green session: push and open its pull request, or merge one already green |
ctrl+o B |
rename a worktree session's branch |
ctrl+o R |
rename the selected session |
ctrl+o c |
choose the agent the selected project's new sessions run |
ctrl+o x |
archive the selected session, or forget an empty project |
ctrl+o / |
jump to a session by typing part of its name |
ctrl+o a |
register a project claude already knows you use |
ctrl+o A |
adopt a claude session already in this project |
ctrl+o ? |
show every key, starting with the ones for the face in front of you; / filters them |
ctrl+o q |
quit |
ctrl+o s ends a session's claude process and frees its memory (a few
hundred MB each) without forgetting the session: its card keeps its status and
age, and its queued review comments stay. The pane then says it is stopped, and
enter starts it again with --resume, so nothing is lost but a turn that was
in flight. Unlike ctrl+o x there is no confirmation, because nothing is lost
that enter cannot bring back.
ctrl+o R opens the session's title for editing, pre-filled, so correcting a
typo is a small edit. enter confirms, esc cancels. The title is
display-only, so a rename never disturbs the session itself.
Mouse
The wheel scrolls whatever is under it: Claude's transcript in the pane, the
diff, tree or preview in the review column. A click on a sidebar row selects
that session. A click on a row of the review column puts the cursor there and
gives the column the keys, and a click on the × at the right end of the
column's rule closes it. The column's rule reads ─ review ─────× so it is
told apart from a diff Claude draws inside its own pane, which is Claude's to
open and close.
A drag inside a session pane selects that pane's text and copies it on release.
The run is highlighted while the button is down, and it is clipped to the pane:
the sidebar and the review column share those screen rows, and the host
terminal's own selection takes every column on them, so a copy that wrapped a
line used to arrive with their text mixed in (#360). Two limits are worth
knowing. A line Claude wrapped for you arrives with a newline in it, because
the emulator does not record where a soft wrap happened. And only what is on
screen can be selected, because the pane has no scrollback of its own.
shift/opt+drag still hands the drag to your terminal, which is how you
select across omatty's panes rather than inside one.
All of that costs the one thing a terminal normally does with a pointer:
while omatty is asking the host for mouse events, the host will not make a
selection of its own. ctrl+o m hands the mouse back, and the header says
mouse off while it is handed back. The terminal then selects, copies on
select and opens its context menu exactly as it does everywhere else; the
wheel, the sidebar's clicks and the review column's stop working until you
press ctrl+o m again. The keyboard is untouched either way.
Paste and copy
A paste goes to the pane that has the keys: Claude's prompt, or the note and
filter lines when one of those is open. It arrives as pasted text, so a
multi-line paste does not submit on every line and nothing is sent until you
press enter.
When the program in the pane copies something itself - Claude's own copy
affordances, tmux's set-clipboard, neovim's clipboard provider - it lands
on your clipboard. omatty lifts the OSC 52 the program writes out of the
pane's output and hands it to your terminal, which the embedded emulator
would otherwise have dropped. Nothing is asked first, exactly as in any other
terminal. The read direction is not bridged: a program in a pane cannot ask
for your clipboard's contents.
Taking text off the screen yourself is still your terminal's job, and
because omatty asks it for the mouse (for the wheel and for clicks), a plain
drag is a scroll rather than a selection. For one selection, hold the modifier
your terminal bypasses reporting with - shift on Ghostty, kitty, xterm and
Alacritty, option on Apple Terminal and iTerm2 - and drag. For anything
longer, ctrl+o m gives the mouse back until you ask for it again. The
selection is the composed screen, so keep it inside one pane. Text that has scrolled out of
the pane is in Claude's transcript, not on screen; pgup reaches it.
On an empty project's header, ctrl+o x forgets the project instead - the
same thing omatty rm <project> does from the shell. The repository is never
touched; a project still holding sessions is refused until they are archived.
ctrl+o x asks before it does anything. Archiving stops the session and drops
it from the sidebar, but the transcript stays on disk, so nothing is lost that
claude --resume could have found. A session on a worktree gets a second
answer, on its own key, that also runs git worktree remove — that one
discards uncommitted work, which is why it is never the key your hand reaches
for. A session on the main checkout is never offered it: omatty did not create
that directory, so it will not delete it.
ctrl+o / filters every session in every project as you type, matching on the
title and the project name, and enter jumps to the one under the cursor. j
and k are filter text here rather than movement — ctrl+j and ctrl+k move
— because a switcher you cannot type "jk" into is not a switcher.
ctrl+o a is omatty discover inside the TUI: the same proposed list, tab
to mark several, enter to register them all at once.
ctrl+o A is the same thing one level down: the claude sessions already in the
project under the cursor that omatty does not yet track, titled by the first
thing you typed in each. Adopting one registers it and opens it in a pane,
resumed where it left off. It is how a session you started in a plain terminal,
or one lost from state.json, gets back on the sidebar. omatty adopt <project> does the same from the command line. An adopted session is never
treated as a worktree omatty owns, so archiving it will not offer to delete its
directory.
esc, shift+tab, ctrl+r and ctrl+c all reach Claude untouched.
Configuration
omatty reads ~/.omatty/config.toml at startup. Every key is optional; with
no file at all these are the values in force:
leader = "ctrl+o" # the one key omatty intercepts; bubbletea spelling ("ctrl+a", not "C-a")
claude_bin = "claude" # the binary each session runs, resolved on PATH or absolute
default_agent = "claude" # the agent a new session runs unless its project or ctrl+o n says otherwise
worktree_root = "~/.omatty/wt" # where `omatty new ... <branch>` and ctrl+o N put worktrees
base_branch = "" # fork worktrees from this branch; empty means the checkout's current one
[agents.claude] # one table per agent; bin is its binary, and here wins over claude_bin
bin = "claude"
# [agents.codex] # built in: status, waiting and resume from codex's own hooks and
# bin = "codex" # rollout, passed per run as -c flags; nothing is written to ~/.codex.
# # codex binds ctrl+o to copy - under omatty that key is the leader
# [agents.aider] # any other agent, declared by its command: it runs in the
# command = ["aider", "--no-auto-commits"] # session's directory, and omatty knows only whether it runs
[naming]
model = false # let a headless claude call improve auto-derived session titles
[gate]
max_parallel = 2 # how many gates may run at once
auto = false # run a session's gate when its turn ends
[sessions]
lazy_start = true # at boot, start only sessions dtach still holds; enter starts the rest
idle_stop = "0" # stop a session quiet this long, keeping it; "0" is off
[ui]
icons = "plain" # "nerd" draws every state mark with a Nerd Font's icons
[forge.hosts] # empty: only the public forges' hosts are recognised
ui.icons is "plain" unless you ask: a Nerd Font glyph in a terminal without
one is a box, which is worse than no icon. Set "nerd" if your terminal font is
a Nerd Font and every state mark - a gate step's verdict, a card's gate strip, a
pull request's CI - switches to its icon at once, and the file tree gains an
icon per file type and folder. Any other value is refused at
startup, naming the key.
sessions.lazy_start is on because every claude costs a few hundred MB
before its first turn, and a boot that started all of them paid that for
sessions nobody opened. With it on, omatty reattaches the sessions dtach is
still holding and leaves the rest stopped: their pane says so, and enter
starts one with --resume. Without dtach nothing survives a quit, so a lazy
boot starts nothing and each session starts the first time you use it. Set it
to false to start every session at boot, as before.
Lazy start stops the fleet re-forming; it does not disband one. Sessions dtach
is already holding are reattached, not stopped, so quitting and relaunching
omatty with eleven held sessions still leaves eleven running. They go away on a
reboot, with ctrl+o s, or with sessions.idle_stop.
sessions.idle_stop takes a duration such as "90m" or "72h" (there is no
d unit), and stops a session that has been quiet that long exactly as ctrl+o s would: its
process ends, its row, transcript and comments stay, and enter resumes it.
Quiet means that its last turn in the transcript, the moment omatty last started
it, and the last key you typed into its pane are all older than the threshold.
A session you are looking at, one in the middle of a turn, and one waiting on
your answer are never stopped. It is off by default, because ending a process
you did not ask to end costs a turn if omatty is wrong about quiet.
gate.auto is off because a test suite on every idle costs real time. With it
on, a session that finishes a turn is gated immediately and a red result
notifies you when omatty is not the window you are looking at. Either way, only
a gate you confirmed is ever run.
[forge.hosts] names a forge omatty cannot recognise by its hostname, such as a
self-managed GitLab, a Forgejo, a Bitbucket Data Center or a GitHub Enterprise.
An Azure DevOps Server can be named too, but is not read yet: Azure's tokens
are for Azure DevOps Services, and a Server gets a token of its own in #596.
[forge.hosts]
"git.corp.example" = "gitlab"
"code.internal" = "forgejo"
"ghe.corp.example" = "github"
The kinds are github, gitlab, azure, gitea (or its alias forgejo) and
bitbucket. A project's forge is read from its origin remote's host. The
public hosts - github.com, gitlab.com, dev.azure.com, codeberg.org, gitea.com,
bitbucket.org - need no line here, and a line here overrides them. A host
omatty does not know shows no pull requests or issues rather than a guess. An
unknown kind, or a key that is not a bare host name (a scheme, a port or a
path in it would never match), is refused at startup.
A project that has no sessions yet is selectable too: ctrl+o ] reaches
it, the pane says which project is empty, and ctrl+o n creates its first
session there. Archiving a project's last session leaves the cursor on that
project for the same reason.
A project you are not working in can be folded away with ctrl+o tab, or a
click on its header, the way a directory folds in the file tree: its sessions
go behind a ▸ header that still shows how many there are and the most urgent
status among them, so one waiting on you is not hidden. The fold is kept in
state.json across restarts. Jumping to a folded session with ctrl+o /, or
creating one there, unfolds the project.
A session created with ctrl+o n and a blank title is named by the first
prompt you type into it. ctrl+o N asks for nothing either: the worktree is
created on a placeholder branch named after the session - omatty-2501d6b4 -
and the same first prompt renames it to fix-the-horizontal-wheel-pan, but
only while the branch has nothing committed to it. After the first commit the
name is in a history you may already have pushed, so it stays and ctrl+o B
is how you change it. A branch you type at creation is never renamed, and the
worktree's directory keeps its original name whatever the branch is called:
Claude is running in it. With naming.model = true, a second, headless
claude -p --model haiku call then turns that prompt into a short slug such
as diff-horizontal-scroll-fix. It is off by default because it spends your
quota: the call carries the CLI's own system prompt, which cost about $0.60 at
list price when measured. It never blocks, never touches the footer, and a
title you set with ctrl+o R always wins.
A malformed file, a wrong type or a key omatty does not know is an error at
startup naming the file and the key, printed before the TUI opens. A blank
leader is refused: with a session focused ctrl+c belongs to Claude, so a
leader that never arrives would leave no way to quit.
Review
ctrl+o d opens a diff of everything the session changed: its commits since
it branched, its uncommitted edits, and the files it created, all in one view.
The pane takes the keys while it is open.
| Key |
Action |
j / k |
move through the diff |
g / G |
the first row, or the last - the same on every face of the column |
ctrl+d / ctrl+u |
half a page down, or up |
h / l |
pan left and right along a line too wide for the column |
0 |
jump back to the left edge |
c |
comment on the line under the cursor |
C |
comment on part of the line: type the words, then the note |
d |
delete the comment under the cursor |
r |
reload the diff |
t |
switch between the whole session and only this turn |
o |
open the preview of this file with the line under the cursor on top |
S |
send every pending comment to Claude as one message |
esc |
give the keys back to Claude, leaving the pane open |
esc and ctrl+o d are a round trip: esc hands the keys back to Claude with
the pane still on screen, and ctrl+o d takes them back. Only a press while the
pane already has the keys closes it.
Comments are anchored to the content of a line, not its number, so they stay
put while Claude edits the file underneath you. A comment whose line disappears
floats to the top of its file marked (moved) rather than silently attaching
itself to the wrong code.
You can leave several comments on one line - they are all shown under it,
all numbered in the message, and d takes the one under the cursor. And C
comments on part of a line: type or paste the words you mean, then the note,
and the message tells Claude about: "do(ctx, timeout)" rather than pointing at
the whole line. The fragment is checked against the line before it is queued, so
a typo is caught while the line is still in front of you. It is stored as text
rather than as a column range, because a range into a line Claude has since
rewritten points at whatever now happens to sit there - and if the line survives
an edit that removes those words, the note still travels and says the fragment is
no longer in it.
ctrl+o u puts the worktree back to where that baseline was taken - the start
of the session's last turn. It asks first, and the question names how many files
will be discarded. Files the turn created go with it; a gitignored file that
existed before the turn - the .env the session needs to run - is in neither
snapshot and is never touched, and your index, HEAD and stash are not moved
either. It refuses mid-turn, and when no baseline has been taken yet. omatty
does not tell the session what happened: sending anything is S's job and needs
you.
t narrows the diff to what changed since you last sent the session a
prompt, and back. omatty takes the baseline when the prompt hook fires, as a
git tree under refs/omatty/turn/<session> built through a temporary index,
so your staging, HEAD and stash are never touched; archiving the session
deletes it. Comments work the same in both views: one outside this turn is
hidden rather than shown as moved, and S still sends it.
S sends the whole batch as a single prompt — file:line, the quoted line and
your note, numbered — so Claude answers them together instead of one at a time.
What it sent stays on its line, muted and marked (sent 14:36), so the next
turn's diff can be read against what you asked; it is never sent again, and it
goes once its line does. The title's count is what the next S would send.
Comments live in memory: quitting omatty drops them.
File tree
ctrl+o f shows the same column as the session's worktree instead of its diff.
A letter marks every file the session changed - M modified, A added, D
deleted, R renamed - in the colour the diff gives that state, and a directory
holding one reads as M, so you can see the shape of a change before reading
it. A deleted file keeps its row, in red, until the next listing without it.
Files nobody wrote are folded out of the listing: lockfiles, protobuf
output, build/, dist/, coverage/, vendor/, node_modules/, and anything
the repository's own .gitattributes marks linguist-generated. A lockfile does
not belong in the queue beside source, and a generated file has no test and never
will - so the coverage markers leave it alone too, rather than making it look
worse than it is. The title says how many are folded (⊞3) and . brings them
back: they are folded, not hidden. Detection is the repository's declaration
first, then the name, then the Go // Code generated ... DO NOT EDIT. header.
v marks the file under the cursor as read. It keeps a ✓ and goes quiet
until its diff changes, at which point it reads ~ - changed since you read
it. On a long session that is the difference between reviewing the turn and
reviewing everything again from the top. What is compared is the file's diff
content, never its modification time: the agent rewrites files while you are
reading them, so a timestamp only says that something was written. The marks
are one session's, they are not written to disk, and quitting omatty drops
them. The two views share one column:
ctrl+o d and ctrl+o f switch between them, and either key closes the column
when it already shows that view.
| Key |
Action |
j / k |
move through the tree, or scroll a preview |
g / G |
the first row, or the last - the same on every face of the column |
ctrl+d / ctrl+u |
half a page down, or up |
enter |
fold or unfold a directory, or preview a file |
h / l |
pan left and right along a line too wide for the column |
0 |
jump back to the left edge |
r |
re-list the worktree |
/ |
filter the tree as you type; enter keeps the filter, esc clears it |
c |
only the files the session changed and the folders above them, or the whole tree again |
a |
attach the row, or the previewed file, to the prompt as @path and go back to typing |
v |
mark the file read: ✓ while its diff is unchanged, ~ once the session changes it again |
. |
show the generated files the tree folded away, or fold them again |
o |
from a preview, jump to the diff at that line; from a diff line, o opens the preview there |
esc |
from a preview back to the tree; from the tree, lift the filter, then back to Claude |
A preview is syntax-highlighted when the file's type is known, in colours
kept apart from the ones the diff uses for added and removed lines, so a
coloured preview never reads as a diff. Files over 64 KiB draw plain and say
so under the last line.
The column is narrow, so a long line runs off its right edge. h and l scroll
it sideways eight columns at a time and the title shows how far, as · +24. The
same keys work in the diff.
The listing is tracked plus untracked files with .gitignore honoured — what
git thinks the worktree contains, not what is on disk. A preview reads at most
256 KiB and says so when it stops; a binary file says it is binary rather than
spraying the pane.
Issues and pull requests
ctrl+o i turns the same column into the project's tracker: its open issues,
then its open pull requests under a rule, each row naming the number, one label
or the pull request's CI mark, the title and how long since it last moved. The
counts are in the title, and on every project's header in the sidebar - 13i 2p
- so "how many are open" needs no keypress at all.
projects · 2 │ omatty ▎ review loop · develop │ tracker · omatty · 13 issues · 2 prs
───────────────────────────┼─────────────────────────────────┼─ review ──────────────────────────×
omatty 13i 2p│ │#399 feat filter the tracker
▎● review loop │ │#397 feat read one issue or p
▎ 399-filter-the-t │ │#315 Upstream: 4 MiB par
other-app 4i 1p │── pull requests ──────────────────
│ │#405 ✓ work from an issue
It is the one view that belongs to a project rather than a session, so it works
on a project you have registered and never started a session in - which is when
its issues matter most.
| Key |
Action |
j / k |
move through the list, or scroll an open item |
g / G |
the first row, or the last - the same on every face of the column |
ctrl+d / ctrl+u |
half a page down, or up |
] / [ |
the first pull request, or back to the first issue |
tab |
fold the list the cursor is in to its heading and count, or open it again |
enter |
read the item under the cursor: its body and its comments |
/ |
filter by number, title or label as you type; enter keeps it, esc clears it |
n |
start a worktree session named and branched from the issue |
a |
type the item's reference into the selected session's prompt, unsent |
b |
open the item in your browser |
r |
read both lists again now, and try again a forge that could not be read |
h / l / 0 |
pan along a row too wide for the column |
esc |
from an item back to the list; from the list, lift the filter, then back to Claude |
n is the point of showing you issues at all: it creates the worktree, names
the branch after the issue (399-filter-the-tracker) and titles the session
#399 …, then hands you the keyboard so the next thing you type is a prompt.
a is the smaller version for a session you already have: it pastes
issue #399 into the composer and stops - no carriage return, so nothing
is sent until you send it. omatty never submits a turn on your behalf.
Everything here is read through your forge's own CLI, with your own
authentication, or through its REST API with a token you already set - see
Forges. The tracker itself writes nothing: no comment, no close, no
label. The board stays the forge's; this is a window onto it. The one thing
omatty does write to the forge is ctrl+o p, below - and only on that
keypress.
Forges
A project's forge is read from its origin remote's host, and each forge is
read through its own CLI when it is installed, or its REST API when it is not,
with a token borrowed from the environment for that one call. omatty stores no
token: not in its config, state.json, a log line or an error, and never over
plain http.
| Forge |
CLI |
REST, without the CLI |
Pull requests + CI |
Issues |
Item |
Browse |
Ship (ctrl+o p) |
| GitHub, GitHub Enterprise |
gh |
GH_TOKEN or GITHUB_TOKEN; GH_ENTERPRISE_TOKEN on an Enterprise host |
✓ |
✓ |
✓ |
✓ |
through gh (#331), not yet run by the probe; protection read over both |
| GitLab, self-managed GitLab |
glab |
GITLAB_TOKEN (or GITLAB_ACCESS_TOKEN) |
✓ through glab; REST untested |
✓ |
✓ |
✓ |
untested; protection read through glab |
| Gitea, Forgejo, Codeberg |
tea 0.12 or later, with a login for the host |
GITEA_TOKEN with GITEA_INSTANCE_URL naming the host; a public repository reads anonymously |
✓ over REST; tea untested |
✓ |
✓ |
✓ |
untested; protection read over REST |
| Bitbucket Cloud |
none exists |
BITBUCKET_TOKEN: an access token alone, or an API token with BITBUCKET_USER, your Atlassian account's email |
untested |
elsewhere: Bitbucket retired its issue API |
untested |
untested |
untested; protection needs repository admin |
| Bitbucket Data Center |
none exists |
BITBUCKET_DC_TOKEN with BITBUCKET_DC_URL naming the instance (and BITBUCKET_DC_USER for Basic auth) |
untested |
elsewhere, in Jira |
untested |
untested |
untested; protection needs repository admin |
| Azure DevOps |
az, logged in |
AZURE_DEVOPS_EXT_PAT |
✓ |
✓ work items |
✓ |
✓ |
✓ open, protection and merge, over both |
A ✓ is a claim a real run showed: testdata/forgeprobe against a real
repository on that forge, read by a person (#463). Untested means the code is
there and its tests pass against recorded answers, and no real run has been
made yet - usually for want of a token or an instance to run it against. The
issues column says elsewhere where the forge keeps no issues of its own; the
tracker then lists the pull requests under a rule saying so.
A token is only ever sent to the instance it is for. Gitea's and Bitbucket
Data Center's are bound by GITEA_INSTANCE_URL and BITBUCKET_DC_URL - for an
ssh clone, which carries no web address, the latter also says where the
instance's web root is, context path and port included - and a Bitbucket Cloud
token goes to Bitbucket Cloud alone.
Without the CLI and without the token, a project's column says which is
missing - "glab is not installed and GITLAB_TOKEN is unset" - and omatty stops
asking that forge until it restarts. A token the forge refuses says so the same
way, naming the host and the variable. A forge omatty cannot recognise by its
host is named in [forge.hosts], above.
Shipping a green session
ctrl+o p on a session whose gate is green does one of two things, and refuses
with a reason the rest of the time.
No pull request yet: it pushes the branch and opens one against the branch
the worktree was forked from - with gh pr create --fill on GitHub, so the body
is your own commits, and with an empty description elsewhere: omatty composes
nothing on your behalf. It refuses if the worktree has uncommitted work — the gate verified a
working tree and a push moves commits, so shipping uncommitted work would open a
pull request that differs from what was checked. Commit it in the session; omatty
will not write a commit message for you, the same way it never submits a turn for
you.
A pull request already open: it merges it, but only when both verdicts are
already green — your gate here, and the checks on the forge. Otherwise it says
which one is missing. It uses the repository's own merge method, never deletes
the branch, never overrides a check, and it refuses to merge into a protected
branch at all, as the forge itself reports protection - a protected branch on
GitHub, GitLab or Gitea, a restriction on Bitbucket, a blocking branch policy on
Azure DevOps: main moves by a promotion pull request, and a key that could
merge there would route around omatty's own release gate. If it cannot tell
whether the base is protected, it refuses. On Bitbucket, reading branch
restrictions needs repository admin; without it, every merge is refused, and
the refusal says why.
It merges into the branch the session was forked from and nowhere else: a pull
request Claude opened against another branch is refused, naming both, and
protection is read on the branch the pull request actually targets. And it
merges the commit the card showed green: a push after the last poll is never
merged unread, on any forge. Azure DevOps completes a merge after accepting
it, so there the notice says the merge was asked for and has not finished yet.
GitHub can delete a branch on merge by a repository setting,
delete_branch_on_merge, which no merge request can turn off: on a repository
with it on, the branch goes when the pull request merges, whoever merges it.
What it will never do is merge when the checks go green. That acts because a
check changed, with nobody reading, which is the line this whole tool is built
around — and every forge's own auto-merge already does it, on the forge, where it
belongs. omatty turns it off by name in every merge it sends.
docs/ROADMAP.md argues the boundary in full.
The cost, on top of the pull request reads the cards already make: one issue
list per project every five minutes, one more when you open the tracker or press
r, and one read of an item you open, cached until you press r on it. Nothing
at all while omatty is in the background, and never more than once in thirty
seconds for one project unless you asked. A forge whose CLI and token are both
missing, or that refused the token, is asked again only every five minutes and
on r - so installing gh or fixing a token mid-run is picked up without a
restart. An item is read to 64 KiB and says so if there was more. For a
repository on no forge omatty reads, the column says so and the sidebar headers
stay as they were.
Session status
Each sidebar row shows what its session is doing and how long it has been in
that state, and the focused session's header shows its cumulative token usage:
a bar and a percentage for how much of the input claude read back from cache
(▰▰▰▰▰▰▱▱ 80% cached), then the in/out counts. Cache reads are what a
long session's prompts mostly are, and the meter says at a glance whether that
is holding.
| Glyph |
Meaning |
- |
idle |
* |
thinking |
@ |
running a tool |
! |
waiting on you (a permission prompt) |
+ |
turn finished |
∅ |
claude exited (ctrl+o r restarts it) |
A card's second line names the session's branch and its diffstat. Once that
branch has a pull request on the project's forge, the branch becomes the pull
request and one mark for it (GitLab and Azure DevOps write it !349):
| Line two |
Meaning |
#349 ✓ |
checks passing |
#349 ◍ |
checks still running |
#349 ✗ |
a check failed |
#349 ⚠ |
conflicts, or behind its base |
#349 |
no checks |
#349 merged / #349 closed |
the pull request is done |
#349 ? |
the last read failed; the old verdict is not shown as current |
omatty reads each project's pull requests - the open ones, then the thirty most
recently finished - when omatty regains focus, when a session finishes a turn,
and every minute while it has focus - never while it is in the background,
never more than once in thirty seconds for one project, and never for longer
than thirty seconds. A check verdict that is final is kept for its commit and
not asked again. For a repository on no forge omatty reads, the card shows the
branch as before and says so once in the log. A pull request from a fork is
never taken for the session's, whatever its branch is called; a session on the
main checkout shows open pull requests only, and a merged or closed one shows
only while the checkout is still at its head commit.
When a session starts waiting on you or finishes a turn while omatty is in the
background, you get a desktop notification. On macOS you may need to allow
notifications from your terminal app in System Settings once.
Status comes from Claude Code hooks (written to ~/.omatty/hooks.json, never
your own ~/.claude/settings.json) and from each session's transcript. If the
hook socket cannot be created, omatty still shows status from the transcript.
State lives in ~/.omatty/state.json, worktrees in ~/.omatty/wt/, logs in
~/.omatty/logs/. Your ~/.claude/settings.json is never read or written.
Contributing
Read AGENTS.md. It is the canonical instruction file for both
people and coding agents.
License
MIT - see LICENSE.