Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions CLAUDE.md
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,7 @@ npm test # Vitest tests
npm run test:packaging # Packaging helper tests
```

Also run `npm run test:security` and the documented dependency gates when relevant. For packaging changes, run `npm run package` and `npm run verify:package`; releases also require `npm run make` and packaged runtime smoke. CI separately builds/audits Helm and audits root/runtime dependencies; see `.github/workflows/ci.yml` and `docs/DEPENDENCY_SECURITY.md`. Settings has nine sections, including CLI tools. See `src/docs/settings.md` for controls and save behavior.
Also run `npm run test:security` and the documented dependency gates when relevant. For packaging changes, run `npm run package` and `npm run verify:package`; releases also require `npm run make` and packaged runtime smoke. CI separately builds/audits Helm and audits root/runtime dependencies; see `.github/workflows/ci.yml` and `docs/DEPENDENCY_SECURITY.md`. Settings has ten sections, including CLI tools and Pip. See `src/docs/settings.md` for controls and save behavior.

**Native packaging:** Forge uses pinned prebuilt node-pty binaries instead of rebuilding with unsupported Visual Studio toolchains. Windows local/Coder PTYs use bundled ConPTY DLL support so shutdown works with `RunAsNode` disabled. Keep the packaged verifier and real PTY startup/stop smoke green; app state remains JSON.

Expand Down Expand Up @@ -275,7 +275,7 @@ src/
MigrateToVaultDialog.tsx
Notifications.tsx
PaneStatusStrip.tsx # Per-session cost/token strip
SettingsDialog.tsx # Nine searchable settings sections
SettingsDialog.tsx # Ten searchable settings sections
CanvasLayout.tsx # Movable/resizable session panels
SetupWizard.tsx # First-run wizard
SplitDivider.tsx # Split pane drag handle
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -119,7 +119,7 @@ Tether gives you a **single window** with a sidebar to manage it all — while e
- **Update notifications** — checks GitHub Releases on launch and links to downloads; stable/beta channels and an opt-out live in Settings → General
- **Diagnostics export** — one-click bundle of scrubbed `data.json` (SSH passwords, tokens, sensitive env-var values redacted) plus rotated logs, for triaging support issues
- **CLI maintenance** — check and update installed Claude Code, Codex CLI, and OpenCode tools on local, SSH, or Coder targets through temporary terminals
- **Optional sidebar companions** — local GIF panel and Pip pet, off by default. Pip's local reactions use status metadata; generated Codex or Claude quips and submitted-prompt sharing have separate opt-ins
- **Optional sidebar companions** — local GIF panel and Pip pet, off by default. Pip's local reactions use status metadata; generated Codex or Claude quips and submitted-prompt sharing have separate opt-ins, with adjustable hourly limits, in **Settings → Pip**
- **J.O.B.S. Office** — optional external office view, off for new setups, with separate connection, remote-session sharing and automatic-launch controls
- **Helm** *(opt-in, personal-experimental)* — designate a session as "helm" so it can dispatch pre-briefed child sessions through the `tether-helm` MCP, including spawning Coder workspaces. Off by default behind a two-level gate. Not on the 1.0 roadmap.

Expand Down
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ both on GitHub and inside Tether.
- [Getting started](../src/docs/getting-started.md) — installation, setup and layouts.
- [Sessions](../src/docs/sessions.md) — launch, resume, restore, recipes, search and child viewers.
- [Environments](../src/docs/environments.md) — local, SSH and Coder requirements.
- [Settings](../src/docs/settings.md) — all nine sections, defaults and consent controls.
- [Settings](../src/docs/settings.md) — all ten sections, defaults and consent controls.
- [Keyboard shortcuts](../src/docs/keyboard-shortcuts.md) — navigation, clipboard and multiline input.
- [Usage and quota](../src/docs/usage-quota.md) — estimates, remote collection, exports and privacy.
- [Vault](../src/docs/vault.md), [Git providers](../src/docs/git-providers.md) and [Helm](../src/docs/helm.md).
Expand Down
2 changes: 1 addition & 1 deletion src/docs-renderer/index.test.ts
Original file line number Diff line number Diff line change
Expand Up @@ -57,7 +57,7 @@ it('opens and navigates settings help anchors in the rendered docs', async () =>
await import('./index');
expect(document.getElementById('appearance')?.classList.contains('docs-anchor-flash')).toBe(true);

for (const anchor of ['general', 'appearance', 'terminal', 'sessions', 'notifications', 'shortcuts', 'integrations', 'usage']) {
for (const anchor of ['general', 'appearance', 'terminal', 'sessions', 'notifications', 'shortcuts', 'integrations', 'usage', 'cli-tools', 'pip-sidebar-pet']) {
navigate({ page: 'settings', anchor });
expect(document.getElementById(anchor)?.classList.contains('docs-anchor-flash'), anchor).toBe(true);
}
Expand Down
2 changes: 1 addition & 1 deletion src/docs/sessions.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ updates** for installation methods and cancellation behavior.

A **session** in Tether is a running CLI process in a specific directory and environment. You can have many sessions open at once, each with its own terminal. Tether is a "dumb pipe" — the PTY stream flows byte-for-byte into the terminal; nothing is parsed, rewritten, or intercepted.

The optional **[Pip sidebar pet](settings.md#pip-sidebar-pet)** follows the focused session, reacts to its status, and taps a tiny keyboard while you type. Enable it from **View → Pip Sidebar Pet**. Its **waiting** button opens another session that needs input, with permission prompts first. Optional AI quips and submitted-prompt sharing have separate controls in **Pip options**, using your Codex or Claude sign-in.
The optional **[Pip sidebar pet](settings.md#pip-sidebar-pet)** follows the focused session, reacts to its status, and taps a tiny keyboard while you type. Enable it from **View → Pip Sidebar Pet**. Its **waiting** button opens another session that needs input, with permission prompts first. Optional AI quips and submitted-prompt sharing have separate controls in **Settings → Pip**, using your Codex or Claude sign-in.

## Creating Sessions

Expand Down
21 changes: 11 additions & 10 deletions src/docs/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,19 +29,20 @@ stops the maintenance terminal. Interrupted updates may need to be retried.
Maintenance terminals are temporary: they are not saved as conversations and do not
install Tether status hooks or contribute session usage statistics.

Open Settings with **Ctrl+,**, the button at the bottom of the sidebar, or **File → Settings…** in the menu bar. Search for a settings section by name or topic, such as “theme”, “hooks”, or “usage”. The dialog has nine sections:
Open Settings with **Ctrl+,**, the button at the bottom of the sidebar, or **File → Settings…** in the menu bar. Search for a settings section by name or topic, such as “theme”, “hooks”, or “usage”. The dialog has ten sections:

- [General](#general) — session restore and update checks
- [Appearance](#appearance) — theme previews, UI font, and interface density
- [Terminal](#terminal) — terminal font, cursor shape, and scrollback
- [Sessions](#sessions) — launch profiles, default env vars, Helm and status hooks
- [CLI tools](#cli-tools) — Claude, Codex, OpenCode and Copilot launch defaults, updates and native controls
- [Notifications](#notifications) — desktop notification triggers and suppression
- [Shortcuts](#shortcuts) — keyboard shortcut customization
- [Integrations](#integrations) — Vault, Git providers, SSH known hosts, J.O.B.S. office
- [CLI tools](#cli-tools) — Claude, Codex, OpenCode and Copilot launch defaults, updates and native controls
- [Usage](#usage) — cost tracking, history dialog, exports, subscription quota
- [Pip](#pip-sidebar-pet) — the optional sidebar pet: personality, nudges, AI quips and their limits

Use **Save** to apply settings changes. Theme selection previews immediately and reverts on **Cancel**. Actions with their own buttons apply immediately: shortcut edits, profile and provider changes, known-host revocation, Vault login/logout and migration, **Test now** for J.O.B.S., exports, and resetting session font sizes. The dialog's **Cancel** button does not undo those actions.
Use **Save** to apply settings changes. Theme selection previews immediately and reverts on **Cancel**. Actions with their own buttons apply immediately: shortcut edits, every control in **Pip**, profile and provider changes, known-host revocation, Vault login/logout and migration, **Test now** for J.O.B.S., exports, and resetting session font sizes. The dialog's **Cancel** button does not undo those actions.

## General

Expand Down Expand Up @@ -156,7 +157,7 @@ On by default. Lists the subagents a Claude Code session (local, SSH or Coder) h

## Sidebar panels

The GIF panel and Pip are not controls in the Settings dialog. Turn each one on from the **View** menu; its options are in the panel itself and save immediately.
Turn the GIF panel and Pip on from the **View** menu. The GIF panel's options are in the panel itself. Pip's are in **Settings → Pip**, which the gear button in Pip's header opens. Both save immediately.

### GIF panel

Expand All @@ -174,28 +175,28 @@ The panel is off by default and ships without media. Files stay on your computer

### Pip sidebar pet

Choose **View → Pip Sidebar Pet** to invite Pip into the sidebar. Pip is a small cable gremlin with a terminal face, a linked-cable badge, and a looped tether tail. Its colors follow your Tether theme. It is off by default and can live alongside the GIF panel.
Choose **View → Pip Sidebar Pet** to invite Pip into the sidebar. Pip is a small cable gremlin with a terminal face, a linked-cable badge, and a looped tether tail. Its colors follow your Tether theme. It is off by default and can live alongside the GIF panel. **Show Pip in the sidebar** in **Settings → Pip** is the same switch.

- Pip follows your focused session in single, split, and Canvas layouts. It reacts to starting or working agents, input and permission waits, idle sessions, stopped sessions, and sessions that ended unexpectedly. A ready-for-input reaction means the agent is waiting for you; it does not certify that a task or test succeeded.
- When a turn Pip watched from its start runs five minutes or longer, the ready reaction mentions how long it took. Pip also notices when the focused Claude or Codex session starts its first subagent or `codex exec` run; this follows **Show subagents in sidebar**, and OpenCode sessions have no child rows to notice.
- When another session is waiting, the **waiting** button switches to it, prioritizing permission prompts. The button stays in the header while the panel is collapsed. While any session is blocked on a permission prompt, Pip stays alert until it is answered. Switching sessions quickly can make Pip dizzy. Click Pip, or focus it and press **Enter** or **Space**, to pet it.
- Pip perks up and taps a tiny keyboard while you type in the focused terminal. Pressing **Enter** gets an occasional reaction; this signals a keypress, not proof that the CLI accepted a prompt. Keys, pasted text, and composed text count as typing; focus changes, mouse movement, and the terminal's own replies do not. Draft text is never collected for this animation.
- **Quiet** keeps the expressions and silences local and AI comments. **Pip options** lets you choose **Dry little gremlin** or **Cozy companion**, and turn ambient motion off. Your system's reduced-motion preference also stops animations and cursor tracking.
- **Quiet**, in Pip's header and in **Settings → Pip**, keeps the expressions and silences local and AI comments. **Settings → Pip** also lets you choose **Dry little gremlin** or **Cozy companion**, and turn ambient motion off. Your system's reduced-motion preference also stops animations and cursor tracking.
- Routine comments appear at most once every 25 seconds. A session becoming ready or stopping can replace a routine comment, and a permission prompt or another session needing you always gets one. A comment stays for 12 seconds, or until what it describes is no longer true, then returns to a greeting. Petting gets an immediate response.
- After 90 seconds without mouse, keyboard, or scroll activity in Tether, Pip takes a nap. Using the app wakes it, and so does a session that needs you. Pip does not nap while a permission prompt is pending.
- Screen readers announce only comments about a session that needs you: a permission prompt, or another session waiting. Other comments, including AI quips, stay visible and silent.
- **Operational nudges** in **Pip options** is off by default. When on, Pip comments once when Vault sign-in is within 30 minutes of expiring, a Claude or Codex quota window passes 90%, a daily or weekly usage budget is crossed, or a Tether update is available. Each occurrence is mentioned once per launch, a nudge waits for the current comment to end, and several quota windows over the mark share one comment. Every nudge repeats an indicator the sidebar already shows; Pip is never the only place a warning appears. Nudges are local lines and are never sent to an AI quip backend. With **Quiet** on, Pip changes expression without the comment.
- **Operational nudges** in **Settings → Pip** is off by default. When on, Pip comments once when Vault sign-in is within 30 minutes of expiring, a Claude or Codex quota window passes 90%, a daily or weekly usage budget is crossed, or a Tether update is available. Each occurrence is mentioned once per launch, a nudge waits for the current comment to end, and several quota windows over the mark share one comment. Every nudge repeats an indicator the sidebar already shows; Pip is never the only place a warning appears. Nudges are local lines and are never sent to an AI quip backend. With **Quiet** on, Pip changes expression without the comment.
- Preferences save immediately and persist across launches. Click **Pip** to collapse the panel, or **Hide Pip** to remove it. Reopen it from **View → Pip Sidebar Pet**. Collapsing it, hiding the sidebar, or minimizing the window suspends its timers and cursor tracking; reopening it does not replay missed reactions.

Local reactions use session labels, focus, status metadata, and a text-free typing signal. They make no model or network requests and work with local, SSH, and Coder sessions. How accurately Pip reacts depends on that session's status detection. Pip never parses or alters terminal output.

#### Optional AI quips

- Choose a backend under **AI quips** in **Pip options** to get occasional generated comments: **Codex (ChatGPT sign-in)** uses your local Codex CLI, and **Claude (Claude subscription)** uses your local Claude Code. Either way the quip uses that subscription's allowance; API-key, proxy, and cloud-provider sign-ins are not used for Pip. **Off** keeps local quips only and remembers your last backend. AI quips are off by default. OpenCode is not supported as a quip backend, because `opencode run` gives no error and never exits when a model call fails.
- The backend is always your explicit choice, not the focused session's CLI, because it decides which company receives the request. When you pick one, a status line shows its sign-in and model, or why it cannot be used. **Try a quip** asks for one immediately so you can confirm it works; it skips the two-minute wait but counts toward the hourly limit.
- Choose a **Backend** under **AI quips** in **Settings → Pip** to get occasional generated comments: **Codex (ChatGPT sign-in)** uses your local Codex CLI, and **Claude (Claude subscription)** uses your local Claude Code. Either way the quip uses that subscription's allowance; API-key, proxy, and cloud-provider sign-ins are not used for Pip. **Off** keeps local quips only and remembers your last backend. AI quips are off by default. OpenCode is not supported as a quip backend, because `opencode run` gives no error and never exits when a model call fails.
- The backend is always your explicit choice, not the focused session's CLI, because it decides which company receives the request. When you pick one, a status line shows its sign-in and model, or why it cannot be used. **Try a quip** asks for one immediately and shows the line, or the reason none came back, beside the button; it skips the gap between quips but counts toward the hourly limit. It needs Pip shown, expanded, and not on Quiet.
- With Codex, Pip selects **GPT-6 Luna**, or **GPT-5.6 Luna** if the current model is absent from the installed CLI's catalog, with the lowest supported reasoning effort and standard speed. With Claude, Pip uses **Claude Haiku** at low effort and accepts a reply only if it was a single Haiku turn. Neither backend silently falls back to a larger model. If sign-in, model access, or the connection is unavailable, local quips continue.
- Pip can ask for a quip when the focused session starts working, waits for input or a permission, finishes a turn (including a long one), or stops; when another session needs you; when you press **Enter**; and when it gets dizzy. Crashes, helpers joining, and operational nudges keep local lines.
- Requests are limited to one every two minutes and twelve attempts per hour, including failures. Tether enforces both limits outside the panel, and the status line under **Share submitted prompts** shows why a moment got a local line instead. A moment that ends within a fraction of a second, before its request is sent, does not count. Each request is a fresh, temporary conversation. Quiet, collapse, hide, and minimize cancel pending requests; missed events are not replayed.
- Requests are limited to one every two minutes and twelve attempts per hour by default, including failures. **Quips per hour** (up to 2 to 30) and **Shortest gap between quips** (30 seconds to 30 minutes) change both limits. Tether enforces them outside the window, so a reload does not reset them, and a moment over a limit gets a local line instead. A moment that ends within a fraction of a second, before its request is sent, does not count. Each request is a fresh, temporary conversation. Quiet, collapse, hide, and minimize cancel pending requests; missed events are not replayed.
- While a quip is on its way, the local line stays up rather than expiring under it. A quip that arrives gets its own 12 seconds; if none arrives, the local line keeps the rest of its time. A newer comment, or the end of what the line describes, discards a reply that is still pending.
- By default Pip supplies only the event (for example, an input wait or Enter press) and chosen personality. Session labels, project paths, draft text, and terminal output are excluded from that context. Both backends run in Tether's neutral app directory rather than your project. Codex uses a temporary conversation with tools, hooks, apps, plugins, and MCP servers off. Claude runs one prompt with no tools, no MCP servers or skills, and none of your user, project, or local settings, so no hooks run (Tether's included); it saves no session, so nothing is added to your Claude history. Claude Code adds its own environment context, including your account email and that neutral folder.
- Separately enable **Share submitted prompts** for specific jokes. Pip reads up to 400 characters of the latest available prompt submitted within the past five minutes from an already-attributed **local Claude or Codex transcript**, or from a **local OpenCode session's** own database, opened read-only, when native OpenCode usage has attributed that session. For OpenCode, only the text you typed counts: OpenCode's own reminders, attached files, and tool output are skipped. SSH and Coder sessions, Copilot, and Custom CLIs use activity only. Common credentials are scrubbed, but arbitrary private text may remain; enabling this sends that excerpt to the backend's company: OpenAI for Codex, Anthropic for Claude. Choosing another backend turns sharing off, so consent always names the current recipient. Pip does not collect draft keystrokes or inspect project files. Tether does not save excerpts or generated comments. Quips are not counted in Tether's usage totals: Codex quips are temporary conversations and Claude quips save no transcript.
Expand Down
Loading
Loading