tide 0.3.4

Mission control for your coding agents — spin up, watch, and steer a fleet of AI coding agents from your terminal.

🌊 tide

Mission control for your coding agents.

Spin up, watch, and steer a fleet of AI coding agents — each in its own isolated workspace — from one delightful terminal cockpit.

---

Running coding agents today means babysitting: open a sandbox, set it up, launch the agent, repeat, then juggle a dozen terminals trying to remember which one is doing what. tide turns that into a single command and a calm dashboard.

• 🚀 Launch in one keystroke. Define an agent profile once — repo, task, model, MCP servers, environment — then cast off as many agents as you need.
• 🧭 Each agent in its own lane. Every run gets an isolated git worktree on its own branch, so agents never step on each other (or your working tree).
• 👀 See what needs you. The dashboard ranks agents by who needs your attention — failed and finished-with-changes float to the top; the calm ones stay out of your way.
• 🪵 Live logs & diffs. Tail any agent's output and review its changes without leaving the terminal.
• 🔌 Bring your own agent. Defaults to Claude Code, but a profile can launch any command, so tide works with whatever you run.
• 🖥️ Terminal or browser. A keyboard-driven TUI and a polished web cockpit, both over the same shared state.
• 🛎️ Event-driven. Point a Wiz / PagerDuty / Sentry / GitHub webhook at tide and a matching alert auto-launches an agent — at the autonomy you choose (propose → it waits for your approval · auto → it runs immediately).
• 🗂️ Across your org. Register repos by name and launch into any — or fan one task out across many at once, an isolated agent (and PR) per repo.
• 🧠 Planner. Hand tide one instruction and it works out which of your repos it touches and what each should change — you review, then it dispatches.
• 🔑 Env once. Reusable env sets (optionally synced from GitHub) attach to profiles.
• 🧩 Any provider. Claude Code, Codex, Gemini, Cursor, Aider — or any command.
• 🧱 Real isolation, when you want it. Run an agent on the host worktree, or inside a container built from the repo's .devcontainer — just set workspace = "devcontainer" on its profile.

tide is local-first and zero-ops: no cloud account, no daemon, no infrastructure. It orchestrates git and your agent CLI on your machine.

Install

uv tool install tide     # recommended — installs as an isolated tool
# or
pipx install tide
# or
pip install tide

Prefer source? uv tool install git+https://github.com/gauthierpiarrette/tide, or clone the repo and run uv tool install ..

Requires Python 3.11+ and git. To launch Claude Code agents, install the Claude Code CLI (claude).

Quickstart

# 1. open the web cockpit in your browser
tide

# 2. ...prefer the terminal? open the TUI instead
tide tui

# 3. ...or launch an agent straight from the shell
tide up "add retry logic to the upload client"

# 4. see your fleet
tide ls

The first time you run tide up, a starter profile is created for you. In the TUI (tide tui), press n to launch a new agent, enter to open one, s to stop it, and ? for the full keymap.

Web cockpit

Bare tide opens a full GUI on localhost with a rich composer — multi-line prompts, pasted context, and drag-&-drop file attachments — plus the live fleet, streaming output, diff review, and the planner. Everything the CLI does, easier. It shares the same state, so agents launched in the browser show up in the terminal (tide tui) and vice-versa.

tide web                 # opens http://127.0.0.1:8765

Across many repos

Registered repos aren't just one-at-a-time targets — fan a single task out across several and tide launches one isolated agent (and one PR) per repo:

tide up "bump the logging lib to v2 and fix the call sites" -r api -r web -r workers

Each agent works in its own worktree on its own branch, so the changes — and the PRs — stay independent. Agents that find nothing to do finish quietly with no PR, so you only get a pull request where the change actually applied. In the web cockpit, the composer's repo picker selects several the same way.

Planner — one instruction, the right repos

Not sure which repos a change belongs in? Let tide plan it. tide plan surveys your registered repos (a quick code search for the terms in your instruction) and proposes which repos are in scope and a tailored prompt for each, with shared cross-repo context threaded through every one.

tide plan new "rename BillingAccount.tier to plan and update everything that reads it"
#   → surveys repos, prints a per-repo plan (which repos · what each will change)

tide plan apply <id>        # dispatch the selected repos — one agent & PR each

