fastclaw

README

⚡ FastClaw

A lightweight, self-hosted AI Agent framework written in Go.

Website · Documentation · Discord

---

FastClaw is a minimal, self-hosted AI agent that connects to your chat platforms and gets things done. It runs on your own machine, uses any LLM provider, and learns about you over time. Built with Go for speed and simplicity — single binary, zero dependencies.

✨ Features

• ReAct Agent Loop — Reasoning + Acting cycle with multi-turn tool calling
• Multi-Channel — Telegram with multi-bot support (more coming: Discord, Slack, WhatsApp...)
• Any LLM — Works with any OpenAI-compatible provider (OpenAI, Claude, DeepSeek, Gemini, OpenRouter...)
• Context Engineering — Auto-pruning & compression to handle long conversations without context overflow
• Dual-Layer Memory — Long-term facts (MEMORY.md) + searchable conversation history with recency weighting
• Hook System — Before/After hooks for system prompt, model calls, and tool calls
• CronTab + Heartbeat — Scheduled tasks and periodic wake-ups for proactive behavior
• Skill System — Progressive disclosure: 100+ skills without bloating context
• Built-in Tools — Shell, file ops, web fetch, memory search, cross-channel messaging
• MCP Support — Connect external tools via Model Context Protocol (HTTP + stdio)
• Multi-Agent — Run multiple agents with independent personalities and workspaces
• Single Binary — No Docker, no cloud services, no dependencies required

🏗 Architecture

┌──────────────────────────────────────────────────────────┐
│                       Gateway                             │
│                                                           │
│  ┌───────────┐   ┌──────────┐   ┌──────────────────────┐ │
│  │ Channels  │──▶│   Bus    │──▶│     Agent Loop       │ │
│  │           │◀──│          │◀──│                      │ │
│  │ Telegram  │   │ Inbound/ │   │  System Prompt Build │ │
│  │ Discord*  │   │ Outbound │   │  ReAct Cycle         │ │
│  │ Slack*    │   │          │   │  Tool Execution      │ │
│  └───────────┘   └──────────┘   │  Context Compaction  │ │
│                                  └──────────────────────┘ │
│                                                           │
│  ┌───────────┐   ┌──────────┐   ┌──────────────────────┐ │
│  │  Session  │   │  Memory  │   │       Tools          │ │
│  │  Manager  │   │          │   │                      │ │
│  │           │   │ MEMORY.md│   │ exec, files, web     │ │
│  │ JSONL     │   │ Logs/    │   │ memory_search        │ │
│  │ Compaction│   │ Search   │   │ load_skill, message  │ │
│  └───────────┘   └──────────┘   │ MCP tools            │ │
│                                  └──────────────────────┘ │
│                                                           │
│  ┌───────────┐   ┌──────────┐   ┌──────────────────────┐ │
│  │   Hooks   │   │   Cron   │   │     Heartbeat        │ │
│  │           │   │ Scheduler│   │   (every 30 min)     │ │
│  │ Pre/Post  │   │          │   │                      │ │
│  │ Logging   │   │ Exact    │   │ Check task list      │ │
│  │ Timing    │   │ Interval │   │ Update memory        │ │
│  └───────────┘   │ Cron Expr│   │ Proactive actions    │ │
│                   └──────────┘   └──────────────────────┘ │
└──────────────────────────────────────────────────────────┘
                        * planned

🚀 Quick Start

Install (one-liner)

curl -fsSL https://raw.githubusercontent.com/fastclaw-ai/fastclaw/main/install.sh | bash

Or with Go:

go install github.com/fastclaw-ai/fastclaw/cmd/fastclaw@latest

Or download a pre-built binary from Releases.

Configure

Create ~/.fastclaw/fastclaw.json:

{
  "providers": {
    "openai": {
      "apiKey": "your-api-key",
      "apiBase": "https://api.openai.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "model": "gpt-4o",
      "maxTokens": 8192,
      "temperature": 0.7,
      "maxToolIterations": 20
    },
    "list": [
      { "id": "main", "workspace": "~/.fastclaw/agents/main/agent" }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "accounts": {
        "default": {
          "botToken": "your-telegram-bot-token"
        }
      }
    }
  }
}

Supported LLM providers:

Provider	apiBase	Example Model
OpenAI	https://api.openai.com/v1	gpt-4o
Anthropic (via OpenRouter)	https://openrouter.ai/api/v1	anthropic/claude-sonnet-4
DeepSeek	https://api.deepseek.com/v1	deepseek-chat
Groq	https://api.groq.com/openai/v1	llama-3.3-70b
Local (Ollama)	http://localhost:11434/v1	qwen2.5:32b

