Skip to content

Guides

Run the factory from Claude Code

The Orkastery mods in Claude Code: what exists today, how to load them and what is still planned.

What exists today

RM-059 aims to let you run the factory from inside the Claude Code session you already work in, through mods: Claude Code function-hook plugins that run inside the client, react to session events and draw panels, bars and notices. In version 0.6.10, all ten planned mods exist, plus the bridge:

  • The bridge (ork-ponte), which the other mods build on: it gives each one the session role (dono for the owner’s session, fase for phase sessions, or dormente), the core snapshot through ork_maestro, the bar above the prompt and the record of what a mod showed the owner. It has both the dono and fase roles.
  • The Control Tower (ork-torre): in the owner’s session, a panel with one line per open thread, showing the six-phase track, the mode, who is running it and since when, the typed blocker in a short sentence, requests to the owner and the action the thread’s state calls for. The /torre command opens the panel, and pressing a line opens the thread’s detail. It depends on the bridge and has only the dono role.
  • The Quota Weather (ork-clima): in the owner’s session, it reads the account’s limit windows at each engine measurement (session.measure), keeps the series and predicts when each window runs out at the current pace. Only on an alert, the bridge’s bar says which queued resume will not fit before the window runs out, how much of the window is used, when it runs out and when it resets; the /clima command shows each window, the resume queue, the open threads stopped by quota and the accounts in the ork accounts esgotamentos record. It only reads and warns: switching account, runtime or model stays with the core and the owner. It also depends on the bridge and has only the dono role.
  • The Batch Brake (ork-freio), the first mod with the fase role: in a phase session, after each batch of tool calls, it finds the files the batch touched (from the edit paths and the git status difference, which also catches edits made through Bash) and the thread’s claims that cite them, asks the core in the background to check them with ork claims conferir, in the verify sandbox, and returns what broke in the next batch: the claim id, the command and the end of the output. It also warns when the batch touched files outside the plan’s touch_paths. It reaches phase sessions on its own through the dispatch, with the adapter installed (ork adapter install claude-code), and needs an ork with ork claims conferir on the session’s PATH: without it, it warns once that checking is unavailable and goes on. It also depends on the bridge.
  • The Collision Radar (ork-radar): in the owner’s session, every 10 minutes and with the /radar command, it computes the merge of each open thread against the local origin/main and between threads, before SHIP, without a worktree and without writing objects to the repository (through git merge-tree --write-tree in a temporary directory). The panel shows the heat map, the conflicting files, the lease that covers each one and, as text, the ork worktree sync <thread> --dry-run command that resolves it; a new collision becomes a line in the bridge’s bar. Fetching stays with the core. It only reads, depends on the bridge and has only the dono role.
  • The Owner’s Desk (ork-mesa): in the owner’s session, it gathers in one panel what is waiting for you. The /mesa command opens the batch of up to five questions, each with the recommended alternative first, the reason and the consequence of the others; the decisions the factory made for you during the week, with how to change them and the cost of reverting now and later; and the stopped items, read-only. The Decide button only asks the core for the host’s native dialog (ork_request_decision, with the threadId and the pedidoId), and the code and letter for Telegram always stay in view; the proof that the dialog opens when the request comes from a mod is still pending from the owner. The Owner’s Desk only decides for you through the core’s autonomous decision (ork_decision_record), and only when the request declares that it follows the recommended one at the deadline and passes the core’s four conditions; today the core marks no request that way, so it decides nothing on its own. It never answers a request. It depends on the bridge and has only the dono role.
  • The Conductor’s Sentinel (ork-sentinela): in the owner’s session, it keeps its presence on this machine through the core, with a heartbeat every 60 s, and removes it when the session ends; while the presence holds, the external conductor yields dispatch. When a thread ledger changes, and at each heartbeat, it rereads the conductor’s next step for each open thread and dispatches the next phase of the #Auto threads the core says to dispatch, once per turn and only through ork phase run; a resume only runs ork retry run when ork retry plan is automatic. Every 5 minutes, what only the owner can resolve in ork pulse becomes a system notification with the core’s next step, once per text, and goes into the bridge’s record so that Telegram does not repeat it. The bridge’s bar shows the threads that are moving and the stopped ones, and the /sentinela command shows each thread’s step and the journal of what it dispatched, yielded and warned about, and also pauses and resumes the Sentinel. It depends on the bridge and has only the dono role.
  • The Task Gate (ork-portao), the second mod with the fase role: in the GO phase session, it turns Claude Code’s task board into the plan’s board. A task only enters when it points to a plan task with touch_paths and verify, and only closes when the core’s check passes (ork claims conferir --tarefa, in the verify sandbox), never with a verify run by the mod; a plan without such tasks gets no gate. With runtime.agent_teams turned on in the manifest, off by default, an idle teammate receives the next task whose region is free, within the owner’s caps, and the Task Gate takes no lease. It depends on the bridge.
  • The Delivery Track (ork-pista): in the owner’s session, the /pista command opens one track per delivery, from a green CHECK to the merge, with the eight steps the core reads (CHECK, verify, bundle, branch, PR, CI, conflict and delivery), the core’s text for each missing one and the next step with its command. It only shows a button for an action the core declares available: publishing the branch through ork ship publicar, only in #Auto and #Maestro, and recording the delivery through ork ship registrar-pr; outside those modes, only the command, for you to run. It never calls Git or the GitHub CLI. It depends on the bridge and has only the dono role.
  • The MASTER Ritual (ork-ritual): in the owner’s session, the /nota command shows the deliveries of the last 7 days that await your score, including those accepted by omission, with each one’s proof: the index derived from the ledger, the POSTMORTEM and the claims. The Give score button asks the core for the host’s native form, with a score from 0 to 5 and the reason, and the core is what records the MASTER, with a receipt; without the dialog, the code for Telegram stays in view. It depends on the bridge and has only the dono role.
  • The Session Messenger (ork-mensageiro), with the dono and fase roles: the answer you give through your session’s native dialog reaches the claude-bg phase session that stopped waiting for it, without you having to attach to it. The core ties the request to the turn that stopped and checks the message at both ends, and only what it confirms enters the phase session. The answer informs the session, but does not authorize what only you approve, such as a gate or a push, and it does not go out through Telegram.

