Agent runtime for the CleanSlice ecosystem. Define an agent as files, connect it to channels (Telegram, Slack), and let it use tools — all powered by a pluggable LLM backend.
Prerequisites:Bun installed.
git clone https://github.com/CleanSlice/runtime.git
cd runtime
bun installbun run cli initThis copies .agent.example/ into .agent/, creating all required files and an agent.config.json with default settings. If .agent.example/ doesn't exist, a minimal scaffold is created from built-in templates.
cp .env.example .envFill in the required values:
| Variable | Required | Description |
|---|---|---|
TELEGRAM_BOT_TOKEN | yes | Bot token from @BotFather |
TELEGRAM_BOT_NAME | yes | Bot username (without @) |
TELEGRAM_BOT_ADMIN_IDS | yes | Comma-separated Telegram user IDs |
CLAUDE_CODE_OAUTH_TOKEN | yes | Anthropic OAuth token (supports comma-separated list for rotation) |
LLM_MODEL | no | Model to use (default: claude-sonnet-4-6) |
LLM_FALLBACK_MODEL | no | Fallback model (default: claude-haiku-4-5) |
LLM_AUX_MODEL | no | Auxiliary model for background work (compaction, memory flush). Defaults to main LLM when unset. |
LLM_AUX_PROVIDER | no | Auxiliary provider — defaults to main provider. |
LLM_AUX_API_KEY | no | Auxiliary API key — defaults to main key. |
LLM_AUX_FALLBACK_MODEL | no | Auxiliary fallback model. |
SLACK_BOT_TOKEN | no | Slack bot token |
SLACK_APP_TOKEN | no | Slack app token |
SECRET_PROVIDER | no | file (dev) or aws (prod) |
CLEANSLICE_AGENT_DIR | no | Override default .agent directory |
bun run start # production
bun run dev # development (auto-reload on file changes)An agent is just files:
.agent/
├── SOUL.md ← who the agent is
├── USER.md ← who it works with
├── MEMORY.md ← what it remembers
├── HEARTBEAT.md ← periodic tasks to run
├── agent.config.json ← runtime configuration
├── skills/ ← pluggable skills
├── data/ ← cron jobs, secrets
├── sessions/ ← conversation history (JSONL)
└── memory/ ← long-term memory storage
The runtime brings those files to life. It handles channels, LLM calls, tool execution, sessions, cron, and heartbeat — all configured through agent.config.json.
All runtime settings live in .agent/agent.config.json. You only need to specify values you want to override — everything has sensible defaults.
On first run, the runtime automatically:
- Checks if
.agent/exists and is initialized - If not — copies all files from
.agent.example/(includingagent.config.json) - Creates required subdirectories (
data/,sessions/,memory/,skills/)
This means you can customize .agent.example/ in your repo as a template for new deployments.
| File | Purpose | Required |
|---|---|---|
SOUL.md | Agent personality and behavior rules | yes |
USER.md | Context about the user the agent serves | yes |
MEMORY.md | Long-term memory (agent writes here) | yes |
HEARTBEAT.md | Periodic tasks — agent checks this on every heartbeat | no |
agent.config.json | Runtime configuration (see above) | no (defaults used) |
skills/<name>/SKILL.md | Pluggable skills activated by keywords in user messages | no |
The CLI provides commands for managing the agent from the terminal.
bun run cli <command> [options]| Command | Description |
|---|---|
init | Scaffold a new .agent directory |
start | Start the agent runtime (foreground) |
status | Show agent directory status and health |
cron | Manage scheduled jobs |
memory | View or clear agent memory |
sessions | List or clear conversation sessions |
skills | List or inspect loaded skills |
version | Show version |
bun run cli init [--dir <path>]Creates the .agent/ directory with all required files. If .agent.example/ exists in the project root, copies files from there. Otherwise creates from built-in templates.
bun run cli start [--dir <agent-dir>]Starts the runtime in the foreground. Equivalent to bun run start but allows overriding the agent directory.
bun run cli statusShows a dashboard of agent health: which files exist, how many sessions/cron jobs are active, which environment variables are set.
bun run cli cron list
bun run cli cron add --name "Daily digest" --schedule "0 9 * * *" --message "Send morning digest" [--to <chat_id>] [--channel telegram] [--tz Europe/Kiev]
bun run cli cron remove <id>
bun run cli cron enable<id>
bun run cli cron disable <id>Manage cron jobs stored in .agent/data/cron.json. Jobs are picked up by the runtime and executed on schedule.
bun run cli memory show # print MEMORY.md
bun run cli memory clear # reset MEMORY.mdbun run cli sessions list # list all sessions with message counts
bun run cli sessions clear # delete all session filesbun run cli skills list # list loaded skills
bun run cli skills show <name># print SKILL.md for a skill| Option | Description |
|---|---|
--help, -h | Show help for any command |
--version, -v | Show version |
CLEANSLICE_AGENT_DIR | Env var to override default .agent directory |
┌─────────────────────────────────────────────────────┐
│ Channels │
│ Telegram · Slack · Discord · API │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ Agent Runtime │
│ │
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ │
│ │ Init │ │ LLM │ │ Tools │ │
│ │ config │ │ Claude │ │ exec │ │
│ │ bootstrap│ │ GPT │ │ browser │ │
│ └──────────┘ │ local │ │ file │ │
│ └──────────┘ │ http │ │
│ ┌──────────┐ │ memory │ │
│ │ Agent │ ┌──────────┐ │ web │ │
│ │ SOUL.md │ │ Session │ │ cron │ │
│ │ USER.md │ │ JSONL │ │ image │ │
│ │ MEMORY │ │ compact │ │ secret │ │
│ │ skills/ │ └──────────┘ │ message │ │
│ └──────────┘ │ spawn │ │
│ └──────────┘ │
└─────────────────────────────────────────────────────┘
The runtime is organized into vertical slices following CleanSlice architecture:
| Slice | Purpose |
|---|---|
init | First-run bootstrap and agent.config.json loading |
agent | Loads agent files (SOUL, USER, MEMORY) and builds system prompt |
session | Append-only JSONL conversation history with auto-compaction |
llm | Pluggable LLM adapters (Claude, OpenClaw, etc.) |
channel | Message routing (Telegram, Slack) |
tool | Tool registry and execution |
task | Task manager with dispatcher (parallel tasks, inbox) |
memory | Agent long-term memory persistence |
skill | Dynamic skill loading from .agent/skills/ |
cron | Scheduled job execution |
heartbeat | Periodic health checks |
access | User authorization and invite codes |
voice | Text-to-speech voice mode |
sync | S3 backup and sync |
Built-in tools available to the agent:
| Tool | Description |
|---|---|
exec | Run shell commands |
process | Run long-running processes |
spawn_agent | Spawn a Claude Code sub-agent for complex tasks |
browser | Fetch web pages (headless Chromium) |
playwright | Full browser automation (click, fill, screenshot) |
screenshot | Take page screenshots with AI analysis |
web_search | Search the web |
web_fetch | Fetch and extract clean text from URLs |
file | Read and write files |
unzip | Extract archives |
http | Make HTTP requests |
memory_search | Search agent memory |
image_analyze | Analyze images with Claude Vision |
pdf_analyze | Extract and analyze PDF content |
telegram_send | Send messages to Telegram chats |
tts | Text-to-speech via Telegram voice messages |
cron_* | Manage cron jobs (list, add, remove, disable) |
invite | Manage user invite codes |
secret_* | Manage encrypted user secrets (set, get, list, delete) |
Users can interact with the bot via Telegram/Slack commands:
| Command | Description |
|---|---|
/start | Start the bot / activate via invite link |
/help | Show available commands |
/status | Agent status and model info |
/clear | Reset current conversation session |
/memory | What the agent remembers about you |
/tasks | List active tasks |
/cancel <id> | Cancel a running task |
/voice | Toggle voice mode (TTS) |
/skills | List loaded skills |
/skills reload | Reload skills from disk (admin only) |
Every conversation is a session — a JSONL file where each line is one event:
{"type":"user","text":"hello","ts":1741900800}
{"type":"tool_call","name":"exec","params":{"command":"ls"}}
{"type":"tool_result","result":"..."}
{"type":"assistant","text":"done","ts":1741900801}Sessions are append-only and crash-safe. When a session exceeds session.compactionThreshold events, older events are summarized by the LLM into an archived context block, keeping only the most recent session.recentKeep events.
- TypeScript — strict, fully typed
- Bun — runtime and package manager
- Zod — schema validation for tool inputs
- Playwright — browser automation
- Anthropic SDK — Claude API integration
MIT
{ // Max LLM iterations per task (tool calls + responses).// Increase if the agent hits "Reached max iterations" on complex tasks."maxIterations": 25, // Max characters shown in task label previews"taskLabelLength": 60, "heartbeat": { // How often the heartbeat fires (minutes)"intervalMin": 30 }, "session": { // Compact session history after this many events"compactionThreshold": 60, // Keep this many recent events after compaction"recentKeep": 20 }, "s3": { // Auto-sync interval for S3 backup (seconds)"syncIntervalSec": 60 }, "tools": { "spawnAgent": { // Timeout for spawned Claude Code sub-agents (minutes)"timeoutMin": 5, // Max characters in sub-agent output notification"outputLimit": 4000 }, "browser": { // Max characters returned from browser tool"outputLimit": 5000 }, "webFetch": { // Max characters returned from web_fetch tool"maxChars": 8000 } } }