Termight

How To Read This Guide

This guide is written for new users but includes the advanced agent workflows that are documented in this repository. UI names can still move because Termight is an early product fork; when a feature is primarily exposed through the local API or service layer, this guide says so explicitly.

Install And Launch

Termight currently documents source builds as the main way to run the app. Package-manager channels from the upstream Wave project are not Termight release channels.

Platform Requirements

Build From Source

git clone https://github.com/termightdev/termight.git
cd termight
task init

task electron:dev

task package

First Launch

On first launch, Termight creates a starter workspace, window, tab, and terminal block. Configuration lives in ~/.config/termight/ for packaged builds and ~/.config/termight-dev/ for development builds. If TERMIGHT_CONFIG_HOME is set, Termight uses that directory. A legacy TERMIGHT_HOME with a termight.lock uses its config subdirectory.

Workspace Basics

Termight organizes work into workspaces, tabs, and blocks. A block is a terminal, preview, web page, process viewer, launcher, or another widget. Tabs are tiled layouts of blocks. Workspaces group tabs and persist saved layouts.

Daily Layout Tutorial

1. Open a new tab. It starts with one terminal block.
2. Run tsh view . to open a directory preview block.
3. Run tsh run -m -- npm test or an equivalent project check to open a magnified command block.
4. Drag block headers to rearrange the layout. Drop on the middle to swap, or on an edge to split.
5. Hover between blocks to resize them. Use Cmd+M to magnify or restore the focused block.
6. Save the workspace from the workspace switcher if you want it to persist.

Useful Shortcuts

Terminal And Chat Surfaces

Termight has two primary surfaces over the same live PTY session: terminal mode and chat mode. Terminal mode is the full shell. Chat mode renders classified agent events as conversational entries while preserving raw terminal access.

Terminal Mode

Use terminal mode when you need full shell control, raw provider UI, unsupported auth flows, or exact terminal behavior. Termight supports normal shells, scrollback, search, copy/paste, OSC shell-command integration, and the tsh command.

Chat Mode

Chat mode hides startup chrome when it can classify it safely, renders assistant messages as markdown, shows tools and checks as cards, surfaces trust/login/permission/question prompts as controls, and keeps a composer at the bottom.

Switch To Raw Terminal

1. Open a Termight-owned agent session in chat mode.
2. Click the Terminal toolbar button in the chat header.
3. Termight clears the block's term:mode metadata and returns to the same live PTY session in raw terminal mode.
4. Use raw terminal mode for ambiguous provider output, unsupported prompts, or direct CLI control.

Composer Basics

• Press Enter to send; press Shift+Enter for a new line.
• Use @file:path, @folder:path, or shorthand @path references. Arrow keys and Tab accept reference suggestions.
• Use slash suggestions such as /help, /model, /status, and provider-specific commands when available.
• Messages entered while the agent is busy are queued by default. Providers with live append capability can support send-now controls.
• Paste or drag images when the provider capability advertises composer image input.
• Project snippets come from .termight/snippets.json; built-in snippets remain available even when the file is absent.

Agent Sessions

The primary path is Termight-owned launch. Termight creates the session first, starts the provider CLI in a real PTY, injects session metadata, starts structured ingestion where possible, and binds provider session IDs, hooks, worktrees, usage, and replay data to one durable record.

Start A Provider Chat

1. Open Settings, then the Termight Agents area.
2. Refresh provider compatibility. Termight detects installed CLIs using each provider command and --version.
3. Complete provider-owned auth by running the CLI once outside or inside Termight if the provider requires it.
4. Optionally enter an initial prompt and enable worktree creation.
5. Click the launch action for the provider. Termight creates a terminal block with term:mode set to chat.

Provider Matrix

Claude Code Tutorial

1. Install Claude Code and run claude --version to confirm the CLI is on PATH.
2. Run claude once to complete provider-owned authentication.
3. In Termight Agents, preview and install Claude hooks if you want semantic permission, tool, stop, and attention events.
4. Choose user hook scope for all projects, or project hook scope when you explicitly want settings under a project.
5. Launch Claude from Termight Agents. If Claude asks whether you trust a folder, answer with the native chat choice when it is shown, or switch to raw terminal if anything looks unfamiliar.
6. Use the composer for prompts, file references, queued messages, and supported image input.
7. Review tool cards, permission prompts, context pressure, usage, and check status in the chat timeline.

For terminal-only Claude sessions, you can also wire Claude Code hooks to tsh badge. The documented examples set gold high-priority badges for permission prompts and user questions, and a green check badge for Stop events.

