← Home · English · 한국어

AgentDeckTabby plugin · 1.1.3

A tool for running several agent CLIs (Claude Code · Codex · Gemini) in one terminal and seeing, at a glance, which session is doing what and which one is waiting for you. Every screenshot in this guide is a capture of the real thing.

01At a glance

The screen is in two parts. The terminal on one side, the session list (sidebar) on the other. Tabby's own tab bar is hidden and this sidebar manages tabs instead — once you have several tabs open, a horizontal tab bar has no room to say what each one is working on.

The session list - four sessions grouped by working folder, each row showing title, task name, status and elapsed time — Four sessions, grouped by working folder. Each row carries **title · task name · status · elapsed time**, and `⏸1 ●1 ✔1 ○1` at the right of a header is the per-status count.

The terminal width is derived from the window height at a fixed 4:3 ratio. However wide you make the window, the terminal does not stretch sideways, so the boxes and line wrapping a TUI draws stay put. The leftover width goes to the sidebar, and whatever is still left is absorbed by the terminal.

02Session status

Each session reports one of six states.

Badge	Meaning	When
● running	the agent is working	output keeps coming
⏸ waiting	it is waiting for you	asking permission to use a tool
⛔ rate limited	usage limit hit	shown with the reset time
✔ done	the turn finished	answered and stopped
✘ error	it failed	an error message appeared
○ idle	nothing is happening	no output for a while

A waiting badge says what it is waiting for. The second row in the screenshot above reads ⏸ waiting · Claude needs your permission to use Bash. When you come back from doing something else, you know which session stopped and why without clicking into it.

Setting a status by hand

Right-click on a session row - the status menu — Right-click a row to set the status yourself. `back to auto` hands it back to detection.

Status is judged from what is printed on screen, with no hook installed. That is why it works for Codex and Gemini too, not just Claude Code. Installing the hook (one click in settings) lets the agent report directly and makes the reading exact — but the tool is built to be usable without it.

03Session groups

Sessions are grouped by working folder (project) — sololv-server, tools and web-shop in the screenshot above. The number next to a header is how many sessions are in that group. Click the header to collapse it.

Two groups collapsed — `tools` and `web-shop` are collapsed. Collapsed state survives a restart.

Grouping is by the folder the tab was born in — cd in the shell does not move a session to another group. If membership shifted while a session was alive you would keep asking "where did that row just go". When there is only one group the header is not drawn at all, so a single-project setup looks exactly as it did before.

04Search and filter

Type in the search box at the top of the sidebar to narrow by title · task name · working folder at once. Click a status chip (⏸1 ●1 …) to keep only that status.

One session left after searching — Searching left a single matching task. `Esc` or `✕` clears it.

A collapsed group opens temporarily if it holds a match. Otherwise the search would look like it found nothing. Clearing the search puts the group back the way it was — the collapse setting itself is never touched.

05Keyboard control

Ctrl+Shift+L moves focus into the list so you can look through it without the mouse.

Key	What it does
`↑` `↓`	move between rows. The active tab does not change
`Home` `End`	first row / last row
`Enter`	switch to that session. On a group header, collapse or expand
`Esc`	if a search or filter is set, clear that first. Otherwise return to the terminal
`Tab`	go to the search box

Keyboard focus on the second row while the active tab is a different row — The outline (keyboard focus) is on the second row while **the highlighted active tab is a different row** — that split is the point of this screenshot.

Focus and selection are deliberately separate. If the tab changed on every row you passed, that tab's output would flood the screen and the terminal width would be re-applied each time, making the display jump. Looking through your sessions would become impossible. So ↑↓ move only the outline, and Enter is the single thing that actually opens a tab.

↑ inside the search box is deliberately not intercepted — in a single-line input that key moves the cursor to the start, and you really do use it when fixing a search term you are typing.

06Reordering

Drag a sidebar row to move it, and Tabby's own tab order moves with it. Hold the cursor at the top or bottom edge of the list while dragging and the list scrolls by itself, so you can reach an off-screen position in one gesture.

With status sorting (sortByStatus) on, you cannot reorder — status decides the order there, so a moved row would snap back on the next render. Dragging is blocked with an explanation instead.

07Output preview

Read the documents, images, tables and code an agent produced right next to the terminal. File paths printed on screen are picked up automatically, so you never have to ask for a file to be opened.

A markdown document rendered in the preview panel — Markdown is rendered with tables, inline code and quotes intact. The chips along the top are recently seen files; the status line at the bottom gives size, time and full path.

