copilot

Overview ¶

Package copilot – abort.go implements abort trigger detection for stopping active agent runs using natural language phrases in multiple languages.

Package copilot – access.go implements the access control system for DevClaw.

The bot does NOT respond to everyone by default. Only explicitly authorized contacts (or groups) can interact with the assistant.

Access levels:

• owner: Full control, can manage admins, workspaces, and settings
• admin: Can manage users, create workspaces, and use admin commands
• user: Can interact with the assistant normally
• blocked: Explicitly blocked, never receives a response

Default policy: "deny" — unknown contacts are silently ignored.

Package copilot – agent.go implements the agentic loop that orchestrates LLM calls with tool execution. The agent iterates: call LLM → if tool_calls → execute tools → append results → call LLM again, until the LLM produces a final text response with no tool calls.

Architecture:

• No fixed max turns — the loop runs until the LLM stops calling tools.
• Single run timeout (default: 600s = 10min) controls the whole run.
• Per-LLM-call safety timeout (5min) prevents individual hung requests.
• Reflection nudge every 15 turns for budget awareness.
• Auto-compaction on context overflow (up to 3 attempts).

Package copilot – agent_router.go implements agent routing based on channel, user, or group. This allows different agents with different models, instructions, and skill sets to handle messages from different sources.

Package copilot – agent_tools.go registers the agent_manage dispatcher tool for creating and managing agents (workspaces) via the AI.

Package copilot – apply_patch.go implements a robust multi-file patch applicator. This is based on the OpenClaw apply_patch tool, allowing the agent to make surgical edits to files without having to rewrite the entire file or use fragile bash/sed commands.

Package copilot implements the main orchestrator for DevClaw. Coordinates channels, skills, scheduler, access control, workspaces, and security to process user messages and generate LLM responses.

Package copilot – block_streamer.go implements progressive message delivery for channels. Instead of waiting for the full LLM response, text is coalesced into blocks and sent as they become available, giving the user near-real-time feedback as blocks become available.

Coalescing rules:

• Wait until at least MinChars are accumulated.
• Flush when MaxChars is reached or the idle timer fires.
• Always try to flush at a natural boundary (newline, sentence end).

Package copilot – browser_act.go implements unified browser actions for browser automation.

Package copilot – browser_snapshot.go implements accessibility tree snapshots and role reference generation for browser automation.

The accessibility tree provides a structured representation of the page that's easier for AI agents to understand and interact with. Role references (e1, e2, ...) provide stable element identifiers across multiple snapshots.

Package copilot – browser_tabs.go implements tab management tools for browser automation.

Package copilot – browser_tool.go implements a browser automation tool using Chrome DevTools Protocol (CDP). This allows the agent to navigate web pages, take screenshots, extract content, click elements, and fill forms.

Architecture:

Agent ──browser_navigate──▶ BrowserManager ──CDP──▶ Chrome/Chromium
Agent ──browser_screenshot──▶ BrowserManager ──CDP──▶ Screenshot → base64
Agent ──browser_content──▶ BrowserManager ──CDP──▶ DOM → text
Agent ──browser_click──▶ BrowserManager ──CDP──▶ Click element

The browser is launched lazily on first use and kept alive for the session. A configurable timeout prevents runaway browser sessions.

Package copilot – builtin_skills.go provides embedded skills that are included in the binary and loaded into the system prompt.

Package copilot – canvas_host.go implements an interactive HTML/JS canvas host. Allows the agent to generate HTML/JS content and serve it via a temporary local HTTP server for the user to interact with.

Use cases:

• Data visualization (charts, graphs)
• Interactive prototypes
• Mini-apps (calculators, forms)
• Rich output that exceeds chat formatting

Architecture:

Agent ──canvas_create──▶ CanvasHost ──HTTP──▶ user browser
Agent ──canvas_update──▶ CanvasHost (live-reload via SSE)
Agent ──canvas_list──▶ list of active canvases

Package copilot – codebase_tools.go implements codebase analysis tools: file tree indexing, code search (ripgrep), symbol extraction, and Cursor rules generator.

Package copilot – commands.go implements admin commands that can be executed via chat messages (WhatsApp, Discord, etc.).

Commands are prefixed with "/" and only available to admins/owners:

