Core Concepts
Relevant source files
The following files were used as context for generating this wiki page:
Clawdbot is an AI-integrated personal assistant framework designed to orchestrate specialized agents, manage complex workflows through modular "Skills," and maintain stateful sessions across various messaging channels. The system operates on the principle of "Progressive Disclosure," ensuring that the AI context remains efficient by loading detailed information only when triggered.
At its heart, Clawdbot functions as a runtime for AI simulators, where detailed system prompts and structured instructions (such as those in OpenProse) transform a general-purpose model into a specialized entity capable of performing technical tasks like coding, document manipulation, and server management.
Sources: CLAUDE.md, skills/skill-creator/SKILL.md:6-14, extensions/open-prose/skills/prose/SKILL.md:6-10
Modular Capabilities: Skills
Skills are self-contained packages that extend Clawdbot's procedural knowledge and tool integration. They act as "onboarding guides" for specific domains, allowing the agent to handle tasks it might not natively possess deep heuristics for.
Skill Anatomy
A skill is defined by a specific directory structure centered around a mandatory SKILL.md file.
| Component | Requirement | Description |
|---|---|---|
SKILL.md | Required | Contains YAML frontmatter (name/description) and Markdown instructions. |
scripts/ | Optional | Executable code (Python/Bash) for deterministic or repetitive tasks. |
references/ | Optional | Detailed documentation (schemas, API docs) loaded into context only when needed. |
assets/ | Optional | Templates, images, or boilerplate files used in the agent's output. |
Sources: skills/skill-creator/SKILL.md:33-45
Progressive Disclosure
To preserve the context window, Clawdbot employs a three-level loading system:
- Metadata: The name and description are always in context to allow the agent to decide when to trigger a skill.
- Body: The instructions within
SKILL.mdare loaded only after the skill triggers. - Resources: Scripts and references are accessed on-demand by the agent during task execution.
Sources: skills/skill-creator/SKILL.md:85-95
The diagram shows the logic of context management where detailed data is withheld until a specific skill is activated.
Sources: skills/skill-creator/SKILL.md:85-115
Agent Orchestration and Runtime
Clawdbot manages agents through a robust system prompt architecture and a hierarchical session model.
System Prompt Architecture
The system prompt is dynamically constructed based on the agent's role (main agent vs. sub-agent). It includes mandatory sections for tooling, workspace configuration, and messaging constraints. Key segments include:
- Tooling: Lists available tools (e.g.,
read,write,exec,web_search). - Workspace: Defines the working directory as the "single global workspace."
- Runtime: Identifies the specific agent ID, host, OS, and model.
- Silent Replies: Instructs agents to respond with a specific token (
🦞) when no action is needed.
Sources: src/agents/system-prompt.ts:208-270, src/agents/system-prompt.ts:474-478
Sub-agent Spawning
For complex tasks, agents can spawn sub-agents (often via the sessions_spawn tool). This allows for parallelization, such as reviewing multiple Pull Requests simultaneously. Sub-agents operate in a "minimal" prompt mode to reduce context overhead.
Sources: src/agents/system-prompt.ts:275-278, skills/coding-agent/SKILL.md:104-120
The sequence shows how an orchestrator delegates tasks to sub-agents who perform filesystem operations before reporting back.
Sources: src/agents/system-prompt.ts:16-25, extensions/open-prose/skills/prose/SKILL.md:12-16
Session Context and Persistence
Persistence is managed through "Agent Memory" and state bindings.
Context Layers
When an agent session begins, it processes context in a specific layering order:
- Outer Agent State: Context from the parent agent or orchestrating VM.
- Persistent Memory: The agent's own accumulated knowledge from prior segments (stored in
memory.md). - Task Context: The specific input for the current session.
Sources: extensions/open-prose/skills/prose/primitives/session.md:19-60
Memory Compaction
To avoid context bloat, agents perform "compaction" rather than summarization. This involves preserving specific locations (e.g., filenames/line numbers) and exact findings while dropping reasoning chains and redundant information.
| Action | What to Preserve | What to Drop |
|---|---|---|
| Compaction | Specific line numbers, exact error findings, rationale. | Reasoning chains, false starts, verbose quotes. |
Sources: extensions/open-prose/skills/prose/primitives/session.md:133-165
Workspace and Tooling
Clawdbot enforces a "bash-first" approach for coding agents, requiring a Pseudo-Terminal (PTY) for interactive CLI applications like Codex or Claude Code.
Tool Execution Modes
- PTY Mode: Mandatory for interactive agents to prevent broken output or hanging.
- Background Mode: Allows agents to run long tasks while returning a
sessionIdfor monitoring. - Sandbox: Most tools execute within a Docker sandbox unless "elevated" access is explicitly granted.
Sources: skills/coding-agent/SKILL.md:10-30, src/agents/system-prompt.ts:315-345
Messaging and Channels
Clawdbot handles routing across multiple channels (Discord, Slack, Telegram, Signal) internally. Agents are prohibited from using external tools (like curl) for messaging; they must use the built-in message tool to ensure allowlists and routing logic are respected.
Sources: CLAUDE.md:12-20, src/agents/system-prompt.ts:80-95
Conclusion
Clawdbot's core concepts revolve around the efficient management of AI context through modular skills, hierarchical agent orchestration, and structured session persistence. By utilizing a "Prose Complete" simulation environment and strict tool-use protocols, it enables complex, multi-agent workflows that remain technically accurate and contextually lean.
Sources: extensions/open-prose/skills/prose/SKILL.md:6-10, skills/skill-creator/SKILL.md:16-25