Every clawq command is listed below. Run clawq COMMAND --help for per-command usage details.

Commands

Command	Description
clawq active	Show active 5-hour window usage (cost, tokens, quota)
clawq agent	Start the daemon (agent loop, gateway, all configured channels)
clawq agents	Manage agent templates (list, show, create, edit, delete, bind, unbind)
clawq agents list	List all templates (builtins marked [builtin], user marked [user])
clawq agents show <name>	Full template details including system prompt preview
clawq agents create <name>	Create a new template in ~/.clawq/agents/
clawq agents edit <name>	Edit a template (copies builtin to user dir first)
clawq agents delete <name>	Delete a user template (refuses for builtins)
clawq agents bind <pattern> <agent>	Add agent routing binding to config
clawq agents unbind <pattern>	Remove an agent routing binding
clawq agents bindings	List all agent routing bindings
clawq audit	View and manage the security audit log
clawq audit list [--limit N]	List recent audit log entries (default 20)
clawq audit verify	Verify audit log integrity (HMAC chain)
clawq audit export [PATH]	Export audit log to file
clawq audit import PATH	Import audit log from file
clawq audit purge	Purge old audit entries per retention policy
clawq auth	Show API key status or encrypt plaintext secrets in config
clawq auth codex-login [PROVIDER]	Start ChatGPT/Codex OAuth login for a configured provider
clawq auth codex-status [PROVIDER]	Show saved Codex OAuth status
clawq auth codex-logout [PROVIDER]	Remove saved Codex OAuth credentials
clawq benchmark	Measure tool invocation latency to diagnose performance
clawq capabilities	List all active runtime capabilities
clawq completions	Generate and install shell tab-completion scripts (bash, zsh, fish)
clawq costs	Show cumulative LLM costs and token usage
clawq background	Inspect and control background coding agent worktree tasks
clawq background add RUNNER [--model MODEL] REPO [--branch NAME] PROMPT	Queue a background coding task in a fresh git worktree
clawq background show ID	Inspect one background task, including log/worktree paths when available
clawq background wait ID [--timeout SECONDS]	Block until a background task finishes, then print the final summary
clawq background logs ID [--lines COUNT] [--offset LINE] [--follow/-f]	Show the captured log for a background task
clawq background resume ID	Resume a previously started worktree-backed background task using the runner’s native session support
clawq background message ID MESSAGE...	Queue a follow-up user-style chat message for a previously started worktree-backed background task and resume it
clawq background cancel ID	Cancel a queued or running background task
clawq background retry ID	Re-queue a failed background task (max 3 retries)
clawq background recover ID [--runner R] [--model M]	Recover a failed or stuck task by spawning a replacement with full context from the original
clawq background finalize ID	Rebase, fast-forward merge, and clean up a completed task’s worktree
clawq channel	List configured channels
clawq channel set-model NAME MODEL	Set a channel-specific default model (overrides global primary_model)
clawq channel show-model NAME	Show the current model for a channel (channel override or global default)
clawq channel clear-model NAME	Clear a channel’s model override to inherit from global default
clawq config	Manage configuration (wizard, get/set/show)
clawq cron	Manage cron jobs for scheduled agent messages
clawq debug html-preview	Preview HTML rendering
clawq debug http on|off|status|clear|tail	Manage HTTP debug logging
clawq doctor	Check configuration for common issues
clawq held-items	Manage held feature plans awaiting admin review (default: list pending)
clawq held-items save --name N --desc D --plan-file F --layer L	Save a feature plan to the held items queue
clawq held-items list [--status STATUS]	List held items by status (pending, approved, rejected, all)
clawq held-items show ID	Show full details of a held item
clawq held-items approve ID [--by ADMIN] [--notes TEXT]	Approve a pending held item
clawq held-items reject ID [--by ADMIN] [--notes TEXT]	Reject a pending held item
clawq manifest teams	Generate Teams bot manifest commands
clawq manifest telegram	Generate Telegram setMyCommands payload
clawq mcp	Start the MCP server (Model Context Protocol)
clawq runner token --session KEY [--ttl-hours N]	Generate a runner bearer token for remote question relay
clawq memory	Show memory backend configuration
clawq migrate	Run database migrations
clawq models	List configured LLM providers and their default models
clawq onboard	Interactive setup wizard (or template when not in a TTY)
`clawq delegate [—runner auto	kimi
clawq phase2	Show Phase 2 feature status
clawq provider	Inspect LLM provider configuration and live quota state
clawq otp-show	Show the current browser pairing code and any Telegram TOTP codes
clawq rig	Manage agent-driven setup rigs (install, adjust, remove, list)
clawq rig install <name>	Install a rig by delegating setup to a background task
clawq rig adjust <name>	Reconfigure an installed rig
clawq rig remove <name>	Remove an installed rig and clean up
clawq rig list	List available rigs and their install status
clawq reset-agent	Wipe all session history, cron jobs, and workspace files
clawq runtime	Manage native and Docker runtimes
clawq service	Manage the clawq system service (start/stop/restart/install/uninstall/systemd-unit)
clawq service systemd-unit	Print a systemd unit file for user-level daemon management
clawq service launchd-plist	Print a launchd plist file for macOS daemon management
clawq service install	Install and enable service autostart (systemd on Linux, launchd on macOS)
clawq service uninstall	Stop and remove the autostart service configuration
clawq session	Inspect and control agent sessions
clawq session list [--include-postmortem]	List active sessions with state, channel, and pending queue counts. Postmortem sessions (__postmortem_*) are hidden by default; pass --include-postmortem to show them.
clawq session show KEY	Show session details and message history
clawq session model SESSION get	Get the current per-session model override (or global default)
clawq session model SESSION set MODEL	Set a per-session model override (auto-normalizes legacy format)
clawq session model SESSION clear	Clear the per-session model override, reverting to global default
clawq session archive show ID [--offset N] [--limit N]	View archived session messages with pagination
clawq session inject [--cwd PATH] SESSION MSG	Inject a message into a session’s durable inbound queue (optionally set agent working directory)
clawq session pending SESSION	Show pending inbound queue entries for a session
clawq session keepalive SESSION on|off	Toggle session keepalive
clawq session heartbeat SESSION on|off	Toggle heartbeat routing for a session
clawq session epochs SESSION	Show session epoch boundaries
clawq session compact SESSION	Compact session history by summarizing older messages
clawq pipeline list	List available pipelines (builtin + user-defined from ~/.clawq/pipelines/)
clawq pipeline show NAME	Show a pipeline definition (inputs, steps, schemas)
clawq pipeline run NAME --input k=v ...	Execute a pipeline with inputs
clawq pipeline validate NAME	Validate a pipeline definition
clawq pipeline create NAME	Scaffold a new pipeline YAML
clawq pipeline wizard	Interactive pipeline builder
clawq pipeline history [--pipeline NAME]	List past pipeline runs
clawq pipeline result RUN-ID	Show detailed results for a pipeline run
clawq skills	Manage agent skills (SKILL.md and shell-script definitions)
clawq setup	Interactive setup wizards for channel integrations
clawq status	Show runtime configuration and daemon status
clawq transcribe	Transcribe an audio file using the configured STT provider
clawq tunnel	Manage a public tunnel to the local gateway
clawq update	Request a live daemon update and graceful restart
clawq usage	Show provider quota/usage status (use --refresh/-r to force fetch)
clawq usage history	Show historical quota snapshots (--provider NAME, --since PERIOD, --limit N, --json)
clawq usage purge [PERIOD]	Delete old quota history (default: 90d; accepts 7d, 30d, 90d, all)
clawq version	Print version and build info
clawq watcher	Manage the error correction watcher (status, enable/disable, reports)
clawq watcher status	Show watcher config and EC process status (default)
clawq watcher enable	Enable the error correction watcher
clawq watcher disable	Disable the error correction watcher
clawq watcher reports	List recent EC reports
clawq watcher report ID	Show a specific EC report with full detail
clawq workspace	Print the current workspace directory
clawq workspace backup [NAME]	Backup all workspace files to a named version (auto-generates timestamp name if omitted)
clawq workspace versions	List all workspace backup versions (newest first)
clawq workspace restore NAME	Restore workspace files from a named backup version
clawq workspace delete NAME	Delete a workspace backup version

Config Subcommands

The config command has four subcommands for managing ~/.clawq/config.json:

config wizard

clawq config wizard

Full interactive TUI wizard that walks through provider, model, security, channels, gateway, and memory configuration. Writes the result to ~/.clawq/config.json.

config set

clawq config set KEY VALUE

Set a config value by dot-path. Examples:

clawq config set providers.openrouter.api_key "sk-..."
clawq config set providers.openrouter.base_url "https://openrouter.ai/api/v1"
clawq config set agent_defaults.primary_model "openrouter:gpt-4o"
clawq config set channels.telegram.accounts.main.bot_token "123:ABC..."
clawq config set channels.telegram.accounts.main.allow_from '["*"]'
clawq config set security.tools_enabled true

config get

clawq config get KEY

Read a single config value by dot-path:

clawq config get providers.openrouter.default_model
# openai/gpt-4o

config show

clawq config show [SECTION]

Display the current configuration with secrets redacted. Optionally pass a section name to view only that section:

clawq config show              # full config
clawq config show channels     # channels section only
clawq config show security     # security section only

Setup Subcommands

The setup command provides per-channel interactive wizards for configuring individual integrations. Each wizard loads any existing configuration, presents a TUI dashboard, and merges changes back into ~/.clawq/config.json.

clawq setup discord      # Discord bot token, guilds, users, gateway intents
clawq setup github       # GitHub PAT, repos, webhook paths
clawq setup slack        # Slack bot token, app token, signing secret
clawq setup teams        # MS Teams app credentials
clawq setup telegram     # Telegram bot token, allowed users
clawq setup tunnel       # Cloudflare / Tailscale / ngrok tunnel
clawq setup summarizer   # Autosummarizer settings

Running clawq setup without a subcommand prints the list of available wizards.

Common Workflows

First-time setup

clawq onboard          # interactive wizard
clawq doctor           # validate configuration
clawq workspace        # show the active workspace path
clawq agent            # start the daemon

Day-to-day operations

clawq status           # check runtime status
clawq models           # list providers and models
clawq channel          # list active channels
clawq capabilities     # list available features

Background coding runs

clawq delegate "implement the task from TASK.md"
clawq delegate --runner codex --model gpt-5.4 --repo /path/to/repo "implement the task from TASK.md"
clawq background add codex --model gpt-5.4 /path/to/repo "implement the task from TASK.md"
clawq background add claude /path/to/repo --branch clawq-fixup "repair the failing tests"
clawq background list
clawq background show 1
clawq background wait 1
clawq background logs 1
clawq background resume 1
clawq background message 1 "Please fix the failing tests before wrapping up"
clawq background cancel 1
clawq background retry 1
clawq background recover 1 --runner claude
clawq background finalize 1

clawq delegate is the high-level handoff command for this flow. The background subcommands are the more explicit control surface when you want to inspect queue state, wait for completion in the terminal, or read the saved task log.

Background tasks are daemon-owned. The full clawq agent process polls the queue, creates a fresh git worktree for each task under ~/.clawq/background-worktrees/, runs the selected CLI non-interactively, and stores the task log under ~/.clawq/background-logs/.

Once a worktree-backed task has started, clawq background resume <id> resumes it using the runner’s tracked session ID (when available) or falls back to the runner’s generic continue flag. Each runner’s session ID is automatically captured: Claude pre-assigns a UUID via --session-id, Codex parses JSONL output for thread_id, and OpenCode/Kimi/Cursor extract session IDs from log output. clawq background message <id> ... injects a new user message into that resumed conversation. The injected message is delivered durably and replayed FIFO for the target task.

Tasks with automerge enabled will automatically rebase onto the target branch and fast-forward merge on success. If a conflict occurs, the parent agent is notified and can use background finalize <id> to retry the rebase and fast-forward merge after resolving conflicts. If the worktree has uncommitted changes (staged or unstaged), finalize and automerge will refuse to proceed and report the dirty state — commit or discard changes first, then retry.

Security and auditing

clawq auth             # show API key status (secrets redacted)
clawq auth encrypt     # encrypt plaintext API keys in config
clawq audit            # view security audit log

Runtime management

# Native runtime
clawq runtime native start
clawq runtime native stop
clawq runtime native health

# Docker runtime
clawq runtime docker start
clawq runtime docker stop
clawq runtime docker health

# Check all runtime status
clawq runtime status

Daemon signals

Signal	Effect
SIGHUP	Reload ~/.clawq/config.json immediately
SIGUSR1	Graceful restart (drain in-flight requests, then restart)
SIGINT / SIGTERM	Graceful shutdown

Config is also auto-reloaded every 10 seconds when the file changes on disk.

Tunnel management

# Standalone tunnel control (when daemon is not running)
clawq tunnel start          # Start tunnel with configured provider
clawq tunnel stop           # Stop the running tunnel
clawq tunnel status         # Show tunnel status (default; detects daemon-managed tunnels)

# Live tunnel control (when daemon is running)
clawq tunnel apply          # Reconcile tunnel state with current config
clawq tunnel restart        # Force stop + restart with current config
clawq tunnel daemon-status  # Show tunnel manager state as JSON

The daemon automatically reconciles tunnel state when config changes are detected (via SIGHUP or file polling). Use tunnel apply to trigger reconciliation explicitly without editing config. Use tunnel restart to force a restart even when config hasn’t changed.

Supported providers: cloudflare (default), tailscale, ngrok, custom. Set tunnel.provider in config.

Make Targets

Build and development tasks are available via Make:

Target	Description
make bootstrap	Create opam switch and install all dependencies
make build	Build the project
make build-minimal	Build minimal binary (clawq-min, core-only)
make build-opt-speed	Optimized build with -O3
make build-opt-size	Optimized build with -O2 -compact
make build-opt-speed-stripped	Stripped optimized speed build
make build-opt-size-stripped	Stripped optimized size build
make build-opt-minimal	Optimized minimal binary
make test	Run all tests
make fmt	Format code with ocamlformat
make fmt-check	Check formatting
make extract	Regenerate OCaml from Coq theories
make extract-check	Check for extraction drift
make ui	Build the web UI and regenerate embedded assets
make ui-dev	Run the web UI watcher with Bun
make ui-check	Verify embedded web UI assets are current
make run	Print CLI help
make clean	Clean build artifacts
make docker-build	Build Docker image
make docker-run	Run daemon in Docker
make verify-report	Generate formal verification report and badge
make release	Build release artifacts

Running Tests

# Run all tests
make test

# List all test suites and cases
opam exec --switch=clawq-5.1 -- dune exec test/test_main.exe -- list

# Run a specific test suite by regex
opam exec --switch=clawq-5.1 -- dune exec test/test_main.exe -- test command_bridge

# Run specific test case indices
opam exec --switch=clawq-5.1 -- dune exec test/test_main.exe -- test command_bridge 20

# Run multiple indices or ranges
opam exec --switch=clawq-5.1 -- dune exec test/test_main.exe -- test scheduler 0,3,8-10

Prefer gpt-5.4 for Codex delegation when quality matters. Use gpt-5.3-codex when you specifically want the Codex-tuned path or need to mirror Codex OAuth defaults.

Plan Subcommands

The plan command manages multi-stage planning pipelines (planner → plan-review → coder → code-review):

clawq plan list                    # List all pipelines (default)
clawq plan start PROMPT [OPTIONS]  # Start a new pipeline (foreground, blocking)
clawq plan show ID                 # Show pipeline status and details
clawq plan logs ID [--lines N]     # Show logs for the current stage
clawq plan cancel ID               # Cancel a running pipeline

Options for plan start:

Option	Description
--repo PATH	Repository path to plan against
--runner NAME	Runner: auto, kimi, opencode, codex, claude, gemini, cursor
--planner-model M	Model for the planner stage
--reviewer-model M	Model for the reviewer stage
--coder-model M	Model for the coder stage
--max-plan-review-iters N	Maximum plan-review iterations (default 3; set 0 to skip)
--max-code-review-iters N	Maximum code-review iterations (default 3; set 0 to skip)
--no-plan-review	Skip plan review phase
--no-code-review	Skip code review phase

Message Interrupts

• !stop — interrupts the in-flight turn and sends “stop” as the next message
• ! (bare) — interrupts and sends “[interrupted]”

When shell_exec is interrupted, the running process is moved to a background shell instead of being killed. Use /tools to see bg_shell_status, bg_shell_wait, and bg_shell_result for tracking background shell jobs.

Slash Commands

Slash commands are available in chat-integrated channels (Telegram, Discord, Slack, Teams, web UI). Type /help in any channel to see the full list.

Command	Description
/start	Show the ready message
/help	List available slash commands, skills, and agents
/new	Reset the current session
/status	Rich table-formatted status report (uptime, PID, sessions, connectors, tunnel)
/runtime_ctx	Show the full per-session runtime context block
/thinking [level]	Show or set thinking level: low, medium, high, off, xhigh, max
/thinking menu	Interactive thinking level selection menu
/show_thinking	Toggle display of model thinking in responses
/heartbeat [on|off|status]	Toggle heartbeat routing for this session
/compact	Compact session history by summarizing older messages
/model	Show current model, favorites, and usage ranking
/model help	Show model command usage text
/model set <name>	Set model for this session (validates against known models)
/model set-force <name>	Set model bypassing validation (for custom/local models)
/model set-default <name>	Set default model in config (persistent, auto-normalizes format)
/model fav <name>	Toggle a model as favorite
/model unfav <name>	Remove from favorites
/model list [provider]	List available models
/model usage	Show provider quota and usage stats
/model menu [page]	Interactive model selection from favorites (paginated)
/costs [session [KEY]|model|provider]	Show cost breakdowns
/costs menu	Interactive cost view selection menu
/usage [session [KEY]|model|provider]	Show token usage breakdowns
/active	Show active 5-hour window usage (cost, tokens, quota)
/bg [list|show|logs|cancel|retry|create] [id|prompt]	Background task management
/bg finalize <id>	Manually finalize a background task (rebase + fast-forward merge + cleanup)
/bg menu	Interactive background task action menu
/cron [list|show|add|edit|remove|history]	Manage cron jobs: list, show details, create (with optional --ttl), edit schedule/message/TTL, remove, view run history
/uptime	Show current daemon uptime
/tools	List all available tools, skills, and agents
/tasks	Show the agent’s current task tree
/agent <name> <prompt>	Invoke a named agent template for a one-off turn
/agent menu [page]	Paginated agent template browser (8 per page, next/prev navigation)
/agent list	List all available agent templates
/delegate <prompt>	Delegate a prompt to a temporary subagent
/fork_and <prompt>	Fork current session and run a prompt in a new subagent
/config [show|get|set|keys|wizard]	View or modify configuration from chat
/config menu [page]	Interactive config section browser (paginated)
/skills [page]	List available skills with interactive selection (paginated)
/pair <code>	Pair with TOTP code from browser
/repo	Show current repository status for this session
/repo <url|path>	Clone or associate a repository with this session
/repo forget	Remove repository association from session
/repo update	Manually fetch/pull the associated repository
/idea <description>	Log an idea to the backlog (invokes bl idea)
/session archives [KEY]	List session archives (optionally filtered by session key)
/session archive show ID	View archived session messages with pagination
/update	Pull, rebuild, and gracefully restart clawq
/debug_dump_chat	Dump session state to file and send as attachment
/bash <command>	Run a bash command (admin only)