Skip to content
felix-runPublic

About

Cloudflare Workers frontends for Felix: a streaming chat UI, the float workspace client, and the docs site — all talking to the self-hosted Python harness (felix-run/felix).

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Repository files navigation

Felix web

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.

Commands

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 tokens

CI runs lint, check-types, build, and the hook tests in .claude/hooks/tests/ on every PR.

Dependencies — pnpm catalogs

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:

// apps/web/package.json
"react": "catalog:",
"wrangler": "catalog:",
  • Bump a shared version in one place — pnpm-workspace.yaml — then pnpm install. No more hunting the same package across seven manifests, and no more silent drift (before catalogs, wrangler was ^4.0.0 in the apps and ^4.90.1 in 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 default catalogMode: manual) — change it to "catalog:" by hand, or set catalogMode if you want that automated.
  • pnpm publish / pnpm pack substitute the real range for catalog:, exactly like workspace:.

Requires pnpm ≥ 9.5; this repo pins 10.33.2 via packageManager.

Add a shadcn component

# Install into the shared UI package
pnpm dlx shadcn@latest add button --cwd packages/ui

Apps 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.

Deploy

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:deploy

The 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>).

License

MIT

About

Cloudflare Workers frontends for Felix: a streaming chat UI, the float workspace client, and the docs site — all talking to the self-hosted Python harness (felix-run/felix).

Topics

Resources

Security policy

Stars

1 star

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages