New-hire setup for FUTO Notes. For how the codebase is organized and the day-to-day rules, read AGENTS.md next — this doc only gets your machine ready.
- Node + pnpm — the JS toolchain (
pnpmis the package manager;npx/npmis not used here). The exact version is pinned in.nvmrc; fnm reads it (fnm use), and every CI surface — Linux, macOS and Windows — installs that same version the same way. - Rust (stable) +
cargo— for the Tauri backend and the shared crates. - just — every build/dev/test command lives
in the
justfile. Runjustwith no args to list recipes. - Desktop (Linux): the usual Tauri/WebKitGTK system deps.
- Mobile (optional): Xcode + an iOS simulator for iOS; Android SDK + NDK +
cargo install cargo-ndkfor Android. See AGENTS.md §2, the nested mobileAGENTS.mdfiles, and theANDROID_*vars in.env.example.
For dependencies owned by the workspace root, use pnpm add -w <package> (or
pnpm add -Dw <package> for a development dependency). Use the owning package's directory
for a package-local dependency; do not disable pnpm's workspace-root guard.
For a fresh task, fetch main and create a sibling worktree, then run just orient there.
just orient --json provides the same inventory for tools; --base <ref> changes the
comparison base (default origin/main). It includes the entire branch since the merge base,
staged/unstaged changes and untracked files. It reports installed tool paths, missing dependencies,
and worktrees sharing a slot; presence alone does not prove a working build or a safe QA target.
just setup # check tools and install pinned workspace dependencies
just tauri-dev # run the desktop app (forces Wayland on Linux; port: just ports)
just verify-run check # lint + tests + build sanity, with a retained evidence bundleWorking alongside another session? just wt new <name> makes a sibling worktree
with deps installed; Rust cache cloning is opt-in with --clone-target (or later,
just qa-clone-target <worktree>). Even reflinks walk the cache and create filesystem
metadata, which can stall the workstation. For reviews, use --no-install too when
local tests are unnecessary. just wt gc reaps stale ones; just orient says where you are.
If a fresh worktree or SSH shell cannot find Node/just, start with
bash scripts/dev-env.sh --install just setup. Wrap later SSH commands with
bash scripts/dev-env.sh too. See worktree setup and verification
for platform preflight, Mac usage, real-app journeys and evidence retention.
Dev/debug builds isolate their notes from production. Desktop/iOS use
com.futo.notes.devandfake-notes; Android isolates package storage by application ID and uses a separate public device folder. Don't weaken those guards — see AGENTS.md M3.
None are needed to build and run the app. They gate specific workflows
(release tooling, Zulip, sync tests, mobile signing). See
.env.example for the full list with descriptions — copy the
ones you need into your shell profile (~/.zshrc/~/.bashrc) or source a
local .env.
This repo ships shared Claude Code config under .claude/:
- Skills (
.claude/skills/) —/ci-doctor,/puppet,/release,/slow-review,/spec-sync,/test-agent,/verify,/verify-specs,/zulip, and more (ls .claude/skills). Available automatically when you open the repo in Claude Code. Note/release,/verify, and/zulipneedGITLAB_TOKEN/ZULIP_API_KEY(see step 3). - Workflows (
.claude/workflows/) — multi-agent flows likesync-adversarial; syntax checks:just check-workflows --help. - Shared settings (
.claude/settings.json) — a small project permission allowlist plus the repo's hooks. Personal overrides go in.claude/settings.local.json(gitignored). - Hooks (
scripts/hooks/, wired from.claude/settings.json) — printjust orientat session start and give each subagent a private scratch directory;scripts/puppet-receipt-hook.mjs(PreToolUse) refuses a piped or filteredjust puppetaction, whose receipt must be read whole. No hook denies process-name kills,git stashin a linked worktree, or OS-level input (the deny hook was removed in 34040eb9); follow those rules by hand — see AGENTS.md §5, M24 and M25.
The general SwiftUI, Swift concurrency, and Swift Testing references are optional
local packages. just skills-swift restores the exact formerly vendored copies from
repository commit 3b1c43c139181b91b7384b478b5edec454b80190 into the gitignored .agents/skills/
and links them for this worktree. It refuses to overwrite existing installations.
A shallow clone must first fetch that commit with git fetch origin 3b1c43c139181b91b7384b478b5edec454b80190.
The snapshot retains the original upstream attribution; future upgrades should be
explicit, rather than silently replacing reference material during app builds.
skills-lock.json records the generic engineering skills we borrow from
mattpocock/skills (/tdd, /research, /code-review, /wayfinder, …). They
are not vendored here — an external installer populates the gitignored
.agents/skills/, and then just skills-link links them into .claude/skills/
for that checkout. Run it once per clone or worktree; skills it cannot find are
reported rather than linked.
Never commit those links: .agents/ is gitignored, so a committed symlink into
it works only in the checkout that happens to have .agents/ populated and
dangles in every fresh clone and git worktree add. just check-agent-docs
fails on one. The repo-side adapters these skills read — how they should consume
our domain docs, our issue tracker, and our triage labels — live in
docs/agents/domain.md, docs/agents/issue-tracker.md, and
docs/agents/triage-labels.md, and only apply when the matching skill is
installed.
To drive/debug the running app from Claude Code, copy the example config:
cp .mcp.json.example .mcp.json # .mcp.json is gitignoredThis wires up the Tauri MCP bridge (@hypothesi/tauri-mcp-server). See
AGENTS.md §9; the driving playbook is the /verify skill's references/desktop.md.
Nothing to set up. The E2EE sync server is a separate repo
(https://gitlab.futo.org/futo-notes/futo-notes-server) that publishes a static
Go binary per release; just test-cross-platform and just qa-server download
the release pinned in scripts/sync-server-pin.json on first use (~15 MB,
cached in ~/.cache/futo-notes) and give each server its own SQLite database.
No checkout, no Postgres, no Docker.
To run an unreleased server change instead, point
FUTO_NOTES_E2EE_SERVER_REPO at your checkout — it is built with go build —
or FUTO_NOTES_E2EE_SERVER_BIN at a binary you already have.
- AGENTS.md — architecture, where logic lives, key constraints, testing matrix.
docs/spec/— behavioral source of truth, by surface.just check— the gate to pass before pushing.just test-tls-fixture --help— generate local QA CA/server files with macOS LibreSSL or Linux OpenSSL.