Contents
Why Tether
Coding agents are fast, but leaving them alone on your repo is a gamble. Tether gives them room to work and keeps you in control:
- Room to run. Every run gets its own git worktree and branch. Your checkout is never touched.
- The line holds. Gates (your test command, a saved API check, a human approval) decide what passes. Never the model's own word.
- Nothing is lost. Every run is an append-only event log. Stop, close the app, come back, and resume from the first unfinished step.
What you get
| |
|---|
| 🧭 Home and Inbox | One place for what needs you, what is running and what just finished. Approve or retry inline. |
| 🗺️ Run view | A live run graph, the output stream, changed files and one approval bar. Click a step to inspect its output, diff and timeline. |
| 💬 Tether assistant (⌘J) | Ask about your runs and code. Answers cite their sources. It can start runs, but only through approval cards. |
| 🧩 Builder | Design workflows on a canvas: planner → architect → coder → tests → reviewer → approval, with fix loops. |
| 👥 Crew | Link any bot to any agent and model. Import 68 extra agents and their skills from ECC. |
| 🤝 Team runs | Give a goal. Tether asks a few questions, writes a plan you approve, then a manager hands the work around. |
| 🎯 Goals | A finish check (tests, a command, a number) that keeps starting runs until it passes or the budget runs out. Or just a checklist. |
| 📂 Code | Browse and edit your project, search it with ⌘⇧F, and see which runs changed each file. |
| 🔌 API client | Saved HTTP requests per project (import cURL, OpenAPI, Postman). Use them as gates or hand them to an agent. |
| 🕸️ Graph | A knowledge graph of runs, workflows, roles and notes from your Obsidian-style vault. |
| ⚡ Triggers | Start a workflow when a GitHub pull request opens or changes, by webhook or polling. |
| 🧪 Evolve | Bots learn from your 👍/👎 and from run outcomes. Tether proposes small, versioned prompt edits. You accept or reject each one. |
| 🧰 Code Mode | Agents call tools by writing one small script, run in a local sandbox, instead of making many separate tool calls. |
| 🔐 Accounts | Connect GitHub, either by reusing your gh login or through a device sign-in. Tokens stay in the macOS Keychain. |
Works with Claude Code, Codex and OpenCode, local servers (Ollama, LM Studio, llama.cpp) and any OpenAI-compatible provider (DeepSeek, OpenAI, OpenRouter, NVIDIA, Groq, Together, Fireworks).
A tour of the app
There is also a full terminal UI (tether tui) with the same runs, workflows, crew, triggers and chat. See Terminal UI tips.
Quick start
You need Node 22.12+ and git. Install whichever agents you want to use (claude, codex, opencode) or run a local model server.
git clone https://github.com/tusharcora/Tether.git && cd Tether
npm install
npm run build
npm link # optional: puts `tether` on your PATH (`aorch` still works too)
tether doctor # which agents and local model servers were found
tether init # install the example workflows
tether serve # the web app on http://127.0.0.1:4177 (loopback only)
tether tui # or the terminal UI
Then start something:
tether team "add rate limiting to the API" --repo ~/code/api # Tether plans with you, then a team works
tether orchestrate "fix the flaky login test" --repo ~/code/api # Tether designs a workflow and runs it
tether run plan-code-review --repo ~/code/api --task "add a /health route" # run a saved workflow
Tether.app (macOS, Apple Silicon)
npm run app # builds dist-app/Tether-darwin-arm64/Tether.app (ad-hoc signed)
npm run app:dev # the app window on the Vite dev server, for UI work
The app runs the same server inside itself and shares the same home folder. It is signed for your Mac only, so the first time you open it, right-click Tether.app → Open. Open a project with File → Open Folder… (⌘O), by dropping a folder on the window, or with open -a Tether <dir>.
How a run works
flowchart LR
A[You: a task or goal] --> B[Tether picks<br/>workflow + crew]
B --> C[New git worktree<br/>branch aorch/<runId>]
C --> D[Scout plans<br/>Brick designs]
D --> E[Bolt writes code]
E --> F{Gates<br/>tests · checks}
F -- fail --> E
F -- pass --> G[Lens reviews]
G -- FAIL --> E
G -- PASS --> H{Gate:<br/>you approve}
H --> I[Merge the branch<br/>when you choose]
- If a step fails, the supervisor retries it, then hands it to a stronger model, then stops and explains what went wrong.
- Bots can ask each other (
@ASK) and hand off work (@HAND). Workers can ask you a question with a recommended answer.
- In live mode you see every report and question. In autonomous mode Tether answers with the recommended options and reports once at the end.
- Budgets and time limits cover the whole run. Team runs default to a
$5 cap.
Any folder, git or not
Workflows, squads and tickets work in any folder you register, with or without git. In a folder without git, Tether keeps a hidden history under your Tether home, never in the folder, and a run works in its own worktree, where your files are copied in. Nothing is added to the folder: no .git, no .aorch, no .tether.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
