Development setup

Set up the toolchain for working on the repository: Nix provides the environment, direnv loads it automatically, and cargo runs the app.

What you need

A Unix-like machine (macOS is the main target today; Linux works for the Rust crates), Nix with flakes enabled, and direnv. The dev shell also brings Node and pnpm for the web packages, so you do not need those installed globally.

What you need

The repository uses Nix flakes for its development environment: the.envrc file loads flake.nix, which provides the Rust toolchain,cargo-watch, Node, pnpm, and the helper commands used below. direnv withnix-direnv loads it automatically when youcd into the repo and caches the shell between visits.

Install Nix

terminal

# Recommended: the Determinate Systems installer (flakes enabled by default)
curl -L https://install.determinate.systems/nix | sh -s -- install

# Or the official multi-user installer, then enable flakes in /etc/nix/nix.conf:
#   experimental-features = nix-command flakes
curl -L https://nixos.org/nix/install | sh -s -- --daemon

Open a new shell afterwards so nix is on your PATH.

Install direnv

terminal

nix profile install nixpkgs#direnv   # or: brew install direnv / apt install direnv

# Hook it into your shell (bash shown; see `direnv hook --help` for others)
echo 'eval "$(direnv hook bash)"' >> ~/.bashrc

Enable nix-direnv

nix-direnv caches the built devShell, so re-entering the repository is fast. The manual install:

terminal

git clone https://github.com/nix-community/nix-direnv ~/.config/direnv/nix-direnv
echo 'source ~/.config/direnv/nix-direnv/direnvrc' >> ~/.config/direnv/direnvrc

Alternatively, use the nix-direnv Home Manager or NixOS module.

Allow the environment

terminal

# From the repository root
direnv allow

# The first run builds the devShell and takes a while; later shells load from
# the nix-direnv cache. Verify it worked:
direnv status        # should show "Found RC allowed true"
which cargo rustc    # should resolve into the Nix store

Run the app

terminal

cargo run -p taskstream-desktop    # run the desktop app
t2                     # or run it under cargo-watch for auto-rebuilds

t2 is the usual development loop: it runs the binary under cargo-watch so logs stream to the terminal and rebuilds happen on save.

Command reference

The dev shell adds the following commands, all available from the repository root.

Command	What it does
`cargo run -p taskstream-desktop`	Run the desktop app.
`t2`	Run the desktop app under cargo-watch, rebuilding on change.
`t2-bundle`	Assemble the macOS bundle (icon, Info.plist, signing) without launching it.
`ccheck`	cargo check the main workspace crates.
`tt`	Run the Rust test suite, with macOS codesign/quarantine fixups for the test binaries.
`testdbg`	Run the storage tests with debug logging.
`mig <args>`	Run a storage migration (cargo run --bin migrate -- migration ...).
`clone-patch <crate>`	Clone a crate's upstream repository into patched/ to vendor a fork.
`skills`	Sync docs/agent_skills/*.md into .agents/skills/.
`web`	Install the JS workspace, stop any dev server left by a previous session, and start the docs site.
`dev-stop`	Stop the dev and preview servers the web packages left running (astro dev stop / astro preview stop).
`astro <args>`	The workspace's pinned Astro CLI, e.g. astro dev status or astro check.
`pnpm dev`	Run this documentation site with auto-rebuilds.
`pnpm dev:ds`	Run the design-system showcase with auto-rebuilds.

Web surfaces

The pnpm workspace holds three packages: the design system (libs/web-design-system), its showcase (demos/design-system-showcase), and this documentation site (apps/docs-web). None of them are Cargo members.

terminal

pnpm install      # install the pnpm workspace (design system, showcase, docs)
pnpm dev          # this site (Astro's default port, or the next free one)
pnpm build:docs   # static build of this site
pnpm dev:ds       # the design-system showcase
pnpm typecheck    # typecheck all three JS packages
pnpm test         # Vitest suite for the design system
pnpm test:e2e     # Playwright smoke, theming, and WCAG 2.1 AA checks

Class parity

The design system, the showcase, and this site each run Panda codegen. Their panda.config.ts files must keep hash, separator, and prefix identical, and each app's include globs must cover the design system's source. If they drift, components render unstyled with no error.

Troubleshooting

direnv reload re-evaluates .envrc after a change (for example, flake.lock).
direnv status explains why the environment is or is not loaded.
If builds fail on a fresh lockfile, try direnv reload or nix flake updatein the repository.
On macOS, launching a bundled .app can prompt for access to Documents/Music/Photos; running the raw binary under t2 keeps the shell's existing permissions.