agent-forge-installer 0.4.3

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.

Native App Scaffold

This repo now includes an Apple-platform scaffold under apps/ for future native clients:

• AgentForgeKit shared Swift module for models, networking stubs, and utilities
• AgentForgeiOS SwiftUI app target for iOS 17+
• AgentForgemacOS SwiftUI app target for macOS 14+

Build commands:

make native-build      # Builds the shared Swift package
make native-test       # Runs the shared Swift package tests
make ios-build         # Builds the iOS app target with xcodebuild
make macos-build       # Builds the macOS app target with xcodebuild
make native-verify     # Runs all of the above

Open the native project in Xcode with open apps/AgentForgeApps.xcodeproj.

Important: this native app currently uses both the Swift package manifest at apps/Package.swift and the Xcode project at apps/AgentForgeApps.xcodeproj. When adding, renaming, or removing Swift source files for the native app, update apps/AgentForgeApps.xcodeproj/project.pbxproj as well or Xcode may show "Cannot find ... in scope" errors even if swift build succeeds.

Quick Start

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

# Configure
agentforge init              # Launch interactive setup wizard

# 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
│   ├── log_action.sh         # Action logging (Google Sheets + local)
│   └── memory_consolidation.sh  # Legacy helper; built-ins now run via heartbeat.sh
├── 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]
agentforge init --non-interactive [--dir /path/to/instance]

Default behavior launches an interactive wizard that validates the Telegram token, detects a chat ID after /start, checks Claude Code CLI readiness, captures bot identity, and writes .env, agents/<name>/config.json, canonical vault prompt files under vault/Agents/<name>/, and shared handbook seeds under vault/Agents/_team/.

Use --non-interactive to preserve the original scaffold-only flow.

The interactive wizard also checks gh auth status and prints a non-blocking warning if GitHub auth is missing. Use either gh auth login or set GH_TOKEN in .env before running GitHub-driven automation.

Configuration

bot/config.json

{
  "telegram": {
    "token_env_var": "AGENTFORGE_TELEGRAM_TOKEN",  // env var name holding the token
    "bot_username": "agentforge_bot",               // optional expected bot username
    "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
  },
  "threads": {
    "11": { "name": "assistant", "model": "sonnet" },
    "12": { "name": "researcher", "model": "opus" }
  }
}

Recent conversation context is selected dynamically at runtime: AgentForge uses messages from roughly the last 4 hours, capped at 20 messages, with a fallback floor of 3 messages if the window is sparse.

.env

AGENTFORGE_TELEGRAM_TOKEN=your_bot_token_here
AGENTFORGE_ROOT=/path/to/instance
# Optional: preferred GitHub auth token for gh/API usage
GH_TOKEN=ghp_xxx
# Compatibility only; prefer GH_TOKEN above
GITHUB_TOKEN=ghp_xxx
# Optional: preserve gh credential lookup when HOME is overridden
GH_CONFIG_DIR=/Users/you/.config/gh

When AgentForge invokes Claude CLI, it sets HOME to AGENTFORGE_ROOT. Setting GH_CONFIG_DIR (or letting AgentForge infer it from your original home directory) keeps gh credential resolution stable in that environment.

Multi-Agent System

Each agent gets its own prompt identity via soul.md, compact durable memory via memory.md, and working notes in daily/:

agents/
├── victor/
│   ├── config.json    # Runtime config, logs, cron, operational files
│   └── ...
├── archie/
└── catherine/
vault/
└── Agents/
    ├── victor/
    │   ├── soul.md    # Canonical personality, role, instructions
    │   ├── memory.md  # Canonical compact durable memory
    │   └── daily/     # Canonical consolidation input only
    └── _team/
        ├── CLAUDE.md  # Shared team-wide operating rules
        ├── memory.md  # Shared compact injected memory
        ├── index.md   # Shared handbook index
        └── *.md       # Team handbook pages, not auto-injected

At runtime, AgentForge builds prompt context from:

1. CLAUDE.md
2. vault/Agents/_team/CLAUDE.md if present, else agents/shared/CLAUDE.md, else CLAUDE.local.md
3. vault/Agents/_team/memory.md if present, else agents/shared/memory.md
4. vault/Agents/<name>/soul.md if present, else agents/<name>/soul.md
5. vault/Agents/<name>/memory.md if present, else agents/<name>/memory.md

Daily notes are not auto-injected. Agents can:

• Have different Claude models (opus for complex reasoning, haiku for quick tasks)
• Maintain separate conversation histories and per-agent memory
• Store per-agent structured memory in the vault