/allow <phone>           - Grant user access
/block <phone>           - Block a user
/unblock <phone>         - Unblock a user
/revoke <phone>          - Revoke user access
/admin <phone>           - Promote user to admin
/users                   - List all authorized users
/ws create <id> <name>   - Create a workspace
/ws delete <id>          - Delete a workspace
/ws assign <phone> <id>  - Assign user to workspace
/ws list                 - List all workspaces
/ws info [id]            - Show workspace details
/ws set <key> <value>    - Update current workspace setting
/group allow             - Allow current group
/group block             - Block current group
/group assign <ws_id>    - Assign current group to workspace
/skills list             - List installed skills
/skills defaults         - List available default skills
/skills install <n|all>  - Install default skills
/status                  - Show bot status
/help                    - Show available commands

Package copilot – compaction_pipeline.go implements a multi-strategy context compaction pipeline that proactively manages context window usage. Instead of waiting for overflow errors, the pipeline monitors context pressure and applies increasingly aggressive compaction strategies as usage grows.

Levels (cheapest → most expensive):

Collapse (70%)     → Truncate oversized tool results in-place
MicroCompact (80%) → Clear old tool result contents with placeholder
AutoCompact (93%)  → LLM-based summarization of conversation history
MemoryCompact (97%)→ Extract memories + summarize (preserves learnings)

Package copilot – compaction_safeguard.go provides safeguards for the context compaction process to ensure critical information is preserved when the conversation is summarized to free context window space.

Package copilot – config.go defines all configuration structures for the DevClaw Copilot assistant.

Package copilot – config_watcher.go polls config.yaml for changes and triggers hot-reload of safe-to-update fields without restarting the daemon.

Package copilot – context_engine.go defines the pluggable ContextEngine interface. A ContextEngine provides additional context layers that are injected into the system prompt alongside the core prompt composition.

The LegacyContextEngine wraps the existing PromptComposer behavior, making it possible to swap in alternative engines (RAG, vector search, code indexing, etc.) without modifying the prompt pipeline.

Package copilot — context_router.go routes incoming messages to the right palace wing based on (channel, external_id) context.

Sprint 1 (v1.18.0), per ADR-001 + ADR-007-v2:

When a message arrives from a channel (telegram, whatsapp, cli, mcp, ...), the context router decides which wing the resulting memory should be associated with. The decision uses a three-tier lookup:

1. EXPLICIT: the user (or a previous heuristic pass) mapped this (channel, external_id) pair to a wing in the channel_wing_map table. Confidence is whatever was recorded at mapping time (usually 1.0 for manual entries, 0.5-0.8 for heuristic ones).

2. HEURISTIC: no explicit mapping exists. The router guesses a wing based on user-configured patterns (HierarchyConfig.Heuristics). The binary ships zero defaults — all heuristics are opt-in via YAML. Confidence is 0.7 (constant). The guess is then persisted so subsequent messages skip straight to tier 1.

3. DEFAULT: neither explicit nor heuristic. Returns an empty wing, which propagates to wing=NULL in storage. This is a first-class citizen per ADR-006: legacy and default-off behavior both live here.

Retrocompat: the router NEVER returns an error. Every resolution path has a graceful fallback. Callers never need to handle "routing failed" — the worst case is a default (empty) wing which matches v1.17.0 behavior.

Feature flag: this router is safe to instantiate regardless of the palace-aware flag state. When the flag is off, callers simply don't invoke Resolve — the router sits idle. When on, Resolve is called at the start of each turn for each incoming message.

Package copilot – context_window_guard.go provides pre-run context window validation to prevent agent runs from starting with models that have insufficient context capacity.

Package copilot – coordinator.go implements a structured multi-agent coordination protocol with four phases:

Research     → parallel read-only workers gather information
Synthesis    → coordinator analyzes findings, creates specs
Implementation → workers execute specs (write operations)
Verification → workers test and validate changes

Each phase restricts worker tools to prevent unintended side effects (e.g., research workers cannot write files). This ensures safe parallel execution and clear separation of concerns.

Implements structured multi-agent coordination for complex tasks.

Package copilot – daemon_manager.go implements a process manager that lets the agent start, monitor, and control long-running background processes (dev servers, watchers, database engines, etc.) with ring-buffer output capture and health checking.

Package copilot – db.go provides the central SQLite database for DevClaw. A single devclaw.db file holds scheduler jobs, session history/meta/facts, and the audit log. The memory.db (FTS5/embeddings) and whatsapp.db (whatsmeow session) remain as separate databases.

Package copilot – db_hub_tools.go implements database hub management tools. These tools use the native Database Hub with Go drivers for better performance than the CLI-based db_tools.go tools.

Package copilot – db_migrate.go handles one-time migration of legacy JSON/JSONL/text data to the central devclaw.db SQLite database. After a successful migration, the old files are renamed to .bak.

