DevClaw — Tools Reference

Complete reference for all tools registered by DevClaw. See index.ts for registration.

Task Lifecycle

`task_start`

Advance an issue to the next queue. State-agnostic — works from any HOLD or QUEUE state. The heartbeat handles actual dispatch on its next cycle.

Source: lib/tools/tasks/task-start.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`issueId`	number	Yes	Issue ID to advance
`level`	string	No	Level hint (`junior`, `medior`, `senior`). Applied as a role:level label.

Behavior by current state type:

State type	Action	Example
HOLD (Planning, Refining)	Follows APPROVE transition to target queue	Planning → To Do
QUEUE (To Do, To Improve, etc.)	No-op (already queued), applies level if provided	Stays in To Do
ACTIVE (Doing, Reviewing, etc.)	Error — already being worked on	—
TERMINAL (Done, Rejected)	Error — cannot start	—

Level hint: If level is provided, a role:level label is applied (e.g. developer:senior). The heartbeat respects this when dispatching.

`work_finish`

Complete a task with a result. Called by workers (DEVELOPER/TESTER/ARCHITECT sub-agent sessions) directly, or by the orchestrator.

Source: lib/tools/worker/work-finish.ts

Parameters:

Parameter	Type	Required	Description
`role`	`"developer"` \| `"tester"` \| `"architect"` \| `"reviewer"`	Yes	Worker role
`result`	string	Yes	Completion result (see table below)
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`summary`	string	No	Brief summary for the announcement
`prUrl`	string	No	PR/MR URL (auto-detected if omitted)

Valid results by role:

Role	Result	Label transition	Side effects
developer	`"done"`	Doing → To Review	auto-detect PR URL. Heartbeat polls PR status.
developer	`"blocked"`	Doing → Refining	Awaits human decision
reviewer	`"approve"`	Reviewing → Done	merge PR, git pull, close issue
reviewer	`"reject"`	Reviewing → To Improve	Sent back to developer
reviewer	`"blocked"`	Reviewing → Refining	Awaits human decision
tester	`"pass"`	Testing → Done	Issue closed (only when test phase enabled)
tester	`"fail"`	Testing → To Improve	Issue reopened (only when test phase enabled)
tester	`"refine"`	Testing → Refining	Awaits human decision
tester	`"blocked"`	Testing → Refining	Awaits human decision
architect	`"done"`	Researching → Done	Research complete, implementation tasks created
architect	`"blocked"`	Researching → Refining	Awaits human decision

What it does atomically:

Validates role:result combination
Resolves project and active worker
Executes completion via pipeline service (label transition + side effects)
Deactivates worker (sessions map preserved for reuse)
Sends notification
Ticks queue to fill free worker slots
Writes audit log

Scheduling: After completion, work_finish ticks the queue. The scheduler sees the new label (To Review or To Improve) and dispatches the next worker if a slot is free.

Task Management

`task_create`

Create a new issue in the project's issue tracker.

Source: lib/tools/tasks/task-create.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`title`	string	Yes	Issue title
`description`	string	No	Full issue body (markdown)
`label`	StateLabel	No	State label. Defaults to `"Planning"`.
`assignees`	string[]	No	GitHub/GitLab usernames to assign
`pickup`	boolean	No	If true, immediately pick up for DEVELOPER after creation

Use cases:

Orchestrator creates tasks from chat messages
Workers file follow-up bugs discovered during development
Breaking down epics into smaller tasks

Default behavior: Creates issues in "Planning" state. Only use "To Do" when the user explicitly requests immediate work.

`task_set_level`

Set the developer level hint on a HOLD-state issue (Planning, Refining).

Source: lib/tools/tasks/task-set-level.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`issueId`	number	Yes	Issue ID to update
`level`	string	Yes	The role:level hint (e.g. 'senior', 'junior')
`reason`	string	No	Audit log reason for the change

Only works on issues in HOLD states (Planning, Refining). The level is applied as a role:level label and respected by the heartbeat when the issue is later advanced via task_start.

Use cases:

Override assigned level before advancing (e.g. set to senior for complex task)
Pre-set level on held issues before task_start moves them to the queue

`task_comment`

Add a comment to an issue for feedback, notes, or discussion.

Source: lib/tools/tasks/task-comment.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`issueId`	number	Yes	Issue ID to comment on
`body`	string	Yes	Comment body (markdown)
`authorRole`	`"developer"` \| `"tester"` \| `"architect"` \| `"reviewer"` \| `"orchestrator"`	No	Attribution role prefix

Use cases:

TESTER adds review feedback before pass/fail decision
DEVELOPER posts implementation notes or progress updates
Orchestrator adds summary comments

