omatty

module
v0.11.0 Latest Latest
Warning

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

Go to latest
Published: Oct 5, 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.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.

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
cli
Package cli is omatty's second driving adapter (ADR 0001, "The second driving adapter"; migration step 7.1, #653): one-shot reads through the same services the TUI uses, written as JSON for a script.
Package cli is omatty's second driving adapter (ADR 0001, "The second driving adapter"; migration step 7.1, #653): one-shot reads through the same services the TUI uses, written as JSON for a script.
domain/agent
Package agent describes the coding agents omatty can run.
Package agent describes the coding agents omatty can run.
domain/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.
domain/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.
domain/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.
domain/forge
Package forge is what omatty knows about a forge's work, independent of the forge: a pull request and its CI and review state, an issue, one item in full with its comments and checks, and how the forge names things (Label).
Package forge is what omatty knows about a forge's work, independent of the forge: a pull request and its CI and review state, an issue, one item in full with its comments and checks, and how the forge names things (Label).
domain/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).
domain/gate
Package gate is the vocabulary of a project's gate - Step, Verdict, StepResult, Report - the caps on what one step's output may contribute, and the prompt Compose writes when a gate fails.
Package gate is the vocabulary of a project's gate - Step, Verdict, StepResult, Report - the caps on what one step's output may contribute, and the prompt Compose writes when a gate fails.
domain/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.
domain/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).
domain/session
Package session is omatty's record of its projects and sessions - Project, Session, State - and the placeholder names a new one starts with.
Package session is omatty's record of its projects and sessions - Project, Session, State - and the placeholder names a new one starts with.
domain/status
Package status is what omatty knows about a session's state: the Kind of each event a transcript or a hook reports, the Status a card shows, the token usage, the hook payload, and Apply, which folds an event into a session's state.
Package status is what omatty knows about a session's state: the Kind of each event a transcript or a hook reports, the Status a card shows, the token usage, the hook payload, and Apply, which folds an event into a session's state.
domain/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.
infra/agentcli
Package agentcli runs the agent's own binary headless for a one-shot answer - today a session's name, asked of its first prompt (#127 step 2) - under a timeout and outside the detach holder, so it dies with omatty.
Package agentcli runs the agent's own binary headless for a one-shot answer - today a session's name, asked of its first prompt (#127 step 2) - under a timeout and outside the detach holder, so it dies with omatty.
infra/config
Package config reads ~/.omatty/config.toml.
Package config reads ~/.omatty/config.toml.
infra/detach
Package detach is omatty's only route to the dtach binary.
Package detach is omatty's only route to the dtach binary.
infra/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.
infra/fsread
Package fsread reads the files omatty only ever reads - a coverage profile, the go.mod beside it - on behalf of the services that declare a port for them.
Package fsread reads the files omatty only ever reads - a coverage profile, the go.mod beside it - on behalf of the services that declare a port for them.
infra/gateexec
Package gateexec runs a project's own verification commands and says, per step, whether they passed.
Package gateexec runs a project's own verification commands and says, per step, whether they passed.
infra/gitdiff
Package gitdiff is omatty's only route to go-gitdiff: it parses git's unified output into internal/domain/review's review.Diff, so nothing else in omatty ever sees go-gitdiff's types (ADR 0001, migration step 3.6b; invariant 4 in spirit).
Package gitdiff is omatty's only route to go-gitdiff: it parses git's unified output into internal/domain/review's review.Diff, so nothing else in omatty ever sees go-gitdiff's types (ADR 0001, migration step 3.6b; invariant 4 in spirit).
infra/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.
infra/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).
infra/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.
infra/hookserver
Package hookserver is omatty's end of the hook socket: it accepts the connections `omatty hook` makes, reads one bounded payload from each, and offers it on - never waiting, so a hook never waits on omatty (invariant 11).
Package hookserver is omatty's end of the hook socket: it accepts the connections `omatty hook` makes, reads one bounded payload from each, and offers it on - never waiting, so a hook never waits on omatty (invariant 11).
infra/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.
infra/paths
Package paths resolves every filesystem location omatty reads or writes.
Package paths resolves every filesystem location omatty reads or writes.
infra/store
Package store is omatty's registry on disk: ~/.omatty/state.json, loaded and saved atomically so a crash cannot leave a truncated file that strands running sessions (invariant 9), and the copy of a project's gitignored files into a new worktree (#309).
Package store is omatty's registry on disk: ~/.omatty/state.json, loaded and saved atomically so a crash cannot leave a truncated file that strands running sessions (invariant 9), and the copy of a project's gitignored files into a new worktree (#309).
infra/transcript
Package transcript reads an agent's JSONL transcript as it grows: the complete lines appended since the last read, and whether the file was cut short in between.
Package transcript reads an agent's JSONL transcript as it grows: the complete lines appended since the last read, and whether the file was cut short in between.
infra/vcs
Package vcs is omatty's only route to git.
Package vcs is omatty's only route to git.
pubsub
Package pubsub is how omatty's services tell their subscribers - the TUI, the notify adapter - that something changed, without either side knowing the other (ADR 0001, "The event model").
Package pubsub is how omatty's services tell their subscribers - the TUI, the notify adapter - that something changed, without either side knowing the other (ADR 0001, "The event model").
service/discovery
Package discovery proposes repositories to register, read from Claude Code's own transcript store (#91).
Package discovery proposes repositories to register, read from Claude Code's own transcript store (#91).
service/gate
Package gate schedules a project's gate for many sessions at once: the Runner bounds how many run together, supersedes a session's stale run, and keeps one session's panic to that session (invariant 6).
Package gate schedules a project's gate for many sessions at once: the Runner bounds how many run together, supersedes a session's stale run, and keeps one session's panic to that session (invariant 6).
service/review
Package review loads a session's diff and turn - through git, parsed by go-gitdiff - reads previews and .gitattributes, and reverts.
Package review loads a session's diff and turn - through git, parsed by go-gitdiff - reads previews and .gitattributes, and reverts.
service/sessions
Package sessions is the session service: the commands that add, adopt, create, rename, rebind, fold and remove projects and sessions, over a StateStore port that internal/infra/store implements.
Package sessions is the session service: the commands that add, adopt, create, rename, rebind, fold and remove projects and sessions, over a StateStore port that internal/infra/store implements.
service/status
Package status 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 status 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).
tui/app
Package app renders omatty: the TUI's root, internal/ui until migration step 6.1 (#653).
Package app renders omatty: the TUI's root, internal/ui until migration step 6.1 (#653).
tui/keys
Package keys decides where a keystroke goes.
Package keys decides where a keystroke goes.
tui/terminal
Package terminal (internal/termwrap until migration step 6.1, #653) is omatty's only route to an embedded terminal emulator.
Package terminal (internal/termwrap until migration step 6.1, #653) is omatty's only route to an embedded terminal emulator.
tui/theme
Package theme is the TUI's one palette and every style it draws with (ADR 0001, "tui/theme"; migration step 6.2, #653).
Package theme is the TUI's one palette and every style it draws with (ADR 0001, "tui/theme"; migration step 6.2, #653).
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.
layercheck command
Command layercheck reports ADR 0001's layer rule against omatty's own import graph (#620).
Command layercheck reports ADR 0001's layer rule against omatty's own import graph (#620).

Jump to

Keyboard shortcuts

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