mirror of
https://github.com/l0ng-ai/tty7.git
synced 2026-09-21 16:02:20 +00:00
l0ng-aiandl0ng-ai
3c0a700907
* feat(switcher): flatten the workspace list, add a create form, sync remote listings on connect The switcher's left column is now one flat most-recently-used list across all machines, each row carrying its machine and link state; the per-machine tree, headers, and the Other Machines band are gone. Machine trouble (install progress, connect errors, parked routes) moves to contextual banners under the list, and machine verbs move into each row's menu. Cmd+Shift+N now opens a create form instead of silently swapping the workspace: a name prefilled with the usual generated codename, and a host combobox (searchable dropdown) defaulting to this computer. Creating on a machine with no live link connects first and completes when the link is up. Connecting to a machine also mirrors its workspace listing into the local store, so its workspaces survive a restart without a connection. Mirrored references are marked synced: launch restore skips them, and their clock follows the machine only until this client opens them. * fix(switcher): drop a parked create when its machine's connect is called off Disconnect clears the in-flight connect, so finish_connect never runs and the PendingCreate outlived the intent behind it: the next successful connect to that machine would have silently created a workspace nobody was waiting for anymore. --------- Co-authored-by: l0ng-ai <24760907+l0ng-ai@users.noreply.github.com>
116 lines
4.4 KiB
Plaintext
116 lines
4.4 KiB
Plaintext
---
|
|
title: "Core concepts"
|
|
description: "Workspaces, tabs, panes — and the background server that owns them all."
|
|
---
|
|
|
|
Four words explain most of tty7. Three of them you can see; the fourth is the
|
|
reason the other three survive a reboot.
|
|
|
|
## Pane
|
|
|
|
A **pane** is one terminal: one shell (or one program) attached to one PTY. It
|
|
is the only thing in tty7 that actually runs something.
|
|
|
|
Panes have stable ids — `%42` — for their whole life. That id is what the
|
|
[CLI](/cli/overview) addresses, and what `$TTY7_PANE` holds inside the pane
|
|
itself.
|
|
|
|
## Tab
|
|
|
|
A **tab** is a layout of panes. One pane to start with; split it and the tab
|
|
holds two, arranged in rows and columns you can drag around.
|
|
|
|
Tabs appear in the sidebar (or the top strip, if you move it there). A tab's
|
|
label is the best evidence tty7 has: a name you set, else the coding agent
|
|
running in it, else the last segment of its working directory.
|
|
|
|
## Workspace
|
|
|
|
A **workspace** is a named set of tabs — a project, usually. One window shows
|
|
one workspace at a time, and <kbd>⌘ ⇧ O</kbd> opens the switcher to move between
|
|
them or open a second window on another one.
|
|
|
|
The switcher is one flat list, most recently used first — local and remote
|
|
workspaces together, each row wearing the machine it lives on. Typing filters
|
|
by workspace, tab, or machine name, so typing a machine's name is how you see
|
|
just that machine. <kbd>⌘ ⇧ N</kbd> opens the New Workspace form, where you
|
|
pick the machine (this computer, or any configured SSH host) and optionally a
|
|
name.
|
|
|
|
Workspaces are how tty7 keeps ten repositories from becoming forty
|
|
indistinguishable tabs. They also travel: a workspace on a remote machine is
|
|
still a workspace, opened from the same switcher.
|
|
|
|
<Frame caption="Placeholder — screenshot: the workspace switcher, workspaces on the left, that workspace's tabs on the right">
|
|
<img src="/images/placeholder.svg" alt="The tty7 workspace switcher" />
|
|
</Frame>
|
|
|
|
## The server
|
|
|
|
Here is the part that matters. **The window does not own your shells — a
|
|
background server does.**
|
|
|
|
Quitting tty7 closes the window and leaves that server running. Your build keeps
|
|
building, your agent keeps working, your SSH session stays up. Open tty7 again
|
|
and it reattaches to exactly what was there.
|
|
|
|
This is also why:
|
|
|
|
- **`tty7` works from any terminal.** The CLI talks to the same server. The GUI
|
|
does not have to be running at all.
|
|
- **A crash is not a catastrophe.** Panes come back showing what was on them:
|
|
a capped tail of each pane's output is kept on disk and handed to the pane
|
|
that reopens on its id.
|
|
- **Stopping is explicit.** *Quit and Stop Server…* in the tray menu is the only
|
|
ordinary way to end everything, and it warns you first.
|
|
|
|
<Warning>
|
|
Restarting the server ends every process in every pane on that machine —
|
|
shells, agents, and SSH sessions alike. Layouts are kept and come back with
|
|
fresh shells. Never do it on someone else's behalf without asking.
|
|
</Warning>
|
|
|
|
### What survives what
|
|
|
|
| | Close a tab | Quit tty7 | Stop the server | Reboot |
|
|
|---|:--:|:--:|:--:|:--:|
|
|
| The shell keeps running | ✗ | ✓ | ✗ | ✗ |
|
|
| The layout comes back | ✗ | ✓ | ✓ | ✓ |
|
|
| What was on screen comes back | ✗ | ✓ | ✓ | ✓ <sup>1</sup> |
|
|
| A supported agent session resumes | ✗ | ✓ | ✓ | ✓ |
|
|
|
|
<sub><sup>1</sup> A capped tail of each pane, restored once. See
|
|
[session restore](/reference/troubleshooting#panes-came-back-empty).</sub>
|
|
|
|
## Machines
|
|
|
|
Everything above exists per **machine**. Your laptop is one; a dev box you
|
|
connect to over SSH is another, with its own server, its own workspaces, and its
|
|
own panes.
|
|
|
|
The switcher lists them together, and the CLI reaches them with `-m`:
|
|
|
|
```bash
|
|
tty7 -m devbox ls
|
|
```
|
|
|
|
Remote panes run on the remote machine — the files, the repository, the git
|
|
data, and the process tree are all over there.
|
|
[Remote workspaces →](/remote/workspaces)
|
|
|
|
## The three environment variables
|
|
|
|
Every pane exports these, and anything you launch from one inherits them:
|
|
|
|
| Variable | What it holds |
|
|
|---|---|
|
|
| `TTY7_PANE` | This pane's id — the default target of `tty7 split`, `send`, `capture`, `procs`. |
|
|
| `TTY7_WS` | This pane's workspace id. |
|
|
| `TTY7_CONFIG_DIR` | The config directory, which is how the CLI finds the right server. |
|
|
|
|
`echo $TTY7_PANE` is the fastest way to tell whether you are inside tty7 at all.
|
|
|
|
<Card title="Drive it from a script" icon="terminal" href="/cli/overview">
|
|
Those ids are the whole interface. The CLI page starts there.
|
|
</Card>
|