Run

fastclaw gateway

Open Telegram and message your bot. That's it. ⚡

📁 Workspace

Each agent has its own workspace with Markdown-based configuration:

workspace/
├── AGENTS.md       # Agent behavior instructions & SOP
├── SOUL.md         # Personality, values, communication style
├── IDENTITY.md     # Name, role, specialty
├── USER.md         # User profile (auto-updated as agent learns about you)
├── TOOLS.md        # Tool usage notes & environment specifics
├── MEMORY.md       # Long-term facts (auto-updated by heartbeat)
├── HEARTBEAT.md    # Periodic task checklist
├── memory/
│   └── logs/       # Compressed conversation history (searchable)
├── sessions/       # JSONL conversation files
└── skills/         # Agent-specific skills

Edit these files to customize your agent. The agent can also update USER.md and MEMORY.md on its own as it learns.

🔧 Built-in Tools

Tool	Description
exec	Execute shell commands with timeout
read_file	Read file contents
write_file	Write or create files
list_dir	List directory contents
web_fetch	Fetch web pages, strip HTML, return text
memory_search	Search conversation history with keyword matching
load_skill	Load full skill instructions on demand
message	Send messages to any connected channel

Plus any tools connected via MCP (Model Context Protocol).

🧠 Memory System

FastClaw implements a dual-layer memory architecture:

Layer 1: MEMORY.md — Core facts auto-extracted during heartbeat. Loaded into every system prompt. The agent knows your preferences, important dates, ongoing projects.

Layer 2: Memory Search — Full conversation history stored as logs. Searchable via memory_search tool with keyword matching and time-decay weighting. The agent can recall details from hundreds of conversations ago.

⏰ Proactive Behavior

FastClaw doesn't just wait for you — it comes to you.

CronTab — Schedule tasks in cron.json:

• Exact time: "2026-03-15T08:00:00"
• Interval: "every 20m"
• Cron expression: "0 8 * * 1-5" (weekdays at 8am)

Heartbeat — Wakes every 30 minutes to check HEARTBEAT.md. If something needs attention (a reminder, a birthday, a follow-up), it acts proactively.

🎯 Skills

Skills are plug-and-play capability packs. Install them in ~/.fastclaw/skills/:

~/.fastclaw/skills/
├── skill-creator/
│   └── SKILL.md
├── weather/
│   └── SKILL.md
└── translator/
    └── SKILL.md

Progressive disclosure: Only skill names + one-line summaries go into the system prompt. Full instructions are loaded on-demand via load_skill — so 100+ skills won't blow up your context.

🤖 Multi-Agent

Run multiple agents with different personalities on the same gateway:

{
  "agents": {
    "list": [
      { "id": "mike", "workspace": "~/.fastclaw/agents/mike/agent" },
      { "id": "mary", "workspace": "~/.fastclaw/agents/mary/agent" }
    ]
  },
  "channels": {
    "telegram": {
      "accounts": {
        "mike": { "botToken": "MIKE_BOT_TOKEN" },
        "mary": { "botToken": "MARY_BOT_TOKEN" }
      }
    }
  },
  "bindings": [
    { "agentId": "mike", "match": { "channel": "telegram", "accountId": "mike" } },
    { "agentId": "mary", "match": { "channel": "telegram", "accountId": "mary" } }
  ]
}

Each agent has its own workspace, personality, memory, and skills.

📋 Roadmap

• Gateway with message bus
• ReAct agent loop with tool calling
• OpenAI-compatible LLM provider (streaming SSE)
• Telegram channel (multi-bot, groups, DMs)
• Session persistence (JSONL)
• Dual-layer memory system
• Context pruning & compression
• Hook system (pre/post for prompts, model, tools)
• CronTab scheduled tasks
• Heartbeat proactive service
• Skill system with progressive disclosure
• MCP protocol support (HTTP + stdio)
• Web fetch tool
• Multi-agent routing with bindings
• Discord channel
• Slack channel
• WhatsApp channel
• Vector-based memory search (SQLite + embeddings)
• Web dashboard
• Plugin system

🛠 Development

# Clone
git clone https://github.com/fastclaw-ai/fastclaw.git
cd fastclaw

# Build
go build -o fastclaw ./cmd/fastclaw

# Run tests
go test ./...

# Run
./fastclaw gateway

Contributing

Contributions welcome! Keep it simple — FastClaw's strength is its minimal codebase.

1. Fork → Clone → Branch → Code → Test → PR
2. Follow Conventional Commits
3. Use Go standard library when possible

License

MIT

---

Built with ⚡ by the FastClaw community