mirror of
https://github.com/Ark0N/Codeman.git
synced 2026-10-09 08:59:40 +02:00
docs(tiles): the tile grid in CLAUDE.md, the invariants, the wiki and the Help modal
- CLAUDE.md: a Tile grid paragraph beside the split-pane one (parking, the one load queue, the selection and close rules, chords, dividers, auto-join, the exited-agent case), tile-grid.js (7.6) in the load order, the desktop-gated header markers and the Tiles picker in the z-index stack. - docs/architecture-invariants.md#tile-grid: the mechanisms and the reason behind each rule; the split section now says where a waiting grid load differs and that every capture carries a deadline. - docs/wiki/Tile-Grid.md: the user manual page (turning it on, the ways in, a tile's header, keys, leaving, persistence, Split), linked from the sidebar, The Dashboard, Keyboard Shortcuts and Settings Reference. - The Help modal lists the tile chords (pinned in help-modal-shortcuts.test). - docs/tile-grid-plan.md: status updated, and an "as built" list of where PR 2 went another way than the spec. Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Codeman maintainer
File diff suppressed because one or more lines are too long
+29
-2
@@ -1,10 +1,37 @@
|
||||
# Tile Grid: Design Spec
|
||||
|
||||
**Status**: PR 1 (tile foundation) implemented on `feat/terminal-tile`, local only; PR 2 (the grid) proposed. Builds on `docs/split-pane-sessions-plan.md`; the split pane stays.
|
||||
**Status**: PR 1 (tile foundation) implemented on `feat/terminal-tile`; PR 2 (the grid) implemented on `feat/tile-grid`, both local only. Builds on `docs/split-pane-sessions-plan.md`; the split pane stays.
|
||||
**Author**: Claude (planning session with the maintainer), 2026-10-06
|
||||
**Branches**: PR 1 `feat/terminal-tile`, PR 2 `feat/tile-grid` stacked on it (worktree `claudeman-tiles`)
|
||||
**Branches**: PR 1 `feat/terminal-tile`, PR 2 `feat/tile-grid` stacked on it (worktrees `claudeman-tiles`, `claudeman-tilegrid`)
|
||||
**Scope**: v1 is fully designed here; follow-ups are named at the end and explicitly deferred.
|
||||
|
||||
## As built: where PR 2 differs from this spec
|
||||
|
||||
The design below stands; these are the places the built grid deliberately went another way,
|
||||
or settled a question the spec left open. The invariants as built are in
|
||||
`docs/architecture-invariants.md#tile-grid`.
|
||||
|
||||
- **An agent that exited in a live pane (`paneExit`) gets no Attach button.** Both attach
|
||||
routes (`/interactive`, `/shell`) refuse while the pane's tmux client still runs ("Session
|
||||
already has a running process") and report that in the envelope of a 200, so the
|
||||
edge-case row below cannot work without a server change. The tile shows the exit and
|
||||
points at Close session. A session with no PTY (`pid === null`) and a socket closed with
|
||||
4009 do get Attach. Restarting an exited agent in place is a follow-up.
|
||||
- **`Ctrl+Shift+G` follows `showTileGridButton`** (the applied default while the owner's
|
||||
answer is pending): with the setting off the toggle chord is inert. A grid opened another
|
||||
way (Ctrl/Cmd+click, a dropped tab, "Open group as tiles") keeps all its chords.
|
||||
- **Dividers are grid tracks.** Each gap between columns and rows is its own 6px track (the
|
||||
grid gap is 0) and tiles are placed explicitly in reading order, which is also what the
|
||||
empty-slot drop targets need. Fractions reset when the column or row count changes.
|
||||
- **Zoom follows tmux.** Moving focus to another tile restores the grid; an automatic zoom
|
||||
(window too small for the minimum tile) follows focus instead.
|
||||
- **Tile loads are bounded** (`boundedLoad`), carry a fetch deadline covering the body (Pane
|
||||
B too), and a refresh clears the screen at its turn in the queue, so a waiting tile keeps
|
||||
its last frame.
|
||||
- **4009 lands on the Attach overlay**, and 4003/4004/4010 remove the tile.
|
||||
- **"+ / New session in this case"** runs the normal Run for that case and joins through
|
||||
the same auto-join as any Run from this tab.
|
||||
|
||||
## Problem
|
||||
|
||||
Codeman's terminal area shows exactly one session at a time. The split pane
|
||||
|
||||
@@ -39,6 +39,19 @@ from its tab, or bind a key to it in App Settings → Shortcuts.
|
||||
|
||||
Anything you copy is cleaned on the way to the clipboard: each line loses the padding spaces a full-screen program paints across the rest of the row. Leading indentation is left exactly as it is, so indented code, a `git log` message body and `git diff` context lines paste back the way they looked on screen. An `Alt+drag` rectangular selection is copied exactly as it looks, so its columns stay lined up.
|
||||
|
||||
## Tile grid
|
||||
|
||||
| Shortcut | Action |
|
||||
| --------------------------- | ------------------------------------------------------------ |
|
||||
| `Ctrl+Shift+G` | Open or close the tile grid (needs the Tiles setting on). |
|
||||
| `Alt+Shift+Arrows` | Focus the tile to the left, right, above or below. |
|
||||
| `Alt+Shift+Enter` | Zoom the focused tile, or restore the grid. |
|
||||
| `Ctrl`+click / `Cmd`+click a tab | Add that session to the grid. |
|
||||
|
||||
While the grid is open, `Ctrl+Tab` and `Alt+[` / `Alt+]` cycle through the tiles, and the
|
||||
terminal shortcuts above act on the focused tile. **Remove Focused Tile** has no key by
|
||||
default. See [Tile Grid](Tile-Grid).
|
||||
|
||||
## Everything else
|
||||
|
||||
| Shortcut | Action |
|
||||
|
||||
@@ -57,7 +57,7 @@ supervised by systemd or launchd; npm installs report as non-updatable. See
|
||||
Chips for every optional header control, with a live preview of the resulting header:
|
||||
|
||||
Run, Font Size, System Stats, Redraw Terminal, Response Viewer, Away Digest, Session
|
||||
Manager, Attachments, File Viewer, Multi-monitor, Split, Plan Usage, Lifecycle Log, Monitor,
|
||||
Manager, Attachments, File Viewer, Multi-monitor, Split, Tiles, Plan Usage, Lifecycle Log, Monitor,
|
||||
Project Insights, File Browser, Subagents, Approvals Inbox, Read My Mind, Ultracode Agents,
|
||||
Ultracode Windows, Cron.
|
||||
|
||||
@@ -71,7 +71,9 @@ window; off lists every file by its full path.
|
||||
Most default to off. The stock desktop header is system stats, File Viewer, and the gear.
|
||||
New header controls never appear on phones. Split is desktop-only regardless of this
|
||||
setting — the button and the feature both stay off below a ~1180px viewport, where two
|
||||
resizable panes plus their divider have nowhere to go.
|
||||
resizable panes plus their divider have nowhere to go. **Tiles** is desktop-only the same
|
||||
way; it also enables the `Ctrl+Shift+G` grid toggle on this device. See
|
||||
[Tile Grid](Tile-Grid).
|
||||
|
||||
This section also holds background-agent tracking, including whether to track agents for
|
||||
every session or only the active tab.
|
||||
|
||||
@@ -118,6 +118,7 @@ The right side of the header. Almost all of these are off until you enable them
|
||||
| Cron ⏰ | Off | Scheduled jobs. |
|
||||
| Multi-monitor | Off, macOS | Opens a window spanning every display. |
|
||||
| Split | Off, desktop only | View a second session beside the active one, with a draggable divider. |
|
||||
| Tiles | Off, desktop only | Up to nine live sessions side by side. See [Tile Grid](Tile-Grid). |
|
||||
| Tunnel indicator | When a tunnel runs | Cloudflare tunnel status. |
|
||||
| Admin panel | Multi-user only | User administration. |
|
||||
|
||||
|
||||
@@ -0,0 +1,93 @@
|
||||
# Tile Grid
|
||||
|
||||
Watch and drive up to nine sessions at once, side by side in one window. Each tile is a
|
||||
full live terminal: it reads, it takes your keystrokes, and it shows at a glance whether
|
||||
its agent is working, idle, or waiting on you.
|
||||
|
||||
The grid is a desktop feature. It needs a window at least about 1180px wide, and it is
|
||||
never offered in a popped-out session window.
|
||||
|
||||
## Turning it on
|
||||
|
||||
**App Settings → Header & Panels → Tiles.** This is a per-device setting, off by default,
|
||||
so turning it on at your desk never puts the button on your phone. It shows a **Tiles**
|
||||
button in the header, beside Split, and enables `Ctrl+Shift+G`.
|
||||
|
||||
## Opening a grid
|
||||
|
||||
- **Tiles button**: with the grid closed it opens a picker, a checkbox per open session in
|
||||
tab order. It starts with the grid you last had (or the session you are on), says how many
|
||||
tiles this window fits, and greys out the rest. **Open tiles** shows them. With the grid
|
||||
open, the same button closes it.
|
||||
- **`Ctrl+Shift+G`**: toggles the grid. Opening brings back the grid you last had, else an
|
||||
open split as two tiles, else the session you are on.
|
||||
- **`Ctrl`+click (or `Cmd`+click) a tab**: adds that session to the grid and focuses it,
|
||||
opening the grid if it was closed. On macOS use `Cmd`: `Ctrl`+click there opens the tab's
|
||||
rename instead.
|
||||
- **Drag a tab onto a tile** to replace that tile with it (the replaced session keeps
|
||||
running), or onto an empty slot to add it. Dragging a session that is already tiled onto
|
||||
another tile swaps the two.
|
||||
- **"Open group as tiles"** in a tab group's menu, in the vertical tab rail with groups.
|
||||
- **Run**: a session you start from this browser tab's Run button while the grid is open
|
||||
joins it. Sessions started elsewhere (an agent, another device, a cron job) do not.
|
||||
|
||||
The layout follows the tile count: 1x1, 2x1, three side by side on a wide screen (else a
|
||||
2x2 with one empty slot), 2x2, 3x2, 3x3.
|
||||
|
||||
## A tile
|
||||
|
||||
Each tile has a small header: `● name ......... ⋯ ⤢ + ×`
|
||||
|
||||
| Part | What it does |
|
||||
| ------ | ------------------------------------------------------------------------------------------------ |
|
||||
| `●` | The session's state: working, idle, waiting on you, needs you (red, and the tile's border pulses), error, ended. Hover the header for how long. |
|
||||
| name | Double-click to rename the session. |
|
||||
| `⋯` | The session menu: options, open in a new window, close the session. |
|
||||
| `⤢` | Zoom: the tile fills the grid; press it again (or `Alt+Shift+Enter`) to get the grid back. |
|
||||
| `+` | Add a session that is not tiled yet, or start a new session in this tile's case. |
|
||||
| `×` | Remove the tile. The session keeps running; close it from `⋯` if you want it gone. |
|
||||
|
||||
Click a tile to focus it. The focused tile has the accent border, takes your keyboard, and
|
||||
is the session every panel follows: files, git status, respawn and Ralph, subagent windows,
|
||||
voice and image paste. Tabs of tiled sessions carry a small underline.
|
||||
|
||||
Drag the thin lines between tiles to resize columns and rows. A tile never gets smaller than
|
||||
about 60 columns; when the window is too small for all the tiles, the grid shows the focused
|
||||
one on its own until the window is big enough again.
|
||||
|
||||
A tile whose session is not running shows **Not attached** with an **Attach** button. A tile
|
||||
whose agent exited inside its pane says so instead; close that session from `⋯`.
|
||||
|
||||
## Keys
|
||||
|
||||
| Shortcut | Action |
|
||||
| ------------------------ | ---------------------------------------------------------- |
|
||||
| `Ctrl+Shift+G` | Open or close the grid. |
|
||||
| `Alt+Shift+Arrows` | Focus the tile to the left, right, above or below. |
|
||||
| `Alt+Shift+Enter` | Zoom the focused tile, or restore the grid. |
|
||||
| `Ctrl+Tab`, `Alt+[` `]` | Cycle through the tiles. |
|
||||
| `Ctrl+L` | Clear the focused tile. |
|
||||
| `Ctrl` `+` / `Ctrl` `-` | Tile font size (tiles have their own, smaller font). |
|
||||
|
||||
All of them can be rebound in App Settings → Shortcuts, where **Remove Focused Tile** can
|
||||
also get a key. Outside the grid, `Alt+Shift+Arrows` and `Alt+Shift+Enter` go to the
|
||||
terminal as usual. With the Tiles setting off, `Ctrl+Shift+G` does nothing.
|
||||
|
||||
## Leaving the grid
|
||||
|
||||
Clicking the tab of a session that is not tiled (or picking it with `Alt+1-9` or the
|
||||
session finder) shows that session on its own, the normal single view. The grid is
|
||||
remembered: the Tiles button or `Ctrl+Shift+G` brings it straight back. Going Home does the
|
||||
same. Narrowing the window below the desktop width also returns to the single view.
|
||||
|
||||
The grid is saved on this device and comes back when you reload the page, with its focus,
|
||||
zoom and column widths. A session that was closed in the meantime is simply left out.
|
||||
|
||||
The grid and Split are never open together: opening the grid turns an open split into two
|
||||
tiles, and Split is unavailable while the grid is open.
|
||||
|
||||
## Read next
|
||||
|
||||
- [The Dashboard](The-Dashboard) - the single view, tabs and the header.
|
||||
- [Keyboard Shortcuts](Keyboard-Shortcuts) - every binding.
|
||||
- [Settings Reference](Settings-Reference) - where the Tiles setting lives.
|
||||
@@ -11,6 +11,7 @@
|
||||
**Using it**
|
||||
|
||||
- [The Dashboard](The-Dashboard)
|
||||
- [Tile Grid](Tile-Grid)
|
||||
- [Agent CLIs](Agent-CLIs)
|
||||
- [Custom Model Endpoints](Custom-Model-Endpoints)
|
||||
- [Working With Files](Working-With-Files)
|
||||
|
||||
Reference in New Issue
Block a user