Package copilot – db_tools.go implements database tools for querying PostgreSQL, MySQL, and SQLite databases. Uses CLI clients (psql, mysql, sqlite3) to avoid heavy driver dependencies.

Package copilot – destructive_tracker.go implements rate limiting and batch detection for destructive tools to prevent accidental mass deletions.

Package copilot – dev_utils.go implements developer utility tools: JSON formatting, JWT decoding, regex testing, base64 encode/decode, hashing, UUID generation, URL parsing, timestamp conversion, etc.

Package copilot – directives.go parses inline directives embedded in message bodies. Unlike standalone commands (e.g., "/think high"), inline directives can appear alongside regular text: "explain this /model gpt-4o /think high". This aligns with OpenClaw's inline directive system.

Package copilot – docker_tools.go implements native Docker tools for container management, image operations, and compose integration.

Package copilot – dream.go implements the Dream System, a background consolidation process that runs when the daemon is idle. It analyzes accumulated memories, detects contradictions, merges duplicates, and produces consolidated summaries — similar to how sleep consolidates learning in biological systems.

The Dream System uses a 3-gate trigger:

• Gate 1: Minimum time since last dream (default: 6 hours)
• Gate 2: Minimum sessions since last dream (default: 2)
• Gate 3: File lock to prevent concurrent dreams

Phases: Orient → Gather → Consolidate → Apply

Package copilot – env_tools.go implements system information and network diagnostic tools: port scanning, environment info, and process listing.

Package copilot – events.go implements an in-memory pub/sub event bus for agent lifecycle events. Replaces channel-based buffering with fan-out to multiple listeners, each receiving events via direct function call.

Event streams:

• "lifecycle": run_start, run_end, abort
• "assistant": delta (text tokens), thinking_start, thinking_delta, thinking_end
• "tool": tool_use, tool_result
• "error": agent errors, LLM errors

Package copilot – exec_analysis.go implements command risk analysis for bash/exec tool calls. Commands are categorized by risk level and appropriate actions are taken (allow, log, require approval, deny).

Package copilot – exec_approval.go implements interactive approval for tools that require confirmation before execution (e.g. bash, ssh, write_file).

Package copilot – failover_coordinator.go provides a unified coordinator for profile authentication and model failover. This replaces the fragmented approach of 3 independent systems (profile cooldown, model failover, LLM inline cooldown) with a single consistent error classification and response strategy.

Package copilot – git_tools.go implements native Git tools that provide structured JSON output for the agent, enabling better decision-making without parsing raw text. Uses os/exec to call git directly.

Package copilot – group_chat.go implements enhanced group chat features Activation modes, intro messages, context injection, participant tracking, and quiet hours.

Package copilot – group_policy.go implements group-specific policies including activation modes, quiet hours, and access control for groups.

Package copilot – heartbeat.go implements a periodic heartbeat that checks for pending scheduled jobs, reads HEARTBEAT.md for custom checklists, and triggers proactive agent turns that can send messages to channels.

Package copilot – hooks.go implements a lifecycle hook system. Hooks allow external code to observe and optionally modify agent behavior at well-defined points in the lifecycle.

Hook events include:

SessionStart      — A new session is created or restored.
SessionEnd        — A session is about to be pruned/deleted.
UserPromptSubmit  — User message received, before processing.
PreToolUse        — Before a tool is called (can block/modify).
PostToolUse       — After a tool returns (observe/log).
AgentStart        — Agent loop is about to begin.
AgentStop         — Agent loop finished (normal or error).
SubagentStart     — A subagent has been spawned.
SubagentStop      — A subagent has finished.
PreCompact        — Before session compaction.
PostCompact       — After session compaction.
MemorySave        — A memory was saved.
MemoryRecall      — Memories were recalled for prompt.
Notification      — An outbound notification/message is being sent.
Heartbeat         — Periodic heartbeat tick.
Error             — An unrecoverable error occurred.

Package copilot – ide_extensions.go provides configuration generators for IDE extensions: VSCode, JetBrains, and Neovim. These generate the necessary config files for connecting to DevClaw's MCP server.

Package copilot – identity.go resolves the assistant's identity from multiple sources: agent profile, IDENTITY.md file, config, or defaults.

Package copilot – keyring.go provides secure credential storage using the operating system's native keyring (Linux: Secret Service/GNOME Keyring, macOS: Keychain, Windows: Credential Manager).

Priority for resolving secrets:

1. Encrypted vault (.devclaw.vault — AES-256-GCM + Argon2, requires master password)
2. OS keyring (encrypted by the OS, requires user session)
3. Environment variable (DEVCLAW_API_KEY, OPENAI_API_KEY, etc.)
4. .env file (loaded by godotenv)
5. config.yaml value (least secure — plaintext on disk)

