Install Code Flow preview

Open the macOS or Windows WSL2 desktop app, or start the local browser app with one command. You do not need to clone Code Flow or add it to your project. The preview uses your installed coding CLIs and their existing logins.

Desktop preview 0.1.0-preview.7. Download a desktop app or use the exact release package below. Each published app release automatically updates the npm latest and preview channels after npm processing completes. See the preview release notes and checksums.

Choose an installation method

Try it with one command

Install Node.js 22.13+ and Git 2.38+, then run:

npx --yes --package=https://github.com/midhunxavier/code-flow/releases/download/v0.1.0-preview.7/midhunxavier-code-flow-0.1.0-preview.7.tgz codeflow

Code Flow starts locally and opens its sign-in link in your default browser. Keep the terminal open while you work. Press Ctrl+C to stop the server.

Windows desktop with WSL2

The Windows desktop preview runs its backend and agents in your WSL2 distribution. Node is bundled; Git and agent CLIs are installed inside WSL. Docker is not required. Download the x64 ZIP or ARM64 ZIP, extract the entire ZIP, and open Code Flow.exe. See the Windows desktop guide for setup and validation status. This portable preview is unsigned.

Use Windows Subsystem for Linux

This preview runs inside WSL2. Install Node.js 22.13+, Git 2.38+ and your agent CLIs inside WSL, sign in there, and keep your repository in the Linux filesystem. In your WSL terminal, run:

npx @midhunxavier/code-flow@preview

The launcher tries to open your Windows browser. If it cannot, copy the local sign-in link from the terminal. Native PowerShell and Command Prompt execution are not supported in this preview.

Install for regular use

With Node.js 22.13+ and Git 2.38+ installed on macOS, Linux or inside WSL2:

npm install -g @midhunxavier/code-flow@preview
codeflow

To update, run the same install command again. To remove the launcher:

npm uninstall -g @midhunxavier/code-flow

Install with Homebrew

The preview release includes a Homebrew formula. Once the maintainer has published the midhunxavier/code-flow tap, install it on macOS or Linux:

brew install midhunxavier/code-flow/code-flow
codeflow

Homebrew installs Node and Git as dependencies. Update with brew update && brew upgrade code-flow. If the tap is unavailable, use npm.

macOS app download

Prefer an app you can open from Applications? Download 0.1.0-preview.7 for your Mac:

Choose arm64 for Apple Silicon, or x64 for an Intel Mac. macOS 13 or later is required.
Open the DMG and drag Code Flow to Applications.
Open Code Flow in its own desktop window. Closing or reloading the window keeps agents running.
Click its Dock icon or use Code Flow → Show Code Flow to return. Use Code Flow → Quit to stop; it asks before interrupting active agents.

Node is included in the app. You still need Git 2.38+, a signed-in supported agent CLI and Chrome or Edge for the shared browser. Install those before your first run. Quit Code Flow before replacing the app with a newer download. Do not run the npm and macOS launchers together against the same data directory.

Files named unnotarized are developer preview builds. macOS may block them. For ordinary installation, use npm until a signed and notarized DMG is available.

Connect an agent and start

Install at least one supported CLI: claude, codex or agy. Run it interactively and sign in before starting a task. Open Settings → Agents & models in Code Flow to inspect availability. Additional ACP agents can be configured in Settings.

Choose a Git repository, describe your task, pick a workflow, and start your first run. Follow the getting started guide for permissions and review.

Startup options

codeflow --no-open           # start without opening a browser
codeflow --port 5320         # use another local port
codeflow --version
codeflow --help
codeflow client --help       # authenticated API client

If the browser does not open, use the Open http://localhost:…/?token=… link printed in the terminal. Keep that link private. A restart creates a new session; use the new link if your browser asks you to sign in.

If another instance is already running, use its browser tab or stop it before starting again. A busy port can be changed with --port; an existing server using the same data directory must be stopped first.

Settings, updates and removal

In desktop versions with the updater, open Settings → General → App updates or Code Flow → Check for Updates…. The app also checks on launch and every six hours, and shows Update available in the sidebar. Preview installs receive newer previews and stable releases; stable installs receive stable releases only.

Click Download update, then Restart to update when ready. If agents are working, Code Flow asks whether to keep running or save progress and restart. In-app installation requires a signed, notarized app and a release containing the matching update package. Developer previews show Download installer instead: download the DMG, quit Code Flow, and replace the app in Applications. Older versions without this button need one manual upgrade first.

Settings and history live in ~/.codeflow, outside the installation. Reinstalling, upgrading or removing the launcher preserves that folder. Set CODEFLOW_HOME to an absolute path to use a separate data directory. Avoid switching an existing data directory back to an older preview; back it up before trying new versions.

The preview does not install or sign in to agent CLIs for you. Provider access and usage limits depend on your account. See security, configuration and preview release preparation.

Documentation library · Getting started