Codex Tutorial

1. Install Codex CLI and run codex --version.
2. Run codex once to complete provider-owned authentication.
3. Use AGENTS.md for shared project instructions and .mcp.json for project MCP servers.
4. Launch Codex from Termight Agents. Termight records a structured user message and starts ingestion for launch-owned capture data.
5. Use Stop, raw terminal switching, queued prompts, and review/check flows the same way as Claude.

Gemini CLI Tutorial

1. Install Gemini CLI and run gemini --version.
2. Configure Gemini auth using the provider's own settings or environment. The completion checklist specifically notes that live Gemini smoke still depends on configured Gemini auth.
3. Use project Gemini configuration and .mcp.json where applicable.
4. Launch Gemini from Termight Agents. Termight uses provider session IDs, Gemini JSONL ingestion where available, and conservative PTY fallback for auth or questions.
5. Switch to raw terminal for any prompt that Termight cannot classify confidently.

Permissions And Trust

Termight draws a hard boundary between native Termight UI, trusted structured provider events, and untrusted terminal bytes. Native controls should appear only when Termight has classified a real provider prompt from a trusted structured source or high-confidence fallback.

Trust And Auth

• Trust prompts ask whether the current folder should be trusted. Termight records prompt responses as audit events.
• Auth links are treated as native links only for known provider domains documented in code, including Claude, Anthropic Console, OpenAI auth, and ChatGPT domains.
• Termight does not collect or proxy provider passwords. Use provider-owned browser or CLI auth flows.
• If a sign-in URL is untrusted or unclassified, use raw terminal mode or your browser only if you trust the source.

Permission Requests

Permission prompts can come from structured provider events, Claude hooks, Codex capture, Gemini/opencode adapters, or fallback terminal frames. For risky commands, Termight can evaluate the action through the permission firewall and attach the decision to the event.

Claude Skip Permissions

The code contains an opt-in setting named termight:agent:skip-permissions. When enabled for Claude, launch arguments include --dangerously-skip-permissions. It is off by default and should be treated as a high-risk convenience for controlled environments only.

Safety Banners

Sessions can carry environment, read-only, and safety-label metadata. Production-like labels produce stronger warnings; read-only sessions remind you to approve only actions that preserve the read-only boundary.

Stop, Reconnect, Session History

Stop A Running Agent

1. While the agent is thinking or responding, click Stop in chat mode.
2. You can also press Esc, or press Ctrl+C when the composer draft is empty.
3. Termight sends the appropriate interrupt to the shell controller and records completion state when the provider exits or returns to idle.

Reconnect

Termight has two reconnect layers. The UI websocket reconnect refreshes attention, usage, and capture status. Agent capture recovery restarts or replays ingestion watchers when a launch-owned local or remote capture source needs recovery. Durable SSH sessions also reconnect terminal state after network loss.

Session History

Agent sessions and events are stored in a normalized local event store. Use the Termight Agents area for recent sessions, attention inbox, usage, recall, retention/export, config files, MCP control, and compatibility. Scripts can query the local API endpoints /termight/sessions, /termight/events, /termight/timeline, and /termight/recall.

curl -s \
  -H "X-AuthKey: ${TERMIGHT_AUTH_KEY:-$WAVETERM_AUTH_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"category":"errors","search":"timeout","limit":10}' \
  "http://$TERMIGHT_SERVER_WEB_ENDPOINT/termight/recall"

Worktrees And Merge-Back

Termight can create one git worktree per agent session. This isolates parallel agents, records branch/worktree identity, tracks changed files, runs checks, and gates merge-back.

Launch In A Worktree

1. In Termight Agents, enable worktree creation before launching a provider, or use Race mode which creates participant worktrees automatically.
2. Termight creates a branch and worktree, records base ref and base SHA metadata, and starts the provider with TERMIGHT_WORKTREE_PATH.
3. Run the agent task in chat or terminal mode.
4. Open the review summary to inspect status, diff, changed files, checks, and merge-gate state.

Run Checks

Check presets are discovered from Taskfile tasks, package.json scripts, Makefile targets, and Go modules. Defaults include test, typecheck, lint, build, and format where available. Project policy in .termight/verification.json controls auto-run, eligible check IDs, timeout, required changes, and whether merge-back requires green verification.

Apply Or Discard

