crux
docs [ log in ]
$ crux tail --project crux --actor lead-crux

agent orchestration for one operator (with a life)

Leaving your desk shouldn't halt your swarm.

Today, walking away means the work stops. Crux gives every project a standing lead that keeps working the threads all night, and reaches your phone only when the call is yours.

[ sign up ] [ log in ] One operator per account · your threads are yours alone
$ npm install -g @coulb/crux-cli
The crux app on a phone. A lead on the Acme project has written and dry-run a migration, then stopped: filling the new column through Eloquent would fire an observer that mails a receipt to all 12,431 existing customers. It offers two options — skip the observer, or send the receipts — and a box to answer in your own words.
You are at the game. The one thing all night that got through.

One night

18:40 to 06:40, and the laptop is shut for all of it. Five of the six marks below happened without you. The sixth is the one that was allowed to reach your phone.

How it works

01 · Threads in

Work arrives as a thread.

A push from an agent, a note from you, an item the router placed on a project. However it starts, it becomes one thread carrying one state — and the project's lead is already watching for it.

02 · A lead works it

One standing lead per project.

The lead parks on crux tail: no polling loop, no tokens burned on an empty queue. It wakes on real input, reads the thread, and either answers it or spawns a worker to do the code.

03 · Escalation out

It blocks — to your phone.

When the call is yours — scope, money, anything client-facing or irreversible — the lead raises a typed block with crux need. That is the one thing that reaches you. A blocked agent stops loudly rather than guessing.

Every thread carries one state ●Waiting on you ●Working ○Idle

The machine and the pocket

A CLI on your local machine. A phone in your pocket. Everything an agent does to a thread it does through the crux CLI, and almost none of it is any of your business. Here is one night on one project, from both sides.

The iOS app is not in the App Store yet — it goes up when it clears App Review. Until then the pocket half is the web: the same threads and the same blocks, answerable from a phone's browser. The push notification is the app's, and it arrives with it.

21:20 The machine is busy.
lead-acme your machine 
$ crux tail
# one JSON line per event, and nothing at all otherwise.

{"topic":"item.created","id":41,"summary":"multi-currency ships thursday"}

$ crux accept 41
→ #41 is now WORKING

$ crux spawn 41 --project-id 3
→ worker running headless. it cannot finish silently.

{"topic":"activity.created","summary":"dry-run clean, no drift","actor":"thread-41"}

$
21:20
Nothing. A thread woke, a worker ran, a worker reported. Your phone never lit. This is the product working.
23:12 The machine hits a call it will not make.
lead-acme your machine 
$ crux need --item 41 --kind decide \
    "Eloquent would mail a receipt to all 12,431 customers. Skip the observer?"
→ #41 is now WAITING ON YOU — and your phone just buzzed.

$
23:12
cruxnow
Waiting on you

Eloquent would mail a receipt to all 12,431 customers. Skip the observer?

Once. The lead will not spend 12,431 customers' goodwill on its own. You answer from the stands, and the work resumes.
Where it runs

It drops into the terminal you already have open.

crux is not a process supervisor and has no ambition to be one. A lead is started through an adapter, and the default is Solo — the terminal workspace for the long-running processes and agents you already have. crux swarm up spawns one lead per project straight into it: nothing to declare first, no repo paths to write down, and each lead lands as a named pane you can open and read while it works.

Not on Solo? --backend exec takes any command template — tmux, or anything else with a command line. Reconciliation works the same either way, because crux reads the OS process table and never asks a backend whether your fleet is alive.

crux swarm up your machine 
$ crux swarm up
# one standing lead per project. nothing to declare first.

START acme       started   lead-acme    → Solo
START orbit      started   lead-orbit   → Solo
START mercury    started   lead-mercury → Solo

3 started

$

→ Every flag above is one the command will not run without. The rest of them — options, a recommendation, who to ask — are in the CLI reference, and the swarm is in Running a swarm.

The worker contract

A spawned worker runs headless, so its final message is its report and its exit is the reap. A run ends in one of three ways, and finishing quietly is not one of them.

✓ reported

The worker finished. The thread gets its final message, verbatim — that report is the process's own output, not a courtesy it chose to send.

your phone stays dark
✗ died

It crashed, hung, was killed, or ended having printed nothing at all. The thread says so in as many words, instead of waiting forever on an agent that is already gone.

cruxnow
thread-41/supervisor

Worker failed — it exited non-zero.

— cancelled

The lead stopped it on purpose with crux cancel — the brief was wrong, the approach changed. Not a crash, and not reported as one. The thread stays open to re-brief.

your phone stays dark

Mobile control

Blocked

Blocked is a verb, not a vibe.

An agent that needs you raises a typed block, and the type is the whole point: it says what kind of human you have to be for the next thirty seconds. You can answer from a phone without opening a laptop to find out what is even being asked.

--kind decide --kind answer --kind secret --kind desk --kind world
On your phone
Every thread is a chat.
Threads render as conversations, on the web and on your phone. You reply the way you'd reply to a text, and the lead picks it up from there.
Remote Control.
Open a live agent session from your phone and talk to it directly. crux spawn --live hands you the running agent, not a transcript of one.
Nothing else gets through.
Progress lands on the thread quietly. Only an open block — or a worker that died — is worth your phone lighting up.
The swarm The crux inbox on a phone: two threads waiting on you, two being worked, two idle — each tagged with its project and its state.
The swarm at a glance. Every thread you own, under the one state that matters: waiting on you, working, idle.
The block A decide block on a phone: the lead's question, its recommendation, two tappable options, and a free-text box to answer in your own words.
Answer with your thumb. Tap an option, or ignore all of them and say what you want.
The thread A thread on a phone, rendered as a chat: the lead reports what it found and what it fixed; your reply sits on the right.
It reads like a chat. The lead reports, you reply, and it picks the work back up.

Go do something else.

The work carries on without you. You'll hear from it when the call is yours.

[ log in ]