# DevClaw — Architecture & Component Interaction ## Agents vs Sessions Understanding the OpenClaw model is key to understanding how DevClaw works: - **Agent** — A configured entity in `openclaw.json`. Has a workspace, model, identity files (SOUL.md, IDENTITY.md), and tool permissions. Persists across restarts. - **Session** — A runtime conversation instance. Each session has its own context window and conversation history, stored as a `.jsonl` transcript file. - **Sub-agent session** — A session created under the orchestrator agent for a specific worker role. NOT a separate agent — it's a child session running under the same agent, with its own isolated context. Format: `agent::subagent:--`. ### Session-per-level design Each project maintains **separate sessions per developer level per role**. A project's DEV might have a junior session, a medior session, and a senior session — each accumulating its own codebase context over time. ``` Orchestrator Agent (configured in openclaw.json) └─ Main session (long-lived, handles all projects) │ ├─ Project A │ ├─ DEV sessions: { junior: , medior: , senior: null } │ └─ QA sessions: { reviewer: , tester: null } │ └─ Project B ├─ DEV sessions: { junior: null, medior: , senior: null } └─ QA sessions: { reviewer: , tester: null } ``` Why per-level instead of switching models on one session: - **No model switching overhead** — each session always uses the same model - **Accumulated context** — a junior session that's done 20 typo fixes knows the project well; a medior session that's done 5 features knows it differently - **No cross-model confusion** — conversation history stays with the model that generated it - **Deterministic reuse** — level selection directly maps to a session key, no patching needed ### Plugin-controlled session lifecycle DevClaw controls the **full** session lifecycle end-to-end. The orchestrator agent never calls `sessions_spawn` or `sessions_send` — the plugin handles session creation and task dispatch internally using the OpenClaw CLI: ``` Plugin dispatch (inside work_start): 1. Assign level, look up session, decide spawn vs send 2. New session: openclaw gateway call sessions.patch → create entry + set model openclaw gateway call agent → dispatch task 3. Existing: openclaw gateway call agent → dispatch task to existing session 4. Return result to orchestrator (announcement text, no session instructions) ``` The agent's only job after `work_start` returns is to post the announcement to Telegram. Everything else — level assignment, session creation, task dispatch, state update, audit logging — is deterministic plugin code. **Why this matters:** Previously the plugin returned instructions like `{ sessionAction: "spawn", model: "sonnet" }` and the agent had to correctly call `sessions_spawn` with the right params. This was the fragile handoff point where agents would forget `cleanup: "keep"`, use wrong models, or corrupt session state. Moving dispatch into the plugin eliminates that entire class of errors. **Session persistence:** Sessions created via `sessions.patch` persist indefinitely (no auto-cleanup). The plugin manages lifecycle explicitly through the `health` tool. **What we trade off vs. registered sub-agents:** | Feature | Sub-agent system | Plugin-controlled | DevClaw equivalent | |---|---|---|---| | Auto-reporting | Sub-agent reports to parent | No | Heartbeat polls for completion | | Concurrency control | `maxConcurrent` | No | `work_start` checks `active` flag | | Lifecycle tracking | Parent-child registry | No | `projects.json` tracks all sessions | | Timeout detection | `runTimeoutSeconds` | No | `health` flags stale >2h | | Cleanup | Auto-archive | No | `health` manual cleanup | DevClaw provides equivalent guardrails for everything except auto-reporting, which the heartbeat handles. ## System overview ```mermaid graph TB subgraph "Telegram" H[Human] TG[Group Chat] end subgraph "OpenClaw Runtime" MS[Main Session
orchestrator agent] GW[Gateway RPC
sessions.patch / sessions.list] CLI[openclaw gateway call agent] DEV_J[DEV session
junior] DEV_M[DEV session
medior] DEV_S[DEV session
senior] QA_R[QA session
reviewer] end subgraph "DevClaw Plugin" WS[work_start] WF[work_finish] TCR[task_create] ST[status] SH[health] PR[project_register] DS[setup] TIER[Level Resolver] PJ[projects.json] AL[audit.log] end subgraph "External" GL[Issue Tracker] REPO[Git Repository] end H -->|messages| TG TG -->|delivers| MS MS -->|announces| TG MS -->|calls| WS MS -->|calls| WF MS -->|calls| TCR MS -->|calls| ST MS -->|calls| SH MS -->|calls| PR MS -->|calls| DS WS -->|resolves level| TIER WS -->|transitions labels| GL WS -->|reads/writes| PJ WS -->|appends| AL WS -->|creates session| GW WS -->|dispatches task| CLI WF -->|transitions labels| GL WF -->|closes/reopens| GL WF -->|reads/writes| PJ WF -->|git pull| REPO WF -->|auto-chain dispatch| CLI WF -->|appends| AL TCR -->|creates issue| GL TCR -->|appends| AL ST -->|lists issues by label| GL ST -->|reads| PJ ST -->|appends| AL SH -->|reads/writes| PJ SH -->|checks sessions| GW SH -->|reverts labels| GL SH -->|appends| AL PR -->|creates labels| GL PR -->|writes entry| PJ PR -->|appends| AL CLI -->|sends task| DEV_J CLI -->|sends task| DEV_M CLI -->|sends task| DEV_S CLI -->|sends task| QA_R DEV_J -->|writes code, creates MRs| REPO DEV_M -->|writes code, creates MRs| REPO DEV_S -->|writes code, creates MRs| REPO QA_R -->|reviews code, tests| REPO ``` ## End-to-end flow: human to sub-agent This diagram shows the complete path from a human message in Telegram through to a sub-agent session working on code: ```mermaid sequenceDiagram participant H as Human (Telegram) participant TG as Telegram Channel participant MS as Main Session
(orchestrator) participant DC as DevClaw Plugin participant GW as Gateway RPC participant CLI as openclaw gateway call agent participant DEV as DEV Session
(medior) participant GL as Issue Tracker Note over H,GL: Issue exists in queue (To Do) H->>TG: "check status" (or heartbeat triggers) TG->>MS: delivers message MS->>DC: status() DC->>GL: list issues by label "To Do" DC-->>MS: { toDo: [#42], dev: idle } Note over MS: Decides to pick up #42 for DEV as medior MS->>DC: work_start({ issueId: 42, role: "dev", level: "medior", ... }) DC->>DC: resolve level "medior" → model ID DC->>DC: lookup dev.sessions.medior → null (first time) DC->>GL: transition label "To Do" → "Doing" DC->>GW: sessions.patch({ key: new-session-key, model: "anthropic/claude-sonnet-4-5" }) DC->>CLI: openclaw gateway call agent --params { sessionKey, message } CLI->>DEV: creates session, delivers task DC->>DC: store session key in projects.json + append audit.log DC-->>MS: { success: true, announcement: "🔧 Spawning DEV (medior) for #42" } MS->>TG: "🔧 Spawning DEV (medior) for #42: Add login page" TG->>H: sees announcement Note over DEV: Works autonomously — reads code, writes code, creates MR Note over DEV: Calls work_finish when done DEV->>DC: work_finish({ role: "dev", result: "done", ... }) DC->>GL: transition label "Doing" → "To Test" DC->>DC: deactivate worker (sessions preserved) DC-->>DEV: { announcement: "✅ DEV DONE #42" } MS->>TG: "✅ DEV DONE #42 — moved to QA queue" TG->>H: sees announcement ``` On the **next DEV task** for this project that also assigns medior: ```mermaid sequenceDiagram participant MS as Main Session participant DC as DevClaw Plugin participant CLI as openclaw gateway call agent participant DEV as DEV Session
(medior, existing) MS->>DC: work_start({ issueId: 57, role: "dev", level: "medior", ... }) DC->>DC: resolve level "medior" → model ID DC->>DC: lookup dev.sessions.medior → existing key! Note over DC: No sessions.patch needed — session already exists DC->>CLI: openclaw gateway call agent --params { sessionKey, message } CLI->>DEV: delivers task to existing session (has full codebase context) DC-->>MS: { success: true, announcement: "⚡ Sending DEV (medior) for #57" } ``` Session reuse saves ~50K tokens per task by not re-reading the codebase. ## Complete ticket lifecycle This traces a single issue from creation to completion, showing every component interaction, data write, and message. ### Phase 1: Issue created Issues are created by the orchestrator agent or by sub-agent sessions via `task_create` or directly via `gh`/`glab`. The orchestrator can create issues based on user requests in Telegram, backlog planning, or QA feedback. Sub-agents can also create issues when they discover bugs during development. ``` Orchestrator Agent → Issue Tracker: creates issue #42 with label "Planning" ``` **State:** Issue tracker has issue #42 labeled "Planning". Nothing in DevClaw yet. ### Phase 2: Heartbeat detects work ``` Heartbeat triggers → Orchestrator calls status() ``` ```mermaid sequenceDiagram participant A as Orchestrator participant QS as status participant GL as Issue Tracker participant PJ as projects.json participant AL as audit.log A->>QS: status({ projectGroupId: "-123" }) QS->>PJ: readProjects() PJ-->>QS: { dev: idle, qa: idle } QS->>GL: list issues by label "To Do" GL-->>QS: [{ id: 42, title: "Add login page" }] QS->>GL: list issues by label "To Test" GL-->>QS: [] QS->>GL: list issues by label "To Improve" GL-->>QS: [] QS->>AL: append { event: "status", ... } QS-->>A: { dev: idle, queue: { toDo: [#42] } } ``` **Orchestrator decides:** DEV is idle, issue #42 is in To Do → pick it up. Evaluates complexity → assigns medior level. ### Phase 3: DEV pickup The plugin handles everything end-to-end — level resolution, session lookup, label transition, state update, **and** task dispatch to the worker session. The agent's only job after is to post the announcement. ```mermaid sequenceDiagram participant A as Orchestrator participant WS as work_start participant GL as Issue Tracker participant TIER as Level Resolver participant GW as Gateway RPC participant CLI as openclaw gateway call agent participant PJ as projects.json participant AL as audit.log A->>WS: work_start({ issueId: 42, role: "dev", projectGroupId: "-123", level: "medior" }) WS->>PJ: readProjects() WS->>GL: getIssue(42) GL-->>WS: { title: "Add login page", labels: ["To Do"] } WS->>WS: Verify label is "To Do" WS->>TIER: resolve "medior" → "anthropic/claude-sonnet-4-5" WS->>PJ: lookup dev.sessions.medior WS->>GL: transitionLabel(42, "To Do", "Doing") alt New session WS->>GW: sessions.patch({ key: new-key, model: "anthropic/claude-sonnet-4-5" }) end WS->>CLI: openclaw gateway call agent --params { sessionKey, message } WS->>PJ: activateWorker + store session key WS->>AL: append work_start + model_selection WS-->>A: { success: true, announcement: "🔧 ..." } ``` **Writes:** - `Issue Tracker`: label "To Do" → "Doing" - `projects.json`: dev.active=true, dev.issueId="42", dev.level="medior", dev.sessions.medior=key - `audit.log`: 2 entries (work_start, model_selection) - `Session`: task message delivered to worker session via CLI ### Phase 4: DEV works ``` DEV sub-agent session → reads codebase, writes code, creates MR DEV sub-agent session → calls work_finish({ role: "dev", result: "done", ... }) ``` This happens inside the OpenClaw session. The worker calls `work_finish` directly for atomic state updates. If the worker discovers unrelated bugs, it calls `task_create` to file them. ### Phase 5: DEV complete (worker self-reports) ```mermaid sequenceDiagram participant DEV as DEV Session participant WF as work_finish participant GL as Issue Tracker participant PJ as projects.json participant AL as audit.log participant REPO as Git Repo participant QA as QA Session (auto-chain) DEV->>WF: work_finish({ role: "dev", result: "done", projectGroupId: "-123", summary: "Login page with OAuth" }) WF->>PJ: readProjects() PJ-->>WF: { dev: { active: true, issueId: "42" } } WF->>REPO: git pull WF->>PJ: deactivateWorker(-123, dev) Note over PJ: active→false, issueId→null
sessions map PRESERVED WF->>GL: transitionLabel "Doing" → "To Test" WF->>AL: append { event: "work_finish", role: "dev", result: "done" } alt autoChain enabled WF->>GL: transitionLabel "To Test" → "Testing" WF->>QA: dispatchTask(role: "qa", level: "reviewer") WF->>PJ: activateWorker(-123, qa) WF-->>DEV: { announcement: "✅ DEV DONE #42", autoChain: { dispatched: true, role: "qa" } } else autoChain disabled WF-->>DEV: { announcement: "✅ DEV DONE #42", nextAction: "qa_pickup" } end ``` **Writes:** - `Git repo`: pulled latest (has DEV's merged code) - `projects.json`: dev.active=false, dev.issueId=null (sessions map preserved for reuse) - `Issue Tracker`: label "Doing" → "To Test" (+ "To Test" → "Testing" if auto-chain) - `audit.log`: 1 entry (work_finish) + optional auto-chain entries ### Phase 6: QA pickup Same as Phase 3, but with `role: "qa"`. Label transitions "To Test" → "Testing". Uses the reviewer level. ### Phase 7: QA result (4 possible outcomes) #### 7a. QA Pass ```mermaid sequenceDiagram participant QA as QA Session participant WF as work_finish participant GL as Issue Tracker participant PJ as projects.json participant AL as audit.log QA->>WF: work_finish({ role: "qa", result: "pass", projectGroupId: "-123" }) WF->>PJ: deactivateWorker(-123, qa) WF->>GL: transitionLabel(42, "Testing", "Done") WF->>GL: closeIssue(42) WF->>AL: append { event: "work_finish", role: "qa", result: "pass" } WF-->>QA: { announcement: "🎉 QA PASS #42. Issue closed." } ``` **Ticket complete.** Issue closed, label "Done". #### 7b. QA Fail ```mermaid sequenceDiagram participant QA as QA Session participant WF as work_finish participant GL as Issue Tracker participant PJ as projects.json participant AL as audit.log QA->>WF: work_finish({ role: "qa", result: "fail", projectGroupId: "-123", summary: "OAuth redirect broken" }) WF->>PJ: deactivateWorker(-123, qa) WF->>GL: transitionLabel(42, "Testing", "To Improve") WF->>GL: reopenIssue(42) WF->>AL: append { event: "work_finish", role: "qa", result: "fail" } WF-->>QA: { announcement: "❌ QA FAIL #42 — OAuth redirect broken. Sent back to DEV." } ``` **Cycle restarts:** Issue goes to "To Improve". Next heartbeat, DEV picks it up again (Phase 3, but from "To Improve" instead of "To Do"). #### 7c. QA Refine ``` Label: "Testing" → "Refining" ``` Issue needs human decision. Pipeline pauses until human moves it to "To Do" or closes it. #### 7d. Blocked (DEV or QA) ``` DEV Blocked: "Doing" → "To Do" QA Blocked: "Testing" → "To Test" ``` Worker cannot complete (missing info, environment errors, etc.). Issue returns to queue for retry. No auto-chain — the task is available for the next heartbeat pickup. ### Completion enforcement Three layers guarantee that `work_finish` always runs: 1. **Completion contract** — Every task message sent to a worker session includes a mandatory `## MANDATORY: Task Completion` section listing available results and requiring `work_finish` even on failure. Workers are instructed to use `"blocked"` if stuck. 2. **Blocked result** — Both DEV and QA can use `"blocked"` to gracefully return a task to queue without losing work. DEV blocked: `Doing → To Do`. QA blocked: `Testing → To Test`. This gives workers an escape hatch instead of silently dying. 3. **Stale worker watchdog** — The heartbeat's health check detects workers active for >2 hours. With `fix=true`, it deactivates the worker and reverts the label back to queue. This catches sessions that crashed, ran out of context, or otherwise failed without calling `work_finish`. The `health` tool provides the same check for manual invocation. ### Phase 8: Heartbeat (continuous) The heartbeat runs periodically (via background service or manual `work_heartbeat` trigger). It combines health check + queue scan: ```mermaid sequenceDiagram participant HB as Heartbeat Service participant SH as health check participant TK as projectTick participant WS as work_start (dispatch) Note over HB: Tick triggered (every 60s) HB->>SH: checkWorkerHealth per project per role Note over SH: Checks for zombies, stale workers SH-->>HB: { fixes applied } HB->>TK: projectTick per project Note over TK: Scans queue: To Improve > To Test > To Do TK->>WS: dispatchTask (fill free slots) WS-->>TK: { dispatched } TK-->>HB: { pickups, skipped } ``` ## Data flow map Every piece of data and where it lives: ``` ┌─────────────────────────────────────────────────────────────────┐ │ Issue Tracker (source of truth for tasks) │ │ │ │ Issue #42: "Add login page" │ │ Labels: [Planning | To Do | Doing | To Test | Testing | ...] │ │ State: open / closed │ │ MRs/PRs: linked merge/pull requests │ │ Created by: orchestrator (task_create), workers, or humans │ └─────────────────────────────────────────────────────────────────┘ ↕ gh/glab CLI (read/write, auto-detected) ┌─────────────────────────────────────────────────────────────────┐ │ DevClaw Plugin (orchestration logic) │ │ │ │ setup → agent creation + workspace + model config │ │ work_start → level + label + dispatch + role instr (e2e) │ │ work_finish → label + state + git pull + auto-chain │ │ task_create → create issue in tracker │ │ task_update → manual label state change │ │ task_comment → add comment to issue │ │ status → read labels + read state │ │ health → check sessions + fix zombies │ │ project_register → labels + prompts + state init (one-time) │ └─────────────────────────────────────────────────────────────────┘ ↕ atomic file I/O ↕ OpenClaw CLI (plugin shells out) ┌────────────────────────────────┐ ┌──────────────────────────────┐ │ projects/projects.json │ │ OpenClaw Gateway + CLI │ │ │ │ (called by plugin, not agent)│ │ Per project: │ │ │ │ dev: │ │ openclaw gateway call │ │ active, issueId, level │ │ sessions.patch → create │ │ sessions: │ │ sessions.list → health │ │ junior: │ │ sessions.delete → cleanup │ │ medior: │ │ │ │ senior: │ │ openclaw gateway call agent │ │ qa: │ │ --params { sessionKey, │ │ active, issueId, level │ │ message, agentId } │ │ sessions: │ │ → dispatches to session │ │ reviewer: │ │ │ │ tester: │ │ │ └────────────────────────────────┘ └──────────────────────────────┘ ↕ append-only ┌─────────────────────────────────────────────────────────────────┐ │ log/audit.log (observability) │ │ │ │ NDJSON, one line per event: │ │ work_start, work_finish, model_selection, │ │ status, health, task_create, task_update, │ │ task_comment, project_register, setup, heartbeat_tick │ │ │ │ Query: cat audit.log | jq 'select(.event=="work_start")' │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Telegram / WhatsApp (user-facing messages) │ │ │ │ Per group chat: │ │ "🔧 Spawning DEV (medior) for #42: Add login page" │ │ "⚡ Sending DEV (medior) for #57: Fix validation" │ │ "✅ DEV DONE #42 — Login page with OAuth." │ │ "🎉 QA PASS #42. Issue closed." │ │ "❌ QA FAIL #42 — OAuth redirect broken." │ │ "🚫 DEV BLOCKED #42 — Missing dependencies." │ │ "🚫 QA BLOCKED #42 — Env not available." │ └─────────────────────────────────────────────────────────────────┘ ┌─────────────────────────────────────────────────────────────────┐ │ Git Repository (codebase) │ │ │ │ DEV sub-agent sessions: read code, write code, create MRs │ │ QA sub-agent sessions: read code, run tests, review MRs │ │ work_finish (DEV done): git pull to sync latest │ └─────────────────────────────────────────────────────────────────┘ ``` ## Scope boundaries What DevClaw controls vs. what it delegates: ```mermaid graph LR subgraph "DevClaw controls (deterministic)" L[Label transitions] S[Worker state] PR[Project registration] SETUP[Agent + workspace setup] SD[Session dispatch
create + send via CLI] AC[Auto-chaining
DEV→QA, QA fail→DEV] RI[Role instructions
loaded per project] A[Audit logging] Z[Zombie cleanup] end subgraph "Orchestrator handles" MSG[Telegram announcements] HB[Heartbeat scheduling] DEC[Task prioritization] M[Developer assignment
junior/medior/senior] end subgraph "Sub-agent sessions handle" CR[Code writing] MR[MR creation/review] WF_W[Task completion
via work_finish] BUG[Bug filing
via task_create] end subgraph "External" DEPLOY[Deployment] HR[Human decisions] end ``` ## IssueProvider abstraction All issue tracker operations go through the `IssueProvider` interface, defined in `lib/providers/provider.ts`. This abstraction allows DevClaw to support multiple issue trackers without changing tool logic. **Interface methods:** - `ensureLabel` / `ensureAllStateLabels` — idempotent label creation - `createIssue` — create issue with label and assignees - `listIssuesByLabel` / `getIssue` — issue queries - `transitionLabel` — atomic label state transition (unlabel + label) - `closeIssue` / `reopenIssue` — issue lifecycle - `hasStateLabel` / `getCurrentStateLabel` — label inspection - `hasMergedMR` / `getMergedMRUrl` — MR/PR verification - `addComment` — add comment to issue - `healthCheck` — verify provider connectivity **Current providers:** - **GitHub** (`lib/providers/github.ts`) — wraps `gh` CLI - **GitLab** (`lib/providers/gitlab.ts`) — wraps `glab` CLI **Planned providers:** - **Jira** — via REST API Provider selection is handled by `createProvider()` in `lib/providers/index.ts`. Auto-detects GitHub vs GitLab from the git remote URL. ## Error recovery | Failure | Detection | Recovery | |---|---|---| | Session dies mid-task | `health` checks via `sessions.list` Gateway RPC | `fix=true`: reverts label, clears active state. Next heartbeat picks up task again (creates fresh session for that level). | | gh/glab command fails | Plugin tool throws error, returns to agent | Agent retries or reports to Telegram group | | `openclaw gateway call agent` fails | Plugin catches error during dispatch | Plugin rolls back: reverts label, clears active state. Returns error. No orphaned state. | | `sessions.patch` fails | Plugin catches error during session creation | Plugin rolls back label transition. Returns error. | | projects.json corrupted | Tool can't parse JSON | Manual fix needed. Atomic writes (temp+rename) prevent partial writes. | | Label out of sync | `work_start` verifies label before transitioning | Throws error if label doesn't match expected state. | | Worker already active | `work_start` checks `active` flag | Throws error: "DEV already active on project". Must complete current task first. | | Stale worker (>2h) | `health` and heartbeat health check | `fix=true`: deactivates worker, reverts label to queue. Task available for next pickup. | | Worker stuck/blocked | Worker calls `work_finish` with `"blocked"` | Deactivates worker, reverts label to queue. Issue available for retry. | | `project_register` fails | Plugin catches error during label creation or state write | Clean error returned. Labels are idempotent, projects.json not written until all labels succeed. | ## File locations | File | Location | Purpose | |---|---|---| | Plugin source | `~/.openclaw/extensions/devclaw/` | Plugin code | | Plugin manifest | `~/.openclaw/extensions/devclaw/openclaw.plugin.json` | Plugin registration | | Agent config | `~/.openclaw/openclaw.json` | Agent definition + tool permissions + model config | | Worker state | `~/.openclaw/workspace-/projects/projects.json` | Per-project DEV/QA state | | Role instructions | `~/.openclaw/workspace-/projects/roles//` | Per-project `dev.md` and `qa.md` | | Audit log | `~/.openclaw/workspace-/log/audit.log` | NDJSON event log | | Session transcripts | `~/.openclaw/agents//sessions/.jsonl` | Conversation history per session | | Git repos | `~/git//` | Project source code |