Package copilot – lanes.go implements a lane-based concurrency system. Each lane has its own queue and concurrency limit, preventing contention between different types of work (sessions, cron, subagents).

Lane types:

• session:{id} — one lane per session, maxConcurrent=1 (serialized)
• global — shared lane for cross-session work, maxConcurrent=3
• cron — scheduled jobs, maxConcurrent=2
• subagent — subagent runs, maxConcurrent=8

Package copilot – lcm.go is the coordinator for the Lossless Compaction Module. It ties together store, compactor, assembler, and retrieval into a single engine.

Package copilot – lcm_assembler.go builds the model's context window from the LCM DAG (root summaries + fresh tail messages), with budget-aware eviction.

Package copilot – lcm_compaction.go implements the DAG-based compaction engine for the Lossless Compaction Module. Two passes: leaf (messages → summaries) and condensed (summaries → higher-level summaries), cascading until stable.

Package copilot – lcm_retrieval.go provides the retrieval operations for the LCM tool: grep (FTS + regex), describe (inspect DAG), expand (recover messages).

Package copilot – lcm_store.go provides SQLite CRUD operations for the Lossless Compaction Module (LCM). All message and summary data lives in the central devclaw.db database.

Package copilot – lcm_tools.go registers the `lcm` dispatcher tool with three actions: grep, describe, expand. Follows the same pattern as RegisterSessionsDispatcher in session_tools.go.

Package copilot – legacy_aliases.go registers dispatcher tools that route to individual tools based on the "action" parameter. The memory, vault, and scheduler dispatchers are the PRIMARY visible tools; individual tools are hidden but callable. skill_manage remains hidden.

Package copilot – link_understanding.go extracts URLs from messages and enriches them with readable content before passing to the agent. This aligns with OpenClaw's link understanding pipeline.

Package copilot – llm.go implements the LLM client for chat completions with function calling / tool use support. Uses the OpenAI-compatible API format, which works with OpenAI, Anthropic proxies, GLM (api.z.ai), and any compatible endpoint.

Package copilot – loader.go handles loading configuration from YAML files with secure credential management via environment variables and .env files.

Package copilot – maintenance_manager.go manages maintenance mode state.

Package copilot – markdown.go converts standard Markdown to channel-specific formats. WhatsApp supports a limited subset; other channels may get plain text or passthrough.

Package copilot – mcp_manager.go implements MCP (Model Context Protocol) server management including listing, adding, editing, removing, and testing MCP connections.

Package copilot – mcp_tools.go bridges MCP (Model Context Protocol) servers with the ToolExecutor, allowing the LLM to call tools exposed by external MCP servers as if they were native DevClaw tools.

Workflow:

1. For each enabled+auto_start MCP server, launch the process (stdio) or connect to the endpoint (SSE/HTTP).
2. Send tools/list to discover available tools.
3. Register each tool in the ToolExecutor with a handler that forwards tool calls via MCP's tools/call JSON-RPC.
4. On shutdown, send a graceful close and terminate processes.

Currently supports stdio transport (most common for MCP).

Package copilot – media_enrichment.go handles extraction of content from documents (PDF, DOCX, TXT) and video frames for enriching agent prompts.

Package copilot – media_registry.go provides a multi-provider registry for media processing (vision and transcription) with priority-based fallback.

Package copilot – media_tools.go registers tools for image understanding (describe_image), audio transcription (transcribe_audio), and the unified send_media tool for sending images, audio, video, and documents.

Package copilot — memory_categorizer.go classifies memory content into categories (event, summary, preference, fact) using keyword patterns. Zero LLM calls — pure regex matching in PT and EN.

Package copilot – memory_extractor.go extracts structured memories from conversation history before context compaction. This preserves valuable information (decisions, preferences, facts, learnings) that would otherwise be lost when messages are summarized or discarded.

Pattern: extract valuable information first, then compact safely knowing nothing important is lost.

Package copilot – memory_hardening.go implements security hardening for memory content that is injected into LLM prompts. Memories are treated as untrusted historical data and sanitized to prevent prompt injection.

Security pattern:

• Escape HTML entities in memory content
• Wrap memories in <relevant-memories> tags with untrusted data warning
• Detect and reject auto-capture of prompt injection patterns
• Only capture from user-role messages

Package copilot — memory_hierarchy_config.go holds the Sprint 1 (v1.18.0) palace-aware feature flag config and observability scaffolding.