What	How
Drag and drop	Drop a file on the panel and it opens. Drop it on the terminal and you are asked — open in panel / paste the path
Edit and save	`✎` to edit, `Ctrl`+`S` to save. BOM and line endings are restored exactly as they were
Find	`Ctrl`+`F`
New file	Put a path that does not exist into `＋` and press `Enter` twice — it is created and opened for editing
Open it after working with it closed	Everything touched so far is waiting as chips and the body shows the most recent file (if you were on Changes, the diff is re-read) — Settings → Preview panel → preload into the panel (on by default)
Make it open by itself	Settings → Preview panel → open the panel automatically (off by default — opening and closing is yours to do). Turn preload off and nothing happens automatically

Each tab remembers its own. Move to another session and the body switches to the file that session was last looking at — so you never mistake another session's document, still sitting open beside you, for the output of the one you are now in.

08Diff view and commit

The Changes tab of the same panel shows git diff for that session's working folder. It does not care who made the change — agent or human, you are looking at the working tree itself.

Changes tab - file list, insertions and deletions, diff with line numbers, commit box — `2 files · +192 -16` at the top, then the file list (including six untracked new files), then the diff with line numbers. The commit message box is at the bottom.

What	How
Stage	Click the tag at the left of a file to `git add` or unstage it
Commit	Write a message and press `commit` — it takes two presses (the first one asks to confirm)
`file:line` reference	Click a diff line and that position is typed into the terminal. `Shift`+click for a range

Clicking a line to insert its position is the most-used thing in this panel. Saying "fix this line" used to mean typing a filename and a line number by hand; that round trip is gone. Commit takes two presses so that it cannot happen by accident.

09Input fixes

While composing text with an IME (Korean, Japanese, Chinese), pressing Home, End or Shift+Enter used to make the syllable still being composed follow the cursor or drop onto the new line. Keys are now held until composition finishes.

Key	What it does
`Ctrl`+`Enter` · `Shift`+`Enter`	newline (next line without sending)
`Ctrl`+`V`	paste. If the clipboard holds only an image, it is pasted as an image
Right-click	copy when there is a selection, paste when there is not. Hold for the menu

10Settings

Sidebar settings button → the AgentDeck section.

The AgentDeck section of the settings window - session list and grouping — Every entry also says **why that is the default**. Most of them apply immediately.

The ones actually worth touching:

Entry	Default	Meaning
keyboard control	on	`Ctrl`+`Shift`+`L` list navigation
wrap around at the ends	off	`↓` at the bottom jumps to the top
show subagent count	on	`❖3` on the row
auto-scroll while dragging	on	the list scrolls at the edges
group by project	on	session groups
sort by status	off	most urgent first (blocks manual reordering)
show elapsed time	on	`2m` at the right of a row

The subagent count (❖3) is how many background agents that session is running. It is counted by matching what was launched against what finished in the transcript, so it is right even when no hook is reporting. Hover the row to see what is running and how long the oldest has been going.

11Key reference

Key	What it does
`Ctrl`+`Shift`+`L`	focus the session list / same key returns to the terminal
`Ctrl`+`Enter` · `Shift`+`Enter`	newline
`Ctrl`+`V`	paste (images included)
`Ctrl`+`F`	find inside the preview panel
`Ctrl`+`S`	save while editing in the panel

Some actions ship unbound — toggling the sidebar, screen repair, opening the panel, switching panel mode. Go to Tabby settings → Hotkeys, search for agentdeck- and bind whatever you like.

12When something breaks

The screen is garbled

If a TUI looks broken, press ↻ in the sidebar (or right-click a row → repair screen). It clears the input-line remnant and has the app redraw. Turning on auto repair in settings detects the breakage and handles it for you.

Reporting a problem

Settings → Report a problem → collect builds a zip of diagnostics — version, environment, settings and recorded exceptions. Terminal contents are left out by default: that file would carry your code verbatim, so it is only included when you explicitly turn it on. Attach the zip to a GitHub issue.

New tabs will not open

Tabby 1.0.235 has a problem tangled up with restoring previous tabs. Turning on do not restore tabs on startup in settings fixes it — only the shell is restored anyway, and the agent session inside it is already dead, so there is nothing to lose.

AgentDeck 1.1.3 · every screenshot here is a capture of the running app.
The full settings table and the reasoning behind the design are in the repository's README.md; the verification checklist is in docs/REGRESSION.md.