A connected session is a coding session that already knows which Wind Stream session it belongs to — before you've typed a word. You run wind, and wind launches your coding tool already wired up — the worktree, the session manifest, the MCP, and the hooks are all in place. This guide walks the full loop, start to finish.
wind agent claude|codex selects the default launcher, and wind up --agent <agent> overrides it once. Claude Code and Codex are connected integrations. When Codex is selected, wind setup configures only Codex and leaves Claude Code configuration alone. On the first Codex launch, open /hooks and trust Wind's lifecycle hooks when prompted.
Not installed yet? See Install (macOS / Linux) or Install (Windows) first.
wind up <release> my-feature
→ worktree at ../worktrees/<repo>-<release>-my-feature, branched off release/<release>
→ Claude or Codex attaches or creates a Wind Stream session
→ …do the work…
→ on session end, the hook returns a trace to Wind Stream
The sections below walk each step.
wind up <release> <slug>creates a worktree off release/<release>, writes the session manifest into it, and launches the selected coding agent there. Claude Code enters /windstream-connect; Codex starts with $windstream-connect. Either path attaches to (or creates) the Wind Stream session behind the work.
If release/<release> doesn't exist yet, wind creates and pushes it first — with a confirm prompt at an interactive terminal, or immediately with --create (what you need non-interactively, e.g. in CI). Run the release-only form on its own to just take that step, with no session attached:
wind up <release> [--create]Add --ws <ref> to attach a specific, already-existing Wind Stream session instead of letting /windstream-connect create a new one. Add --gh <issue> to record the GitHub issue the session is anchored to in the session manifest — the bare number or a pasted issue URL both work. No name for the work yet? Leave the slug off: with --ws/--gh, wind fetches the source and proposes one.
wind up current <slug> starts a session on the open release train, and wind up bump patch <slug> cuts the next one and starts there — so you don't have to look up or type an exact version; see the command reference for the full alias grammar.
Work that isn't on a release train has its own form: wind up feature <slug> opens the same kind of session off your repo's default branch — branch feature/<slug>, no release involved — and wind up continue <slug> reopens that branch later in a fresh worktree. Starting a feature works offline; continue does too, once the branch is local; see Feature sessions.
Reviewing someone else's PR has its own form too: wind up review --gh <pr-url|number> [<slug>] cuts a review/<slug> seat on the PR's head, with the PR recorded as the manifest's anchor. This one needs the network up front, like the current/bump aliases — it's fetching the PR from GitHub; see Review sessions.
Deliberate with Wind Stream from your terminal, any time:
wind surf <topic>It opens a full-screen terminal UI (TUI) — continuing an existing Wind Stream conversation about that topic, or starting a new one. Type /exit to leave (/quit works too, as a silent alias) and drop back to your shell. Always give it a topic — bare wind surf currently just prints a reminder to add one.
Inside Claude Code, the same reach is available through the windstream-* slash commands that wind setup deployed there — /windstream-connect is the one that opened this session. In Codex, $windstream-connect owns that connection step and the native windstream MCP supplies the conversation tool.
Want the session in your browser instead of the terminal? From anywhere in the worktree:
wind openopens the Wind Stream session this work is attached to — it reads the session manifest, so you never have to fish the URL out of a file. Where a browser can't appear (SSH, CI), wind open --print prints the URL instead, ready to paste. And when someone hands you an id instead of a link — wind open session-… (any Wind Stream id works) opens it directly, from any directory.
wind downdrafts a retrospective from this seat's own work and agent sessions, shows what wind verified (and what it couldn't), and asks anything to add? Choose Down to record it to the Wind Stream session this worktree is attached to, or Add something to type an addition (typing down there records it). Cancel, or /exit, records no retrospective; the draft exchange stays on the session as context. For the free-form interview instead, run wind down --interview.
You don't have to run it, though: the SessionEnd hook returns a trace of the session to Wind Stream automatically when the coding session ends, wind down or not. Claude uploads within its hook budget. Codex spools locally within its three-second hook budget, notifies the parent wind CLI, and that CLI completes the upload after Codex exits. Running wind down adds your own account of the work on top of that trace — it doesn't replace it.
For non-interactive runs (CI, scripts), add --yes to record the generated draft without asking, or --message <text> to record your own words verbatim instead (the argument is the retrospective — supplying it is the approval). For text kept in a file, --message-file <path> records the file's contents as they are. Off a terminal with neither, wind down refuses rather than hang, then prints a short self-review brief for the agent driving it to write from. (--easy is still accepted for compatibility and does nothing.) The exit code says what happened to your words: 0 delivered, 2 saved on this machine and not yet sent (it syncs on a later session start, and wind sync sends it now), 1 nothing saved.
wind up is the on-ramp for release work, but you don't need a release worktree to talk to Wind Stream. From any repo:
wind connect <ws-session-ref> [--url <url>]attaches the current repo to an existing Wind Stream session, ad hoc. It writes the same kind of manifest wind up does, just minimal — no release, no branch, only enough for the hooks to know where this session's trace goes when it ends.
.session-state.json, at the root of the worktree, is the session manifest — the record of which Wind Stream session this work belongs to. wind up and wind connect write it, and the selected agent's connect command or skill fills in the Wind Stream session id once it attaches; the hooks and wind down read it to know where things go. Don't edit it by hand — let wind manage it.