Hands-off mode — DirectorHub

What it is

DirectorHub works fully without it — the Claude Code connector already lets you pull work and report back by hand. Hands-off mode removes the last bit of friction: instead of triggering each directive in a terminal, a small program called directorhub-watcher runs quietly on your machine, watches for the directives you send, and executes them for you.

It's the same pull-only bridge — the Hub never reaches into your machine. The ignition key stays on your side: you install it, you choose which projects it may touch, and you can pause it at any moment.

Zero-terminal, end to end

You send an @executor directive

From any session, address a directive to the executor — a small, concrete task tied to that project.

The watcher picks it up

Running on your machine, it sees the directive on its next poll, acknowledges it, and the timeline shows “working (auto-executor)”.

It runs your chosen engine

On a fresh directive/… branch in the mapped repo, with a strict tool allow-list — read, edit, build, test, commit. Never push.

It reports and resolves

A full report lands on the timeline as an executor round and the directive is marked resolved — you review the branch when you're ready.

Automation you stay in charge of

Whitelist-only. You map each project to a specific local repo. There is no “all projects” mode — it only ever touches what you list.

Never pushes. Work stays on a local branch. Nothing leaves your machine to a remote; you decide what to push.

One at a time. Directives run serially with a hard timeout, so a stuck task can't pile up or run away.

Pause from the Hub. Pausing is enforced on the server — while paused, directives simply wait as “awaiting pickup”.

Private by design. Your API key and repo paths never leave your machine. The Hub only knows which project IDs you're watching.

Setup guide

Install hands-off mode, step by step

Before you start

Node.js (npm) on your machine — the watcher is an npm package.
Claude Code installed & signed in — the watcher drives the CLI on your account.
A DirectorHub token — from Skills & connectors → Claude Code → Generate token (the watcher reuses it automatically if you already added the connector).

Install the watcher

One global npm install:

npm i -g directorhub-watcher

Configure it

Run init. It asks for the Hub URL (directorhub.app), your token (reused from Claude Code if found), then you pick which projects to watch and map each to a local repo path — use an absolute path (e.g. /Users/you/Git/project). Optionally enable autostart.

directorhub-watcher init

Start it

Run it in the foreground, or install autostart so it runs on login and survives reboots:

directorhub-watcher start        # foreground
directorhub-watcher autostart    # background, on login

Send a directive

From a session in a whitelisted project, address a task to @executor. The watcher picks it up and runs it — no terminal needed.

✓ Verify. In the app, Skills & connectors → Hands-off mode shows ● Online with the version and watched projects. Your directive moves awaiting → working (auto) → resolved on a directive/… branch.

Troubleshooting

spawn claude ENOENT. The watcher can't find the Claude Code CLI. Make sure claude is installed and re-run directorhub-watcher init so it re-detects the absolute path.
Repo path not found. Use an absolute path in init — ~ is not expanded.
Directive stuck on "awaiting pickup". The watcher is paused (resume it in the Hub) or not running — check directorhub-watcher status.
Report came back "failed". Open the report — if headless claude -p failed, the reason (its stderr tail) is included.

Handy commands

directorhub-watcher status        # running state + watched projects
directorhub-watcher stop          # stop the watcher
directorhub-watcher autostart --off   # remove autostart

Pause anytime from the Hub — Skills & connectors → Hands-off → Pause. It's enforced on the server, so directives just wait while paused.

Claude Code or Cursor — your choice, per project

The watcher isn't tied to one tool. During init you pick the engine for each project: Claude Code (the default), Cursor, or Codex. The loop, the guardrails and the directive/… branch are identical — only the coding agent underneath changes. In Skills & connectors → Hands-off every project then shows its live engine, e.g. NexTutor → Cursor · <model>.

Turn on the Cursor engine

Node ≥ 22.13 — the Cursor SDK requires it. Check with node --version.

A Cursor API key — Cursor dashboard → Settings → API Keys. It bills to your Cursor plan.

directorhub-watcher 0.2.0+ — the Cursor engine ships from this version (check directorhub-watcher --version).

In init, answer yes to enabling Cursor and paste the key — it's stored owner-only in ~/.directorhub/watcher.json and never logged. Then choose Cursor for a project and pick a model from the live list. The report's cost line reads execution: $0.00 (Cursor plan) whenever your plan covers the run.

No-push, technically enforced. The Cursor runtime is sandboxed with the network denied, so pushing is impossible — while inference still runs on Cursor's hosted models, unaffected.

Or the Codex engine

Codex needs no key at all: run codex login once (a one-time browser sign-in), and the watcher reuses that cached ChatGPT login for headless codex exec — exactly like the Claude CLI. It's a Rust binary, so there's no Node requirement. In init, choose Codex for a project; reports carry execution: $0.00 (ChatGPT plan).

Same no-push guarantee. Codex runs in its workspace-write sandbox with the network denied, so pushing is impossible while build and test still run — its inference is in the ChatGPT cloud, unaffected. (macOS uses the built-in sandbox; on Linux, install bubblewrap.)