Waku: a native GPUI desktop app for local coding agents

The problem Waku solves: too many agent CLIs, too many terminals

If you use more than one coding agent, you already know the shape of the problem. Claude Code lives in one directory, Codex CLI in another, OpenCode somewhere else, and each one keeps its own transcript, its own session model and its own idea of what a task is. Switching models means switching tools. Comparing two agents on the same task means reconstructing context by hand.

Waku's answer is a native desktop control plane. The README describes it as "a fast, native desktop app for working with local coding agents", and the Cargo manifest calls it "a fast, native control plane for local coding agents". The audience is narrow and specific: developers who already have at least one supported agent CLI installed and authenticated, and who want projects, sessions and transcripts in one window instead of one terminal per agent.

The supported list in the README is Amp, Claude Code, Codex CLI, Cursor CLI, Fx, Grok Build, Kimi Code, OpenCode and Pi. Waku does not reimplement any of them. It detects the CLIs you have and speaks each provider's native structured protocol, which is why the README tells you to install and authenticate at least one agent before starting the app.

Daemon, protocol and client: how the pieces actually fit

The architecture is the most interesting part of the repository and the part most likely to surprise you. Waku Desktop is not the thing running your agents. It is an RPC client of a separate `waku-daemon` process. Provider sessions run in the `waku-core` crate, behind an authenticated, versioned WebSocket contract defined in `waku-protocol`. The desktop depends on `waku-client`, not on the daemon implementation, so the two can be replaced independently.

That split has consequences the README spells out. The daemon owns task SQLite data, uploaded attachments, provider-native session forks, and all workspace filesystem and Git operations. Paths it returns always refer to the daemon host. The desktop keeps only presentation state and a disposable preview cache. Projectless task workspaces live on the daemon host under `~/.waku/projects/<date>/<slug>`, and the daemon migrates workspaces created under the older `~/.waku/<date>/<slug>` layout on first load.

Configuration ownership is split too. The Release desktop writes `~/.waku/app.json`; Debug stays isolated at `temp/app.json`. Daemon provider and Computer Use settings live in `~/.waku/settings.json`. The Settings -> Daemon page can expose the child daemon on a fixed port, configure exact browser origins and copy its stable authentication token, and the README states it remains loopback-only by default.

There is a browser client at `apps/web` that uses generated types from `packages/waku-client`. Those types are generated from the Rust protocol, and the README warns you to run `bun run protocol:generate` after changing a wire type and `bun run protocol:check` to verify the generated files are current. That is a real maintenance obligation, not a formality: the browser client reimplements the same handshake, request IDs, subscriptions, sequence deduplication and replay cursors as the Rust client, so drift between the two is a class of bug the project has to police with tooling.

Installing Waku and connecting your first agent

Installation differs by platform. On macOS the README points at a signed `.dmg` from waku.sh, and the app updates itself. On Linux the documented path is a shell script that installs into `~/.local` without root:

curl -fsSL https://waku.sh/install.sh | sh

The README says `docs/linux.md` covers requirements, manual installation and uninstalling, so read that file before running the script if you care about where files land. On Windows you run `Waku-<version>-<arch>-Setup.exe` from the latest release; it installs per-user and updates itself, and a portable `.zip` is published alongside it. `docs/windows.md` documents requirements and what is not available there yet.

Before launching, make sure at least one supported agent CLI is installed and authenticated. Waku detects available CLIs automatically, so there is no agent list to configure by hand. Once the app is open, the README's described workflow is to keep projects and independent agent sessions in one place, switch models, reasoning effort and access modes from a shared interface, and queue or steer follow-up messages while an agent is still working. Git-backed tasks can be rewound with conversation-aware checkpoints.

If you are building from source rather than installing, the README requires Rust 1.96 or newer and Bun, with Linux supporting both Wayland and X11 and Windows needing the MSVC toolchain. The documented commands are:

bun install
bun run dev

The development entry point is `bun ./scripts/dev.ts`, and the README notes that in development the daemon lives at `target/debug/waku-debug-daemon`, which lets provider-only edits rebuild and replace the daemon without relaunching Waku Debug. Release apps bundle and sign `waku-daemon` instead.

Where Waku stops working: remote daemons, platform gaps and an early version number

