Core¶
This section explains how CraftBot actually works: the concepts behind every task it runs, the interfaces you drive it from, the commands and providers it runs on, and the configuration that ties it together. Read it when you want to move from using the agent to understanding it: predicting what it will do, diagnosing what it did, and tuning how it behaves.
How the pieces fit¶
A trigger (your message, a schedule firing, a Telegram DM) wakes the agent loop, which routes it to the right session and runs one turn: the context engine assembles what the model sees (profile, memory, the task's event stream), a prompt asks the model to pick from the available actions, the actions execute, and the loop queues the next turn until the task (simple or complex) completes. Along the way, skills supply know-how, memory supplies recall, and everything the agent is and knows lives as plain files in its file system.
Concepts¶
-
The turn cycle: trigger → route → select actions → execute → continue. The page to read first.
-
Everything that wakes the agent (messages, schedules, platform events) and the durability guarantees behind it.
-
How messages route to the right conversation or running task, and how parallel work stays separate.
-
The agent's working record (every message, action, and result) and how the UI renders from it.
-
1,100+ registered actions, grouped in sets, selected per task. How availability is decided and execution works.
-
Packaged know-how the agent loads per task: 195 bundled, slash-invokable, and it can write its own.
-
Exactly what the model sees each turn, and the caching strategy that keeps costs down.
-
The prompt families behind routing and action selection, and the files (
SOUL.md,USER.md,FORMAT.md) that let you shape them. -
Local hybrid RAG: capture → nightly distillation → recall injected mid-task. What it remembers and how to correct it.
-
One-off and recurring scheduled tasks, and how fired schedules become agent work.
-
Delegated child agents that run pieces of a task in parallel and report back.
-
Portable agent profiles. Import a prebuilt persona in one click, or export your own configured agent.
-
The markdown files that are the agent's identity, knowledge, and workspace, and which ones you should edit.
-
Per-run log directories, subsystem tags, and the grep recipes for finding out what actually happened.
Task modes¶
How the loop behaves depends on the task's mode. Task modes maps the decision. Each mode then has a full reference: simple, complex, the system-initiated special workflows, and proactive, where the agent proposes work on its own.
Interfaces¶
CraftBot has two interfaces over one shared engine: the browser UI (the default: chat, live action panel, Living UI tabs, settings) and the CLI (terminal chat for scripting and headless machines). The UI layer page explains the shared architecture. Overview and comparison: Interfaces.
Commands¶
Slash commands work identically in both interfaces: built-in commands (/help, /provider, /mcp, /skill, ...), plus one command per invokable skill. CLI-anything is the skill that lets the agent drive desktop apps (GIMP, Blender, LibreOffice, and two dozen others) without you naming them. Overview: Commands.
Providers¶
The agent needs models: an LLM to think, and optionally vision, image-generation, and video-generation models. Thirteen providers are supported, switchable with one setting. See LLM providers, Vision & media models, and Subscription authentication for running on a ChatGPT or SuperGrok subscription instead of an API key. Overview: Providers.
Configuration¶
Everything above is tunable from one settings file plus a handful of purpose-specific configs. The map is at Configuration, the full reference at Settings, and agent-bundle manifests at Agent bundle config.
Next¶
- New here? Do the Quickstart first: these pages assume a running agent.
- Building something? The Learning path sequences this section by goal.
- Going deeper than concepts? Develop covers architecture and extension points.