mirror of
https://github.com/l0ng-ai/tty7.git
synced 2026-09-21 16:02:20 +00:00
l0ng-ai
4af4452900
tty7 injects shell integration into the shell it launches for a pane, and only that one. A shell the user starts by hand afterwards -- `zsh` typed at a bash prompt -- is a new process nobody injected into, so it emits no OSC 7 and no OSC 133, and the pane keeps showing whatever directory the outer shell reported last. On a local machine that is invisible, because oh-my-zsh reports OSC 7 itself from lib/termsupport.zsh. Over SSH it is not: that file returns early when SSH_CLIENT or SSH_TTY is set, which sshd always sets, so on a remote host neither oh-my-zsh nor tty7 reports the directory of a hand-started zsh. That combination is the whole of #698, and it is why the reporter sees it work over SSH under bash and stop under zsh. Documented in two places: a "Shells you start yourself" section in the shell integration reference, and a troubleshooting entry that names the symptom the way a user would ("the directory stopped following my shell"). Both give the two remedies -- `chsh -s /bin/zsh` on the remote host, which is what moves the integration into the shell tty7 bootstraps, and, when the login shell cannot be changed, a four-line precmd hook that reports OSC 7 by hand. The entry also says why a login script or `exec zsh` from .bashrc is not a fix: both run after (or instead of) the shell tty7 set up. The same pages now describe the process-inspection fallback honestly. It was one parenthetical -- "tty7 falls back to inspecting the process" -- which overpromises: it exists only where the daemon can see the pane's processes, so a local macOS/Linux pane or a remote-workspace pane gets it and an SSH pane or a Windows pane does not, and it is a poll driven by pane output at most twice a second, not a report, so it trails a `cd`. That poll is the mechanism behind the issue's second, unconfirmed half: with tty7-server on the remote host the daemon is on that host, so a nested zsh's cwd does get picked up out of /proc -- late, and only when the pane writes something. Deliberately no code. Propagating the integration into a shell the user starts by hand would mean exporting ZDOTDIR (or rewriting the user's startup files) from every pane, which leaks into every zsh in the session including scripts, and the remote bootstrap deletes its throwaway ZDOTDIR at the first prompt precisely because an SSH session has no reliable exit hook -- a directory that outlives its deletion is exactly what would break a nested shell rather than help it. Tightening the cwd poll for uninstrumented panes is a real possibility, but it is a Linux-only daemon path that cannot be exercised from here, for a symptom nobody has yet reproduced; the mechanism is written down instead. Claude-Session: https://claude.ai/code/session_01UUyWQXzcBAoBzaSX8pc7nU
tty7
A terminal workbench: persistent sessions, remote work, agents.
Pure Rust · GPU rendering on Zed's gpui · VT core from Alacritty
English · 简体中文
Why
A background server owns your shells and panes — not the window. Everything below follows from that.
- Performance — ~2× the throughput of Alacritty, Ghostty, or Kitty (benchmarks)
- Persistent sessions — quit or reboot; your shells and supported agent sessions keep running, no tmux
- Agent-aware — Claude Code, Codex & co.: status, notifications, and git context for every repo at once
- Scriptable by agents — one agent opens a pane for another, hands off a task, waits, and reads the result, with or without the GUI running
- Editor-grade input — suggestions, completion, highlighting, history search, with no plugin to install
- Remote development — files, repos, panes, and git data stay on the remote machine, over a native SSH stack
- Git beside the terminal — source control, diffs, and worktrees without leaving the window
Install
Native builds for macOS, Windows, and Linux on Releases:
| macOS | …-macos-arm64.dmg · …-x86_64.dmg |
drag into Applications |
| Windows | …-setup.exe · portable ….zip |
|
| Linux | …-x86_64.AppImage |
chmod +x and run — X11/Wayland libraries bundled |
What's inside
| Agent-aware | per-pane detection (20 CLIs) · status dot · notifications · branch + diff · tray icon when input is needed · resume after reboot · tab sidebar grouped by repository |
| CLI + Skills | bundled tty7 CLI · agent skill · run streams a command and exits with its code · split · send · wait --until free · capture |
| Editor-grade input | ghost suggestions from history · explained tab completion · syntax highlighting · multi-line editing · click places the caret · ⌃ R fuzzy history |
| Window | tabs & splits · ⌘ P palette · ⌘ F scrollback search · ⌘ J panel with process tree and listening ports · 13 themes, your own YAML, iTerm2 import · IME |
| Shell integration | injected when a pane starts, nothing to install · prompt marks · working directory · exit codes · command-finished notifications · zsh, bash, fish, PowerShell, WSL, remote panes |
| Remote workspaces | remote files, repos, changes, diffs, worktrees, tabs, and panes · reconnect from any client and continue where you left off |
| SSH | native russh stack: profiles with keychain secrets · SFTP panel · port forwarding · jump hosts · one-time, unprivileged tty7-server install |
| Git | panel follows the focused pane · stage, commit, amend, branch, push, stash · side-by-side or unified diffs · commit graph with cherry-pick, revert, and reset · a new worktree opens its own tab |
Supported agents
Detection is free: brand avatar, branch + diff, tab title.
Status takes one click under Settings → Agents to install that agent's hook,
and brings the status dot, notifications, the tray icon, tty7 wait, and resume
after a reboot. Fork needs both — the agent's own fork command, and the hook
that tells tty7 which session to fork.
The full support matrix, all twenty
| Agent | Detected | Status · resume | Fork |
|---|---|---|---|
| Claude Code | ✓ | ✓ | ✓ |
| Codex | ✓ | ✓ | ✓ |
| TraeCode | ✓ | ✓ | ✓ |
| Grok | ✓ | ✓ | ✓ |
| OpenCode | ✓ | ✓ | ✓ |
| Oh My Pi | ✓ | ✓ | ✓ |
| Droid | ✓ | ✓ | ✓ |
| Qwen Code | ✓ | ✓ | ✓ |
| Goose | ✓ | ✓ | ✓ |
| Gemini | ✓ | ✓ | |
| Copilot | ✓ | ✓ | |
| Kimi Code | ✓ | ✓ | |
| Pi | ✓ | ✓ | |
| Aider | ✓ | ||
| Amp | ✓ | ||
| Cursor | ✓ | ||
| Auggie | ✓ | ||
| Hermes | ✓ | ||
| Vibe | ✓ | ||
| Antigravity | ✓ |
None of them are wrapped or proxied — the agent you start is the agent you get,
in a normal PTY, with its own interface. An agent launched through a wrapper
script can be mapped to one by name with agent_commands in config.json.
Documentation
Full documentation lives in docs/ —
keyboard shortcuts ·
config.json ·
CLI reference. The agent-facing CLI interface is also
documented in skills/tty7/SKILL.md.
Install the skill with:
npx skills add l0ng-ai/tty7 # install
npx skills update tty7 # update later
Benchmarks
Same machine, same day, same 155×40 grid — Apple M1 Pro, macOS 26.3.1, five-run averages (2026-07-04):
| tty7 | Alacritty | Ghostty | Kitty | |
|---|---|---|---|---|
Plaintext I/O — 11 MB cat (lower = better) |
95 ms | 239 ms | 179 ms | 185 ms |
| DOOM-fire frame rate (higher = better) | 888 fps | 485 fps | 552 fps | 617 fps |
| Cold-launch memory | 116 MB¹ | 105 MB | 128 MB | 130 MB |
¹ GUI 105 MB + the persistent server 11 MB.
Methodology and one-command reproduction: scripts/bench/.
Built on gpui and alacritty_terminal · Apache-2.0 · Discord · Changelog