The README is unusually direct about a limitation that will bite anyone who tries to run the daemon somewhere other than the machine in front of them. When connected to a daemon managed outside the desktop process, Waku never interprets daemon paths on the client machine. The local folder picker and the PTY are therefore unavailable until the protocol gains daemon-host picker and terminal-stream endpoints. Files, diffs, Git, skills, usage, task state and attachments already work over daemon RPC, so the gap is narrow but real: you get the data plane without the two most tactile pieces of the interface.

Platform coverage is uneven in a way the README admits. The embedded browser and the experimental computer-use integration remain macOS-only. Agent sessions, projects, transcripts, skills, usage, diffs, file editing and the terminal do run natively on Linux and Windows, so the core workflow is cross-platform while the extras are not.

The build itself is tied to a fork. The Cargo manifest pins GPUI to `egoist/zed` on the `waku-webview` branch, described in a comment as upstream main plus PR #61945 for layered scene rendering, which lets GPUI composite menus and tooltips above native child views such as the browser surface's WKWebView. The comment says to drop back to upstream once that PR merges. Until then, anyone building Waku is building against a personal fork of a large dependency.

Finally, the version is 0.1.19, with 0.1.18 and 0.1.17 released within the same month. That cadence is a sign of movement, not of interface stability. The protocol is versioned, which helps, but nothing in the README promises that a config key or a settings file layout will survive the next release.

Waku compared with running each agent in its own terminal

The realistic alternative is not another product; it is the terminal multiplexer you already have. tmux or a set of terminal tabs gives you every agent CLI at once, with no daemon, no WebSocket contract and no extra process to keep alive. Nothing needs to be installed beyond the agents themselves, and nothing breaks when a provider ships a new flag.

The difference in approach is where state lives. With tmux, each agent owns its own session and transcript, and your window layout is the only thing tying them together. Waku moves that state into the daemon: task SQLite data, provider-native session forks, attachments and Git operations all sit behind `waku-daemon`, and the desktop is a view onto it. That is what makes shared model switching, queued follow-ups and conversation-aware rewind possible across agents. It is also what makes the daemon a single point of failure and the reason the remote-daemon picker and PTY gaps exist at all.

If you only ever run one agent, Waku adds a process and a protocol for very little. If you run three and keep losing track of which session holds which decision, the shared interface is the point.

Licence and the cost of keeping up

Waku is licensed under GPL-3.0-only, as stated in both the README and the Cargo manifest's `license` field. For individual use that changes nothing. For anyone embedding Waku or its crates in a distributed product, the copyleft terms are the thing to check before writing code against `waku-client` or `waku-protocol`, and that is a question for your own legal review rather than something the README answers.

Upgrade cost is dominated by two things. The first is the daemon split: because the desktop talks to the daemon over a versioned protocol, a daemon upgrade and an app upgrade can get out of step, and the README's note that the desktop depends on `waku-client` rather than the daemon implementation suggests the project has thought about this, but it does not document a rollback path. The second is the GPUI fork. Every release built from this tree carries a dependency on `egoist/zed` at the `waku-webview` branch, and the comment in Cargo.toml only says to drop back to upstream once PR #61945 merges. There is no documented plan for what happens if that branch diverges further in the meantime.

On the tooling side, the repository expects Bun and Drizzle for the JavaScript half. `bun run protocol:generate` and `bun run protocol:check` are the two commands that keep generated types honest, and `db:generate` and `db:push` wrap `drizzle-kit` for schema changes. Contributing work is described in CONTRIBUTING.md; release maintainers are pointed at RELEASING.md.

Editorial conclusion

Adopt Waku if you already run several agent CLIs and want one native window with shared model switching, queued follow-ups and Git-backed rewind, and if your agents all run on the same machine as the app. Do not adopt it if you need a stable interface, if you rely on the local folder picker or PTY against a remote daemon, or if the Linux and Windows gaps listed in docs/linux.md and docs/windows.md matter to your workflow. Before committing, verify on your own machine that the agents you use are detected, that the daemon port and token settings in Settings -> Daemon behave as you expect, and that the GPL-3.0-only licence is compatible with how you plan to distribute anything built on it.

Frequently asked questions

Official sources

1. egoist/waku on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases