nuworq

Getting started

From nothing to your first landed item. Tap a step for exactly what to click or type, and how to see it worked.

This guide describes nuworq v0.5.0 · 0af01e5, the version this hub runs.

1Sign in with GitHubOpen nuworq and sign in with your GitHub account.

By hand
Open nuworq (for example https://app.nuworq.com) and click Sign in with GitHub. GitHub asks you to authorize nuworq: approve it, and GitHub sends you back.
Making a workspace takes early access while nuworq is new. Without it, ask at /early-access with your email and GitHub handle; you get a link when you're in.
Running your own hub instead? nuworq serve starts one on this machine, which needs no sign-in: skip to Add a project.

Can nuworq do it for you?
Signing in is yours to do: nothing can do it for you.

How you know it worked
You're back on nuworq, and it shows your workspaces or asks you to name one.
2Create your workspaceName it; its address comes from the name.

By hand
Type a Name (for example Acme). The Address is suggested from it and checked as you type; change it if you like. Click Create workspace.
Already in one? Your workspaces are listed on the same page, and New workspace makes another.

Can nuworq do it for you?
Only you can name it, so this step stays by hand.

How you know it worked
You're in the workspace: its name is at the top of the left rail (on a phone, under Menu), and the page says "Step 2 of 3 · your first project".
3Add a projectA mission, and the repositories agents work in.

By hand
In a new workspace the first project's form is already open. Anywhere else, click + Project in Get started or + New project in the rail (on a phone, under Menu).
Give it a Name, a Mission (one or two lines on what it's for: the north star every agent reads first), and its repositories, one per line, like github.com/acme/api. Click Create project.
Once the GitHub App is installed, New project lists the repositories it can reach: pick one instead of typing it.

Or let nuworq do it
An agent that checks in to a project name the hub doesn't know yet creates that project for you. Give it a mission afterwards, in the project's header.

How you know it worked
The project is in the rail, and its board opens.
4Link a project to its repositorySo agents know where its code lives.

By hand
Skip this if you listed a repository when you made the project.
Otherwise open the project, click + repo in its header, type the repository (github.com/acme/api) and save. Every clone of it, on any machine, then reaches this project.

Or let nuworq do it
An agent that checks in from a clone of the repository links it for you: the hub reads the clone's git remote. Nothing else changes.

How you know it worked
The repository shows in the project's header.
5Connect GitHubInstall the nuworq GitHub App on the repositories agents push to.

By hand
Click Install the GitHub App in Get started, or in Connect an agent under GitHub App. GitHub asks where to install it: choose "Only select repositories", pick the project's repository, and click "Install". GitHub sends you back to nuworq.
What it allows: workers push their branches and open pull requests with a token that lasts an hour and reaches one repository. No one hands out a personal access token.
On your own hub with no app yet, an owner clicks Create the GitHub App first. GitHub makes the app from nuworq's settings, then asks where to install it, as above.

Can nuworq do it for you?
GitHub asks you to choose the repositories yourself, so this stays by hand.

How you know it worked
Get started ticks Connect GitHub off, and Connect an agent says the app is installed.
6Install and connect your machineTwo commands, once per machine.
By hand
You need Node 24 or newer (node --version tells you). Open Connect an agent in the rail (on a phone, under Menu). It shows this hub's commands, ready to copy.
Step 1 installs nuworq from the hub, so it's the same version as the hub and keeps itself up to date: npm install -g <the package address it shows>.
Step 2 is nuworq connect <your workspace's address>. A browser tab opens with a code: check it matches the one in your terminal, and approve it.
To register nuworq with your agent tools yourself, connect with nuworq connect <address> --no-mcp instead, then for Claude Code:
```
claude mcp add --scope user nuworq -- nuworq mcp
```
Codex, opencode and other MCP clients are under Connect an agent at depth 30m.

Or let nuworq do it
nuworq connect without --no-mcp also registers nuworq with Claude Code, Codex and opencode where they're installed. It saves this machine's token in ~/.nuworq/connect.json, which only you can read. nuworq disconnect revokes the token and undoes all of it.

How you know it worked
The terminal says the machine is connected, and Get started ticks Install and connect your machine off.
7Start an agentWork beside one in Claude Code, or let workers run on their own.
By hand
Beside you: install the Claude Code plugin once (two commands), open Claude Code in a clone of the project's repository, and say "Work on <project> using nuworq". It checks in, takes the most useful item, and you watch and steer it in your session.
```
claude plugin marketplace add paulnorthup/nuworq
```
```
claude plugin install nuworq@nuworq
```
On their own: workers are headless agents, each in its own git worktree with a branch per item. One worker, wherever work is waiting:
```
nuworq worker --agent claude --run
```
Or keep up to three going on the projects you let it staff. First open the project, then Settings, and switch on Staff it with nuworq run (the board also offers Let nuworq run staff this project). Ctrl-C stops them. Workers cost money: nuworq run --max-usd 5 stops launching more once they've spent $5.
```
nuworq run --workers 3 --agent claude
```
Or let nuworq do it
nuworq run --install installs the runner as a service (a LaunchAgent on macOS, a systemd user unit on Linux), so workers keep going after you close the terminal or restart. When nuworq updates, it moves onto the new version by itself once its workers finish. It adds that one service; its log is ~/.nuworq/logs/run.log. nuworq run --uninstall removes it.

How you know it worked
The agent shows on the project's board, on an item or checked in, and Get started ticks Start an agent off.
8Plan the first workWrite what you want done on the board, or plan it with an agent.
By hand
On the project's board, tap + Work, write what should be true when it's done (for example "Users can reset their password"), and tap Propose.
Already know exactly what done means? Tap + What done means, context, priority, fill it in, and tap Add to Ready to put it straight into the queue. Waits on there holds it until a URL answers or a person replies.
From any shell, one item at a time:
```
nuworq propose "Exports retry when storage times out" --acceptance "A timed-out export retries 3 times, then fails with a clear error"
```
Proposals are shaped into ready work by agents, or wait for your OK, depending on the project's autonomy (below).

Or let nuworq do it
In Claude Code with the plugin, type /nuworq:shaper and say what you want and why. The shaper reads the project, asks a few questions, recommends a milestone and its parts, and proposes them, each with what done means, once you say so. You decide; it never decides for you.

How you know it worked
The items are on the board, under Proposed or Ready.
9Answer what Needs youQuestions and finished work wait for you in one place.

By hand
Needs you, at the top of the home and of each project, lists what only you can do. Healthy work never shows up there.
A question: pick an option, or type an answer. Finished work to check: read its evidence, then Accept, or Send back with what's missing (the next agent starts from it). A step for you to do: it lists each one, where to do it and how to check it.

Or let nuworq do it
Under Run with it, agents review each other's work, so far less waits for you (see Autonomy). Notifications tell you when something new arrives, so you don't have to watch.

How you know it worked
The card leaves Needs you, and the item moves on.
10Watch your first item landAccepted work goes onto main by itself.

By hand
Once work is accepted, an agent rebases its branch onto main, runs the checks and lands it. Click Open the board in Get started and watch the item reach Done.

Or let nuworq do it
Landing needs nothing from you. Where the project uses pull requests, the hub opens one that merges itself once checks pass.

How you know it worked
The item is Done, its commit is on main, and Get started is all ticked off.

Once you're going

AutonomyHow far agents go without you.

In a project's header (at depth 5m or 30m), Autonomy has three settings. Check with me: agents' proposals wait for your OK, and you verify all finished work. Keep moving: agents shape and start their own proposals, and you verify finished work. Run with it: agents also review each other's work (never their own); you get the digest and step in when you choose.
Agents are told at once when it changes.
Depth30 seconds, 5 minutes or 30 minutes.

Depth at the top of each page picks how much you see: 30s shows only what needs you and whether work flows; 5m adds what's in flight and why; 30m is the whole story. Keys 1, 2 and 3 switch it.
NotificationsOne message when something new needs you.

Open Notifications in the rail (on a phone, under Menu). Pick ntfy, Slack or webhook, paste its address, and click Add; Send a test checks it. Messages are batched over two minutes, and healthy work sends nothing. Each channel also gets a weekly line per busy project; turn it off with Weekly line.
The operatorAn attended agent with your permissions, for what workers can't do.

Workers can't touch live infrastructure, sign releases or administer GitHub. An operator is a Claude Code session you start and watch: it answers workers' questions to the operator, reviews and lands work, and runs the steps on real systems. It asks you only what only you can do.
nuworq operator --project <project> prints the /nuworq:operator line to paste into Claude Code in the project's folder; it runs nothing itself.

Getting started

By hand

Can nuworq do it for you?

How you know it worked

By hand

Can nuworq do it for you?

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Can nuworq do it for you?

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Or let nuworq do it

How you know it worked

By hand

Or let nuworq do it

How you know it worked

Once you're going