• Apply uses confirmation APPLY when the gate is ready or APPLY-WARN when checks are missing, stale, running, failed, or policy cannot be loaded but merge is still warn-allowed.
• If merge_requires_green is true, stale or failed verification blocks apply.
• Discard uses confirmation DISCARD and resets tracked/untracked worktree changes.
• Apply rejects dirty targets, unsafe relative paths, and symlinks during copy-based apply.

Race Mode

Race mode runs the same task across multiple providers or models in isolated worktrees, compares the results, and lets you apply the winner.

Race Tutorial

1. Open a Race Review block. The view type is termightrace.
2. Enter the project path and the task prompt.
3. Choose participants. The UI supports claude, codex, gemini, and opencode, with optional model, profile, and config labels.
4. Click Prepare. Termight creates a durable race record, participant sessions, branches, and worktrees.
5. Click Open agents to start or focus the participant terminal blocks.
6. Refresh the race comparison. Review answer summary, status, changed files, gate, latest check, attention, usage, adapter health, and fallback diagnostics for each participant.
7. Run checks for all runnable participants or a single participant.
8. Review the suggested winner. Type the required apply confirmation and apply the winner to the project.
9. After applying, close the race with confirmation CLOSE.
10. Remove losing worktrees after close. Cleanup has a dry-run step and can also remove branches with confirmation REMOVE-WORKTREES.

MCP Discovery And Control

Termight discovers MCP servers from .mcp.json and .claude/settings.json. Discovery returns server names, source files, command/args or URLs, transport, type, and environment key names without exposing secret values.

Control Center Concepts

• Trust scope: project config files are project-scoped; other sources are user-scoped.
• Health: local stdio servers need a command; remote/http/sse servers need a valid URL. Servers that depend on environment variables are marked with warnings.
• Risk tags: Termight tags remote servers, env-dependent servers, workspace-data services, mutating tool names, and privileged command families.
• Observed usage: recent MCP tool, resource, and prompt usage is attached from normalized events.
• Firewall decision: observed tools can be evaluated by the permission firewall, producing allow, ask, warn, or deny decisions.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "$ENV:GITHUB_TOKEN" }
    }
  }
}

Observability Export

The local API endpoint /termight/trace-export exports a provider-neutral trace for a stored session. The export maps the session, normalized events, verification checks, and merge-gate decision into span records with stable IDs and parent-child relationships.

1. Find a session ID from the Termight Agents session list or /termight/sessions.
2. Request /termight/trace-export with include_raw_payload:false for the safer default.
3. Use span fields such as provider, adapter, source, event type, prompt ID, request ID, checkpoint ID, commit SHA, worktree path, token counts, cost, redaction status, and attributes.
4. Only request raw payloads when you need them; they are still redacted before return.

Replay And Evals

Replay turns a retained session into an inspectable plan, prepares an isolated launch, and compares original and replay runs. It is designed for regression evaluation across provider versions, models, or environments.

1. Build a replay plan with /termight/replay-plan. The plan includes the original session, retained prompt, capsule baseline, target provider/model, verification policy, and lineage metadata.
2. Prepare a launch with /termight/replay-launch. The first implementation launches local worktree targets and records replay lineage on the created session.
3. Run the replay agent and checks.
4. Compare with /termight/replay-comparison. The comparison reports duration, event count, tool calls, approval requests, checks, changed files, worktree fingerprint, token usage, cost, and failure modes.

Context Packs

A context pack is an inspectable bundle of files, folders, diffs, recalled events, event searches, and snippets with token estimates. Use it before launching or steering an agent when you want reproducible, reviewable context.

1. Choose a root path or session ID.
2. Add files and folders. Termight skips symlinks and common heavy directories such as .git, node_modules, vendor, dist, build, .next, .cache, coverage, and target.
3. Include the worktree diff when relevant.
4. Add recall queries, event queries, and custom snippets.
5. Set a token budget. The response reports the estimate and whether it fits.
6. Set persist:true with a session ID to record a context.packBuilt event.

Permission Firewall

The permission firewall evaluates shell, provider-permission, MCP, browser, git, package-manager, and file actions. Decisions are allow, ask, warn, or deny, with risk level, reason, command family, mutation status, and optional audit event ID.

{
  "version": 1,
  "rules": [
    {
      "id": "allow-known-plan",
      "action": "allow",
      "environment": "prod",
      "command_pattern": "terraform plan",
      "reason": "Read-only planning is approved for this repo"
    }
  ]
}

Store project overrides in .termight/permission-firewall.json. Use persist:true when you want the firewall decision recorded as permission.firewallDecision.

Reproducible Capsules

