Documentation

The shim wraps your agent CLI, coaxes a plan before any action, and submits it to the master. The master detects conflicts at plan stage — before any code lands. The dashboard gives you a live view of intents, concepts, and conflicts.

Quick start

1. •
   Install the tether CLI:

   TERMINAL

   # Homebrew (macOS / Linux)
   brew install tetherlab/tap/tether
   
   # Or via install script
   curl -fsSL https://raw.githubusercontent.com/tetherlab/tether/main/install/install.sh | sh

2. •
   Sign in and configure:

   TERMINAL

   tether login
   tether init --global --developer alice

   This discovers your SSH key, writes ~/.tether/config.toml, and launches the onboarding wizard.

3. •
   Wrap your agent:

   TERMINAL

   tether wrap claude -p "Add a login endpoint"

Open the dashboard at /app/intents to watch your first intent arrive. The shim submits the plan, the master returns continue, stop, or revert.

# Homebrew (macOS / Linux)
brew install tetherlab/tap/tether

# Install script (macOS / Linux)
curl -fsSL https://raw.githubusercontent.com/tetherlab/tether/main/install/install.sh | sh

# Install script (Windows)
irm https://raw.githubusercontent.com/tetherlab/tether/main/install/install.ps1 | iex

The install script verifies SHA-256 checksums and installs to ~/.tether/bin. Flags include --version, --no-modify-path, and --no-login.

Verify: tether --version and tether doctor.

The shim reads two TOML config files. Per-project overrides global.

developer = "alice"
master_url = "http://localhost:8080"
ssh_key_path = "/home/alice/.ssh/id_ed25519"
# workspace_id = ""   # set after first workspace bind

developer = ""                        # inherited from global
master_url = "http://localhost:8080"  # inherited
workspace_id = "550e8400-..."         # bound by init

SSH key discovery precedence: ~/.ssh/id_ed25519 → id_rsa → id_ecdsa → --ssh-key flag. Your SSH public key must be registered with Tetherlab.

Run tether init inside a git repo for project config. The onboarding wizard (tether onboard) walks through identity, workspace binding, and concept bootstrap. Verify with tether status and tether doctor.

A workspace is the coordination unit. Each workspace holds its own intents, concepts, conflicts, agent registrations, and a bare git clone. All coordination happens within a workspace boundary.

Workspace membership is invite-based. An owner creates an invite from the dashboard at /app/workspace/settings. Members have roles: Owner (full control), Member (submit intents, resolve conflicts), Viewer (read-only).

The shim intercepts the agent process at launch. Before the agent takes any action, the shim coaxes a plan from it, captures a worktree snapshot, and submits both as an intent. Execution proceeds only on continue.

tether wrap claude -p "Refactor the auth middleware"
tether wrap opencode "Add rate limiting"
tether wrap --continuous claude     # multi-plan session
tether wrap npm test                # passthrough

Safety invariants

• Pre-decision action gate — no agent action before master says continue
• No fabricated intents — plan extraction failure exits without contacting master
• Fail closed on identity — auth errors abort; concept resolve errors warn

Add --continuous to keep the agent alive across multiple plans. After each completion the shim re-enters the planning phase. The agent conversation, context, and file state persist.

tether wrap --continuous claude

The lifecycle: Plan → Decide (continue/stop/revert) → Execute → Complete (agent emits ::tether-done::) → Await next plan. End the session with ::tether-end-session::. Capped at 100 plans per session (TETHER_MAX_CONTINUOUS_PLANS).

An alternative integration path for agents that speak the Model Context Protocol. The agent calls MCP tools directly instead of being wrapped by the shim.

{
  "mcpServers": {
    "tether": {
      "command": "tether-mcp-server",
      "args": ["--continuous"]
    }
  }
}

Every wrap session runs through a 14-state machine in the shim.

Idle → Authenticating → PreparingAgent → ExtractingPlan → SubmittingIntent → AwaitingMasterDecision → Executing → WatchingSemanticDiffs → HandlingRescope → AwaitingNextPlan → Complete/Stopped/Reverted/Failed/Done

Each transition is gated. Auth must succeed before the agent spawns. Plan extraction must succeed before an intent is submitted. The master's decision must return before execution.

Conflicts are detected at plan stage, not merge time. When two agents submit intents touching overlapping concepts, the master flags a hard conflict. Overlapping file paths trigger a coarse conflict (tunable via TETHER_COORDINATE_NOT_BLOCK).

The dashboard uses Supabase Auth (GitHub and Google OAuth) and maintains one WebSocket connection per mount for real-time updates. Workspace switches trigger socket reconnects. Events broadcast by the master update the SWR cache in place.

Design: Forest Clay dark theme (evergreen + clay + parchment). Poppins for UI, JetBrains Mono for code. 5-level elevation stack.

Tauri 2 + React 19 native app. Mirrors the web dashboard with React Router 7. The Rust backend imports tether-shim-core for local operations. IPC commands: config discovery, SSH identity, master health checks, agent log tailing, git status.

Distributed as .dmg (macOS) and .deb/.AppImage (Linux).

A concept is a named, semantically meaningful unit of code — "auth module", "rate limiter", "payment handler". Concepts bridge the gap between what an agent says it will change and what files will be modified. They enable intent resolution, conflict detection, and blast radius analysis.

Concept graph edges

When the LLM matcher detects concepts not yet in the registry, the master creates proposals and parks the engagement in blocked — the shim prompts the agent (via the developer) to confirm or reject. Duplicate concepts can be merged from the dashboard.

Tetherlab detects conflicts at plan time, before code is written. Overlapping concepts → hard conflict (losing intent gets stop/revert). Overlapping files → coarse conflict (advisory by default). No overlap → parallel execution.

Resolution flow: Conflict appears in dashboard and inbox → loser is blocked → developer resolves (continue/stop/revert/dismiss) → loser unblocks. The dashboard at /app/conflicts shows collapsible cards with winner/loser intents, overlapping concepts, and blast radius visualization. Bulk resolution is supported.

The tether binary. All commands read config from ~/.tether/config.toml (global) and .tether/config.toml (project).

Start with tether doctor. The shim writes logs to file only (not stderr) — check ~/.tether/shim.log.

The MCP server reads the same TOML as the shim. CLI overrides: --continuous, --agent claude|opencode, --master-url, --workspace-id, --log-level.

~/.tether/
config.toml      # global config
shim.log          # shim logs (file-only)
mcp.log           # MCP server logs
daemon.sock       # Unix domain socket
daemon.pid        # PID file

my-project/.tether/
config.toml       # project config
hook-dispatch.txt # Claude hook buffer