Skip to content
  1. fael.tech
  2. Studies
  3. Demerzel

Demerzel.

How each unit of a Radiant contract becomes a Claude Code or Codex session in herdr, without me setting it up by hand.

Type
Project
Status
In progress
Published

The question

How does a piece of work become a running session, on the right tool, without me setting everything up by hand and without taking acceptance away from whoever orchestrates?

Setting up a subtask by hand means creating a worktree and a branch, opening a tab, picking the tool and the model, starting the tool, and pasting in the context and the contract. Each tool's native subagent saves part of that, but it ties the subtask to the main session's tool and leaves no record of the split.

What it does

Demerzel reads the units declared in a Radiant contract and dispatches each one as a Claude Code or Codex session. Then it tracks that session's state and, when it finishes, collects the completion report and hands it to the orchestrator, which rereads the result and decides whether to accept it.

It has no judgment. It doesn't split the work, doesn't pick the routing rule, and doesn't accept deliveries. It validates and runs the rule the orchestrator chose. The orchestrator calls Demerzel instead of the native subagent tool, and I can call it directly too.

It's a non-interactive CLI, in Bun and TypeScript, with no runtime dependencies. The commands are dispatch, status, wait, collect, resume, and close, and the output can come as JSON. The exit code says whether it worked, whether something is pending, or whether it refused without side effects, and errors say what to do next.

units:
  - id: TC-0025.1
    role: radiant-dev
    requires: []
    objective: Fetch external sources by rev for the cache.
    writes: [src/sources/, tests/sources/]
    depends_on: []
    done_when: The tests in tests/sources pass and the cache refuses a mismatched digest.
  - id: TC-0025.2
    role: radiant-dev
    capability: deep
    capability_reason: Refusing a digest requires security judgment.
    requires: []
    objective: Wire digest verification into sync.
    writes: [src/sync/]
    depends_on: [TC-0025.1]
    done_when: bun run check passes and sync refuses content without a matching digest.
An example of a contract's unit block, in the format defined by the Radiant decision that gave rise to Demerzel. This is what Demerzel reads.

Core and integration

Demerzel has two layers. The core receives everything already resolved (tool, model, effort, paths, and request), keeps each project's dispatch log, and tracks the sessions. It doesn't know about Radiant. The proof is the core's test suite, which runs with a fake backend and no copy of Radiant in the environment.

The Radiant integration finds the project, reads the contract's units, checks that the project is on the Radiant revision it declared, applies the routing rules, and waits for the completion report. In this first version, it's the only way in. Dispatching outside a Radiant project waits until a real case calls for it.

Radiant is also the process I use to build Demerzel, with a Frame, a Spec, a Plan, and contracts. That dependency stays in the process. The core's code still doesn't have it.

In herdr

Sessions run in herdr, the first backend, behind an interface of Demerzel's own. A dispatch goes in this order:

  1. Checks the project and the Radiant revision.
  2. Reads the unit and checks that its dependencies are done and that the paths it writes don't overlap with another unit in progress.
  3. Applies the routing rule and records the decision before launching.
  4. In herdr, creates the worktree with its own branch, starts the tool, and sends the request.
  5. status and wait follow the session until it finishes or gets stuck.
  6. collect reads the completion report in the worktree and hands it to the orchestrator.

The request carries only paths: the role, where Radiant is, the contract, the unit, and where to leave the return. It never carries the contract's content or secrets. The launched tool reads the contract and sends it to its model provider, as it would in a session opened by hand. So picking the tool also means picking where the contract goes.

What it refuses

Some decisions stay outside Demerzel on purpose:

Every check runs before the first side effect, and a refusal creates nothing.

With Radiant

Demerzel came out of a Radiant decision to split contracts into units and route each one to a tool. Radiant defines the format of units and rules, and Demerzel does the mechanical part. I've already used Demerzel to dispatch the units of a real AIKM contract.

Demerzel repositoryPublic, MIT license

Updates

  1. First published.
← All studies