Advanced Features

Onboarding (BOOTSTRAP.md)

On first run, CamelAGI seeds a BOOTSTRAP.md file in the workspace. This is a one-time onboarding ritual that guides the agent through identity discovery — learning who you are, what you work on, and how you like to interact.

Once the agent completes onboarding (deletes the file), it’s marked as done and never shown again. The state is tracked in ~/.camelagi/.state/workspace-state.json.

Heartbeat (HEARTBEAT.md)

A periodic agent checklist. When enabled, the agent runs a heartbeat prompt at a configurable interval — checking tasks, reviewing memory, or any custom routine you define.

Configuration

In ~/.camelagi/config.yaml:

heartbeat:
  enabled: true
  interval: "1h"          # How often to run
  prompt: "Review your HEARTBEAT.md checklist"

The heartbeat skips API calls when the file is empty or contains only comments.

HEARTBEAT.md

Create ~/.camelagi/workspace/HEARTBEAT.md with your checklist:

# Daily Checklist

- [ ] Check for unread messages
- [ ] Review today's memory notes
- [ ] Update MEMORY.md if needed

Session-Specific Context

CamelAGI optimizes token usage by loading different bootstrap files depending on the session type:

This saves significant tokens on every cron tick and subagent spawn.

Context Compaction

When conversation history reaches 80% of the token limit, CamelAGI automatically:

1. Extracts durable facts from old messages → saves to daily memory file
2. Summarizes old messages into a compact summary
3. Keeps the last 6 turns verbatim

Nothing is lost — facts are flushed to memory before summarization.

Force compaction manually:

• CLI: part of the TUI slash commands
• Telegram: /compact

Cron Jobs

Schedule AI tasks — daily summaries, monitoring, automations.

From CLI

camel cron add --schedule "1h" --prompt "Check disk usage and alert if over 80%"
camel cron add --schedule "+30m" --prompt "Remind me about the meeting"  # one-shot
camel cron add --schedule "0 9 * * *" --prompt "Morning briefing"       # cron expression

From the Agent

The agent can create its own cron jobs using the cron tool:

"Set a reminder in 20 minutes to check the deployment"
→ Agent uses cron tool with schedule: "+20m"

Schedule Formats

MCP Servers

Connect external tool servers to give agents access to databases, APIs, and services.

From Telegram

Send /mcp to the admin bot → Add Server → choose type:

• stdio — local command (e.g. npx -y @modelcontextprotocol/server-github)
• HTTP — remote server via URL
• SSE — streaming server via URL

In Config

mcp:
  servers:
    github:
      type: stdio
      command: npx
      args: ["-y", "@modelcontextprotocol/server-github"]
      env:
        GITHUB_TOKEN: "ghp_..."
    supabase:
      type: http
      url: "https://mcp.supabase.com/mcp?project_ref=..."

MCP servers can be global or per-agent. Per-agent servers override global ones with the same name.

Tool Approvals

Human-in-the-loop safety for dangerous operations.

Modes

Configuration

approvals:
  mode: smart
  allowlist: ["Read", "Glob", "Grep"]  # Always allowed
  timeoutSeconds: 120
  fallback: deny                        # deny or allow on timeout
  forwardTo: 172583317                  # Telegram chat ID for headless approval

When a tool needs approval, inline buttons appear in Telegram: Allow / Always / Deny.

Skills

Teach agents new capabilities via markdown files.

Create a Skill

~/.camelagi/skills/my-skill/SKILL.md

---
name: my-skill
description: Does something useful
---

# Instructions

When asked to do X, follow these steps...

Skills are listed in the system prompt. When a user’s request matches, the agent reads the SKILL.md and follows the instructions.

List Skills

• CLI: camel (shown in status)
• Telegram: /skills

Remote Access

Run CamelAGI on one machine, control it from another. See the dedicated Remote Access guide for full details.

Quick start with Tailscale:

# On the server:
camel tailscale serve
camel serve

# On your local machine:
camel tailscale link

Monitor from another terminal:

camel watch                        # Local
camel watch wss://server.ts.net    # Remote

Hooks

Run shell or JavaScript scripts before/after tool calls.

Setup

Create hook scripts in ~/.camelagi/hooks/:

# ~/.camelagi/hooks/before-bash.sh
#!/bin/bash
echo "Running: $TOOL_NAME"

Enable in config:

hooks:
  enabled: true

Hooks run on before_tool and after_tool events.