Developers: start here
For developers building Remy or an app on it: shared authentication for Remy apps, Better Auth on Cloudflare Workers, the shared remy-ui package, and where to start.
For developers building Remy, or an app on its shared UI package. Using the app? Read the product guide. Calling the API? The API reference.
https://github.com/joeblew999/remy-auth
Shared authentication for Remy apps, using Better Auth on Cloudflare Workers with D1 as the identity and session store, and relationship-based permissions every app gets from the shared package (sign-in and permissions).
Status: the GUI foundation is live on Cloudflare in two apps built on TanStack Start, from the
shared @joeblew999/remy-ui package. remy-auth signs people in with an emailed code, guards its API
by policy, and decides who may do what by relations, shown in its own notes demo. How another app
learns who is signed in is the next piece; open work is listed in .plans/now.md.
Where to look
Two live sites, each with site pages for Google and app pages under /app;
paths.js defines both kinds. Swap /en for /es or /ar anywhere.
| Site | Rendering | Open |
|---|---|---|
| remy-auth | server-rendered on every request | https://remy-auth.gedw99.workers.dev/en |
| remy-auth-app | prerendered static pages | https://remy-auth-app.gedw99.workers.dev/en |
| Kind | Page | remy-auth link |
|---|---|---|
| Site | Home | https://remy-auth.gedw99.workers.dev/en |
| Site | Formats, with settings in the address | https://remy-auth.gedw99.workers.dev/en/formats?currency=JPY&count=11&calendar=islamic |
| Site | A time zone | https://remy-auth.gedw99.workers.dev/en/time-zones/Asia/Tokyo |
| Site | Not found, localized | https://remy-auth.gedw99.workers.dev/ar/time-zones/Mars/Olympus |
| Site | Sitemap (site pages only) | https://remy-auth.gedw99.workers.dev/sitemap.xml |
| App | Home, with the live status card | https://remy-auth.gedw99.workers.dev/en/app |
| App | Demo form: server reply and leave warning | https://remy-auth.gedw99.workers.dev/en/app/demo |
| App | Location: Cloudflare's and your device's | https://remy-auth.gedw99.workers.dev/en/app/location |
| Ops | Liveness | https://remy-auth.gedw99.workers.dev/healthz |
Get started
Node as .node-version says (26), then from this checkout:
npm install # once, for the lockfile and the remy bin
npm run setup # the pinned skills, MCP, the flow's guard, the installation's checks
npm run dev # http://127.0.0.1:5173/enOpen localhost/en; switch to Spanish or try the demo. Setup installs dependencies and skills, registers MCP, then runs the installation's checks (no browser).
Setup installs the pinned Codex CLI; authenticate when prompted. Claude Code is optional and installed separately. Install Google Chrome before setup; browser checks use the installed Chrome.
Work with an agent
Starting, resuming and reloading Codex or Claude Code, in VS Code or a terminal, is in developer tooling.
Everyday commands
The everyday commands, the same in every app on the platform (package.json's scripts, run by the
package's remy bin):
| Task | Command |
|---|---|
| See what is going on | npm run dev:status |
| Start a piece of work, in a worktree of its own | npm run dev:start -- <name> |
| Check, after every change | npm run dev:change |
| Land finished work: main, GitHub's checks, staging | npm run dev:land -- "<what changed>" |
| List the scripts | npm run |
| Run the local GUI | npm run dev |
| Try the production build locally | npm run preview |
| The tooling's versions | npx remy verify doctor |
| Check for package updates | npm run packages -- check |
| Upgrade packages, including major versions | npm run packages -- upgrade |
| Better Auth CLI help | npm run auth -- --help |
| Cloudflare CLI help | npm run wrangler -- --help |
| Inspect browser tooling | npm run browser -- --help |
| Inspect MCP status in both clients | npx remy mcp status |
The first four are the flow, which also says who runs production and a release. The heavy checks are not everyday commands: GitHub runs them after every landing, and the tooling refuses them outside the flow.
Local preview and remote deployment use the same build and Wrangler configuration. See local/remote commands for deployment and running the same tests against a deployed URL.
Review dependency changes after upgrading. Node is pinned in .node-version and package.json's
engines; the skill-source commits are in the package (packages/ui/src/cli/skills.ts), which every
app installs (the command line).
Project documentation
- Agents: start here: where agents start; the root
AGENTS.mdandCLAUDE.mdonly point at it. - Development principles: what the code must be, and how plans work.
- How we work: how people and agents work.
- Developer tooling: the scripts and commands, skills, MCP and browser tools.
- GUI runtime workflow: one Worker, local and remote test targets.
- The command line:
remy, the tooling every app installs with the package. - Shared UI package and its changelog.
- Plans: .plans/now.md is the only list of what is open and where it stands.