When authorRole is provided, the comment is prefixed with a role emoji and attribution label.

`task_edit_body`

Update issue title and/or description. Only allowed when the issue is in the initial workflow state (e.g. "Planning") or an active architect state (e.g. "Researching"). Prevents editing in-progress work.

Source: lib/tools/tasks/task-edit-body.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug
`issueId`	number	Yes	Issue ID to edit
`title`	string	No	New title for the issue
`body`	string	No	New body/description for the issue
`reason`	string	No	Why the edit was made (for audit trail)
`addComment`	boolean	No	Post an auto-comment noting the edit. Default: `true`.

At least one of title or body must be provided.

Audit: Logs the edit with timestamp, caller, and a diff summary. Optionally posts an auto-comment on the issue for traceability.

`task_owner`

Claim issue ownership for this instance. Adds an owner:{instanceName} label so this instance owns the issue for queue scanning and dispatch. Supports claiming a single issue or all unclaimed queued issues.

Source: lib/tools/tasks/task-owner.ts

Parameters:

Parameter	Type	Required	Description
`channelId`	string	Yes	Current chat/group ID
`projectSlug`	string	No	Project slug (resolved from channel if omitted)
`issueId`	number	No	Specific issue to claim. Omit to claim all unclaimed queued issues.
`force`	boolean	No	Transfer ownership from another instance. Default: `false`.

Use cases:

Multi-instance deployments where each instance handles a subset of issues
Transfer ownership of an issue between instances

Operations

`tasks_status`

Full project dashboard showing all non-terminal state types with issue details.

Source: lib/tools/tasks/tasks-status.ts

Context: Auto-filters to project in group chats. Shows all projects in DMs.

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	No	Filter to specific project. Omit for all.

Returns per project:

hold — Waiting for input (Planning, Refining): issue IDs, titles, URLs
active — Work in progress (Doing, Reviewing, etc.): issue IDs, titles, URLs
queue — Queued for work (To Do, To Improve, To Review): issue IDs, titles, URLs
Worker state per role: active/idle, current issue, level, start time
Active workflow summary: review policy, test phase status, state flow
Summary totals: totalHold, totalActive, totalQueued

`project_status`

Instant local project info for the current channel. Returns registration details, channel bindings, worker slot states, workflow config, and execution settings — all from local data, no issue tracker API calls.

Source: lib/tools/admin/project-status.ts

Parameters:

Parameter	Type	Required	Description
`channelId`	string	Yes	Current chat/group ID

Returns:

Project registration: name, repo, base branch, deploy URL, provider
Channel bindings: linked channels with types
Worker slots: per-role active/idle state, current issue, level
Workflow config: review policy, test phase, state flow
Execution settings: role execution mode

Use cases:

Quick check of project setup without querying the issue tracker
Verify channel bindings and worker slot configuration
Use tasks_status instead when you need live issue counts from the tracker

`task_list`

Browse and search issues by workflow state. Returns individual issues grouped by state label.

Source: lib/tools/tasks/task-list.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug
`stateType`	`"queue"` \| `"active"` \| `"hold"` \| `"terminal"` \| `"all"`	No	Filter by state type. Default: all non-terminal.
`label`	string	No	Specific state label (e.g. `"Planning"`, `"Done"`). Overrides `stateType`.
`search`	string	No	Text search in issue titles (case-insensitive).
`limit`	number	No	Max issues per state. Default: 20.

Returns per matching state:

State label, type, and role
Issue list: ID, title, URL
Total count (before limit)

Use cases:

Browse all issues in Planning: { projectSlug: "my-app", label: "Planning" }
Find blocked work: { projectSlug: "my-app", stateType: "hold" }
Search across queues: { projectSlug: "my-app", stateType: "queue", search: "auth" }
View completed work: { projectSlug: "my-app", stateType: "terminal" }

Note: When browsing terminal states (Done), the tool queries closed issues from the provider.

`health`

Worker health scan with optional auto-fix.

Source: lib/tools/admin/health.ts

Context: Auto-filters to project in group chats.

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	No	Project slug. Omit for all.
`fix`	boolean	No	Apply fixes for detected issues. Default: `false` (read-only).
`activeSessions`	string[]	No	Active session IDs for zombie detection.

Health checks:

Issue	Severity	Detection	Auto-fix
Active worker with no session key	Critical	`active=true` but no session in map	Deactivate worker
Active worker whose session is dead	Critical	Session key not in active sessions list	Deactivate worker, revert label
Worker active >2 hours	Warning	`startTime` older than 2h	Deactivate worker, revert label to queue
Inactive worker with lingering issue ID	Warning	`active=false` but `issueId` still set	Clear issueId

