Documentation

Everything you need to get noxdev running.

Quickstart

# Install
npm install -g @eugene218/noxdev

# Check prerequisites
noxdev doctor

# Register an existing project (must have at least one commit)
cd ~/projects/my-project
noxdev init my-project --repo .

# Write tasks in the worktree
vi ~/worktrees/my-project/TASKS.md

# Run
noxdev run my-project

# Review
noxdev status my-project
noxdev merge my-project

End-to-end demo run

A full walkthrough from init to merge using a temporary test project.

1. Initialize a project

mkdir -p /tmp/test-noxdev && cd /tmp/test-noxdev && git init
echo "# test" > README.md && git add . && git commit -m "init"
noxdev init test-verify --repo .
noxdev projects

2. Check status (no runs yet)

noxdev status test-verify

3. Write a task and run

cat > ~/worktrees/test-verify/TASKS.md << 'EOF'
## T1: Create hello.txt
- STATUS: pending
- FILES: hello.txt
- VERIFY: cat hello.txt
- CRITIC: skip
- PUSH: auto
- SPEC: Create a file called hello.txt containing "hello from noxdev"
EOF

noxdev run test-verify

4. Review results

# Summary
noxdev status test-verify

# Full task detail: spec, agent logs, diff, duration
noxdev log T1

5. Merge (from the repo, not the worktree)

cd /tmp/test-noxdev
noxdev merge test-verify

# Then push when ready
# git push origin master

6. Dashboard (optional)

noxdev dashboard
# Opens http://localhost:4400 — Ctrl+C to stop

7. Cleanup

noxdev remove test-verify --force

All CLI commands

    ,___,
    [O.O]         noxdev v0.1.0
   /)   )\        ship code while you sleep
   " \|/ "
  ---m-m---

Command	Description
noxdev init <project>	Initialize a new project. Creates worktree, branch, registers in SQLite. Auto-creates initial commit if repo is empty.
noxdev run [project]	Run pending tasks from TASKS.md. Parses specs, spins up Docker containers, executes tasks, writes results to SQLite.
noxdev run --all	Run all registered projects sequentially. Each project runs its full task queue. Circuit breaker applies per project.
noxdev run --overnight	Detached background mode. Frees your terminal, prevents system sleep (systemd-inhibit on Linux, caffeinate on macOS), writes PID to ~/.noxdev/noxdev.pid.
noxdev status [project]	Morning summary. Shows last run: completed/failed counts, commit list, pending merge decisions.
noxdev log <task-id>	Full task execution detail: spec, agent logs, diff, duration, merge status.
noxdev merge [project]	Interactive per-commit approve/reject/diff/skip workflow. Approved commits merge to main. Rejected commits are explicitly reverted. Skipped tasks stay pending for next review.
noxdev projects	List all registered projects with last run status.
noxdev dashboard	Launch React web UI on localhost:4400. Overview, run detail, task detail with diff viewer, merge review, dark mode.
noxdev doctor	Check all prerequisites: Docker, git, Claude Code CLI, Node.js, pnpm, SOPS, age.
noxdev remove <project>	Unregister a project. Removes worktree directory, deletes from SQLite. Use --force to skip confirmation.

noxdev merge vs git merge: Unlike git merge which merges an entire branch, noxdev merge operates per-task — you approve, reject, or skip each commit individually. Rejected work is explicitly reverted with a traceable commit. Skipped tasks remain pending. All decisions are tracked in SQLite.

TASKS.md format

The task spec is the unit of work. No spec, no session.

Fields

Field	Description
STATUS	pending, done, failed, skipped — auto-updated by noxdev after each run
FILES	Hint for the agent about which files to modify. Not a constraint — the agent can touch other files.
VERIFY	Command that must exit 0 for the task to succeed. Test that it works, not just that it compiles.
CRITIC	skip or review. When review, a second agent reviews the diff for correctness and scope.
PUSH	auto (tests pass → commit), gate (commit stays local for manual review), manual (no auto-commit).
SPEC	The directive. Be specific. Include working code inline when wrapping existing logic.

Tips from practice

Good spec: "Add loading spinner to the match button. Show spinner while request is in flight, hide on response. VERIFY: pnpm build passes."

Bad spec: "Improve the UX of the matching flow."

Directive specs with explicit stopping conditions work reliably. Open-ended or exploratory specs cause the agent to hang indefinitely in Docker. When wrapping existing code, paste the working code into the SPEC — otherwise the agent invents new patterns instead of preserving yours.

Configuration

Global: ~/.noxdev/

~/.noxdev/
  ledger.db        # SQLite database (auto-created)
  config.json      # Global settings
  logs/            # Run logs per project + run ID
  noxdev.pid       # PID file when running --overnight

Per-project: .noxdev/config.json

{
  "project": "my-project",
  "display_name": "My Project",
  "test_command": "pnpm test",
  "build_command": "pnpm build",
  "lint_command": "pnpm lint --fix",
  "docker": {
    "memory": "4g",
    "timeout_minutes": 30,
    "cpus": 2
  },
  "api": {
    "fallback": true,
    "dailyCapUsd": 5,
    "model": "claude-sonnet-4-20250514"
  }
}

--overnight mode

noxdev run <project> --overnight runs the exact same task execution as a normal run, but as a detached background process:

Detaches the process — spawns a child node process with detached: true and stdio: "ignore", then calls child.unref() so your terminal is immediately freed.

Inhibits system sleep — wraps the child process in systemd-inhibit --what=sleep on Linux or caffeinate -s on macOS. Your machine stays awake while the run is in progress.

Writes a PID file to ~/.noxdev/noxdev.pid so you can check on it later.

Designed for kicking off a long run before closing your laptop lid or walking away. Fire and forget.

Requirements

noxdev doctor   # checks all of these

Node.js 18+ · Docker (running) · Git · Claude Code CLI (installed + authenticated) · pnpm (recommended)