▄▀█   ▄█▀▄   █▀▀   █▄░█   ▀█▀      ▄███   ▄▀█   █▀▀   ▀█▀   █▀█   █▀▄   █▄█
  █▀█   █▀▀█   █▄█   █░▀█   ░█░      ██░█   █▀█   █▄▄   ░█░   █▄█   █▀▄   ░█░
        ● ▂ ●                          ║ █ ║
         ▀▀▀                           █▀█▀█

  🤖  Build your own personal AI agent — one Claude Code command, zero boilerplate  🏭
                 4 LLM providers · Telegram bot · Docker · VPS · Raspberry Pi

---

A Claude Code skill that generates fully-configured, deployable personal AI agents. Walk through an interactive setup — LLM provider, Telegram bot, personality, features, hosting — and your agent lands in Agents/<name>/ ready to run.

No web UI. No framework lock-in. No boilerplate. Just the architecture from the best open-source personal-agent harnesses (Hermes Agent & OpenClaw), assembled into a single /create-agent command.

Quick start

git clone https://github.com/Bernaljp/agent-factory.git
cd agent-factory
claude                      # open with Claude Code
/create-agent               # run the skill

The skill walks you through everything interactively — you answer the questions and it generates the agent:

Step	What you configure
1. Features	Pick from Hermes (H1–H11) + OpenClaw (O1–O10) feature menus, or go MVP
2. Identity	Agent name, purpose, your name, timezone
3. LLM	Anthropic · OpenRouter · Ollama · DeepSeek — guided key setup for each
4. Telegram	@BotFather walkthrough, user-ID whitelist, or paste existing creds
5. Soul	Craft the personality — identity, tone, formatting, anti-injection guards
6. Skills	Pre-seed starter skills from a paste, a GitHub repo, or skip
7. Hosting	Docker (local/VPS) · Raspberry Pi (systemd) · Railway ($5/mo)
8. Generate	Template copied → variables replaced → npm install → .env written
9. Deploy	Step-by-step instructions + safety checklist for your chosen host

What each generated agent includes

System	Description
Agent loop	message → LLM → tool-calling → response, max 10 iterations
3-tier memory	core facts (SQLite+WAL) + conversation buffer + Pinecone semantic search
Tool system	shell_exec, read/write file, memory CRUD, list directory, load skill
LLM layer	model-agnostic — Anthropic / OpenRouter / Ollama / DeepSeek, hot-swap via env
Telegram bot	whitelist auth, private-chat only, streaming responses, voice note handling
Heartbeats	morning check-in + evening recap, randomised times to avoid predictable patterns
MCP bridge	zero-code plug into Gmail, Notion, GitHub, Linear, Supabase — anything with an MCP server
Prompt-injection defence	tool output wrappers + destructive-call approval flow
Docker	hardened container — --read-only, --cap-drop=ALL, non-root user (uid 1001)

Optional features (toggled via env vars)

Feature	What it does
Reflection (H2)	Nightly 3am consolidation — extracts goals, decisions, facts, open loops
Auto-skills (H3)	After 5+ tool calls, auto-generates a reusable SKILL.md procedure
Voice (H6)	Telegram voice note → Whisper transcription → normal message processing
Dashboard	Express API at 127.0.0.1:5173 — memory browser, activity feed, skill library
Cost tracking	Per-request pricing, daily spend alerts at configurable threshold
Approval flow (O7)	Inline Telegram approve/deny buttons for destructive tools (5min auto-deny)

LLM providers at a glance

Provider	Cost	Model quality	Best for
Anthropic	~$3/1M tok	Reference	Daily driver, sensitive work
OpenRouter	Varies	Mix	One key, any model
DeepSeek	~$0.27/1M tok	Strong	Bulk processing, budget
Ollama	Free	Varies	Privacy, offline, experimentation

Hosting — pick your path

Option	Cost	Setup	Best for
Docker (laptop)	Free	docker compose up -d	Development, testing
VPS (Hetzner/DigitalOcean)	~$5/mo	rsync + docker compose up -d	24/7 production
Raspberry Pi	Free*	npm install + systemd unit	Home server, always-on
Railway	~$5/mo	railway up	Push-and-forget cloud

Architecture

┌─────────────────────────────────────────────────────────┐
│                      YOUR AGENT                          │
│                                                          │
│  ┌─────────┐  ┌─────────┐  ┌──────────┐  ┌────────┐    │
│  │ AGENT   │  │ MEMORY  │  │ TOOLS    │  │ LLM    │    │
│  │ LOOP    │◄─┤ 3 TIERS │  │ SYSTEM   │  │ LAYER  │    │
│  └────┬────┘  └─────────┘  └──────────┘  └────────┘    │
│       │                                                  │
│  ┌────┴────┐  ┌─────────┐  ┌──────────┐                 │
│  │HEARTBEAT│  │TELEGRAM │  │ MCP      │                 │
│  │SCHEDULER│  │ BOT     │  │ BRIDGE   │                 │
│  └─────────┘  └─────────┘  └──────────┘                 │
└─────────────────────────────────────────────────────────┘

Safety

• .env and Agents/ are gitignored from the factory repo
• Telegram bot rejects group chats and non-whitelisted users
• Docker runs read-only root FS, no capabilities, non-root user
• soul.md includes prompt-injection defence by default
• Destructive tools require inline approval buttons (when enabled)
• Dashboard binds to 127.0.0.1 only — never exposed on a public interface

Based on

This factory synthesizes patterns from the two leading open-source personal-agent projects:

• Hermes Agent — GEPA reflection, auto-skills, agentskills.io standard, 15+ gateways (ICLR 2026 paper)
• OpenClaw — 22 messaging channels, ClawHub registry, per-command approval, sandboxed execution

The 26-step build guide this factory automates is included in claude-agent-setup.md.

Requirements

• Node 20+ — runtime
• Claude Code — the harness that runs the skill
• Telegram account — your agent's only interface
• An LLM API key — Anthropic, OpenRouter, DeepSeek, or local Ollama
• Docker (optional) — for containerized deployment