Skip to content
Back to search

worklings

MarketplaceWorks with Claude CodeGitHub

Worklings: Claude Code with an office around it, or an AI studio for any project.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

Its scripts were only partly scanned.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/zeusstudiodev/worklings with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/zeusstudiodev/worklings'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/zeusstudiodev--worklings/badge.svg)](/listings/zeusstudiodev--worklings)

HTML

<a href="/listings/zeusstudiodev--worklings"><img src="/api/listings/zeusstudiodev--worklings/badge.svg" alt="findsafeskills safety rating" /></a>

Install

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 14 lines
  1. {
  2. "name": "worklings",
  3. "description": "Worklings: Claude Code with an office around it, or an AI studio for any project.",
  4. "owner": {
  5. "name": "Zeus Studio"
  6. },
  7. "plugins": [
  8. {
  9. "name": "worklings",
  10. "source": "./plugin",
  11. "description": "Watch, approve and steer your own Claude Code from a 3D office (/worklings:hub), or staff a project with an AI studio."
  12. }
  13. ]
  14. }
README.md · README · 533 lines
  1. <h1 align="center">
  2. <picture>
  3. <source media="(prefers-color-scheme: dark)" srcset="docs/launch/brand/logo-dark.png">
  4. <img alt="Worklings" src="docs/launch/brand/logo-light.png" width="520">
  5. </picture>
  6. </h1>
  7. <p align="center"><strong>Claude Code, with an office around it.</strong></p>
  8. <p align="center">
  9. <a href="docs/launch/film/hero.mp4"><img src="docs/launch/film/teaser.gif" width="720" alt="From the launch film: Claude Code at work in a small CLI's office with two helpers and their cost, its todo list on the task board, and its npm test prompt allowed on a phone. Links to the whole film"></a>
  10. </p>
  11. *Watch [the launch film](docs/launch/film/hero.mp4) (39 seconds): three real Claude Code jobs started from one sentence
  12. each, a small CLI followed from its office to its last words, and its `npm test` prompt answered on a phone. Shots
  13. that run faster than real time say so; [how it was made](docs/launch/film/how-it-was-made.md).*
  14. <p align="center">
  15. <a href="https://www.npmjs.com/package/worklings"><img alt="npm" src="https://img.shields.io/npm/v/worklings"></a>
  16. <a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/github/license/zeusstudiodev/worklings"></a>
  17. <a href="https://github.com/zeusstudiodev/worklings/stargazers"><img alt="Stars" src="https://img.shields.io/github/stars/zeusstudiodev/worklings"></a>
  18. <a href="https://github.com/zeusstudiodev/worklings/actions/workflows/package.yml"><img alt="Package check" src="https://github.com/zeusstudiodev/worklings/actions/workflows/package.yml/badge.svg"></a>
  19. <img alt="Node 22 or later" src="https://img.shields.io/badge/node-%3E%3D22-brightgreen">
  20. </p>
  21. Worklings starts your own, unchanged Claude Code on your words and puts a cozy low-poly 3D office around it: one inbox
  22. for its prompts and questions, budgets, its todo list as a task board and its subagents as helpers with their own cost.
  23. <table>
  24. <tr>
  25. <th width="50%" align="left">Just want to build something?</th>
  26. <th width="50%" align="left">Live in Claude Code already?</th>
  27. </tr>
  28. <tr>
  29. <td valign="top">
  30. 1. Try the [live demo](https://zeusstudiodev.github.io/worklings/): nothing to install.
  31. 2. Add the [plugin](#try-it-in-30-seconds) to Claude Code and run `/worklings:hub`.
  32. 3. Pick a folder and say what you want.
  33. 4. Watch it work. Questions and permission prompts wait in the inbox, on your computer or
  34. [your phone](#phone-access-with-tailscale).
  35. Worklings itself never pushes or deploys. It asks exactly when your Claude Code would.
  36. </td>
  37. <td valign="top">
  38. - **Your `claude`, unchanged:** your CLAUDE.md, skills, hooks, MCP servers and rules.
  39. - **Held to plain `claude -p`** by a [contract test](test/parity-contract.test.ts); the
  40. [parity bench](#is-it-as-good-as-plain-claude-code) found no difference 20 pairs can detect.
  41. - **Budgets** as Claude Code's own `--max-budget-usd`, and each subagent's cost apart.
  42. - **One inbox** for its permission prompts, questions and plan approvals.
  43. - **From a terminal:** `worklings new ./app --prompt "..."` with `--model` and `--effort` ([more](#run-a-job)).
  44. </td>
  45. </tr>
  46. </table>
  47. ## Try it in 30 seconds
  48. You need Node 22 or later. Anything beyond the demo also needs [Claude Code](https://code.claude.com/docs), signed in.
  49. 1. **The live demo, with nothing to install:** <https://zeusstudiodev.github.io/worklings/>. It is a made-up café
  50. company that runs entirely in your browser, with no Claude Code and no server. It is a company of roles, with a CEO
  51. and an org, so it shows the office and its boards rather than a single Claude Code job.
  52. 2. **As a Claude Code plugin:**
  53. ```bash
  54. claude plugin marketplace add zeusstudiodev/worklings
  55. ```
  56. ```bash
  57. claude plugin install worklings@worklings
  58. ```
  59. Then, in Claude Code, `/worklings:hub` opens the lobby.
  60. 3. **From a terminal, with a clone:**
  61. ```bash
  62. git clone https://github.com/zeusstudiodev/worklings.git
  63. cd worklings
  64. npm install
  65. npm run build
  66. node dist/bin.js
  67. ```
  68. This opens the lobby of your companies in your browser, with "Open the demo company" (made up, free) and "Start your
  69. first company". `node dist/bin.js doctor` checks Node, Claude Code and its sign-in, git, the ports and Tailscale, and
  70. gives one plain fix for anything missing. `npm link` once makes it `worklings` anywhere.
  71. When the npm package is out, `npx worklings` does the same with nothing to clone. From a clone, read the
  72. `npx worklings` in the commands below as `node dist/bin.js`, or `worklings` after `npm link`.
  73. The start form asks for a folder, what to build and how the work runs. **One Claude Code session** (the default) starts
  74. at once and takes you straight to the office. **A team (experimental)** takes you to a proposal first. The first time,
  75. the lobby tells you when Claude Code is missing or signed out and what to do (run `claude` once).
  76. ## What the office adds
  77. One company per project. By default it is one unmodified Claude Code session working on your words, and the office
  78. reads what it does from its stream without changing it.
  79. ### Control
  80. - **Pause, resume and stop** a job.
  81. - **Budgets** per job and per portfolio, at API prices. A job's budget becomes Claude Code's own `--max-budget-usd` for
  82. what is left of it, so Claude Code stops there. At 80% the inbox tells you.
  83. - **One inbox** for Claude Code's own permission prompts and for its end-of-turn words: when the session ends a turn,
  84. what it last said (a question, or what it finished) waits there for your reply, which goes back verbatim. The inbox
  85. has a count on every screen, and the feed over the talk bar answers the same items inline.
  86. - **Steering by message:** what you type in the talk bar reaches the session as you typed it.
  87. - **Model, effort and permission mode per job** at the start (`worklings new --model`, `--effort`,
  88. `--permission-mode`); anything you leave out is your Claude Code's own default. Effort can also be changed in the
  89. office, and applies when the desk next opens.
  90. ![A plain job's office: Claude Code at the front desk with a helper writing tests beside it, and its permission prompt to run npm install on the inbox card over the talk bar, with the command one click away and Allow once, Always allow and Deny](docs/images/v3/inbox-approval.png)
  91. ### Organization
  92. - **One company per project,** and one hub on your computer that runs several at once from a lobby.
  93. - **Portfolios** group companies under a name, a shared brief and a shared budget.
  94. - **The studio chat** in the lobby asks and relays across your companies. It cannot write to a plain job: a plain
  95. session hears only your words.
  96. - **Timeline and history** of each job.
  97. ![The demo lobby: made-up jobs and companies as small buildings, each with its state, what waits for you across them, and "Try it: start a project", which replays a recorded run](docs/images/v3/lobby.png)
  98. ### Granularity
  99. Claude Code's own structure, shown in the office:
  100. | Claude Code | In the office |
  101. |---|---|
  102. | The session | The person at the desk |
  103. | Its todo list | The task board, live |
  104. | Subagents | Helpers beside the desk, each with its own cost |
  105. | Tool calls | Desk activity, and the timeline |
  106. | Plan mode | The plan, approved in the inbox |
  107. | Permission prompts and end-of-turn words | The inbox |
  108. The task board shows a todo list only when the model keeps one: Sonnet 5.5 and Haiku 5.5 keep none by default. Plan
  109. first (`--plan-first`) is an extra, off by default: the job starts in Claude Code's own plan mode, and you approve the
  110. plan in the inbox before it builds.
  111. Progress, Spend and Timeline dashboards are built in. The preview runs the project's dev server behind a proxy on its
  112. own port and shows it in a board over the office, full screen or on your phone.
  113. ![The Progress dashboard: tasks done, who is working, who is blocked, what waits for you, the goal's milestones and tasks per room](docs/images/v3/dashboards.png)
  114. Clips: [dashboards](docs/launch/clips/dashboards.mp4) and [the preview](docs/launch/clips/preview.mp4).
  115. ### Fun
  116. The 3D office fills the window, with boards that open over it and shrink it to a live mini-map. On a phone the office
  117. opens first and what needs you sits on one card over the talk bar; `worklings hub --tailnet` puts it on your phone over
  118. [Tailscale](https://tailscale.com/) (see [Phone access](#phone-access-with-tailscale)).
  119. <img src="docs/images/v3/phone.png" alt="The same job on a phone: the office above, and the npm install prompt on the inbox card with Allow once, Always allow and Deny" width="320">
  120. ### What differs from plain Claude Code
  121. One thing a job is refused that Claude Code would allow: **stopping programs machine-wide**, by name, image, pattern or
  122. port lookup. A stop by process id goes through as Claude Code decides. The office's records live in `.worklings/` in
  123. the project, which git ignores; that folder is the one thing a session can see that plain Claude Code wouldn't create.
  124. ## Is it as good as plain Claude Code?
  125. We ran a parity bench: 20 pairs over 10 tasks. Existing code: a bug fix, a feature, a refactor guarded by tests and a
  126. change across several files. New projects: two web apps, a CLI, an API, a game and a data script. Both arms used a
  127. blank Claude Code profile, Sonnet, Claude Code's default effort and the same permission mode.
  128. - **Hidden tests:** level. The Worklings arm's pass rate was 4.7 points higher, all of it from one plain run whose game
  129. could not be served; the interval includes zero.
  130. - **Cost:** 1.01x plain.
  131. - **Extra prompts:** none (0 and 0).
  132. - **A blind pairwise judge** (Opus, both orders) gave the Worklings arm 0.46 on average, where 0.5 is a tie.
  133. - **Time:** median 1.04x per pair. The mean was 1.21x because two Worklings runs hung for five minutes on a test script
  134. the model itself wrote.
  135. This shows no difference that 20 pairs can detect. It doesn't prove the two are equal, and we don't claim Worklings is
  136. better. The launch is also held to plain `claude -p` by a test
  137. ([test/parity-contract.test.ts](test/parity-contract.test.ts)); the differences it allows are listed in
  138. [src/core/plain.ts](src/core/plain.ts).
  139. ## The team (experimental)
  140. Choose "A team (experimental)" in the start form, or `worklings new --team`: a Lead plans, a Builder builds, and a
  141. strict Reviewer checks and sends fixes back. In our tests it cost about twice as much as one session and was not
  142. better. It is there for people who want to try it.
  143. A team starts with a proposal of its org, which you can change before you press **Start the company**. The office asks
  144. "How thorough?" (unanswered, Balanced stands), and the proposal shows what each choice costs an hour and for the job:
  145. | | People | At work at once |
  146. |---|---|---|
  147. | Lean | 2 to 4 | 3 |
  148. | Balanced (default) | 3 to 10 | 5 |
  149. | Thorough | 6 to 25 | 8 |
  150. After Start the plan waits for your approval before work begins. A team keeps the steering of earlier versions: a task
  151. board you can reorder, pause and reassign, a decision log with Undo, a leash per person, messages to anyone with `@`,
  152. the command palette (Ctrl+K), and Open in Claude Code, which hands you a person's session. Finished tasks are committed
  153. to the company's own work branch, and nobody pushes. The team's desks start lean: each loads only the tools, skills and
  154. MCP servers its role was assigned, and the office copies your deny and ask rules, hooks, sandbox and environment into
  155. its settings. Approvals follow the office's own policy: routine work goes on, while pushing, deploying, publishing,
  156. spending money, deleting outside the project, messaging people outside the company and changes to `.claude/`,
  157. `CLAUDE.md` or git config ask you.
  158. ![The team's proposal: the org chart over the office, with its rooms and people, and the summary and the size it chose beside it](docs/images/v3/proposal.png)
  159. ![The Org board of a demo company at work: every person's card says what they are doing and what they have cost, with one person's panel beside it](docs/images/v3/people-at-work.png)
  160. ![The plan on the Tasks board, awaiting approval, with what changed from the previous version](docs/images/v3/plan-approval.png)
  161. Clips: [starting a company](docs/launch/clips/start-company.mp4), [the proposal chart](docs/launch/clips/proposal-chart.mp4),
  162. [people at work](docs/launch/clips/people-at-work.mp4), [the inbox](docs/launch/clips/inbox.mp4),
  163. [steering](docs/launch/clips/steering.mp4) and [talking and relays](docs/launch/clips/talking-and-relays.mp4).
  164. `WORKLINGS_SHAPE` (`plain`, `solo`, `harness`, `classic`) is a developer override for the parked shapes of earlier
  165. versions.
  166. ## How it compares
  167. Each of these is a good project, for a different job. Facts come from each project's own repository, read on
  168. 11 November 2026; star counts and versions move.
  169. | | Worklings | Bot Crossing | Pixel Agents | Claude Squad | Claude Code Game Studios |
  170. |---|---|---|---|---|---|
  171. | What it is | An office around Claude Code: control, organization and a 3D view of each job; also generates a studio for a project | A 3D colony that draws every coding-agent thread on your machine as a bot | An office of pixel-art characters, one per agent terminal | A terminal app that manages several agents, each in its own workspace | A template that turns one Claude Code session into a simulated game studio |
  172. | Runs agents, or only watches | Runs them (your own `claude`, one session per job by default), and watches ordinary sessions | Only watches; it can open a thread in the agent's own app | Launches Claude Code in terminals it hosts, and picks up sessions started elsewhere | Runs them, in tmux sessions on git worktrees | Structures one session's subagents |
  173. | Agents it works with | Claude Code | Claude Code, Codex, OpenCode, Antigravity CLI, Cursor, Hermes, Kilo Code | Claude Code (Codex, Gemini, Cursor and others on its roadmap) | Claude Code, Codex, Gemini, Aider and others | Claude Code |
  174. | What you see | A 3D cut-away office, an inbox, dashboards | A 3D planet, a bot per session | A 2D pixel office with a layout editor | A text interface | A status line |
  175. | Shows cost per agent | Yes, as API-equivalent estimates | Not stated | Not stated | Not stated | Not stated |
  176. | Install | `npx worklings` or the plugin | Clone, `npm install && npm run dev` | VS Code extension, or `npx pixel-agents` | `brew install claude-squad` or an install script; needs tmux | Clone the repository |
  177. | Licence | MIT | MIT | MIT | AGPL-3.0 | MIT |
  178. | GitHub stars | New | 888 | 10,158 | 8,782 | 38,334 |
  179. Where Worklings is behind:
  180. - **It is new,** and it has only been run on Windows. The package check runs on macOS and Linux in CI, but nobody has run
  181. the full suite or a real job there yet.
  182. - **It works with Claude Code only.** Bot Crossing and Claude Squad already work with other tools; Pixel Agents plans to.
  183. - **It needs more setup than Claude Squad or Pixel Agents** for what they do: Worklings runs a hub, and a job needs a
  184. signed-in Claude Code.
  185. If you want parallel agents in a terminal with the least ceremony, [Claude Squad](https://github.com/smtg-ai/claude-squad)
  186. fits better. Game Studios' README says its heavier process tier "costs more to reach working code without producing a
  187. better result"; our own benches agree, which is why a Worklings job is one session by default.
  188. Sources, all read on 11 November 2026:
  189. [Bot Crossing](https://github.com/Station-Sciences/bot-crossing),
  190. [Pixel Agents](https://github.com/pixel-agents-hq/pixel-agents),
  191. [Claude Squad](https://github.com/smtg-ai/claude-squad),
  192. [Claude Code Game Studios](https://github.com/Donchitos/Claude-Code-Game-Studios).
  193. ## FAQ
  194. ### Costs and plan limits
  195. **What does a job cost?** What the same Claude Code session would cost: in the parity bench, 1.01x plain. Spend shows
  196. what the session and each helper used. A team costs more (about twice one session in our tests), and its proposal shows
  197. an hour's cost on your plan before you start. [Measuring a run](#measuring-a-run) says where a run's tokens went.
  198. **Will it use up my Pro or Max plan?** A job is one Claude Code session on your plan, plus the subagents it starts
  199. itself. Several jobs at once, or a team (3, 5 or 8 people at work at once on Lean, Balanced or Thorough), use your
  200. limits faster. Anthropic says plan limits assume ordinary,
  201. individual use. Set a budget to hold a job back before your plan's own limit. When Claude Code reports a limit or
  202. overload, the hub rests every company until the reset time it gives ("Resting until 14:00"), without retry loops, and
  203. work resumes by itself.
  204. **Are the dollar figures a bill?** Not on a subscription. They are what the same tokens would cost on the Claude API at
  205. list prices, with the price date next to the figure. If your own Claude Code uses an API key, or its OpenTelemetry
  206. export points at the office ([how](docs/architecture.md#exact-cost-with-opentelemetry)), they are what was billed.
  207. **Does Worklings cost money?** No. It is MIT licensed, has no account or paid tier, and holds no API key.
  208. ### Terms
  209. **Is this allowed by Anthropic's terms?** Worklings is built to stay on the end-user side of them. See
  210. [Terms and publishing](#terms-and-publishing). It is a summary, not legal advice.
  211. ### Privacy
  212. **What leaves my computer?** Nothing of Worklings' own: it has no analytics, account or update check, and the hub and
  213. the office listen on `127.0.0.1` and refuse requests from other sites. The one outward path is your own Claude Code,
  214. which talks to Anthropic as it always does. Catch me up and Ask aside run your Claude Code once per press (Haiku by
  215. default) with no tools, no MCP servers and no hooks, so a trimmed excerpt of the session with credentials masked goes to
  216. Anthropic like any Claude Code request. The demo calls nothing.
  217. **What does it write?** `.worklings/` in a company's folder (git ignores it: the signed event log, the state and shared
  218. screenshots); `~/.worklings/` (the hub's registry, the access token, the key that signs each log, portfolios and the
  219. studio chat); and, only for a studio or a team and only when you confirm, files in the project's `.claude/` and
  220. `CLAUDE.md`. A plain job writes nothing in the project besides `.worklings/`. Hooks for watching ordinary sessions, if
  221. you install them, live in `.claude/settings.local.json`, which stays out of git; `worklings hooks uninstall` removes them.
  222. **Does it push my code?** A plain job asks exactly when your Claude Code would, so a push follows your own permission
  223. rules, and its prompt comes to the inbox. A team commits finished tasks to its own work branch, and pushing always asks.
  224. **Are the sessions sandboxed?** No. See [How much to trust a job](#how-much-to-trust-a-job).
  225. ### Windows, macOS and Linux
  226. Worklings was built and tested on Windows 11 with Claude Code 2.1.312 and Node 24. Node 22 or later is required. The code
  227. has macOS and Linux paths (opening the browser, finding `claude`, stopping process groups), and CI packs the package and
  228. runs `npx` on Windows, macOS and Linux. **Nobody has run the full test suite or a real job on macOS or Linux yet**:
  229. please report problems as bugs. If Worklings can't find `claude`, set `WORKLINGS_CLAUDE` to its full path.
  230. ### Codex later
  231. Not today: Worklings runs Claude Code only. The code that starts, feeds, interrupts and closes a session sits behind a
  232. small interface (`src/runtime/harness.ts`) with Claude Code as its one implementation, so another tool could be added
  233. without rewriting the company. It has no date; see [ROADMAP.md](ROADMAP.md).
  234. ## Run a job
  235. From the lobby, pick or create a folder and say what to build. Or from a terminal (the folder can be new or empty):
  236. ```bash
  237. npx worklings new ./plant-pal --prompt "A plant-care app with watering streaks"
  238. ```
  239. Add `--model`, `--effort` or `--permission-mode` (`acceptEdits`, `auto`, `bypassPermissions`, `manual`, `dontAsk`) for
  240. this job, `--plan-first` to start in plan mode, or `--team` for the experimental team. If a hub is running, the job
  241. starts there; if not, one starts for it. The hub listens on `127.0.0.1:7430` unless you pass `--port`, and prints a link
  242. with an access token (kept in `~/.worklings/token`). A folder that already has a company reopens it. Stop the hub, which
  243. closes every desk first, with `npx worklings hub --stop`; when it opens again, desks pick up where they stopped.
  244. ### Phone access with Tailscale
  245. ```bash
  246. npx worklings hub --tailnet
  247. ```
  248. This serves the hub through `tailscale serve` on your computer's `ts.net` name, over HTTPS, to your tailnet only. It
  249. never uses Tailscale Funnel, so nothing is on the public internet, and every request needs the token in the link it
  250. prints. Treat that link as a password. Set up once, by you:
  251. - Install Tailscale (1.52 or later) on the computer and on the phone, and sign in to the same tailnet on both.
  252. - In the Tailscale admin console's DNS page, turn on MagicDNS and HTTPS certificates. Without them Worklings says so
  253. and stops.
  254. - Open the printed `https://<name>.ts.net/?token=...` link on the phone.
  255. `WORKLINGS_TAILSCALE` names the Tailscale program when it is not on your path. This has been tested against a fake
  256. `tailscale` only; the real check on a computer and a phone has not been done yet.
  257. ### How much to trust a job
  258. A job is your own Claude Code with your authority, your permission mode and your rules, as if you ran it yourself. The
  259. office asks exactly when Claude Code would ask and decides none of those prompts itself; it refuses only machine-wide
  260. stops. It does not make Worklings a sandbox: code a session writes and then runs runs as you and can reach whatever you
  261. can, including the office's token for that desk. Run jobs on projects whose content you trust, as you would Claude Code.
  262. A team's desks follow the office's own approvals policy instead (see [The team](#the-team-experimental)): a person may
  263. stop a program their own desk started by its process id; an MCP server's first use asks; a desk that comes up with MCP
  264. tools nobody assigned is stopped; and what a role loads counts only when it matches what you approved at the start, so
  265. a pull request that edits `.claude/studio.yaml` can't give a role more. In every company, messages reach sessions as
  266. fenced user turns, and the log is signed, so editing `.worklings/` can't forge a message from you.
  267. ## Kinds of project
  268. `worklings new` (without `--prompt`) writes a studio: a team of Claude Code subagents, path-scoped rules, workflow
  269. skills and review gates for a project, as ordinary files in `.claude/`. It detects the kind of project from your
  270. dependencies and files, or you pick one with `--domain`. Each comes in three sizes: `lean` (the default), `standard`
  271. and `full`.
  272. | Domain | Kind of project | Lean team |
  273. |---|---|---|
  274. | `ai-app` | AI app | `ai-engineer`, `ux-designer`, `qa-engineer`, `security-reviewer` |
  275. | `api-service` | API service | `backend-engineer`, `code-reviewer`, `qa-engineer`, `security-reviewer` |
  276. | `automation` | Automation | `automation-engineer`, `qa-engineer`, `code-reviewer` |
  277. | `browser-extension` | Browser extension | `extension-engineer`, `ux-designer`, `qa-engineer`, `security-reviewer` |
  278. | `cli-library` | CLI or library | `library-engineer`, `code-reviewer`, `qa-engineer`, `docs-writer` |
  279. | `data-ml` | Data and ML | `ml-engineer`, `data-engineer`, `code-reviewer`, `qa-engineer` |
  280. | `desktop-app` | Desktop app | `desktop-engineer`, `ux-designer`, `qa-engineer`, `security-reviewer` |
  281. | `engine-game` | Engine game | `engine-specialist`, `game-designer`, `art-director`, `qa-engineer` |
  282. | `generic` | Software project | `architect`, `code-reviewer`, `qa-engineer` |
  283. | `mobile-app` | Mobile app | `mobile-engineer`, `ux-designer`, `qa-engineer` |
  284. | `web-app` | Web app | `frontend-engineer`, `backend-engineer`, `ux-designer`, `qa-engineer` |
  285. | `web-game` | Web game | `game-programmer`, `game-designer`, `art-director`, `qa-engineer` |
  286. | `website` | Website | `frontend-engineer`, `ui-designer`, `copywriter`, `seo-specialist` |
  287. The library behind them has 44 roles, 24 stack rules, 8 workflows and 8 review gates, all plain Markdown and YAML in
  288. [`library/`](library/README.md). A studio is ordinary Claude Code configuration: agents in `.claude/agents/`, rules in
  289. `.claude/rules/`, skills in `.claude/skills/`, a short section in `CLAUDE.md`, and `.claude/studio.yaml`, which says
  290. which room everyone sits in. Delete Worklings tomorrow and the studio keeps working. Already have agents? `worklings
  291. adopt` sorts them into rooms.
  292. ## The office that watches a project
  293. Run Claude Code in a project as usual and `worklings office` shows it as a 3D office: people light up while their agent
  294. works, bubbles say the outcome ("Needs your OK to run npm install", "Stuck for 2 min"), and Now, Team, Payroll and Story
  295. panels say what is going on and what it costs. **Catch me up** writes a few plain sentences on what happened since you
  296. last looked. **Ask aside** opens a conversation with any person ("What are you working on?"), answered in the first
  297. person without interrupting a live lead. `worklings replay` plays a recorded session back.
  298. Install the hooks the office reads (it asks first, and `worklings hooks uninstall` removes them):
  299. ```bash
  300. npx worklings hooks install
  301. ```
  302. ```bash
  303. npx worklings office
  304. ```
  305. The office reads Claude Code's hook events and the session transcripts on your machine, listens on `127.0.0.1` only
  306. (port 7421) and shows your prompts and costs only to the link it prints. `--lan` lets a phone on your network watch over
  307. plain HTTP, so use it on a network you trust.
  308. ## Commands
  309. | Command | What it does |
  310. |---|---|
  311. | `worklings` | Open the hub's lobby: your companies, the demo company and a new company (port 7430; `--port`, `--tailnet`, `--no-open`) |
  312. | `worklings hub [--stop]` | The same; `--stop` stops the hub and closes every desk first |
  313. | `worklings demo` | The demo company, made up, with no Claude Code (port 7420; `--port`) |
  314. | `worklings doctor` | Check Node, Claude Code and its sign-in, git, the hub's ports and Tailscale |
  315. | `worklings new [dir] --prompt <text>` | Start a job: Claude Code works on your words as you wrote them (`--model`, `--effort`, `--permission-mode`, `--plan-first`, `--team`) |
  316. | `worklings new [dir]` | Write a studio (`--domain`, `--rigor`, `--idea`, `--stack`, `--add`, `--remove`, `--dry-run`, `--force`, `--offline`) |
  317. | `worklings office [dir]` | Watch a project's Claude Code sessions (port 7421; `--yes`, `--lan`, `--no-open`) |
  318. | `worklings detect [dir]` | Show the detected stack, commands and kinds of project |
  319. | `worklings domains` | List the kinds of project and their lean teams |
  320. | `worklings adopt [dir]` | Sort existing agents into rooms (`--write` saves studio.yaml) |
  321. | `worklings tailor <role> --note <text>` | Add project notes to a role |
  322. | `worklings hire`, `fire`, `rehire <role>` | Change the studio's team |
  323. | `worklings move <role> <room>`, `model <role> <model>` | Reseat a role, or change the model it runs on |
  324. | `worklings hooks install`, `status`, `uninstall` | Live events for the office |
  325. | `worklings replay [dir]` | Replay a recorded session (`--session`, `--speed`) |
  326. | `worklings lint-library` | Check a library folder against the writing bar |
  327. Add `--json` to `new`, `detect`, `domains`, `adopt`, `hooks` and `doctor` for machine-readable output. The plugin adds
  328. `/worklings:hub`, `/worklings:new`, `/worklings:office`, `/worklings:hire`, `/worklings:fire` and `/worklings:adopt`.
  329. ## How it works
  330. The hub runs each job as your own `claude -p` with stream-json on stdin and stdout (a "desk"), and keeps the company's
  331. state in `.worklings/`. A plain desk's launch is plain `claude -p` with your choices for the job plus only the allowed
  332. differences in [src/core/plain.ts](src/core/plain.ts): the stream-json and verbose flags the office reads, a session id
  333. so the job can be resumed, the budget cap, and one `--settings` holding the office's hooks. Those hooks send Claude
  334. Code's own permission prompts to the inbox, tell the office when a turn or a subagent ends, and refuse a machine-wide
  335. stop. The office reads the todo list, subagents and tool calls from the stream and prices each request from its usage.
  336. A team adds org tools served over MCP on `127.0.0.1` (post a status, report, message, ask, assign) and lean desks, which
  337. start with only the project's and local settings and copy the parts of your user settings that protect you; if anything
  338. can't be carried in full, that desk starts with your whole setup and the log says why. The office that watches a project
  339. reads Claude Code's `http` hooks and transcripts. The browser gets a snapshot of the building over Server-Sent Events and
  340. draws it with React Three Fiber.
  341. [docs/architecture.md](docs/architecture.md) has the module map, and
  342. [docs/claude-code-surfaces.md](docs/claude-code-surfaces.md) lists exactly what Worklings reads from Claude Code and how
  343. that was checked. Tested with Claude Code 2.1.312 on Windows. The stream-json and MCP protocols and the transcript format
  344. are internal to Claude Code and can change; they are pinned by recorded fixtures, and the parser skips what it doesn't
  345. understand instead of failing.
  346. ## Terms and publishing
  347. Worklings is built to stay inside Anthropic's terms for Claude Code by design:
  348. - It starts **your own, unmodified `claude`** on your own computer and talks to it through Claude Code's own headless
  349. mode (`claude -p`, with stream-json in and out).
  350. - **Sign-in stays with Anthropic.** You sign in to Claude Code yourself, through Anthropic's own flow. Worklings never
  351. asks for, reads, stores or logs your sign-in or any credential: it starts your `claude` with your own environment,
  352. and `claude` signs itself in as it always does.
  353. - It does **not use the Claude Agent SDK**, runs **no hosted service**, and does **not resell, pay for or intermediate**
  354. anyone's usage. Each person runs it on their own machine, on their own plan or API key.
  355. - "Claude Code" appears only to say what Worklings works with, never in its name. Worklings is not made by,
  356. endorsed by or partnered with Anthropic.
  357. - **API-key mode** is there if you prefer per-token billing: when your own Claude Code is signed in with an API key,
  358. desks use it and the office shows what was billed.
  359. What the terms allow, from Anthropic's
  360. [legal and compliance page](https://code.claude.com/docs/en/legal-and-compliance.md) (read on 5 November 2026):
  361. - Third-party developers may not offer Claude.ai login in their own apps, route requests through plan credentials on
  362. behalf of their users, or collect, store or intermediate Claude.ai credentials. Products built on Claude should use
  363. API-key authentication.
  364. - The same page says that does not prevent an end user from "signing in to the unmodified Claude Code binary with
  365. their own Claude subscription". That is the route Worklings takes.
  366. - Anthropic says the advertised limits of its Pro, Max and Ultra plans assume ordinary, individual use of Claude Code.
  367. **Heavy parallel use counts against your own plan limits.** Each job is a Claude Code session on your plan or key, and a
  368. team has up to 5 people working at once (Balanced; 3 on Lean, 8 on Thorough). More at once is faster and uses your
  369. limits faster. When Claude Code reports a limit, the hub rests every company until the reset time it gives.
  370. This is a plain-words summary of the terms as they stood on that date, not legal advice. They can change, so read the
  371. page yourself.
  372. ## Measuring a run
  373. `scripts/accounting.ts` says where a company run's tokens went. It reads the company's records and the Claude Code
  374. transcripts in `~/.claude/projects`, makes no model calls and writes nothing:
  375. ```bash
  376. node scripts/accounting.ts <company folder> [--projects <claude projects dir>] [--json]
  377. ```
  378. The folder is a project with a `.worklings/` in it, or a run folder that holds one in `project/`. With several folders it
  379. prints each run and then a summary: the dollars by what they paid for, by person, by what began each turn and what it
  380. did, each desk's fixed first request, how the context grew and the costliest turns. `--json` prints the same as data.
  381. Point it only at runs you trust: it reads the company's log without checking its signatures.
  382. ## What is not finished
  383. - **Phone access** over Tailscale has been tested against a fake `tailscale`, not on a real tailnet and phone.
  384. - **macOS and Linux** have not run the full tests or a real job; Windows is where Worklings was built.
  385. - **Sessions are not sandboxed** (see above), and Claude Code is the only agent tool supported.
  386. - **The team** is an experiment that has not beaten one session.
  387. - The version is 0.2.0. Claude Code's internal protocols can change under it.
  388. [ROADMAP.md](ROADMAP.md) has what comes next and what Worklings will not do.
  389. ## Contributing
  390. New roles, rules and kinds of project need no code: see [CONTRIBUTING.md](CONTRIBUTING.md) and
  391. [library/README.md](library/README.md). Please follow the [Code of Conduct](CODE_OF_CONDUCT.md), report security problems
  392. through [SECURITY.md](SECURITY.md), and see [ROADMAP.md](ROADMAP.md) for what is planned.
  393. [docs/launch/good-first-issues.md](docs/launch/good-first-issues.md) lists small first tasks. To run it from a clone:
  394. ```bash
  395. npm install
  396. npm run build
  397. node dist/bin.js doctor
  398. ```
  399. The changelog, including the project's earlier name (Headcount), is in [CHANGELOG.md](CHANGELOG.md). The art packs are
  400. credited in [CREDITS.md](CREDITS.md).
  401. ## License
  402. [MIT](LICENSE)
  403. Made by [Zeus Studio](https://zeusstudio.dev) ([legal details](https://zeusstudio.dev/legal/)).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.