The config lives in its own file so config.go stays focused on core memory configuration. One line in config.go's MemoryConfig struct pulls HierarchyConfig in.

Metric emission follows the devclaw convention of structured slog lines with a known prefix. A log aggregator (fluent-bit, vector, loki) can scrape these into Prometheus time series without DevClaw needing a direct Prometheus dependency.

Metric naming convention (dot-separated, matching ADR-008):

memory.context_router.confidence      histogram bucket counter
memory.search.wing_filter_usage       counter labeled {on, off, fallback}
memory.hierarchy.enabled              gauge (0 or 1)
memory.layer_tokens                   histogram labeled {layer=L0|L1|L2}

All metrics are emitted via slog at INFO level with a "metric" attribute equal to the metric name and a "value" attribute equal to the data point. Zero external dependencies.

Package copilot — memory_hierarchy_tools.go registers the palace-aware memory tools introduced in Sprint 1 (v1.18.0).

These tools are ADDITIVE: they extend the existing memory toolset (memory_save, memory_search, memory_list, memory_index) with five new focused tools that expose the wing/room hierarchy and the context router.

The tools are registered separately from the core memory tools so that:

• The core set continues to work when hierarchy is disabled
• Enabling/disabling hierarchy is a single call site change
• Tests can register one set without the other

Feature flag: each tool checks cfg.Enabled before doing any work. When disabled, the tool is still registered (so the LLM discovers it), but returns a helpful error explaining that the feature is off. This is better UX than hiding the tool entirely — the LLM learns the capability exists and the user can opt in.

New tools added in this file:

memory_list_wings       — enumerate wings with counts
memory_list_rooms       — enumerate rooms inside a wing
memory_get_taxonomy     — full wing → rooms tree
memory_wing_pin         — pin (channel, chatID) → wing mapping
memory_wing_unpin       — remove a pinned mapping
memory_wing_status      — show current wing for a channel/chat

NOT added in this PR (deferred):

• memory_save wing/room params — requires rerouting markdown file path into wing subdirectories, which is a larger change. Sprint 1 PR #4+.
• memory_search wing filter — requires wing boost in hybrid fusion, which affects score semantics. Sprint 2.
• memory_wing_merge / memory_room_merge — bot commands first, see PR #4.

The deferral is intentional: PR #3 adds the taxonomy/routing primitives without touching the hot path of save/search. This keeps retrocompat airtight while delivering user-visible functionality.

Package copilot – memory_indexer.go provides background memory indexing.

Package copilot — memory_stack.go implements Sprint 2 Room 2.4's MemoryStack: the composer that assembles the layered memory system (L0 Identity + L1 Essential + L2 OnDemand) into a single prompt prefix that buildMemoryLayer prepends to the legacy L3 output.

Design principles (do not revise without an ADR):

1. Stack-over-legacy: the stack NEVER rewrites buildMemoryLayer. It renders a prefix that is prepended. When the stack is nil or all layers return empty, buildMemoryLayer is byte-identical to v1.18.0. This is the retrocompat gate — enforced by the golden fixture test in prompt_layers_golden_test.go.

2. L0-never-trimmed: the Identity layer is the user's anchor. It is ALWAYS rendered in full, even when it exceeds the total byte budget. Rationale: a 50-byte identity blurb that the user curated themselves is never the reason a prompt is over-budget, and losing it silently breaks persona continuity across turns. If the caller provides an unusually large identity file, the stack logs a WARN but still includes it.

3. Trim priority L2 > L1 > L0 (trim L2 first, L1 second, L0 never). L2 is ephemeral per-turn context; L1 is the per-wing story summary; L0 is the user's persona anchor.

4. Panic isolation: a layer that panics is caught, logged, and its contribution becomes the empty string. The remaining layers still render and the prompt is still produced. No single bad layer can prevent the assistant from answering.

5. Context cancellation short-circuits: a pre-cancelled context returns "" without touching any layer. This keeps the hot path responsive when the caller has already given up.

The stack has zero dependencies on the legacy memory path. It reads the three Room 2.1/2.2/2.3 layers via interfaces so tests can inject mocks that panic, sleep, or return large payloads.

Package copilot – memory_tools.go implements individual memory tools. Each tool has a focused schema with only the parameters it needs, eliminating the ambiguity of the dispatcher pattern.

Package copilot – message_queue.go handles message bursts with debouncing. When a session is already processing, incoming messages are queued and combined after a debounce period.

Package copilot – message_split.go provides splitting of long messages for channels with character limits (e.g. WhatsApp 4096).

Package copilot – metrics_collector.go provides background metrics collection.