Setup

`project_register`

One-time project setup. Creates state labels, scaffolds project directory with override instructions, adds project to state.

Source: lib/tools/admin/project-register.ts

Context: Only works in the Telegram/WhatsApp group being registered.

Parameters:

Parameter	Type	Required	Description
`projectGroupId`	string	No	Auto-detected from current group if omitted
`name`	string	Yes	Short project name (e.g. `my-webapp`)
`repo`	string	Yes	Path to git repo (e.g. `~/git/my-project`)
`groupName`	string	No	Display name. Defaults to `Project: {name}`.
`baseBranch`	string	Yes	Base branch for development
`deployBranch`	string	No	Deploy branch. Defaults to baseBranch.
`deployUrl`	string	No	Deployment URL
`roleExecution`	`"parallel"` \| `"sequential"`	No	DEVELOPER/TESTER parallelism. Default: `"parallel"`.

What it does atomically:

Validates project not already registered
Resolves repo path, auto-detects GitHub/GitLab from git remote
Verifies provider health (CLI installed and authenticated)
Creates all state labels (idempotent — safe to run again)
Adds project entry to projects.json with empty worker state for all registered roles
Scaffolds project directory with prompts/ folder and README.md explaining prompt and workflow overrides
Writes audit log

`setup`

Agent + workspace initialization.

Source: lib/tools/admin/setup.ts

Parameters:

Parameter	Type	Required	Description
`newAgentName`	string	No	Create a new agent. Omit to configure current workspace.
`channelBinding`	`"telegram"` \| `"whatsapp"`	No	Channel to bind (with `newAgentName` only)
`migrateFrom`	string	No	Agent ID to migrate channel binding from
`models`	object	No	Model overrides per role and level (see Configuration)
`projectExecution`	`"parallel"` \| `"sequential"`	No	Project execution mode

What it does:

Creates a new agent or configures existing workspace
Optionally binds messaging channel (Telegram/WhatsApp)
Optionally migrates channel binding from another agent
Writes workspace files: AGENTS.md, HEARTBEAT.md, IDENTITY.md, TOOLS.md, SOUL.md, devclaw/projects.json, devclaw/workflow.yaml
Scaffolds default prompt files for all roles

`onboard`

Conversational onboarding guide. Returns step-by-step instructions for the agent to walk the user through setup.

Source: lib/tools/admin/onboard.ts

Note: Call this before setup to get step-by-step guidance.

Parameters:

Parameter	Type	Required	Description
`mode`	`"first-run"` \| `"reconfigure"`	No	Auto-detected from current state

`workflow_guide`

Reference guide for workflow configuration. Call before making any workflow changes.

Source: lib/tools/admin/workflow-guide.ts

Parameters:

Parameter	Type	Required	Description
`topic`	string	No	Narrow to: `overview`, `states`, `roles`, `review`, `testing`, `timeouts`, `overrides`. Omit for full guide.

Returns: Comprehensive documentation about the workflow config structure, valid values (enums vs free-form), config layer system, and common customization recipes.

Use cases:

User asks to change review policy → call workflow_guide first, then edit workflow.yaml
User asks to enable test phase → call workflow_guide("testing") for step-by-step
User asks about config options → call workflow_guide("overview") for the full picture

`research_task`

Spawn an architect for a design investigation. Creates a To Research issue with rich context and dispatches an architect worker through To Research → Researching states.

Source: lib/tools/tasks/research-task.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	Yes	Project slug (e.g. 'my-webapp')
`title`	string	Yes	Design task title
`description`	string	Yes	Detailed background context for the architect
`focusAreas`	string[]	No	Specific areas to investigate
`complexity`	`"simple"` \| `"medium"` \| `"complex"`	No	Guides level selection. Default: `"medium"`.

Completion Rules Reference

The pipeline service (lib/services/pipeline.ts) derives completion rules from the workflow config.

Default flow (human review, no test phase):

developer:done    → Doing     → To Review    (detect PR, heartbeat polls PR status)
developer:blocked → Doing     → Refining     (awaits human decision)
reviewer:approve  → Reviewing → Done         (merge PR, git pull, close issue)
reviewer:reject   → Reviewing → To Improve   (sent back to developer)
reviewer:blocked  → Reviewing → Refining     (awaits human decision)
architect:done    → Researching → Done          (research complete, implementation tasks created)
architect:blocked → Researching → Refining     (awaits human decision)

With test phase enabled:

