Skip to content

Development

Use Node 24.19 or newer and the pnpm version in the root package.json:

Terminal window
git clone https://github.com/AidanZealley/familiar.git
cd familiar
pnpm install
Terminal window
pnpm dev

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

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.

Before you open a pull request:

Terminal window
pnpm typecheck && pnpm lint && pnpm test && pnpm build && pnpm exec prettier --check .

Also run:

  • pnpm test:cloudflare for core or Cloudflare changes. Tests run in workerd and need no Cloudflare account.
  • pnpm test:packages for package exports or dependencies. It packs the libraries and installs them outside the workspace.
  • pnpm build:docs for 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.

Terminal window
pnpm dev:docs

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

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.