agent-forge-installer 0.1.0

AgentForge — multi-agent Telegram bot framework powered by Claude Code

AgentForge

A reusable framework for building multi-agent Telegram bots powered by Claude AI.

Zero dependencies by default — runs on Python 3.10+ stdlib. Optional extras for voice transcription and faster HTTP.

Quick Start

# Clone and install
git clone https://github.com/Martin-Rancourt/AgentForge.git
cd AgentForge
./install.sh

# Configure
nano .env                    # Add your Telegram bot token
nano bot/config.json         # Add your chat IDs

# Create agents
agentforge agent create assistant --model sonnet --thread-id 11
agentforge agent create researcher --model opus --thread-id 12

# Run
agentforge bot

How It Works

AgentForge turns a Telegram Supergroup with Forum Topics into a multi-agent workspace. Each topic routes to a different Claude-powered agent with its own identity, model, and memory.

Telegram Topic (thread_id: 12)
  → telegram_adapter.py (long-polling)
  → message_router.py (resolve agent config)
  → claude_runner.py (invoke Claude CLI with agent's soul.md)
  → Response sent back to Telegram

Message Flow

1. Bot polls Telegram for new messages
2. message_thread_id determines which agent handles the message
3. Conversation history is loaded from SQLite (configurable context window)
4. Claude Code CLI is invoked with the agent's soul.md as system prompt
5. Response is stored in SQLite and sent back to Telegram

Architecture

agentforge/
├── src/agentforge/
│   ├── telegram_adapter.py   # Main bot — polling, routing, sending
│   ├── claude_runner.py      # Claude Code CLI subprocess wrapper
│   ├── message_router.py     # Thread → agent config resolution
│   ├── config.py             # Typed config loader (dataclasses)
│   ├── memory_manager.py     # SQLite + FTS5 conversation database
│   ├── vault.py              # Structured memory store (per-agent)
│   ├── voice.py              # Voice note transcription (optional)
│   ├── http_client.py        # Dual-stack: requests or urllib
│   └── cli/                  # CLI commands (bot, agent, memory, init, vault)
├── scripts/                   # Bash utilities
│   ├── telegram_send.sh      # Send messages to topics (with dedup)
│   ├── heartbeat.sh          # Proactive task runner (cron)
│   ├── healthcheck.sh        # Daily system health check
│   ├── agent_task.sh         # Cross-agent task delegation
│   ├── log_action.sh         # Action logging (Google Sheets + local)
│   └── memory_consolidation.sh  # Weekly memory merge
├── tests/                     # Pytest suite (49 tests)
├── install.sh                # One-liner bootstrap
└── pyproject.toml            # Package metadata

CLI Reference

agentforge bot

Start the Telegram bot.

agentforge bot [--config path/to/config.json]

agentforge agent

Manage agents declaratively.

# Create — scaffolds soul.md, memory.md, daily/ directory
agentforge agent create <name> --model <model> --thread-id <id>

# List all configured agents
agentforge agent list

# Remove an agent (--keep-files to preserve files on disk)
agentforge agent remove <name> [--keep-files]

Models: sonnet (fast, balanced), opus (strongest reasoning), haiku (fastest, cheapest)

agentforge memory

Query the conversation database.

agentforge memory search "deployment error"    # Full-text search (FTS5)
agentforge memory recent 50                     # Last 50 messages
agentforge memory stats                         # Database statistics

agentforge vault

Structured memory store — facts, preferences, and knowledge per agent.

agentforge vault write --agent victor --category knowledge --title "API design" --content "..."
agentforge vault search "deployment"
agentforge vault list --agent archie

agentforge init

Bootstrap a new instance from scratch.

agentforge init [--dir /path/to/instance]

Creates: bot/, agents/, data/, logs/, memory/, skills/, config.json, .env

Configuration

bot/config.json

{
  "telegram": {
    "token_env_var": "AGENTFORGE_TELEGRAM_TOKEN",  // env var name holding the token
    "allowed_chat_ids": [123456789],                // whitelist
    "group_chat_id": -100123456789,                 // supergroup ID
    "topics": {                                      // named topic shortcuts
      "general": 11,
      "dev": 12
    }
  },
  "claude": {
    "model": "sonnet",          // default model
    "max_budget_usd": 1.0       // per-invocation spend cap
  },
  "memory": {
    "context_messages": 10      // messages included as context
  },
  "threads": {
    "11": { "name": "assistant", "model": "sonnet", "context_messages": 10 },
    "12": { "name": "researcher", "model": "opus",  "context_messages": 15 }
  }
}

.env

AGENTFORGE_TELEGRAM_TOKEN=your_bot_token_here
AGENTFORGE_ROOT=/path/to/instance    # defaults to /home/clawdia

Multi-Agent System

Each agent gets its own identity via a soul.md file:

agents/
├── victor/
│   ├── soul.md        # Personality, role, instructions
│   ├── memory.md      # Long-term consolidated memory
│   └── daily/         # Daily learnings (YYYY-MM-DD.md)
├── archie/
└── catherine/

The soul.md is passed as --system-prompt to Claude, completely overriding the default identity. Agents can:

• Have different Claude models (opus for complex reasoning, haiku for quick tasks)
• Maintain separate conversation histories and context windows
• Store per-agent structured memory in the vault
• Delegate tasks to each other via agent_task.sh

Project Topics

Beyond agent topics, you can configure project topics where multiple agents collaborate:

"project_topics": {
  "42": {
    "label": "🏗 Dev",
    "agents": ["victor", "archie"],
    "default_agent": "victor"
  }
}

Use @agentname mentions to address a specific agent in a shared topic.

Scripts

Script	Purpose	Trigger
telegram_send.sh	Send messages to topics	Manual / cross-agent
heartbeat.sh	Run proactive tasks from heartbeat.md	Cron
healthcheck.sh	System health report	Cron (daily)
agent_task.sh	Delegate tasks between agents	Inter-agent
log_action.sh	Log external actions to Sheets + file	After side-effects
memory_consolidation.sh	Merge daily logs → memory.md	Cron (weekly)

Dedup

telegram_send.sh has built-in deduplication: identical messages to the same topic within 60 seconds are silently dropped.

Memory System

AgentForge provides three layers of memory:

Layer	Storage	Purpose
Conversations	SQLite + FTS5	Full message history, searchable
Vault	SQLite + FTS5	Structured facts/preferences per agent
Files	Markdown	soul.md (identity), memory.md (long-term), daily/ (learnings)

The weekly memory_consolidation.sh script merges daily learnings into each agent's memory.md.

Dependencies

Core: Python 3.10+ stdlib only (no pip install required for basic operation)

Optional extras:

pip install agentforge[full]    # requests + faster-whisper
pip install agentforge[dev]     # pytest + pytest-cov

Extra	Package	Purpose
full	requests>=2.28	Faster HTTP client (falls back to urllib)
full	faster-whisper>=1.0	Voice note transcription
dev	pytest>=7	Test runner
dev	pytest-cov	Coverage reports

External Requirements

• Claude Code CLI — must be installed at $AGENTFORGE_ROOT/.local/bin/claude
• Telegram Bot — create one via @BotFather, enable Forum Topics in your supergroup

Testing

pip install -e ".[dev]"
pytest                      # Run all 49 tests
pytest --cov=agentforge     # With coverage

Tests cover: config validation, message routing, memory manager, vault operations.

Releases

This project uses release-please for automated releases:

1. Use conventional commits (feat:, fix:, docs:, chore:, etc.)
2. Release-please accumulates changes and opens a Release PR with version bump + changelog
3. Merge the Release PR → GitHub Release + git tag created automatically

License

MIT