run-things

Run your coding agents in the cloud, not on your laptop.

Kick off five of them, close the lid, walk away. They keep going. Reattach from anywhere and pick up exactly where it was, and every session you've ever run stays searchable.

npm install -g run-things

Both install a things command (and run-things as an alias, if things is already taken on your machine).

Usage

things claude [args…]          run Claude Code locally, visible in your inbox
things remote [id] [--force]   teleport a local session into a cloud sandbox
things pull <id> [--fork]      bring a teleported session back down
things login [token]           use your own Claude subscription in sessions
things new --repo <url> --task <text> [--agent claude|shell] [--detach]
things ls                      the session inbox (enter attaches, q quits)
things attach <id>             stream a session (ctrl-] detaches)
things search <query>          across every session ever run
things kill <id>               stop a session and destroy its sandbox

Start local, escalate to the cloud

things claude runs the real Claude Code on your machine — same TUI, same speed, your own credentials. things watches from the side: the session shows up in things ls, its conversation is searchable, and the inbox knows when it's blocked on a permission prompt (needs_input) or waiting on you (idle).

When you need to leave, ctrl-C out — it prints both roads back:

  resume locally:  claude --resume 6257f5bd-…
  resume remotely: things remote 6257f5bd

things remote moves the conversation into a cloud sandbox and drops you into it, exactly where you left off. Detach with ctrl-], close the laptop, go to the meeting — the agent keeps working. Later:

things ls              # who's blocked, who's done
things attach 6257f5bd # answer it from anywhere
things pull 6257f5bd   # bring the conversation home again

pull refuses if the conversation also advanced locally in the meantime — --fork keeps both as separate sessions.

Teleporting uses your own Claude subscription. Set it up once:

claude setup-token | things login

(things claude offers to do this for you on first run.)

Or start in the cloud

things new --repo https://github.com/you/your-repo --task "fix the failing migration test"

Session ids are shown truncated, and any unambiguous prefix works — either things' own id or Claude Code's session uuid.

Recording

Sessions run through things claude stream their conversation (prompts, replies, tool calls) to your control plane so search and the inbox work. Credential-shaped strings are redacted before anything leaves your machine. Set THINGS_RECORD=metadata to record activity without content — the inbox still works, search won't.

Configuration

| Variable | Default | Meaning | |---|---|---| | THINGS_URL | https://api.things.dev | The control plane this client talks to |

The CLI holds no state of its own. Everything it shows is replayed from the control plane, so if it crashes — or you close the laptop — nothing is lost and the session keeps running.

Out of the box the client talks to https://api.things.dev. Point THINGS_URL somewhere else to run against a local control plane or your own deployment:

export THINGS_URL=http://localhost:3000     # a control plane you're running
export THINGS_URL=https://things.internal   # your own deployment

Requirements

Node.js 22 or newer (it relies on the built-in WebSocket and fetch). The published package is a single dependency-free bundle. attach and the ls inbox need a real TTY; when piped, ls degrades to plain text and attach exits with an error.

Status

Early. The wire protocol and command surface are still moving, and releases before 1.0 may break them. See docs/things.md for the design.

License

MIT © Shane Neubauer