omatty

module
v0.8.2 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2026 License: MIT

README

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.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.

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                                # 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
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 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
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

[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

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.

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
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
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 own gh, with your own authentication. The tracker itself writes nothing: no comment, no close, no label. The board stays GitHub'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.

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, so the body is your own commits. 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 --delete-branch, never --admin, and it refuses to merge into a protected branch at all: 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.

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 GitHub's auto-merge already does it, on the forge, where it belongs. docs/ROADMAP.md argues the boundary in full.

The cost, on top of the two gh pr list calls the cards already make: one gh issue list per project every five minutes, one more when you open the tracker or press r, and one gh issue view or gh pr view for an item you open, cached until you press r on it. Nothing at all while omatty is in the background, never more than once in thirty seconds for one project, and nothing after gh is found missing. An item is read to 64 KiB and says so if there was more. Without gh, or for a repository that is not on GitHub, the column says which 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 GitHub, the branch becomes the pull request and one mark for it, read through your own gh:

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 with two gh pr list calls - 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. Without gh, or for a repository that is not on GitHub, 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.

Directories

Path Synopsis
cmd
omatty command
Command omatty runs the terminal ADE: multiple projects and multiple parallel Claude Code sessions in one window.
Command omatty runs the terminal ADE: multiple projects and multiple parallel Claude Code sessions in one window.
internal
agent
Package agent describes the coding agents omatty can run.
Package agent describes the coding agents omatty can run.
config
Package config reads ~/.omatty/config.toml.
Package config reads ~/.omatty/config.toml.
coverage
Package coverage turns a coverage profile into per-line verdicts, so the review column can say which of the lines a session just added are not exercised by anything.
Package coverage turns a coverage profile into per-line verdicts, so the review column can say which of the lines a session just added are not exercised by anything.
crap
Package crap scores every function by the C.R.A.P. metric - Change Risk Anti-Patterns - which is cyclomatic complexity weighted by how much of the function its tests actually reach.
Package crap scores every function by the C.R.A.P. metric - Change Risk Anti-Patterns - which is cyclomatic complexity weighted by how much of the function its tests actually reach.
depgraph
Package depgraph measures the shape of omatty's own import graph, using Robert Martin's package metrics.
Package depgraph measures the shape of omatty's own import graph, using Robert Martin's package metrics.
detach
Package detach is omatty's only route to the dtach binary.
Package detach is omatty's only route to the dtach binary.
discover
Package discover proposes repositories to register, read from Claude Code's own transcript store (#91).
Package discover proposes repositories to register, read from Claude Code's own transcript store (#91).
forge
Package forge is omatty's interface over the gh CLI (#310): a repository's pull requests and their CI, its open issues, one item in full - and, since #331, the three writes a ship key makes.
Package forge is omatty's interface over the gh CLI (#310): a repository's pull requests and their CI, its open issues, one item in full - and, since #331, the three writes a ship key makes.
fuzzy
Package fuzzy ranks strings against a subsequence query, for omatty's session switcher (#42) and project picker (#91).
Package fuzzy ranks strings against a subsequence query, for omatty's session switcher (#42) and project picker (#91).
gate
Package gate runs a project's own verification commands and says, per step, whether they passed.
Package gate runs a project's own verification commands and says, per step, whether they passed.
golist
Package golist is omatty's only route to the `go list` command.
Package golist is omatty's only route to the `go list` command.
highlight
Package highlight is omatty's seam over chroma, the way termwrap is over bubbleterm and vcs over git: nothing else imports the highlighter, so a change in it lands in one package (invariant 4 in spirit, #197).
Package highlight is omatty's seam over chroma, the way termwrap is over bubbleterm and vcs over git: nothing else imports the highlighter, so a change in it lands in one package (invariant 4 in spirit, #197).
hooks
Package hooks generates the settings file that makes Claude Code report status to omatty, and implements the `omatty hook` command that does the reporting.
Package hooks generates the settings file that makes Claude Code report status to omatty, and implements the `omatty hook` command that does the reporting.
keys
Package keys decides where a keystroke goes.
Package keys decides where a keystroke goes.
notify
Package notify posts desktop notifications when a session needs attention while omatty is in the background.
Package notify posts desktop notifications when a session needs attention while omatty is in the background.
paste
Package paste owns invariant 8: text omatty sends into a session's PTY on the operator's behalf travels between bracketed-paste delimiters, and only a deliberate carriage return submits it.
Package paste owns invariant 8: text omatty sends into a session's PTY on the operator's behalf travels between bracketed-paste delimiters, and only a deliberate carriage return submits it.
paths
Package paths resolves every filesystem location omatty reads or writes.
Package paths resolves every filesystem location omatty reads or writes.
registry
Package registry holds omatty's projects and sessions and persists them.
Package registry holds omatty's projects and sessions and persists them.
review
Package review turns a session's diff into hunks, anchors comments on their content rather than their line numbers (invariant 7), and composes the one message that sends them back to Claude (M3).
Package review turns a session's diff into hunks, anchors comments on their content rather than their line numbers (invariant 7), and composes the one message that sends them back to Claude (M3).
supervisor
Package supervisor owns the lifecycle of the claude process behind each session.
Package supervisor owns the lifecycle of the claude process behind each session.
tally
Package tally measures the two numbers #332 asks for: how long a session takes to reach a merged pull request, and how often a project's gate passes the first time.
Package tally measures the two numbers #332 asks for: how long a session takes to reach a merged pull request, and how often a project's gate passes the first time.
termwrap
Package termwrap is omatty's only route to an embedded terminal emulator.
Package termwrap is omatty's only route to an embedded terminal emulator.
ui
Package ui renders omatty.
Package ui renders omatty.
vcs
Package vcs is omatty's only route to git.
Package vcs is omatty's only route to git.
watcher
Package watcher derives each session's live status from two sources: hook events over a unix socket (fast, and the only source that can tell "waiting for you" from "tool running") and the transcript JSONL (the truth on attach, self-healing, and the only source of age and tokens).
Package watcher derives each session's live status from two sources: hook events over a unix socket (fast, and the only source that can tell "waiting for you" from "tool running") and the transcript JSONL (the truth on attach, self-healing, and the only source of age and tokens).
tools
crapcheck command
Command crapcheck scores every function in ./internal/...
Command crapcheck scores every function in ./internal/...
depcheck command
Command depcheck reports omatty's own package dependency structure and enforces the two rules that hold across it.
Command depcheck reports omatty's own package dependency structure and enforces the two rules that hold across it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL