nerve/docs/skill-setup.md

Skill: Setup nerve from scratch

When to use

Setting up the nerve project for local development from a fresh clone.

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 9 (npm install -g pnpm)
• Git access to git.shazhou.work

Steps

1. Clone

git clone https://git.shazhou.work/uncaged/nerve.git
cd nerve

2. Install dependencies

pnpm install

This installs all workspace packages and links internal dependencies (core → daemon → cli).

3. Build all packages

pnpm -r run build

Build order is handled automatically by pnpm workspace — core builds first, then daemon, then cli.

4. Run tests

pnpm -r run test

Or test individual packages:

pnpm --filter @uncaged/nerve-core test
pnpm --filter @uncaged/nerve-daemon test
pnpm --filter @uncaged/nerve-cli test

5. Try the CLI

# Link the CLI globally
cd packages/cli && npm link

# Initialize a workspace
mkdir ~/my-nerve-workspace && cd ~/my-nerve-workspace
nerve init

# Edit senses in nerve.yaml, then:
nerve start      # start the daemon
nerve sense list  # list registered senses
nerve stop       # stop the daemon

6. Lint & format

pnpm run check    # biome lint check
pnpm run format   # biome auto-format

Project structure

nerve/
├── packages/
│   ├── core/       # @uncaged/nerve-core — shared types, log store, blob store
│   ├── daemon/     # @uncaged/nerve-daemon — kernel, sense runtime, workflow manager
│   └── cli/        # @uncaged/nerve-cli — CLI commands (init, start, stop, sense, etc.)
├── docs/           # RFCs, conventions, skills
├── pnpm-workspace.yaml
└── biome.json      # linter/formatter config

Key conventions

• Monorepo with pnpm workspaces
• ESM only — all packages output ESM ("type": "module")
• tsup for builds, vitest for tests, biome for lint/format
• SQLite (better-sqlite3) for log store and blob store
• See docs/coding-conventions.md for code style rules

Pitfalls

• Must build before test — daemon and cli import compiled output from core
• better-sqlite3 requires native compilation — if pnpm install fails, ensure you have build tools (build-essential on Linux, Xcode CLI tools on macOS)
• Node 18+ required — uses native fetch, crypto.randomUUID, etc.
• pnpm only — don't use npm/yarn, workspace links won't resolve correctly