Package copilot – model_failover.go implements automatic model failover with cooldowns and reason classification. When the primary LLM returns persistent errors, the system rotates through fallback models automatically.

Package copilot – multiuser.go implements multi-user support with user management, role-based access control, shared memory spaces, and team collaboration features.

Package copilot – ops_tools.go implements operations tools for deploy pipeline execution, server health monitoring, and tunnel management.

Package copilot – pairing.go implements the DM pairing system for secure access onboarding.

The pairing system allows admins to generate shareable tokens that new users can send to the bot to request access. Tokens can be configured for:

• Auto-approval (immediate access) or manual approval
• Expiration time
• Maximum number of uses
• Role to grant (user or admin)
• Workspace assignment

Package copilot — palace_bot_commands.go parses and handles slash commands for palace-aware memory operations directly, without invoking the LLM.

This is a pre-agent text parser: the assistant (or channel router) can call HandlePalaceBotCommand at the start of message processing. If the command is handled, the reply is returned directly and the LLM is never invoked. If the input is not a palace command, handled=false and the message continues through the normal LLM path.

Supported commands (all slash-prefixed):

/wing                          Show current wing for this chat
/wing list                     List all wings with counts
/wing set <name>               Pin this chat to <name>
/wing unset                    Remove the pin
/wing merge <from> <to>        Merge one wing into another
/room                          Show rooms in the current chat's wing
/room list [wing]              List rooms (filtered by wing if given)
/tree                          Show full palace taxonomy
/palace help                   Show help text

Design notes:

• All commands check the HierarchyConfig.Enabled flag. When off, they reply with a "disabled" message that tells the user how to enable.
• Commands that modify state (set, unset, merge) call through the ContextRouter and SQLiteStore. Read-only commands go directly to the store.
• Responses are plain text suitable for Telegram/WhatsApp rendering. No markdown escaping needed because channels re-escape on send.
• Bot commands never wait for LLM provider I/O, so they're cheap and fast — good for rapid iteration on wing config.

Per Sprint 0.5 critic feedback MAJOR-5: the `/wing merge` command MUST ship in Sprint 1 (was originally planned for Sprint 4 WebUI) because users in Telegram/WhatsApp have no other way to fix wing duplicates.

Package copilot – product_tools.go implements product management tools: project management API integration (Jira, Linear), sprint reporting, documentation sync (Notion/Confluence), and DORA metrics calculation.

Package copilot – project.go implements the ProjectManager for managing development projects. Provides project registration, activation, auto-detection of language/framework, and per-session project context.

A "project" maps to a filesystem directory (typically a git repo root) with associated metadata like language, framework, build/test/lint commands, and MCP server configurations.

Package copilot – project_adapter.go provides an adapter that bridges copilot.ProjectManager to skills.ProjectProvider, breaking the import cycle between the two packages.

The adapter converts between copilot.Project and skills.ProjectInfo structs which have the same shape but live in different packages.

Package copilot – prompt_layers.go implements the layered system prompt Each layer has a priority and contributes to the final prompt that is sent to the LLM as the system message.

Bootstrap files (SOUL.md, AGENTS.md, IDENTITY.md, USER.md, TOOLS.md) are loaded from the workspace root and injected as "Project Context". If SOUL.md is present, the agent is instructed to embody its persona.

Package copilot – provider_discovery.go implements optional, non-blocking discovery of locally-hosted LLM providers (Ollama, vLLM).

During startup, the assistant can probe known endpoints to discover available models and their context window sizes. This information supplements the static getModelContextWindowByName() lookup, allowing DevClaw to use correct settings for custom or fine-tuned local models.

Package copilot – queryloop.go defines the Phase-based query loop architecture. This extracts the conceptual phases from the monolithic agent.go Run() method into composable, testable units.

The existing Run() method continues to work unchanged. This module provides the interfaces and orchestrator for incremental migration to phased execution.

Phases:

Prepare   → build messages, resolve tools, load context
APICall   → call LLM with streaming/non-streaming
ToolExec  → execute tool calls from LLM response
Decision  → decide: tool_use → loop back, text → proceed to stop
StopCheck → verify completion before returning

Package copilot – queue_modes.go implements configurable queue modes that control how the agent handles incoming messages while a session is busy. Supports: collect, steer, followup, interrupt, steer-backlog.

Package copilot – scheduler_tools.go implements scheduler tools for managing scheduled tasks and reminders: scheduler_add, scheduler_list, scheduler_remove, and scheduler_search.

session.go implementa o gerenciamento de sessões isoladas por chat/grupo. Cada grupo ou DM possui sua própria sessão com memória, skills ativas e configurações independentes.

