0013: Go monorepo with a shared core and native shells
- Status: accepted
- Date: 2026-09-22
Context
Targets: macOS, Windows and Linux CLI/TUI/agent installed through brew,
chocolatey, scoop, winget, apt, nix and npm; desktop GUIs; native iOS and
Android apps that approve requests, hold hardware-backed keys and browse
vaults; a hosted relay and sync service. run wraps every developer command,
so startup latency matters.
Decision
- Language: Go. One static binary per platform for
cli,tuiandagent; trivial cross-compilation; Bubble Tea for the TUI;gomobileproduces an.xcframeworkand.aarfrom the core; the tailscaled LocalAPI is reachable without embedding a node. - Layout (single repository, Go workspace):
core/: crypto, format, events, fold, policy, storage interface and backends. No UI, no I/O beyond the storage interface. This is the module exported to mobile.cmd/vaultfold/: CLI, TUI and agent daemon in one binary; MCP server; harness hooks.desktop/: Wails application over the core.ios/,android/: thin native shells (SwiftUI, Jetpack Compose) over the gomobile core; platform code limited to key stores, biometrics, QR, URL scheme and push.cloud/: hosted service: relay, sync, share blob store, accounts and billing.web/: marketing site and documentation (Astro + Starlight, static).openspec/,docs/adr/,docs/threat-model.md: specifications and records.
- Distribution: GoReleaser for brew, scoop, winget, apt/rpm, nix; an npm
wrapper package with per-platform
optionalDependencies(the esbuild pattern), no postinstall download. - Format independence: the on-disk format is specified in
openspec/specs/with test vectors, independently of the Go implementation, so that other implementations can exist. - Secrets are never accepted as command-line arguments; values are prompted for or read from stdin or the out-of-band form.
Consequences
- Cryptography is written once and audited once.
- Two mobile UI codebases, each small.
- The npm package is a thin shim; Node is not a runtime dependency.
Alternatives considered
- Rust with Tauri v2 (desktop and mobile) and UniFFI. Viable; rejected for build speed and the tailscaled and gomobile precedents (WireGuard, Tailscale apps).
- TypeScript with Electron. Rejected: startup latency on every
run, native crypto module friction on Windows, large desktop binaries. - Flutter or React Native for mobile. Rejected: the core still has to be linked, and Secure Enclave operations would depend on third-party plugins.