Load them into your session

The Tower, the Quota Weather, the Collision Radar, the Owner’s Desk, the Sentinel, the Delivery Track and the MASTER Ritual only turn on in the owner’s session, and the Session Messenger turns on there and in phase sessions (the Batch Brake and the Task Gate, phase-session mods, reach phase sessions through the dispatch), which the bridge recognizes by two things: orkastery.yaml at the root and the project’s orkastery MCP server being connected. The commands below come in three groups: the project’s MCP server; the Claude Code adapter, which puts each mod’s copy in .claude/plugins/orkastery/mods/<mod>, and loading them into the session with --plugin-dir; and, without the local adapter, installing from the repository’s marketplace at project scope. The Sentinel’s commands are in the next section.

The mods API needs Claude Code 2.1.287 or newer. In CI, the mods job installs Claude Code 2.1.296, validates and tests each mod and searches the binary for every event they use; in that search, builds 2.1.288 and 2.1.289 fail, lacking ui.notify.

Both marketplaces are named orkastery, and the local one, registered from .claude/plugins/orkastery when the adapter is activated, does not list the mods. Do not swap one for the other in a project that uses the adapter’s plugin: removing a marketplace uninstalls the plugins that came from it, and the plugin from the repository’s marketplace does not include the adapter’s PreToolUse guard or MCP server.

ork mcp install --project "$PWD" --host claude-code

ork adapter install claude-code
claude --plugin-dir .claude/plugins/orkastery/mods/ork-ponte --plugin-dir .claude/plugins/orkastery/mods/ork-torre --plugin-dir .claude/plugins/orkastery/mods/ork-clima --plugin-dir .claude/plugins/orkastery/mods/ork-radar --plugin-dir .claude/plugins/orkastery/mods/ork-mesa --plugin-dir .claude/plugins/orkastery/mods/ork-pista --plugin-dir .claude/plugins/orkastery/mods/ork-ritual --plugin-dir .claude/plugins/orkastery/mods/ork-mensageiro

claude plugin marketplace add orkastery/orkastery
claude plugin install ork-ponte@orkastery --scope project
claude plugin install ork-torre@orkastery --scope project
claude plugin install ork-clima@orkastery --scope project
claude plugin install ork-radar@orkastery --scope project
claude plugin install ork-mesa@orkastery --scope project
claude plugin install ork-pista@orkastery --scope project
claude plugin install ork-ritual@orkastery --scope project
claude plugin install ork-mensageiro@orkastery --scope project

Let the Sentinel dispatch

With your session open in Claude Code and the Sentinel on and not paused, the Sentinel dispatches the next phase of the #Auto threads and retries them, and the external conductor (for example, a cron job on the Hermes gateway) yields. With the Sentinel paused, or with the session closed (the presence expires 3 minutes after the last heartbeat), the external conductor takes over again. In version 0.6.10, ork's own external conductor is the conduction beat (ork conducao batida): it reads the presence and yields dispatch and retry while the Sentinel conducts, except the resume of a phase stopped by quota, which stays with the beat because the Sentinel's account can run out too. It goes on with merging the green PR, recording the delivery and the MASTER by omission, within the owner's durable authorization; with it in cron, the outside script is no longer needed. Publishing the branch, merging the green PR and the Telegram notices always stay with the external conductor: the Sentinel does not publish branches, does not open or merge PRs and does not send Telegram messages.

It uses the core’s presence commands, in version 0.6.10, and it loads together with the bridge, from the adapter folder or from the repository’s marketplace, as in the block below. The external conductor’s script lives outside the repository, and the change to it is yours: once per round, before the dispatch loop, it reads the Sentinel status with --json and, while presenca.ativa is true, skips dispatching the next phase and ork retry run for the #Auto threads. Publishing a branch that only awaits a push, merging the green PR and the notices to the owner stay as they are; with no live presence, the external conductor runs as before.

