backend/ and ui/ — orchestrated by Turborepo. A single bun install from the repo root installs every dependency across both workspaces, and Turborepo’s task cache means repeated runs skip unchanged work automatically.
Prerequisites
Before cloning the repo, make sure you have the following installed:- Bun 1.3.11 — the required package manager and runtime (pinned via
packageManagerinpackage.json) - Node — needed by some Turborepo internals and the Vitest test runner
The repo’s
package.json declares "packageManager": "[email protected]". Using a different Bun version may produce lockfile conflicts.Install Dependencies and Git Hooks
Install all workspace dependencies
Run
bun install from the repo root. Bun workspaces ensure this single command resolves dependencies for both backend/ and ui/:Install Git hooks
The project uses prek to manage pre-commit and pre-push hooks declared in This writes hooks into
prek.toml. Install them with:.git/hooks/ and overwrites any existing hooks with --overwrite.Running the Servers
The project exposes several entrypoints. Use the root-level scripts to launch them without changing directories.- Backend HTTP
- Frontend Dev
- CLI
- MCP stdio
- MCP HTTP
Starts the Effect HTTP server defined in
backend/src/presentation/http/main.ts:Portless Subdomain Local Dev
For HTTP-only subdomain-based local development you can use portless. This runs the API and UI on.localhost URLs without HTTPS trust prompts and without requiring sudo.
Start the API proxy
Serves the in-memory backend with REST API and MCP HTTP at
http://api.onion.localhost:1365:The Portless daemon runs on port
1365 with an isolated state directory at /tmp/effect-v4-onion-portless, so it does not interfere with any other Portless instance you may already have running. .localhost resolution works in Chrome, Firefox, and Edge. Safari may require additional host syncing.Workspace and Caching Structure
The monorepo uses two complementary tools:Bun Workspaces
Declared in the root
package.json as ["backend", "ui"]. A single bun install resolves and deduplicates dependencies for both workspaces at once.Turborepo Task Caching
turbo.json defines tasks such as build, typecheck, lint, and test with explicit input hashes. Outputs are cached in .turbo/ so unchanged workspaces are never rebuilt or retested unnecessarily.