Metadata-Version: 2.4
Name: tide
Version: 0.3.3
Summary: Mission control for your coding agents — spin up, watch, and steer a fleet of AI coding agents from your terminal.
Project-URL: Homepage, https://github.com/gauthierpiarrette/tide
Project-URL: Repository, https://github.com/gauthierpiarrette/tide
Author: Gauthier Piarrette
License: MIT
License-File: LICENSE
Keywords: agents,ai,claude,claude-code,developer-tools,orchestration,tui
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.110
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: rich>=13.0
Requires-Dist: textual>=0.80
Requires-Dist: tomli-w>=1.0
Requires-Dist: typer>=0.12
Requires-Dist: uvicorn[standard]>=0.29
Provides-Extra: dev
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: textual-dev>=1.5; extra == 'dev'
Description-Content-Type: text/markdown

<div align="center">

# 🌊 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.

</div>

---

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](https://claude.com/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

```bash
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](https://claude.com/claude-code) (`claude`).

## Quickstart

```bash
# 1. open the cockpit (run this inside a git repo)
tide

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

# 3. see your fleet
tide ls
```

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

## Web cockpit

Prefer a browser? `tide web` 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, and diff review.
Everything the CLI does, easier. It shares the same state, so agents launched in
the browser show up in the terminal and vice-versa.

```bash
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**:

```bash
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.

```bash
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).

```toml
[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 TUI cockpit |
| `tide web` | Open the web cockpit in your browser |
| `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.

```bash
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