For operational questions about current runtime behavior, prefer the generated read-only note vault/Agents/_team/system-state.md. After manual config.json edits or after upgrading to a release that changes shared verification guidance, run agentforge agent sync-system-state.

• Delegate directly via each agent's bot for 1:1 handoffs; use project topics only for shared multi-agent work

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 the single 2Do-backed heartbeat	Cron
healthcheck.sh	System health report	Cron (daily)
log_action.sh	Log external actions to Sheets + file	After side-effects
memory_consolidation.sh	Legacy helper script	Manual / legacy

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)

memory.md stores durable facts only. Recurring consolidation work should be modeled as 2Do tasks, typically assigned to architect, instead of separate cron jobs.

Todo System

AgentForge uses the structured 2Do backend as the canonical task system. Every mention of todo, to-do, task system, or 2Do refers to that same system.

Every agent runs a single heartbeat every 10 minutes. Before the model is called, heartbeat asks the 2Do task engine for one actionable task. If there is no actionable work, the model is not called.

Actionable heartbeat injection includes:

• overdue tasks
• tasks due now
• tasks without a due date
• tasks not cooling down after a recent failure

Selection order is currently:

• higher 2Do priority first
• then tasks with a due date
• then undated/background tasks

When a user says "update your task ..." or references the todo system, that means updating the 2Do task's notes body. The notes body is the prompt injected into heartbeat.

The installer seeds vault/Agents/_team/todo-system.md with the canonical rules for humans and agents.

Slash Commands

The following slash commands are available for managing todos (defined in commands/):

Command	Description
/todo-add	Add a todo to an agent
/todo-all	List all todos for an agent
/todo-next	Show the next single todo
/todo-nexts	Show the next few todos
/todo-projet	Show todos for a specific project tag
/todo-projets	List all projects that have todos
/todo-goal	Show todos for a specific goal tag
/todo-goals	List all goals that have todos
/todo-autres	Show todos without a project or goal tag
/todo-migrer	Migrate unchecked todos from a daily note to the Inbox

Heartbeat Integration

Heartbeat injects only actionable 2Do tasks, with at most one task executed per heartbeat run. Legacy extra cron templates remain in the repo for migration reference but ship disabled.

When expects_completion_signal: true is set for a cron config, the wrapper expects one of TASK_DONE, TASK_SKIP, or TASK_FAIL. Missing all three is treated as a silent failure.

Failure notifications are sent to the Telegram topic Daily, which must resolve through the normal topic lookup path used by telegram_send.sh (for example via TELEGRAM_THREAD_DAILY).

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_RUNTIME_ROOT/.local/bin/claude
• Telegram Bot — create one via @BotFather, enable Forum Topics in your supergroup

---

Full Installation Guide (Fresh Linux Server)

This is the step-by-step procedure to install AgentForge on a fresh Linux machine (Ubuntu/Debian).

Prerequisites

# System packages
sudo apt update && sudo apt install -y python3.12 python3.12-venv git curl

# Node.js (required for Claude Code CLI)
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs

Step 1 — Create a dedicated user

sudo adduser --disabled-password --gecos "AgentForge Bot" agentforge
sudo loginctl enable-linger agentforge   # allows systemd user services to run without login

Step 2 — Install Claude Code CLI

sudo -u agentforge -i   # switch to agentforge user

# Install Claude Code
npm install -g @anthropic-ai/claude-code
# Verify
claude --version

Note: Claude Code requires an Anthropic API key or Claude Max subscription. Run claude once to authenticate.

Step 3 — Clone and install AgentForge

# Still as agentforge user
cd ~
git clone https://github.com/Martin-Rancourt/AgentForge.git
cd AgentForge
./install.sh ~

The installer will:

1. Check Python 3.10+ ✓
2. Check Claude CLI ✓
3. Create a virtual environment
4. Install the agentforge package
5. Run the interactive agentforge init wizard
6. Generate a systemd user service
7. Check for Syncthing

Step 4 — Set up Telegram

Before running the bot, you need a Telegram Bot + Supergroup:

1. Create a bot — Talk to @BotFather on Telegram:

   • /newbot → choose a name and username
   • Copy the bot token

2. Create a Supergroup with Forum Topics enabled:

   • Telegram → New Group → add your bot → make it a Supergroup
   • Group Settings → Topics → Enable
   • Create one topic per agent (e.g. "Assistant", "Researcher", "Dev")