Package copilot – session_lock.go implements cross-process session write locks using advisory file locking. This prevents two DevClaw processes from writing to the same session simultaneously, which could corrupt session state.

Architecture:

• Lock file: <sessions_dir>/<session_id>.lock
• Contains JSON: {"pid": <PID>, "acquired_at": "<RFC3339>"}
• Uses syscall.Flock for advisory locking (safe on Linux/macOS)
• Watchdog goroutine refreshes the lock file mtime every 60s
• Stale detection: locks older than 30 min are considered abandoned

session_persistence.go implements disk persistence for sessions using JSONL format.

Package copilot – session_persistence_sqlite.go implements session persistence backed by the central devclaw.db SQLite database. It is a drop-in replacement for the JSONL-based SessionPersistence.

Package copilot – session_reaper.go periodically removes stale persisted sessions that haven't been active within a configurable time window. This prevents unbounded storage growth from long-lived deployments.

Package copilot – session_tools.go implements the sessions dispatcher tool. Uses dispatcher pattern to consolidate 4 session tools into 1.

Package copilot - settings.go manages application settings stored separately from config. This includes tool profiles and other infrequently-changed settings.

Package copilot – skill_creator.go implements tools that allow the agent to create, edit, and manage skills via chat. Skills are created as ClawdHub-compatible SKILL.md files in the workspace skills directory.

The agent can use these tools to:

• Initialize a new skill with a SKILL.md template
• Edit an existing skill's instructions
• Add scripts (Python, Node, Shell) to a skill
• List installed skills
• Test a skill by executing it

Package copilot – skill_db.go provides a database system for skills. It allows skills to store structured data in a dedicated SQLite database without requiring users to know SQL or create scripts.

Each skill can have multiple tables. Table names are automatically prefixed with the skill name to ensure isolation (e.g., "crm_contacts" for skill "crm").

Package copilot – skill_db_tools.go registers individual skill database tools that allow the agent to store and retrieve structured data.

Package copilot – skill_watcher.go watches skill directories for SKILL.md changes and increments the PromptComposer's skills version to invalidate the cached skills layer. This replaces TTL-based refresh with event-driven invalidation, matching the OpenClaw chokidar pattern.

Package copilot provides startup verification for DevClaw. Checks vault, database, channels, and system dependencies.

Package copilot – stop_hooks.go implements pre-stop completion verification. Before the agent stops, these hooks analyze the conversation to detect incomplete work patterns (e.g., files edited but tests not run, code written but not compiled). If incomplete work is detected, the hook can inject a continuation message to prompt the agent to finish.

Pattern: verify completion before allowing the agent to stop, preventing premature task completion.

Package copilot – subagent.go implements a subagent system that allows the main agent to spawn independent child agents to handle tasks concurrently.

Architecture:

Main Agent ──spawn_subagent──▶ SubagentManager ──goroutine──▶ Child AgentRun
                                   │                              │
                                   ▼                              ▼
                            SubagentRegistry           (runs with own session,
                            tracks runs + results       limited tools, separate
                                                        prompt, optional model)

Subagents:

• Run in isolated goroutines with their own session context.
• Cannot spawn nested subagents (no recursion).
• Have a configurable subset of tools (deny list applied).
• Results are collected and can be polled or waited on.
• Are announced back to the parent session when complete.

Package copilot – techops_commands.go implements administrative commands for remote operations. These commands allow operators to manage the system via chat channels without SSH access.

Package copilot – system_tools.go registers built-in tools that are always available to the agent, independent of skills. These tools provide core capabilities like shell execution, file I/O, memory operations, and scheduling.

Package copilot – techops_types.go provides data structures for TechOps commands.

Package copilot – tailscale.go implements Tailscale Serve/Funnel integration for secure remote access to DevClaw's web services.

Tailscale Serve proxies HTTPS traffic from the Tailscale network to a local port. Tailscale Funnel extends this to the public internet with automatic TLS certificates.

Provides secure remote access without manual port forwarding, dynamic DNS, or certificate management.

Architecture:

Internet ──HTTPS──▶ Tailscale Funnel ──▶ Local DevClaw (e.g. :8085)
Tailnet  ──HTTPS──▶ Tailscale Serve  ──▶ Local DevClaw (e.g. :8085)

Package copilot – testing_tools.go implements a testing engine that wraps common test runners and provides tools for running tests, API testing, and generating test reports.

Package copilot – tool_executor.go manages a registry of callable tools and dispatches tool calls from the LLM to the appropriate handlers. Tools can be registered from skills, system built-ins, or plugins.

