Turborepo + Biome monorepo for Felix frontends on Cloudflare Workers. Talks to the self-hosted Python harness (felix-run/felix).
Layout follows the Turborepo basic example
(apps/* + shared packages/*). UI primitives are shadcn/ui
in packages/ui (@felix/ui).
| Path | Role |
|---|---|
apps/web |
Streaming chat + inspector (Vite → CF Workers) |
apps/tui |
Full-screen terminal client (OpenTUI → Bun) — README |
apps/docs |
Starlight docs site (@felix/docs) → CF Workers |
packages/ui |
Shared shadcn/ui components |
packages/felix-protocol |
The harness wire contract — SSE reader + shared types |
packages/felix-client |
Headless chat client — transport, transcript model, the one StreamEvent switch |
packages/cowork-client |
Browser VFS, File System Access mount, client-side tool executor |
packages/design |
Neutral palette + theme-CSS builders (generates the docs theme) |
packages/test-kit |
Reusable behavioral suites (proxy Worker contract, SSE reader) |
packages/typescript-config |
Shared tsconfig bases |
PRODUCT.md is the brief the UI is designed against; ROADMAP.md is
the known, unaddressed work, with the evidence for each item recorded beside it.
pnpm install
pnpm web:dev # Vite → proxies /api to Python Felix :8080
pnpm tui:dev # terminal client, straight to FELIX_ORIGIN (needs Bun)
pnpm docs:dev
pnpm build # turbo run build
pnpm lint # turbo → biome
pnpm format # biome format
pnpm check-types
pnpm test # turbo → vitest, and bun test for apps/tui
pnpm sync:theme # regenerate apps/docs theme.css from @felix/design tokensCI runs lint, check-types, build, and the hook tests in .claude/hooks/tests/ on every PR.
Every dependency used by more than one workspace package is declared once in
pnpm-workspace.yaml under catalog:, and referenced from each
package.json with the catalog: protocol:
- Bump a shared version in one place —
pnpm-workspace.yaml— thenpnpm install. No more hunting the same package across seven manifests, and no more silent drift (before catalogs,wranglerwas^4.0.0in the apps and^4.90.1in docs). - A dependency used by exactly one package keeps its literal version in that package's
package.json(astro,streamdown,turbo,@biomejs/biome, …). Promote it to the catalog when a second package starts using it. pnpm add <pkg>writes a literal version even when the catalog already has that package (pnpm's defaultcatalogMode: manual) — change it to"catalog:"by hand, or setcatalogModeif you want that automated.pnpm publish/pnpm packsubstitute the real range forcatalog:, exactly likeworkspace:.
Requires pnpm ≥ 9.5; this repo pins 10.33.2 via packageManager.
# Install into the shared UI package
pnpm dlx shadcn@latest add button --cwd packages/uiApps import from @felix/ui/<name> (e.g. import { Button } from '@felix/ui/button').
If shadcn pulls in a new dependency that another package already uses, add it to the catalog in
pnpm-workspace.yaml and reference it as "catalog:" rather than pinning a second version.
Both apps deploy from CI: .github/workflows/deploy.yml deploys each Worker after CI passes on
main, and redeploys the docs when felix-run/ops reports a production roll (felix-deployed).
Dispatch it from the Actions tab to deploy by hand. Each app's wrangler.jsonc is tracked and holds
no ids; for your own deployment change its routes and chat-ui's vars.FELIX_ORIGIN.
From a machine with wrangler login:
pnpm web:deploy
pnpm docs:deployThe docs build downloads the API reference's spec: it asks https://api.felix.run/health for the
version and fetches that felix release's openapi.json (apps/docs/scripts/fetch-api-spec.mjs), and
fails if either is unreachable. Offline, point FELIX_OPENAPI_SPEC at a local file. Redeploy the
docs after upgrading production — the daily reference-freshness workflow fails until you do.
The chat-ui proxy Worker takes no secrets: it holds no credential, and a browser gets in by signing
in to the harness (GitHub or Google login), whose bearer the Worker forwards untouched. A Worker
deployed before the shared access key was retired still has CHAT_UI_KEY and FELIX_API_KEY set;
they are ignored, and worth deleting (wrangler secret delete <name>).
MIT