Skip to content

Docs / Claude Code

Claude Code

Trigger Claude Code on triaged issues. Fleet dispatch on your own model key, or your own runner over webhook. Full audit trail (every tool call logged).

developerz.ai is a thin orchestrator: the code is written on your side, never on our servers. developerz.ai triages the issue and talks to the reporter, then hands the work off one of two ways. The primary path, handoff.mode: fleet, runs it on your own enrolled boxes (BYOVM): the dz-runner's own harness writes the fix there, under your own model key, and opens the PR. Or you drive your own Claude Code runner over a webhook, and Claude Code writes the fix wherever you run it. Either way developerz.ai watches CI and review and merges when the machine gates pass.

How the handoff works

Set handoff.mode: fleet in maintainer.yml:

# yaml-language-server: $schema=https://developerz.ai/schemas/maintainer.v1.json
version: 1

handoff:
  mode: fleet             # webhook | label | fleet | none
  ask_reporter_first: true

mode takes one of four values, default none:

Mode What fires
webhook A signed issue.handoff POST to a dashboard webhook wired to your Claude Code runner. webhook_ref is required and the webhook must be registered in the dashboard.
label A GitHub label your CI or coding agent picks up. Set handoff.label to the label name.
fleet Runs the work on your own enrolled boxes (BYOVM); no webhook fires and webhook_ref is not required.
none Default. Handoff disabled; triage runs and nothing is dispatched.

On a fleet repo a new issue is filed as an ask for triage, which mints the durable tasks rows that the fleet assigner claims onto a box you or a member of your account enrolled. With ask_reporter_first: true the bot asks the reporter for consent first, and a dispatch with no agreement from the reporter is refused. See the maintainer.yml reference for every handoff field.

Two gates can refuse a fleet dispatch before any work is queued. An account with no AI devs is refused no-capacity, and it clears only by a grant or a seat; a full backlog is queue-full until it drains. The API doc has the exact REST responses.

Run Claude Code on your own box instead? Set mode: webhook and point it at a dashboard webhook wired to your Claude Code runner. webhook_ref is required there and the webhook must be registered in the dashboard; a qualified issue then fires a signed issue.handoff event your runner picks up. See the webhooks doc.

Convention support

Claude Code works from the repo's own steering files, and the handoff lanes read them back rather than only writing prose to a database:

  • CLAUDE.md / AGENTS.md brain. Whichever of the two root files exists is read back into the run's prompt; AGENTS.md is treated as the same artifact under the vendor-neutral name, and a run takes only the FIRST hit, never both concatenated. The file is capped at a fixed character budget so a large brain file cannot silently eat the model's working room; past the cap the run keeps the first portion and appends a visible marker naming the true size and the path.
  • .claude/agents roster. Specialist definitions placed under .claude/agents/ are indexed by name, path, and one-line description, and routed by matching a unit of work's file paths and purpose against that index. A repo with no roster behaves exactly like one with no .claude/agents directory at all.
  • Setup scaffolding. Setup mode can write a starting CLAUDE.md, .claude/agents/, and .claude/skills/ for a repo that has none. It is establish-or-verify: it never overwrites files the repo already has.

What the PR loop does

Once Claude Code's PR is open, developerz.ai takes over:

  1. Waits for CI to go green and review threads to settle.
  2. Classifies risk: breaking changes, large diffs, and first-time contributors pause for approval (escalate.ask_before_acting).
  3. Merges when the machine gates pass, CI green, review verdict, and branch protections, never blindly. Set auto_merge: false to keep a human in the loop.

BYOK: your key, your bill

Claude Code runs on your Anthropic key. developerz.ai never proxies or resells tokens, your provider invoice shows exactly what the agent spent. Swap models any time without touching your policy. See the BYOK doc.

Native tools over MCP

Claude Code can connect straight to our MCP server at mcp.developerz.ai and use the maintainer tools natively, dispatch tasks, check fleet status, re-run a review, from inside the editor. Register it with claude mcp add --transport http or a project-root .mcp.json, with a PAT; MCP clients has the exact commands. MCP is the integration surface; the full tool list is in the MCP verb reference.

What's audited

Every maintainer decision, the handoff dispatch itself, and every MCP tool call Claude Code makes against mcp.developerz.ai, is written to the append-only audit log. The bot always discloses that it is an automated agent, and defers to any other review bot on the PR (no bot-on-bot loops). If it isn't logged, it didn't happen. See the security doc.