Package copilot – tool_guard.go implements a security layer that controls which tools can be used, by whom, and under what conditions.

Security features:

• Tool-level access control (owner/admin/user)
• Destructive command detection and blocking
• Sensitive path protection
• SSH host allowlist
• Full audit logging of every tool execution
• Configurable confirmation for dangerous operations

Package copilot – tool_guard_audit_sqlite.go provides a SQLite-backed audit logger for the ToolGuard. It writes tool execution records to the audit_log table in the central devclaw.db and auto-prunes entries older than 30 days.

Package copilot – tool_loop_detection.go detects when the agent enters a tool call loop (repeating the same call with no progress) and triggers circuit breakers to prevent infinite loops.

Four detectors:

• Generic repeat: same tool+args hash repeated N times
• Ping-pong: alternating between two tool calls
• Known no-progress poll: tools that poll external state without progress
• Global circuit breaker: total no-progress calls across all patterns

Package copilot – tool_mutation.go classifies tool calls as mutating vs read-only. Aligned with OpenClaw's tool-mutation.ts pattern. Used for: - More granular error reporting (warn only on mutating tool errors) - Action fingerprinting for deduplication

Package copilot – tool_outcomes.go implements a per-turn, thread-safe log of tool execution outcomes used for structural provenance checks.

The memory layer uses this log to reject fact saves whose content echoes a tool call that failed earlier in the same turn AND for which no later successful call on the same subject has been observed. This replaces the keyword-based access-failure filter with a locale-agnostic, content-signal-free mechanism: all decisions derive from the tool error flag, ordering, and generic token overlap.

Package copilot – tool_profiles.go implements predefined tool permission profiles. Profiles simplify tool configuration by providing presets for common use cases.

Package copilot – tool_result_truncation.go provides two-layer tool result truncation to prevent context overflow while preserving important content.

Layer 1 (per-result): Smart head+tail truncation that detects error summaries, JSON closing brackets, and other important content at the end of tool results.

Layer 2 (pre-LLM context guard): Caps individual tool results and compacts oldest tool results when total content exceeds the context budget.

Package copilot – transcript_policy.go defines per-provider transcript sanitization policies. Different LLM providers have different requirements for message format, turn ordering, and content types. This policy system ensures that the conversation transcript is compatible with each provider before sending.

Package copilot – typing_controller.go provides a lifecycle-aware typing indicator controller that replaces the simple goroutine+ticker pattern.

State machine:

Started → Active → RunComplete → DispatchIdle → Sealed

• Started: Controller created, not yet sending.
• Active: Ticker running, sending typing indicators at regular intervals.
• RunComplete: Agent execution finished; if block streamer is still dispatching buffered output we keep typing active for a grace period.
• DispatchIdle: Block streamer has finished; typing stops but can be restarted if a followup run begins within the grace window.
• Sealed: Terminal state; no further typing will be sent.

The controller also enforces a TTL so a stuck agent cannot send typing indicators indefinitely.

Package copilot – usage_tracker.go records LLM token usage and estimated costs per session and globally.

Package copilot – vault.go provides encrypted credential storage using AES-256-GCM with Argon2id key derivation. Secrets are stored in a local file (.devclaw.vault) that is unreadable without the master password.

Even if someone has filesystem access, the vault contents remain encrypted. The master password is never stored — only a derived key is used in memory.

Package copilot – vault_tools.go implements individual vault tools. Each tool has a focused schema with only the parameters it needs.

Package copilot – web_fetch_readability.go provides HTML-to-text conversion and an in-memory LRU cache for web_fetch results.

Package copilot – webhooks.go implements external webhook support for hooks. Webhooks allow sending hook events to external HTTP endpoints.

Package copilot – workspace.go implements the multi-tenant workspace system.

Workspaces (also called "profiles") allow multiple people to use the same WhatsApp number with completely isolated contexts:

• Each workspace has its own system prompt, skills, model, and language
• Each workspace has its own session store (isolated conversation memory)
• A workspace can be assigned to specific users (JIDs) or groups
• One user can belong to one workspace at a time
• There is always a "main" workspace for unassigned users

Example use cases:

• Personal workspace: your own assistant with custom instructions
• Team workspace: shared context for a project team
• Client workspace: different personality/language per client
• Testing workspace: experimental settings without affecting production

Package copilot – workspace_containment.go implements workspace path containment and symlink escape protection for file operations.

All file tools (read_file, write_file, edit_file, apply_patch) must call AssertSandboxPath before performing any I/O to ensure the resolved path is within the workspace root.