Suikou

A human-in-the-loop code review tool: a server-authoritative Musubi runtime on Phoenix (API + Musubi socket), a React frontend, and a single-file suikou binary that an agent drives over a small CLI.

Develop

Requires mise (provisions Elixir/Erlang/Bun).

mix setup        # install deps + set up the database
mise run dev     # Phoenix (distributed node, :4710) + Vite (:5173) together
mix precommit    # format, compile --warnings-as-errors, test — run before pushing

mise run cli -- <args> drives the agent CLI against the live dev node (e.g. mise run cli -- review list --project <id>).

Package & install

mix suikou.package builds the whole app — React frontend, a self-contained mix release (ERTS bundled), and the bun launcher — into one file at dist/suikou. It does not install; copy it onto your PATH and restart the daemon so the new binary and any config.toml changes take effect:

mix suikou.package
suikou stop                                    # if a daemon from an older build is running
cp dist/suikou ~/.local/bin/suikou
xattr -c ~/.local/bin/suikou                   # drop provenance/quarantine xattrs
codesign --force --sign - ~/.local/bin/suikou  # re-sign ad-hoc
suikou start                                   # boots the new binary, opens the browser

The xattr/codesign steps matter: cp invalidates the bun binary's ad-hoc signature, and macOS then SIGKILLs the copy on exec — a silent Killed: 9 with no output, before the server can even start. Re-signing the installed copy ad-hoc makes it runnable.

Lifecycle state lives in ~/Library/Application Support/Suikou (independent of the binary), so stop/start reach the daemon across versions. Targets the host platform only (macOS arm64).

Run

suikou           # foreground, opens the browser; Ctrl-C stops it
suikou start     # background daemon, opens the browser
suikou stop      # stop the daemon
suikou status    # is the daemon running, and where
suikou skill     # print the agent CLI skill markdown (no server needed)

Configure

Runtime config is read once at boot from ~/.config/suikou/config.toml (packaged build only; dev/test ignore it). Every key is optional — see config.toml.example for the full list and defaults. Edit, then suikou stop && suikou start to apply.

Common keys: host (Tailscale MagicDNS name for tailnet links), url_scheme / url_port (set to https / 443 only behind a TLS front like tailscale serve), port (HTTP listener, default 47100).