Tether

Tether is the local-first agent session control plane. A per-user daemon (tetherd) owns session lifecycle, process/PTY management, sandboxed execution, checkpoint/resume, brokered messaging, and event streams for CLI-backed agents such as Claude Code, Codex, Kiro, OpenCode, and Antigravity (agy). Clients reach it over a Unix-domain socket through the tether CLI, the HTTP API, the MCP stdio adapter, the ACP surface, or go-tether-client.

Pre-1.0. Tether is under active development. Tagged releases package the runtime and Sysop for macOS and Linux; interfaces can change between releases. See the changelog and install guide for the shipped contracts.

What it is today

• Session control plane. Every launch, attach, stop, and checkpoint for a CLI agent goes through tetherd; clients never manage the process directly.
• Brokered messaging. Durable mail (tether messages send) and notify+wake (tether messages notify) between agents and humans, plus typed envelope delivery through /broker/*.
• Event streams. Durable event history and an SSE bus (/events*, tether events watch) for daemon and session activity.
• MCP adapter, both directions. tether mcp exposes the runtime as MCP tools over stdio for any MCP client (Claude Desktop, Claude Code, Cursor); Tether is also the MCP connection this assistant is running on right now — every torque_*, tesseract_*, tangent_*, cerberus_*, and loom_* tool call in this session arrives over one tether MCP endpoint.
• AI gateway. A typed, multi-provider chat/embeddings surface (Anthropic, Gemini, OpenAI, OpenAI-compatible) with routing rules, request budgets, and durable usage accounting — reachable over HTTP, CLI, or MCP.
• Sysop GUI. tether_sysop, bundled in release archives, gives a local operations view over sessions, MCP, AI routing, activity, and the registry.

Where it sits in the stack

   you / agents / other apps      Claude Code, Codex, OpenCode, Torque,
         │                        Tesseract, Nanite — anything with an
         ▼                        MCP client or the tether CLI/HTTP API
   ┌───────────┐
   │  tetherd     │   session lifecycle, messaging, events, AI gateway,
   │ (Tether)  │   sandboxing — the agent session, mesh and orchestration layer
   └───────────┘
         │
   launched sessions      the actual coding-agent processes Tether
                           supervises (PTY, checkpoint, recovery)

Tether doesn't decide what a task means or what an agent should do next — that's Torque's and each agent's job. It owns getting a session running, keeping it addressable, and moving messages and events between whatever is attached.

Examples

Daily driver. Chrispian launches and attaches to CLI agent sessions through tether sessions launch / tether sessions attach, and this Claude Code session itself is reached through Tether's MCP adapter.

Composition. An agent running under Tether calls out to Torque and Tesseract as ordinary MCP tools over the same connection, sends durable mail to another agent via tether messages send, and gets notified back through tether messages notify when a reply lands — no polling, no direct process-to-process coupling.

Cross-host. docs/messaging-federation.md covers routing messages to a peer Tether daemon on another host, for agents that aren't all running on the same machine.

External Claude sessions. Opt-in tether messages claude-hook emits unread mail counts and message-check reminders using the existing authenticated daemon client. It leaves delivery and read state unchanged. See the external-session guide for lifecycle hooks, bounded one-shot idle notification and a recurring native /loop recipe. Configuration and schedules are installed explicitly, and require a Claude version that supports the chosen interface.

Roadmap

• Platform reshape to a directory-registry substrate. Moving from precomputed per-project/agent/provider launch files to a live directory service that consumers register capabilities with (agent sources, skill sources, MCP servers, execution templates) and a parameterized launch engine (substrate/harness/agentlaunch) that resolves them at call time. Ships alongside the current catalog system so existing launches keep working during the migration.
• Boot Assembly Spec. Replacing static launches/ and boot-profiles/ files with a single parameterized artifact per agent, resolved against live inputs instead of a frozen file per project × agent × provider tuple.
• Foundation completion for downstream consumers. Hardening provider/session contracts, message routing, and agent/skill/boot specification so Nanite and other systems can build on Tether as an opt-in substrate rather than a bespoke integration.

License & Branding

Tether is open source under the MIT License.

You are free to use, modify, and build on Tether for personal or commercial use.

The Tether name and Hollis Labs branding are protected trademarks. If you build on Tether, describe that relationship in a way that does not imply your fork or service is the official Tether distribution.

See TRADEMARK.md for details.

Install

Release archives ship three binaries:

• tether — the main CLI and daemon launcher
• tether-apikey-helper — optional helper for local keychain-backed AI secrets
• tether_sysop — the operations GUI with its frontend embedded

Install paths:

Option 1: Homebrew

Once the tap formula is published:

brew install hollis-labs/tap/tether

Option 2: Release tarball

Download the archive for your platform from a tagged release:

curl -L -o tether.tar.gz \
  https://github.com/hollis-labs/tether/releases/download/v<version>/tether_<version>_darwin_arm64.tar.gz
tar -xzf tether.tar.gz
install -d "$HOME/.local/bin"
install -m 0755 tether "$HOME/.local/bin/"
install -m 0755 tether-apikey-helper "$HOME/.local/bin/"
install -m 0755 tether_sysop "$HOME/.local/bin/"
export PATH="$HOME/.local/bin:$PATH"

Option 3: Build from source

git clone git@github.com:hollis-labs/tether.git
cd tether
make release-build
export PATH="$PWD/bin:$PWD/apps/sysop:$PATH"

Or install into a prefix:

make install PREFIX="$HOME/.local"
GOBIN="$HOME/.local/bin" make sysop-install

Option 4: go install

go install github.com/hollis-labs/tether/cmd/tether@latest
go install github.com/hollis-labs/tether/cmd/tether-apikey-helper@latest

After install, run tether init for the guided first-time setup (idempotent, skippable at every step). See docs/install.md for prerequisites, keychain configuration, and path details.

Build

make build          # produces bin/tether and bin/tether-apikey-helper
make sysop-build    # builds the frontend and apps/sysop/tether_sysop
make check          # fmt + vet + lint + test-race + vuln

Requires the Go version in go.mod; Sysop source builds also need Node.js 22+ and npm. See docs/dev-setup.md for the full development setup including catalog configuration.

Quick start

# Guided first-time setup (idempotent; detects claude/codex/opencode/agy automatically)
tether init

# Start the daemon
tether daemon start

# Check detected provider binaries and system health
tether detect
tether doctor

# Launch an agent session from a catalog launch profile
tether sessions launch myproject-backend

# Attach to a running session
tether sessions attach <session-id>

# List sessions
tether sessions list

# Send durable mail, or notify + wake a live recipient session
tether messages send --from msg://user/local/me --to msg://agent/local/worker "hello"
tether messages notify --from msg://user/local/me --to msg://agent/local/worker --urgency high "check inbox"

# Stop a session
tether sessions stop <session-id>

# Generate a boot prompt and pipe it to a new session
tether generate-boot nanite.backend.main | pbcopy

# Start the MCP adapter (for LLM tool access)
TETHER_TOKEN='<tth_issued-token>' \
TETHER_MCP_SCOPES=session.write,message.write \
tether mcp

# Inspect configured AI providers
tether ai providers

# Inspect durable event history
tether events history --scope daemon --limit 20

# Stream live events
tether events watch --scope daemon --kind daemon.started

# Preview or invoke the AI gateway
tether ai route-preview "Summarize this diff"
tether ai chat "Summarize this diff"
tether ai chat --stream "Summarize this diff"

Sysop GUI

tether_sysop is the operations GUI, bundled in every release tarball and the Homebrew formula. Start it after tether daemon start:

tether_sysop
# → http://localhost:8947/

The Operations page is the home landing; direct routes include /overview, /mcp, /ai, /activity, /tools, /registry, /logs, /settings.

To build from source:

cd apps/sysop
make all
./tether_sysop

See apps/sysop/README.md for development and packaging details.

MCP adapter

tether mcp exposes the runtime as 23 MCP tools over stdio, usable from Claude Desktop, Claude Code, Cursor, or any MCP-capable agent:

{
  "mcpServers": {
    "tether": {
      "command": "tether",
      "args": ["mcp"],
      "env": {
        "TETHER_TOKEN": "<issued-tth-token>",
        "TETHER_MCP_SCOPES": "session.write,message.write"
      }
    }
  }
}

See docs/mcp.md for the full tool reference and setup guide.

AI gateway

Tether also exposes a typed local AI gateway when global.yaml configures at least one enabled AI provider. Supported provider types currently include anthropic, gemini, openai, and openai-compatible. The current surfaces are:

• HTTP: /ai/providers, /ai/models, /ai/routes, /ai/routes/preview, /ai/routes/explain, /ai/chat, /ai/chat/stream, /ai/embeddings, /ai/decide, /ai/usage, /ai/budgets, /ai/audit
• CLI: tether ai providers|models|routes|route-preview|route-explain|chat|embeddings|usage|budgets|audit|watch-budgets
• MCP: tether_ai_list_providers, tether_ai_list_models, tether_ai_list_routes, tether_ai_route_preview, tether_ai_route_explain, tether_ai_chat, tether_ai_chat_stream, tether_ai_embeddings, tether_ai_decide, tether_ai_usage, tether_ai_budgets, tether_ai_audit

tether ai chat and tether ai route-preview accept either simple text input or a full normalized request via --request-file or --request-json. tether ai chat --stream uses the daemon SSE surface and renders incremental text deltas plus the final normalized response summary. For multimodal shorthand, tether ai chat, tether ai route-preview, and tether ai route-explain also accept --image-file and --image-url to append image parts without hand-writing normalized JSON. tether ai embeddings "hello world" generates vectors through the same routed gateway, and configured custom local model ids remain routable even when models.dev does not yet know them. Operators can also define ordered ai.routing.routes entries in global.yaml to steer provider/model selection by mode, intent, reasoning, or tool requirements, plus optional allow_* policy gates that reject disallowed request shapes with explicit route-explain diagnostics. Those policy gates, request-local budget ceilings, and durable usage_budget controls can be set globally, per provider, or per route. Durable usage budgets are enforced from the ai_events history with daily or monthly windows and total, caller, or session scope. tether ai watch-budgets tails live ai.budget_rejected daemon events over /events/stream?scope=daemon&kind=ai.budget_rejected.

Keychain setup examples:

printf '%s\n' "$OPENAI_API_KEY" | tether-apikey-helper set keychain://openai/work
printf '%s\n' "$GEMINI_API_KEY" | tether-apikey-helper set keychain://gemini/work
printf '%s\n' "$ANTHROPIC_API_KEY" | tether-apikey-helper set keychain://anthropic/work

Documentation

Doc	Contents
docs/dev-setup.md	Full dev setup, catalog schema, common tasks
docs/messaging.md	Direct mail, notify+wake, inbox/list semantics
docs/messaging-adoption.md	How an app, agent or hand-run MCP session joins messaging
docs/messaging-integration.md	Implementer's guide: identity ownership, binding lifecycle, error handling
docs/messaging-federation.md	Cross-host peer routing and trust
docs/external-session-wake.md	Opt-in Claude mailbox count/reminder hooks and provider capability limits
docs/shim-host.md	Hosted provider placement, recovery and public delivery boundaries
docs/agy-shim-acceptance.md	Operator-owned AGY restart acceptance matrix
docs/workstreams.md	Workstreams, session refs, and the recovery digest
docs/mcp.md	MCP adapter setup, auth, tool reference
docs/api/README.md	HTTP/UDS daemon API reference
docs/go-client-migration.md	Migrating apps from go-agenttether-client to go-tether-client
docs/sandboxing.md	Sandbox profiles (macOS + Linux)
CONTRIBUTING.md	Contribution workflow and code style

Architecture decision records and internal planning history moved out of the repo in a docs cleanup pass — see AGENTS.md for where.

Catalog

Tether is driven by a YAML catalog at ~/.tether/catalog/. The catalog defines projects, agent profiles, providers, and launch configurations. See examples/catalog/ for working examples and docs/dev-setup.md for the full schema.