tester:pass       → Testing   → Done         (close issue)
tester:fail       → Testing   → To Improve   (reopen issue)
tester:refine     → Testing   → Refining     (awaits human decision)
tester:blocked    → Testing   → Refining     (awaits human decision)

Heartbeat auto-transitions (on "To Review" state):

PR approved       → To Review → Done         (merge PR, git pull, close issue)
PR comments       → To Review → To Improve   (developer fixes)
Merge conflict    → To Review → To Improve   (developer resolves)

Issue Priority Order

When the heartbeat fills free worker slots, issues are prioritized:

To Improve — Review failures get fixed first (highest priority)
To Review — Completed developer work awaits review (priority 2)
To Do — Fresh tasks are picked up last

This ensures the pipeline clears its backlog before starting new work.

Maintenance

`sync_labels`

Sync GitHub/GitLab labels with the current workflow config. Creates any missing state labels, role:level labels, and step routing labels from the resolved (three-layer merged) config.

Source: lib/tools/admin/sync-labels.ts

Parameters:

Parameter	Type	Required	Description
`projectSlug`	string	No	Project slug to sync. Omit to sync all registered projects.

What it does:

Loads the resolved workflow config (built-in → workspace → project)
Derives all required labels: state labels, role:level labels, step routing labels
Creates any missing labels on the GitHub/GitLab repo via the provider
Reports created vs. already-existing labels

When to use: After editing workflow.yaml to add custom states, change label names, or enable the test phase.

`channel_link`

Link a chat/channel to a project. If the channel is already linked to a different project, the old bond is removed first (auto-detach).

Source: lib/tools/admin/channel-link.ts

Parameters:

Parameter	Type	Required	Description
`channelId`	string	Yes	Chat/group ID to link
`project`	string	Yes	Project name or slug to link to

Use cases:

Connect a new chat to an existing project
Switch which project a chat controls

`channel_unlink`

Remove a channel from a project. Validates that the channel exists and prevents removing the last channel (projects must have at least one notification endpoint).

Source: lib/tools/admin/channel-unlink.ts

Parameters:

Parameter	Type	Required	Description
`channelId`	string	Yes	Channel ID to remove
`project`	string	Yes	Project name or slug

`channel_list`

List channels for a project or all projects. Shows channel type, ID, name, and event subscriptions.

Source: lib/tools/admin/channel-list.ts

Parameters:

Parameter	Type	Required	Description
`project`	string	No	Project name or slug. Omit to list channels for all projects.

`config`

Manage DevClaw workspace configuration. Supports three actions: reset config files to defaults, diff against defaults, and show version info.

Source: lib/tools/admin/config.ts

Parameters:

Parameter	Type	Required	Description
`action`	`"reset"` \| `"diff"` \| `"version"`	Yes	Action to perform
`scope`	`"prompts"` \| `"workflow"` \| `"all"`	No	Reset scope (only for `action: "reset"`)

Actions:

Action	Description
`reset`	Reset config files to package defaults. Creates `.bak` backups. Use `scope` to target: `prompts` (role prompts only), `workflow` (workflow.yaml only), `all` (everything).
`diff`	Show differences between current `workflow.yaml` and the built-in default template. Helps identify customizations and see what changed in new versions.
`version`	Show DevClaw package version and workspace tracked version.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

DevClaw — Tools Reference

Task Lifecycle

`task_start`

`work_finish`

Task Management

`task_create`

`task_set_level`

`task_comment`

`task_edit_body`

`task_owner`

Operations

`tasks_status`

`project_status`

`task_list`

`health`

Setup

`project_register`

`setup`

`onboard`

`workflow_guide`

`research_task`

Completion Rules Reference

Issue Priority Order

Maintenance

`sync_labels`

`channel_link`

`channel_unlink`

`channel_list`

`config`

FilesExpand file tree

TOOLS.md

Latest commit

History

TOOLS.md

File metadata and controls

DevClaw — Tools Reference

Task Lifecycle

task_start

work_finish

Task Management

task_create

task_set_level

task_comment

task_edit_body

task_owner

Operations

tasks_status

project_status

task_list

health

Setup

project_register

setup

onboard

workflow_guide

research_task

Completion Rules Reference

Issue Priority Order

Maintenance

sync_labels

channel_link

channel_unlink

channel_list

config

`task_start`

`work_finish`

`task_create`

`task_set_level`

`task_comment`

`task_edit_body`

`task_owner`

`tasks_status`

`project_status`

`task_list`

`health`

`project_register`

`setup`

`onboard`

`workflow_guide`

`research_task`

`sync_labels`

`channel_link`

`channel_unlink`

`channel_list`

`config`