The plan is a proposal you review — deselect a repo before applying, or pass --apply to dispatch immediately. Planning uses your configured Claude CLI by default (override with TIDE_PLANNER_BIN).

Profiles

A profile is a reusable recipe for spinning up an agent. Profiles live in ~/.config/tide/config.toml (global) or .tide/config.toml (per-project).

[profiles.default]
description = "Claude Code on the current repo"
command = 'claude -p "{task}"'        # {task} is filled in at launch
base_branch = "main"                   # branch each worktree forks from

[profiles.review]
description = "Read-only reviewer with the GitHub MCP server"
command = 'claude -p "{task}"'
model = "claude-opus-4-8"
env = { CLAUDE_PERMISSION_MODE = "plan" }

  [profiles.review.mcp_servers.github]
  command = "npx"
  args = ["-y", "@modelcontextprotocol/server-github"]

When a profile defines mcp_servers, tide writes a .mcp.json into that agent's worktree before launch — so each agent gets exactly the tools you chose.

To run a profile's agents inside a container (real dependency/OS isolation), set workspace = "devcontainer" (or tide profile add <name> --workspace devcontainer). tide bind-mounts the worktree into the container, so diffs still flow back to the host. Requires Docker and the Dev Containers CLI (npm i -g @devcontainers/cli).

How it works

            tide up "task"
                  │
        ┌─────────▼──────────┐
        │   FleetManager     │   tracks every agent, persists state
        └─────────┬──────────┘
                  │ creates
        ┌─────────▼──────────┐
        │  WorktreeRuntime   │   git worktree + branch  →  isolated lane
        └─────────┬──────────┘
                  │ runs your profile's command (cwd = worktree)
        ┌─────────▼──────────┐
        │   your agent CLI   │   e.g. `claude -p "..."`
        └────────────────────┘

Each agent is a real OS process running your command inside a dedicated git worktree. tide records its branch, status, runtime, and diff, and surfaces the ones that need you. Stopping an agent terminates its process group; removing one cleans up its worktree.

Commands

Command	What it does
tide	Open the web cockpit in your browser
tide tui	Open the terminal cockpit (TUI)
tide web	Open the web cockpit (with --host/--port options)
tide up "<task>" [-p profile] [-r repo …]	Launch an agent — repeat -r to fan out across repos
tide ls	List the fleet
tide logs <id>	Stream an agent's output
tide follow <id> "<msg>"	Send a follow-up turn into the agent's worktree
tide stop <id>	Stop a running agent
tide done <id>	Mark a finished agent reviewed (clears it from the inbox)
tide rm <id>	Remove an agent and clean up its worktree
tide profile ls	List profiles
tide profile add <name>	Create/update a profile (provider/workspace)
tide approve <id>	Approve a trigger-proposed agent
tide repo add/ls/rm	Manage the org repo registry
tide plan new "<instruction>"	Survey repos & propose a per-repo plan
tide plan apply <id>	Dispatch a plan's selected repos (one agent & PR each)
tide plan ls/show/rm	List, inspect, or delete plans
tide env set/ls/sync-github	Manage reusable env sets
tide trigger add/ls/rm/toggle	Manage event triggers (sensors)
tide trigger webhook-url	Print the inbound webhook URL

Sensors & triggers

Turn events into agents. Create a trigger, point an alert source at tide's webhook, and matching events launch an agent automatically — gated by the autonomy level you chose.

tide trigger add wiz-high -p investigate -m severity=high -a propose
tide trigger webhook-url        # → point Wiz / PagerDuty / Sentry / GitHub here

A high-severity alert then auto-proposes an investigator agent built from the payload; you approve it (tide approve <id> or the web button) and it runs in its own isolated worktree. Schedule triggers (--every <seconds>) run on a timer.

Roadmap

• Remote & cloud workspaces — run agents on a remote Docker host or a cloud sandbox, beyond the local devcontainer backend.
• Routing flywheel — use the recorded outcomes to send each task to the provider/profile that has historically succeeded at it.
• Team plane — shared profiles, secrets, and triggers; audit and cost.
• Parallel exploration — launch the same task N ways, keep the best.
• Planner in the cockpit — a visual plan-review UI (the planner ships CLI-first today).

License

MIT