A capsule manifest captures enough redacted evidence to reason about whether a session can be reproduced. It includes session state, provider and adapter versions, command-line hash, repo head/branch/remote evidence, worktree status/diff/fingerprint, config fingerprints, MCP fingerprints, verification policy, selected environment key fingerprints, and checks.

1. Request /termight/capsule-manifest with a session ID.
2. Pass only environment key names in env_keys. Termight fingerprints server-side values when present and never returns the values.
3. Use warnings to identify missing repo, worktree, check, config, or MCP evidence.

Tool Hygiene

The tool inventory indexes package scripts, Taskfile tasks, Makefile targets, Go defaults, simple project shell aliases, configured and observed MCP tools, and Termight local API actions. It attaches usage and failure counts from the event store, marks risky tools, and surfaces unused, stale, failing, duplicate, or high-risk warnings.

{
  "tools": [
    {
      "name": "deploy",
      "kind": "package-script",
      "examples": [
        { "label": "dry run", "command": "npm run deploy -- --dry-run" }
      ],
      "tests": [
        { "name": "deploy smoke", "command_line": "npm run deploy -- --help" }
      ]
    }
  ]
}

Store examples and compatibility checks in .termight/tool-hygiene.json. Compatibility checks run only when run_compatibility is true. With persist:true and a session ID, Termight records tool.inventoryBuilt.

PR Loop

The GitHub PR loop planner is local-first. It infers the repository from origin, captures base/head branch state, summarizes supplied GitHub checks and review comments, and returns explicit gh commands for creating a draft PR, opening the PR, and watching checks. The planner does not mutate GitHub resources by itself.

1. Review an agent session and ensure worktree changes are intentional.
2. Run checks and inspect the merge gate.
3. Build a PR loop plan with /termight/github-pr-loop, providing title, base branch, checks, and review comments if available.
4. Review returned commands before running them.
5. Persist the plan to make PR checks and review comments searchable as normalized events.

Workflow Builder

The workflow planner creates reusable multi-agent workflows with ordered stages, provider/model/profile assignments, handoff payloads, stop conditions, verification gates, owners, and worktree strategy.

If no stages are supplied, Termight creates four default stages: implementer, reviewer, test fixer, and doc updater. Actions can pause, rerun, skip, or replace stages. With persist:true, Termight records workflow.planned, workflow.stageDefined, and workflow.stageAction events.

Team Knowledge

The team knowledge layer shares selected sessions as redacted summaries, attaches annotations to sessions/events/diffs/prompts/checks/decisions, promotes snippets/context packs/tool bundles, loads approved bundles and policies from .termight/team-knowledge.json, and queries prior sessions by intent, error, file, command, provider, review outcome, or tags.

Use project or team scope depending on where the knowledge should apply. With persist:true, Termight records knowledge archive, annotation, promotion, and query events.

Archive/share builds are currently local API automation. The in-app Knowledge panel covers create, import, review, conflict resolution, and audit history.

Project-Owned .termight Files

Project-owned files make agent sessions repeatable across terminals, worktrees, and teammates. The Settings agent tab discovers and edits known files, while the local API exposes read-only discovery through /termight/config-files and /termight/mcp-servers.

WSL, SSH, Remote Usage

Termight supports local terminals, SSH connections, and WSL distributions on Windows. Remote terminals can use the tsh shell extension to bridge Termight features into the remote shell.

Connect To SSH

1. Click the connection button in a terminal header, or press Cmd+G on macOS / Alt+G on Windows/Linux.
2. Enter user@host, host, or user@host:port.
3. Termight parses supported SSH config fields such as Host, User, HostName, Port, IdentityFile, ProxyJump, auth preferences, and known-host files.
4. When prompted, install tsh on the remote host unless you want terminal-only behavior.

Connect To WSL

1. Use the connection switcher and select a WSL distribution, or enter wsl://<distribution name>.
2. From the CLI, run tsh wsl -d <distribution-name>, or omit -d for the default distro.
3. WSL sessions are standard sessions rather than durable sessions.

Durable SSH Sessions

Durable sessions keep remote SSH shells alive through network changes, computer sleep, and Termight restarts. They preserve shell state, running programs, and scrollback by running a lightweight job manager on the remote server.

• Enable globally with "term:durable": true, per connection, or per block.
• Use the terminal shield icon or context menu to restart as durable or standard. Switching modes restarts the shell.
• Durable sessions are for SSH only. Local and WSL terminals use standard sessions.

Remote File Bridge

