nst

nst creates copy-on-write Git workspaces for coding agents. A new workspace starts with the source checkout's installed dependencies and environment files, but subsequent changes stay isolated.

Requires macOS, Node 20+, and a destination volume that supports copy-on-write file cloning.

Install

npm install -g @anuragdev/nst

The package installs a single nst executable.

Use

Run nst from inside a Git repository.

nst create agent/my-task      # new branch + isolated workspace
nst list                      # activity board for every workspace
nst editor agent/my-task      # open the workspace in your editor
nst test agent/my-task        # run tests in the isolated runtime
nst publish agent/my-task     # push the branch (--pr opens a pull request)
nst remove agent/my-task      # stop services and delete the workspace

To work on an existing branch or pull request instead of creating one:

nst checkout feature/existing
nst checkout pr:123

Pass --json to any command for machine-readable output. The full command surface — shadow testing, verification receipts, handoff capsules, causal diffs, knowledge salvage, managed services, previews — is documented in COMMANDS.md.

Configuration

Repositories can add nst.config.json for monorepo-specific artifacts, ports, services, and setup hooks:

{
  "envFiles": ["apps/*/.env.local"],
  "dependencyPaths": ["apps/legacy/node_modules"],
  "postCreate": {
    "command": "pnpm prisma generate && pnpm db:seed",
    "timeoutMs": 300000
  },
  "ports": [
    {
      "name": "frontend",
      "preferred": 5173,
      "env": "VITE_PORT",
      "originEnv": ["CORS_ALLOWED_ORIGIN"]
    },
    { "name": "api", "preferred": 8000, "env": "API_PORT" }
  ],
  "services": [
    { "name": "web", "command": "pnpm dev", "cwd": "apps/web", "stopTimeoutMs": 5000 }
  ],
  "runtime": {
    "env": {
      "DATABASE_SCHEMA": "databaseSchema",
      "QUEUE_NAMESPACE": "queuePrefix",
      "CALLBACK_URL": "callbackOrigin"
    }
  }
}

Every workspace receives ports distinct from the preferred main-checkout ports, plus a persisted runtime profile (compose project name, database schema, queue prefix, socket and cache directories). originEnv can override an API's allowed CORS origin with the workspace frontend origin.

A configured postCreate command runs once, from the new workspace, after dependencies, env files, and ports are ready. Because hooks are executable code committed to the repository, nst prints the exact command and asks for approval on the first interactive run; non-interactive agents opt in with --trust, and --no-post-create skips the hook entirely.

Coding-agent integration

nst integrate codex     # AGENTS.md block
nst integrate claude    # WorktreeCreate/WorktreeRemove adapters + .claude/settings.json
nst integrate copilot   # .github/copilot-instructions.md
nst docs agent          # print the stable agent contract

Every integration is idempotent and supports --dry-run --json. Agents get a versioned JSON envelope with stable error codes, retryability, remediation, and stable exit-code families — see the agent-safe contract in COMMANDS.md.

How it fits together

• Isolation. Each workspace is a Git worktree with cloned dependencies, its own ports, and its own runtime namespace, so parallel agents never collide on a database, port, or compose project.
• Coordination. nst intent declare reserves symbols and contracts before editing; nst shadow run --pairs merges every workspace pair in memory and optionally tests the mergeable cells.
• Evidence. nst verify stores tamper-evident receipts of what was run against exactly which inputs; nst explain records why a changed range exists.
• Continuity. nst handoff export hands one agent's context to the next, and nst discard --salvage keeps the useful dead-end knowledge from a failed attempt without keeping its code.

Development

pnpm install
pnpm build
npm link

npm link installs a global symlink to this checkout rather than copying it. To rebuild the linked CLI whenever local source files change, keep this running in another terminal:

pnpm dev

Other scripts: pnpm typecheck, pnpm test, pnpm test:watch.

Source architecture

Production code is organized by product domain rather than kept in a flat src/ directory:

• core/ contains durable state and shared protocol primitives.
• workspaces/, lifecycle/, and git/ own workspace creation, recovery, and repository operations.
• integrations/, services/, and observability/ own external tools, processes, and live state presentation.
• coordination/, evidence/, delivery/, and preview/ own their complete feature workflows.
• cli/ contains small command registrars; the root cli.ts is only the executable bootstrap.

Each domain exposes an index.ts public surface. Domain internals import concrete sibling modules so dependency direction remains visible and barrel cycles do not become hidden runtime behavior.

License

MIT