3. Get the chat ID and thread IDs:

   • Send a message in each topic
   • Use https://api.telegram.org/bot<TOKEN>/getUpdates to see recent messages
   • Note the chat.id (negative number) and each message_thread_id

4. Update config:

   # Edit .env with your token
   nano ~/.env
   # → AGENTFORGE_TELEGRAM_TOKEN=your_token_here
   
   # Edit config with your chat ID and thread IDs
   nano ~/bot/config.json
   

Step 5 — Create your agents

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

# Edit each agent's personality
nano ~/vault/Agents/assistant/soul.md
nano ~/vault/Agents/researcher/soul.md

Step 6 — Start the bot

# Enable and start the systemd service
systemctl --user daemon-reload
systemctl --user enable --now agentforge

# Verify it's running
systemctl --user status agentforge

# Watch logs
journalctl --user -u agentforge -f

Step 7 — Set up cron jobs (optional but recommended)

crontab -e

Add:

# Heartbeat — single scheduler for all built-in and per-agent cron jobs
*/30 * * * * AGENTFORGE_ROOT=$HOME $HOME/.venv/bin/agentforge heartbeat >> $HOME/logs/heartbeat.log 2>&1

# Daily health check at 08:00
0 8 * * * $HOME/scripts/healthcheck.sh >> $HOME/logs/healthcheck.log 2>&1

---

Syncthing — Cross-Device Knowledge Sync

AgentForge uses Syncthing to sync your knowledge vault (Obsidian vault, agent memory, etc.) across devices. This is optional but recommended if you want to access your bot's brain from your phone or laptop.

Architecture

┌──────────────┐     Syncthing      ┌──────────────┐
│ Linux Server │ ◄──────────────► │    macOS     │
│  (always-on) │                    │  (laptop)    │
└──────┬───────┘                    └──────────────┘
       │
       │  Syncthing
       ▼
┌──────────────┐
│   iPhone     │
│ (Möbius Sync)│
└──────────────┘

The Linux server is the hub — always on, always syncing. Other devices sync when they're online.

Linux Server Setup

# Install Syncthing
sudo apt install -y syncthing

# Enable as a user service (runs without login thanks to lingering)
systemctl --user enable --now syncthing

# Access the web UI
# Syncthing listens on http://localhost:8384
# If remote: ssh -L 8384:localhost:8384 agentforge@your-server

Configure the shared folder:

1. Open Syncthing web UI (http://localhost:8384)
2. Add Folder → set the path to your knowledge vault (e.g. ~/obsidian-brain/)
3. Set a Folder ID (e.g. agentforge-vault) — you'll need this on other devices
4. Under Advanced → set Folder Type to "Send & Receive"

macOS Setup

# Install via Homebrew
brew install syncthing

# Start as a background service
brew services start syncthing

1. Open http://localhost:8384 in your browser
2. Add Remote Device → paste the Linux server's Device ID (found in the server's Syncthing UI under Actions → Show ID)
3. On the Linux server, accept the incoming device request
4. The shared folder should auto-appear for approval on macOS — accept it
5. Choose a local path (e.g. ~/Documents/agentforge-vault/)

For Obsidian: Point Obsidian's vault to the synced folder. Your bot's knowledge base stays in sync with your laptop.

iOS Setup (Möbius Sync)

Möbius Sync is the only Syncthing-compatible app for iOS. It costs ~$5 USD (one-time purchase).

1. Install Möbius Sync from the App Store
2. Open the app → go to Settings → note your Device ID
3. On your Linux server Syncthing UI:
   • Add Remote Device → paste the iOS Device ID
   • Share the agentforge-vault folder with this device
4. Back in Möbius Sync:
   • Accept the incoming device connection
   • Accept the shared folder
   • Choose a local location (e.g. under "On My iPhone" or iCloud)
5. For Obsidian Mobile: Point Obsidian to the Möbius Sync folder to browse your vault on the go

Tip: Möbius Sync works best with "Background Sync" enabled (Settings → Background Sync → On). iOS may still throttle it, so open the app occasionally to force a full sync.

Syncthing Tips

• Device IDs are the only thing you exchange — no accounts, no cloud, fully P2P encrypted
• Ignore patterns: Add a .stignore file in your vault root to exclude files:

  .obsidian/workspace.json
  .DS_Store
  *.tmp
  

• Conflict resolution: Syncthing creates .sync-conflict-* files if two devices edit the same file simultaneously. Resolve manually.
• Bandwidth: Initial sync can be slow for large vaults. Subsequent syncs are incremental and near-instant.

---

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