Development
Set up
Section titled “Set up”Use Node 24.19 or newer and the pnpm version in the root package.json:
git clone https://github.com/AidanZealley/familiar.gitcd familiarpnpm installRun the demo
Section titled “Run the demo”pnpm devThis starts a daemon on port 4318 with a scripted model and in-memory storage, and the web app on port 5174. It needs no sign-in and touches no installed assistant’s data. Vite accepts LAN and tailnet connections, so you can open it from another device.
The demo opens on Rowan’s household, a few days in: four Familiars with their own tools, memory and schedules, their DMs, named rooms and a print still being watched. It’s written as data in apps/daemon/src/demo/household/story.ts, each message with the replies it gets. Anything the story doesn’t script falls back to a scenario: type tool, memory, remind, key, mcp, slow, compact or error in Juniper’s DM. Only the model and external services are simulated. Add scenarios under apps/daemon/src/demo/scenarios/ and register them in apps/daemon/src/demo/model.ts.
Workspace
Section titled “Workspace”| Path | What it is |
|---|---|
packages/core |
The assistant. Portable: no Node-only or Workers-only code |
packages/client |
Browser store and React bindings. Imports only types from core |
packages/cloudflare |
Durable Object adapter. The only Workers-specific package |
packages/computer |
Familiars’ computers, their agent and the Docker host |
apps/daemon |
The installed Node host, CLI and demo |
apps/web |
The web UI |
apps/docs |
This site |
examples/embedded-kanban |
Task board with Familiar embedded. Built into this site |
examples/shared-conversation |
Several people sharing one Familiar. Built into this site |
examples/cloudflare-worker |
A Worker hosting Familiar on Durable Objects |
Workspace packages import each other’s TypeScript source. Published packages ship compiled dist files, which pnpm build:packages builds. ESLint enforces the portability rules.
Checks
Section titled “Checks”Before you open a pull request:
pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm exec prettier --check .Also run:
pnpm test:cloudflarefor core or Cloudflare changes. Tests run in workerd and need no Cloudflare account.pnpm test:packagesfor package exports or dependencies. It packs the libraries and installs them outside the workspace.pnpm build:docsfor documentation changes. It builds this site and fails on broken internal links.
CI runs the main checks and pnpm test:packages on every pull request. The workerd tests, the CLI on macOS, Linux and Windows, and the docs build run when a pull request changes their files.
Computers need the computers’ image. pnpm image builds it from your checkout, tagged with the version a checkout’s hosts use, and the Docker test is skipped until it’s built.
Use the faux provider, or scriptedModels for a script that answers every request, to test the real harness without model requests. pnpm eval:recall and pnpm eval:unfiled check memory retrieval without a model. pnpm eval:memory-scenarios and pnpm eval:longmem run memory on real models, through an eval-only sign-in.
The docs site
Section titled “The docs site”pnpm dev:docsPages are Markdown and MDX under apps/docs/src/content/docs/. Code samples longer than a few lines live in apps/docs/snippets/ and are type-checked by pnpm typecheck. Internal links include the /familiar/ base path.
Pushes to main that change the docs or packages deploy the site to GitHub Pages through .github/workflows/docs.yml.
Releases
Section titled “Releases”Pushing a v* tag runs the release workflow. It publishes the npm packages, the installable assistant and the computers’ image, ghcr.io/aidanzealley/familiar-computer:<version>, which hosts of that version pull. pnpm bundle builds the installable tarball locally, and pnpm test:release checks it with temporary storage.