The kit and release repository for Engin's connected apps. The six
warpui-kit-* crates live under kits/; every app lives in its own repository
and pins a kit tag. warp-suite builds and releases the kits, assembles the
combined suite release from pinned app releases, and keeps apps/ as local
symlinks to the sibling checkouts so one workspace still builds everything
against the local kits.
Currently in the suite:
| App | Repository | What it is |
|---|---|---|
| warp-station | warp-station | Repository workbench (Rust/GPUI) |
| warp-agent | warp-agent | Chat client over opencode serve and dsh web (Rust/GPUI) |
| warp-snapit | warp-snapit | Rust port of the SnapIt zone snapper (Windows-only, portable zip) |
| warp-notes | warp-notes | Per-repo markdown notes with a live editor (Rust/GPUI) |
| warp-pomodoro | warp-pomodoro | Pomodoro focus timer with a live Station rail page, a countdown ring and a mini always-on-top card (Rust/GPUI) |
| warp-android-scribe | warp-android-scribe | Android dictation IME with a full QWERTY keyboard over Superwhisper or Hex (Kotlin/Compose + Rust bridge) |
The C#/.NET SnapIt repo (enginkirmaci/SnapIt) stays excluded — the Rust port above is the suite's zone snapper. See Adding an app.
A suite release is a pin table (suite.toml): the kit tag plus
one tag per app. Each app release is built and published in its own repository;
the suite job downloads the pinned releases and assembles one Linux tarball and
one Windows ZIP.
Tag this repo with the suite version and dispatch the assembler:
git tag -a "v0.1.0" -m "warp-suite 0.1.0"
git push origin "v0.1.0"
gh workflow run suite-release.yml --ref v0.1.0 -f version=0.1.0The job downloads the app releases pinned in suite.toml, verifies their
SHA256SUMS, and publishes the combined Linux bundle and Windows ZIP. All app
repositories are public, so GITHUB_TOKEN is enough; the job never rebuilds an
app.
git clone https://github.com/enginkirmaci/warp-suite && cd warp-suite
scripts/dev/link-apps.sh # link the sibling app checkouts
./install.sh --local # build the linked workspace, then installBinaries go to ~/.local/bin, desktop entries + hicolor icons to
~/.local/share. Everything is per-user; no root needed.
Download warp-suite-<version>-windows-x64.zip from the suite release,
extract it, and run install.cmd. It installs under
%LOCALAPPDATA%\Programs\warp-suite, adds a warp-suite Start Menu folder
with one shortcut per app, and records what it wrote for uninstall.cmd.
The same ZIP is portable: run the executables under apps\ directly without
installing. It contains Warp Station, Warp Agent, Warp Notes, Warp Pomodoro and
Warp SnapIt.
scripts/dev/link-apps.sh # once per checkout
scripts/dev/refresh.sh # pull the apps' latest main, then build
scripts/dev/refresh.sh --app warp-notes # one app, sync and build
scripts/build/build.sh # Linux bundle + tarball
scripts/build/build.sh --app warp-notes # one app, fast loop
scripts/deploy/deploy.sh --local # build, then install into ~/.local
scripts/deploy/deploy.sh --uninstall # remove exactly what it installedscripts\dev\link-apps.ps1 # junctions on Windows
scripts\dev\refresh.ps1 # latest main, then a portable build (no installers)
scripts\build\build.ps1 # Windows: dist\windows\ zips + installers
scripts\build\build.ps1 -App warp-notes -NoPackage
scripts\deploy\deploy.ps1 -Local # build, then install a portable copy
scripts\deploy\deploy.ps1 -Release # install the published Windows ZIP
scripts\deploy\deploy.ps1 -Uninstallrefresh.sh / refresh.ps1 fetch each app's origin, fast-forward main and
then call the platform build with installers off (build.ps1 -NoPackage on
Windows; the Linux build has no installer step). A checkout with uncommitted
changes, on another branch or with diverged history is reported and left
alone. --check only fetches and reports, --no-build stops after the sync.
Both builds default the version to git describe --tags --always --first-parent; CI passes --version / -Version explicitly.
| Path | Purpose |
|---|---|
AGENTS.md |
suite-wide agent instructions (pins, gates, contracts, traps) |
apps/<name> |
local symlinks to the sibling app checkouts (gitignored); scripts/dev/link-apps.sh creates them |
plans/ |
working design plans and proposals, one markdown file per topic |
suite.toml |
the pin table: the kit tag and one tag per app |
scripts/meta/manifest.py |
suite.toml + app.toml reader shared by the scripts + CI |
.cargo/config.toml |
one cargo target dir for the whole suite: .build/target for every app, kits and scripts/build/build.sh |
kits/ |
the seven warpui-kit-* crates, members of the kit workspace; their paths live in the root [workspace.dependencies] |
scripts/dev/refresh.sh |
pulls each app's latest main, then builds without installers (refresh.ps1 on Windows) |
scripts/build/build.sh |
Linux build: cargo build --release each app → dist/linux/warp-suite-<v>-linux/ + tarball |
scripts/build/build.ps1 |
Windows build: dist/windows/ portable zips + Inno Setup installers |
scripts/deploy/deploy.sh |
Linux install/uninstall: local bundle or published release |
scripts/deploy/deploy.ps1 |
Windows install/uninstall: portable locally, the combined ZIP from a release |
scripts/deploy/bundle-install.sh |
runs inside an extracted bundle; installs into ~/.local and records what it wrote |
install.sh |
shim over scripts/deploy/deploy.sh for the documented one-liner |
.github/workflows/suite-release.yml |
the combined release pipeline |
design/v3/ |
the committed design contract (DESIGN.md + prototype source); the live source is the OpenDesign project warp-suite-v3 |
Each app repository owns its packaging assets and its own build/release workflows. warp-suite owns the kit build, the suite assembly and the install scripts.
Agents start at AGENTS.md for the suite-wide rules, then the
app repository's AGENTS.md; the deep guides are in docs/agents/,
including settings-schema.md. Design plans
and proposals go in plans/, one file per topic, and are deleted
once the work lands.
The apps talk to each other; these are the interfaces that must move together. When one changes, update the other side in the same commit.
-
warp-agent loopback door (
~/.warp/agent/ipc.port+ipc.token, token-authenticated NDJSON on127.0.0.1): commandsping,open-workspace,new-chat,run-prompt,cancel,models,status(+ status pushes).new-chat/run-prompttake a folder, orgeneralfor warp-agent's built-in Tasks workspace, where the AI wands run: a wand prompt carries its own diff or file tree, so it must not add the repo to warp-agent's sidebar as a workspace. A worktree chat uses the same command: Warp Station sendsnew-chatwith the checkout's folder (<repo>/.worktrees/<branch>), which warp-agent opens as a workspace and nests under the repository's row.new-chat/run-promptacceptharness/model/variant, andmodelsanswers with the harnesses and each model's variants.modelsalso takesrefresh: true: the door re-reads that harness's backend (starting it when needed) instead of answering from its in-memory catalog, which is what the settings refresh buttons ask for; without the flag the answer may be the catalog loaded earlier in the session. warp-agent owns the protocol; Warp Station is the client — a missing warp-agent binary turns Warp Station's AI features off, a closed one is launched on demand. -
SnapIt settings: warp-snapit and Warp Station read the same versioned snake_case
~/.warp/snapitsettings.json/layouts. The old .NET-shaped files are importer input only;"x,y"points and"#AARRGGBB"colours stay. Warp Station'ssnapit.executablesetting names the Rustwarp-snapit.exe(empty = the packaged exe next to the app), which is a portable-zip deliverable (no installer) and skipped in the Linux bundle (linux_skip = trueinwarp-snapit/app.toml). -
Shared notes store (default
~/notes,notes_store_pathoverrides; one repo per folder underprojects/): warp-notes always gets--store(Warp Station's resolvednotes_store_path) and an explicit scope — the titlebar toggle and the global-search note hits ask for--root(the whole store), a repo's launcher pins its folder with--repo— plus--notewhen a hit names one. Standalone launches root at the shared store; a store an older release kept in~/.warp/notes(or the older~/.devtools/notes) moves to~/noteson whichever app runs first. Missing warp-notes binary = the notes surfaces fail with a toast, nothing else breaks. -
Pomodoro timer (
~/.warp/pomodoro): warp-pomodoro ownssettings.json,history.jsonand the livestate.jsonsnapshot, and while it runs it publishes the family's token-authenticated door (ipc.port+ipc.token) withping,status,start,pause,reset,skipandfocus. Warp Station's rail page is the only client: it pollsstatusonce a second while it is on screen, falls back tostate.jsonwhen the app is closed, starts a session by launchingwarp-pomodoro --start, and never toasts over a closed app. A second launch forwardsfocusand exits. The durations, the long-break cycle, auto-start, notifications, the alert sound and the window mode (full dashboard or mini card) live in the app's own settings; Warp Station keeps onlypomodoro.enable_pomodoroandpomodoro.executable. -
Per-user layout (
~/.warp): every app's own data sits in its own folder —station/,agent/,notes/,pomodoro/— beside the SnapIt settings insnapit/, the sharedui.jsonat the root and onelogs/for every app's rolling file. Station and agent keep regenerable caches in<app>/cache/; deleting one loses no user setting or repo tag. The notes store is user content, not app data, so it stays outside at~/notes.warpui_kit_platform::pathsowns the tree and the startup migrations that adopt the older folders. -
Settings and caches: suite-owned JSON is versioned snake_case; the contract and the importer rules are in
docs/agents/settings-schema.md. Every app, SnapIt included, imports its pre-versioning files once at the edge. -
Shared text size and palette (
~/.warp/ui.json:text_sizeissmall,normal,largeorlarger— the oldcompactspelling reads as normal — andpaletteiscopper,plum,pine,blueorgray):warpui-kit-coreowns the file and the one control that writes each key. A click applies in that app at once; the other apps read the value when they next start. The apps' old per-apptext_size/font_scalesettings only seed the file on its first run, so every app must be on the samewarpui-kit-core. Both keys are additive: a file that lacks one keeps the other. -
warp-android-scribe bridge (LAN
<nas-lan>:8787, publichttps://<nas-host>): the Android IME posts a 16 kHz mono WAV toPOST /transcribe?engine=hex|superwhisper&lang=tr|auto&tone=semi-formal|formal|…withAuthorization: Bearer <token>and receives{"text","language","duration"}.GET /healthis the token-checked server test;GET /enginesreports both engines, their readiness and the default, and the phone picks one per request, so both must keep working.GET /settings,PUT /settings/vocabularyandPOST /settings/processingread and edit the NAS profile (language list, tone, words, processing mode and model downloads). Superwhisper keepssuperwhisper transcribeplusstatuspolling on the NAS; Hex ishex model transcribe --model whisper_large_v3_turbo --language …, one call per request with no profile, and the phone's tone is ignored for it. The phone sends its tone on every request, so for Superwhisper it overrides the profile's. The bridge serializes requests because the daemon has one active session; language and tone are set inside that mutex. The public route is Cloudflare Tunnel -> Nginx Proxy Manager -> 8787. The bearer scheme, field names and status codes are one contract: change the bridge and the Android client in the same commit. Android 17 needsACCESS_LOCAL_NETWORKfor LAN; the app requests it and has Local/Remote modes. The APK is sideloaded; the bridge is a systemd user service installed fromwarp-android-scribe/deploy/. -
Version facts: each repository owns its
version.toml. The kit line moves PATCH on every warp-suite commit through its pre-commit hook; each app line does the same in its own repository.kits/warpui-kit-buildstamps the app's version, commit, channel and released facts into each binary (About,--version, the Windows file version, the bridge's/health). The APK reads its repository's file. OneCopy versionline (Warp Station 0.1.8 (d904edc) · dev) is the family contract;docs/agents/versioning.mdis the rulebook.
- Create the app repository; it carries its own
version.toml,app.toml, CI and release workflows, and pins the kit tag inCargo.toml. - Add its tag to
suite.toml. - Run
scripts/dev/link-apps.sh;apps/<name>appears next to the others. - Document its contracts in Cross-app contracts.
The app's app.toml carries the build knobs (package, linux_skip,
icon_prefix, scalable_svg); both suite build scripts read it through the
symlink. Windows compiles an installer only when
packaging/windows/<app>.iss exists.
- The apps live in their own repositories.
warp-suiteis the kit source and the release pin table; it is not a second source of truth for app code. suite.tomlpins one tag per app and the kit tag. A suite release names exactly those tags;REVISIONS.txtrecords them.- The apt dependency list in
suite-release.ymlcovers GPUI's Linux needs (wayland, xkbcommon, vulkan, fontconfig); expect to touch it when GPUI's requirements grow. - Kit crates: the apps depend on
warpui-kit-core/-diff/-markdown/-picker/-platformthrough path entries in the root[workspace.dependencies]. They live in this repo as members of the one suite workspace (rootCargo.toml), so a release builds from this repo alone. The suite commit is the kits' provenance — no sync step, no second copy. Everything resolves from the one committed rootCargo.lock, so CI resolves the same versions every run;cargo testafter changing a kit builds the apps against it directly.
Both workflows use Swatinem/rust-cache, and both must name the target dir
explicitly (workspaces: <workspace> -> <target>):
.cargo/config.tomlsends every workspace to.build/target, so the action's default<workspace>/targetdoes not exist. Without the explicit path the action caches only the registry and every run compiles from scratch.- The whole suite is one workspace now, so each job names it once
(
workspaces: . -> .build/target) with its ownshared-key(release-linux/release-windowsin the release workflow,kits/appsin the gate). Earlier schemes that listed several workspaces hit a prune war — the action prunes a target dir down to the owning workspace's dependency closure, several workspaces meant several prune passes over the same tree and the last one won, deleting everything the others had built. One workspace retired the problem; the workflow comments keep the history.
The target dir is ~4.5 GB release / ~2.9 GB debug, so the caches are pruned rather than uploaded whole (the repo cache limit is 10 GB).