From a remote shell, run tsh file commands to access local files. Local file paths still use the wsh://local/~/ URI scheme, or the shorthand /~/:

tsh file cat wsh://local/~/config/app.json
tsh file cp ./results.txt wsh://local/~/results.txt
bash <(tsh file cat /~/scripts/deploy.sh)

Desktop Launcher

The launcher is a block type for starting widgets. Replace the focused block with the launcher using Ctrl+Shift+X. You can also set app:defaultnewblock to launcher so new-block commands open the launcher instead of a terminal.

1. Open or focus any block.
2. Press Ctrl+Shift+X.
3. Type to filter launcher entries.
4. Press Enter to launch the selected widget.

Termight Assistant

Termight Assistant is a context-aware sidebar assistant separate from provider CLI chat sessions. Toggle it with Cmd+Shift+A on macOS or the corresponding Alt shortcut on Windows/Linux.

• Widget context on: assistant can read terminal output, capture widget screenshots, access approved files/directories, navigate web widgets, and use custom widget tools.
• Widget context off: assistant sees only your messages and attachments.
• Attach images, PDFs, and text/code files within documented size limits.
• Use tsh ai to send stdin, files, logs, or diffs to the assistant.
• Configure local models and BYOK modes in termightassistant.json; edit it with tsh editconfig termightassistant.json.

Troubleshooting

Provider CLI Not Ready

• Run claude --version, codex --version, or gemini --version in a Termight terminal.
• Run the provider once to finish provider-owned auth.
• Refresh the compatibility panel in Termight Agents.

Native Prompt Looks Wrong

• Switch to raw terminal mode.
• Answer directly in the provider-owned CLI.
• Check the session compatibility view for fallback activation or adapter drift.

tsh Missing On Remote

• Use tsh conn reinstall user@host or tsh conn reinstall wsl://distro.
• Check that the remote shell is bash, zsh, PowerShell, or fish.
• For SSH, verify AllowTcpForwarding is yes or local in remote sshd_config.
• Use tsh termightpath log to find the log file, or enable Debug Connection from the terminal gear menu.

Checks Or Merge-Back Blocked

• Open the review summary and read the merge gate message.
• Run or rerun checks if the fingerprint is stale.
• Inspect .termight/verification.json for merge_requires_green.
• Clean dirty target changes before applying an agent worktree.

Telemetry And Privacy

• Telemetry is disabled by default in the documented default config and can be changed with tsh setconfig telemetry:enabled=false.
• Termight telemetry docs say it does not collect PII, keystrokes, file contents, AI prompts, IP addresses, hostnames, or commands.
• Set TERMIGHT_NOPING to disable the separate anonymous diagnostics ping.

Glossary

Sources And Gaps

This guide was compiled only from repo-local documentation, code, and tests. Key source files include:

• README.md
• BUILD.md
• docs/docs/gettingstarted.mdx
• docs/docs/workspaces.mdx
• docs/docs/tabs.mdx
• docs/docs/widgets.mdx
• docs/docs/keybindings.mdx
• docs/docs/connections.mdx
• docs/docs/durable-sessions.mdx
• docs/docs/wsh.mdx
• docs/docs/wsh-reference.mdx
• docs/docs/claude-code.mdx
• docs/docs/agent-project-files.mdx
• docs/docs/waveai.mdx
• docs/docs/waveai-modes.mdx
• docs/docs/config.mdx
• docs/docs/telemetry.mdx
• docs/termight-product-direction.md
• docs/termight-local-api.md
• docs/termight-completion-checklist.md
• pkg/termight/*.go feature implementations
• frontend/app/termight/*.ts agent UI helpers
• frontend/app/view/termightconfig/termightagentscontent.tsx
• frontend/app/view/termightrace/termightrace.tsx

Known Source Gaps And Assumptions

• docs/docs/termight-status.mdx lists several live smoke gaps that the newer docs/termight-completion-checklist.md marks done. This guide follows the newer checklist where they conflict.
• Gemini CLI support is documented and implemented as partial; the checklist says live Gemini smoke still needs configured Gemini auth.
• WSL shell integration smoke is documented but still needs live evidence on a Windows/WSL host.
• Some advanced workflows, including workflow builder, team knowledge, replay, capsule, trace export, tool inventory, and PR loop, are documented primarily through local API and service contracts rather than polished end-user screens.
• The phrase "desktop launcher" is not a separate packaged app-launcher doc in the repo; this guide maps it to the documented Termight launcher block and app:defaultnewblock behavior.