There is no duplicate dispatch, because both conductors dispatch only through the core: ork phase run takes the thread’s conduction under a kernel lock. With two requests at the same instant, one dispatches and the other exits without a new session; with the thread already being conducted, the request exits with code 3, conducao.em-andamento, and records conducao_recusada; and the same request from whoever is already conducting records despacho_idempotente and returns the session in progress. The Sentinel also rereads the conduction right before dispatching, never uses ork conducao assumir and remembers the turn it has already dispatched. Its dispatch carries the Claude Code channel and its session in the correlation, and phase_dispatch shows where it came from.

The Sentinel does not choose the phase: it follows the action the core gives each thread in the status. In #Auto, after a completed phase, what goes out is the phase after the most advanced proof the block’s session left: the phase artifact (goal.md, plan.md, check.md) written after the dispatch, the product on the branch, which shows there was a GO, or ship_done and master_done. If the block is already past CHECK, nothing goes out: delivery stays with the external conductor and the owner. A CHECK that ended without exactly one verdict is dispatched again, and a dispatch that failed before opening a session goes to ork retry plan. Anything pending with the owner (a thread at a HITL point, an open question, an escalation) holds every step and, without a request stored when the thread was created (ork thread new --pedido), the Sentinel does not dispatch and warns.

A passing refusal (another conductor, no free slot in the project, an open request, a failure) does not burn the turn: the Sentinel tries again after 3 minutes, and the same refusal in a row doubles the wait up to 30 minutes; only a completed dispatch, or the repeated request of whoever is already conducting, is final. If your external conductor dispatches from the last line of the ledger, it may repeat a phase the block’s session already did; reading each thread’s action in the same status avoids that.

To check, the Sentinel status says whether it is active on this machine and each thread’s step, ork phase list <thread> shows the dispatch with the Claude Code channel and, in the owner’s session, /sentinela shows the journal; the last two lines of the block pause and resume the Sentinel.

claude --plugin-dir .claude/plugins/orkastery/mods/ork-ponte --plugin-dir .claude/plugins/orkastery/mods/ork-sentinela
claude plugin install ork-sentinela@orkastery --scope project

ork conducao sentinela status
ork phase list <thread>

/sentinela
/sentinela pausar
/sentinela retomar

In phase sessions

The claude-bg dispatch passes one --plugin-dir per mod with the fase role, after the Orkastery plugin, when the mod’s installed folder has exactly the files in INSTALADO.json and the Claude Code version meets the mod’s minimum. A mod that needs a newer version is left out, along with the mods that depend on it, and the dispatch goes on; an extra file, a link or an invalid declaration refuses the dispatch with runtime.context.installation. Today the bridge, the Batch Brake, the Task Gate and the Session Messenger have the fase role. The role lives in the mod’s orkastery-mod.json (ork.mod/v1): to take a mod out of phase sessions, change its role in the catalog and reinstall the adapter.

The RM-059 proof measured, on Claude Code 2.1.296, that a mod loaded with --plugin-dir in a phase session receives the session’s events; the core/scripts/prova-mods-sessao-de-fase.cjs script repeats that proof.

The mods foundation also brings two core pieces. ork claims conferir reruns, in the ork_verify sandbox and without recording a receipt, only the requested claims (--claims) or the verify of one plan task (--tarefa); a test that spawns a process may fail there and pass in ork verify. ork thread new --pedido stores the thread’s request in pedido.md, with its sha256, and ork prompt render without --pedido uses that request.

What no mod does

No mod approves a gate, permission, MASTER score, push or tag on the owner’s behalf, or speaks as the owner. The rule lives in adapters/claude-code/mods/autoridade.json and has two guards: node core/scripts/checar-mods.cjs fails a mod from its source, and the bridge refuses at run time. The Batch Brake never runs a claim’s command, never records claim state and never stops the loop: ork verify is still the one that verifies. The Sentinel reads only through the core, dispatches and resumes only through ork phase run and ork retry run, and never uses ork conducao assumir. The Tower, the Quota Weather and the Collision Radar only read, and the Owner’s Desk only asks the core for the dialog and never answers a request: an action with an effect opens the mod that owns it, when that mod is loaded, or shows up as a command for you to run with ork.

Mods run with your user’s permissions, without a sandbox, and the Claude Code mods API is in early access and may change between versions. Nothing in the core depends on them: without mods, dispatch and the cycle go on as before, and Telegram remains a channel.

What comes next

In version 0.6.10, the four RM-059 waves are in the code: wave 0, the foundation described above; wave 1, with the Control Tower, the Quota Weather, the Batch Brake and the Collision Radar; wave 2, with the Owner’s Desk and the Conductor’s Sentinel; and wave 3, with the Delivery Track, the MASTER Ritual, the Session Messenger and the Task Gate. The item is still in development, with partial exposure and enablement in progress, and the proofs that need the owner, such as the dialog opened at a mod’s request, stay with the owner.