🧪 Heisenberg Team

A multi-agent system with 8 AI agents working as a team. Built on OpenClaw. Inspired by Breaking Bad.

Canonical source

This project is maintained by Aleksei Ulianov / Sprut_AI. Original repository: https://github.com/AlekseiUL/heisenberg-team

If you found this project mirrored, repackaged, or redistributed elsewhere, check this repository as the source of truth.

Attribution

Where permitted by the applicable license, if you reuse, fork, modify, package, or publish this work, keep the original copyright and license notice and link back to the canonical repository.

Release 2 adds better direct-message behavior, durable-memory rules, and updated OpenClaw operations.

---

Table of Contents

• What is this?
• Why?
• How is this different?
• Architecture
• Agents
• Quick Start
• Skills (34)
• Project Structure
• Examples
• Documentation
• Contributing
• License

---

Requirements

• Node.js v24 LTS
• OpenClaw (npm install -g openclaw)
• Auth for at least one LLM provider (Anthropic, OpenAI, OpenAI Codex, Google, DeepSeek, or local models)
• Telegram bot token (optional, for notifications via @BotFather)

System Requirements

What is this?

A production-ready template for running a team of AI agents that communicate, delegate tasks, and deliver results. Each agent has a defined role, personality, and set of skills.

This is not a framework. This is a working system you can clone, configure, and run.

Who is this for?

Use this repository if you want a self-hosted OpenClaw team that feels like an operating crew, not a single chatbot:

• founders and operators who want a Telegram-accessible AI command center;
• builders experimenting with multi-agent delegation and durable task boards;
• AI automation consultants who need a concrete reference implementation;
• OpenClaw users who want memory, recovery, skills, and specialist roles already wired together.

Not for: people looking for a generic SaaS chatbot or a no-code toy demo. This is a working template for a local/operator-owned agent system.

Why?

• One boss, seven specialists. You talk to Heisenberg. He delegates to the right agent. You get results.
• 34 skills. PDF generation, research, marketing, security audits, financial tracking, code review — out of the box.
• Board-First protocol. Tasks survive crashes. File-based state, not memory. No work is lost.
• Self-healing. Health checks, watchdogs, automatic session cleanup. The system monitors itself.
• Your data stays yours. All personal data uses {{PLACEHOLDER}} format. Setup wizard fills them in 5 minutes.

How is this different?

Architecture

Operating loop

flowchart LR
    U[User / Telegram] --> H[Heisenberg Orchestrator]
    H --> B[Board-First Task State]
    H --> A1[Research]
    H --> A2[Code / Technical]
    H --> A3[Marketing]
    H --> A4[Finance]
    H --> A5[Quality / Legal]
    A1 --> B
    A2 --> B
    A3 --> B
    A4 --> B
    A5 --> B
    B --> H
    H --> U

graph TB
    User["👤 You (Telegram)"]
    
    subgraph team["🧪 Heisenberg Team"]
        HB["🧪 HeisenbergBoss & CoordinatorOpus"]
        
        subgraph specialists["Specialists"]
            Saul["💼 Saul GoodmanProducerSonnet"]
            Walter["👨‍🔬 Walter WhiteTech LeadSonnet"]
            Jesse["🎯 Jesse PinkmanMarketingSonnet"]
            Skyler["💰 Skyler WhiteFinanceSonnet"]
            Hank["🔫 Hank SchraderSecuritySonnet"]
            Gus["🎯 Gus FringKaizen/GoalsSonnet"]
            Twins["👥 Salamanca TwinsResearchSonnet"]
        end
        
        Board["📋 Team BoardFile-based state"]
        Memory["🧠 MemorySQLite + Vectors"]
        Skills["⚡ 34 SkillsPDF, XLSX, Research..."]
    end
    
    User -->|"message"| HB
    HB -->|"sessions_send"| Saul
    HB -->|"sessions_send"| Walter
    HB -->|"sessions_send"| Jesse
    HB -->|"sessions_send"| Skyler
    HB -->|"sessions_send"| Hank
    HB -->|"sessions_send"| Gus
    HB -->|"sessions_send"| Twins
    Saul -->|"coordinate"| Board
    Walter --> Skills
    Jesse --> Skills
    Skyler --> Skills
    HB --> Memory
    Saul --> Memory
    
    style HB fill:#ff6b35,stroke:#333,color:#fff
    style Saul fill:#4ecdc4,stroke:#333,color:#fff
    style Walter fill:#45b7d1,stroke:#333,color:#fff
    style Jesse fill:#96ceb4,stroke:#333,color:#fff
    style Skyler fill:#dda0dd,stroke:#333,color:#fff
    style Hank fill:#ff6b6b,stroke:#333,color:#fff
    style Gus fill:#ffd93d,stroke:#333,color:#000
    style Twins fill:#6c5ce7,stroke:#333,color:#fff
    style Board fill:#2d3436,stroke:#333,color:#fff
    style Memory fill:#2d3436,stroke:#333,color:#fff
    style Skills fill:#2d3436,stroke:#333,color:#fff

Agents

Quick Start

# 1. Clone
git clone https://github.com/AlekseiUL/heisenberg-team.git
cd heisenberg-team

# 2. Optional bootstrap installer
bash scripts/bootstrap-install.sh

# 3. Configure environment
cp .env.example .env
# Edit .env with your LLM API key

# 4. Interactive setup (recommended)
bash scripts/setup-wizard.sh

# 4. Initialize OpenClaw (first time only)
openclaw init

# 5. Run
openclaw gateway start
bash scripts/smoke-test.sh

The setup wizard will ask for your name, Telegram ID, and other settings, then configure everything automatically.

The setup wizard now supports:

• selected agents only
• per-agent Telegram bot tokens
• custom display names
• generated configs in configs/generated/
• a dedicated team directory root

Need a narrower rollout first?

# Selected agents only
bash scripts/setup.sh --agents heisenberg,saul,walter
bash scripts/smoke-test.sh --agents heisenberg,saul,walter

# Attach to an existing OpenClaw install
bash scripts/setup.sh --attach-existing --agents heisenberg,walter

See SETUP.md for detailed installation guide or docs/first-task.md for your first walkthrough.

Language note: Agent personalities and team protocols are in Russian. The architecture works in any language — edit SOUL.md and AGENTS.md in each agent to change language.

Platform note: Utility scripts in scripts/ are optimized for macOS but support Linux/WSL. See Linux Setup for platform-specific instructions.

Skills (34)

The team shares a library of 34 skills covering:

• Content: copywriter, youtube-seo, presentation, pptx-generator
• Research: researcher, deep-research-pro, channel-analyzer, reddit
• Documents: minimax-pdf, minimax-docx, minimax-xlsx, nano-pdf
• Development: coding-agent, cursor-agent, github-publisher
• Automation: n8n-workflow-automation, blogwatcher, browser-use
• Analysis: analytics, audit-website, business-architect
• Specialized: family-doctor, auto-mechanic, dog-kinolog, astrologer, weather

Full list with dependencies in skills/README.md.

Project Structure

heisenberg-team/
├── agents/          # 8 agents, each with config files
├── skills/          # 34 shared skills
├── scripts/         # Utility and automation scripts
├── references/      # Team constitution, standards
├── examples/        # Cookbooks and guides
└── docs/            # Architecture, FAQ

🤖 Deploy Full Team (Optional)

Want all 8 agents working together? See the Multi-Agent Deployment Guide.

# Automated workspace setup
bash scripts/deploy-team.sh

Examples

• Add a new agent
• Create a skill
• Configure cron jobs

Documentation

• Your First Task - step-by-step walkthrough
• Upgrade from Single Agent - migrate from single-agent setup
• Supported Providers - Anthropic, OpenAI, Google, DeepSeek, Ollama
• Agent Onboarding - configure agents on first launch
• Architecture - how agents communicate
• Agent Roles - what each agent does
• Linux Setup - running on Ubuntu/Debian
• FAQ - common questions and troubleshooting
• Skills Index - all 34 skills with dependencies

Contributing

1. Fork the repo
2. Create a branch (git checkout -b feature/new-agent)
3. Commit changes (git commit -m 'Add new agent')
4. Push (git push origin feature/new-agent)
5. Open a Pull Request

Русская версия

Heisenberg Team - это multi-agent AI system template для OpenClaw-style работы: несколько специализированных агентов, board-first coordination, self-healing/crash-recovery идеи и общий operating loop.

Репозиторий показывает, как может выглядеть агентская команда, где роли разделены, задачи идут через board, а runtime должен быть наблюдаемым. Это полезно как пример архитектуры и стартовая точка для своего self-hosted setup.

Что внутри

• 8 specialized agents;
• board-first coordination pattern;
• operating loop;
• self-healing и crash-recovery notes;
• provider support notes;
• setup / requirements / architecture documentation.

Для кого

• для людей, которые собирают multi-agent workflow;
• для OpenClaw-style пользователей;
• для тех, кто хочет понять разделение ролей в агентской команде;
• для разработчиков, которым нужен не один agent prompt, а структура команды.

Что это не делает

Это не hosted service и не готовая production-инсталляция с вашими ключами. Repo не должен содержать secrets, private memory, sessions или live customer data. Любой реальный запуск требует локальной настройки providers, routing, auth и safety policies.

Быстрый старт

git clone https://github.com/AlekseiUL/heisenberg-team.git
cd heisenberg-team

После clone проверьте requirements, настройте providers локально и не коммитьте свои runtime secrets.

Links / Resources

• YouTube: https://youtube.com/@alekseiulianov
• Telegram channel Sprut AI: https://t.me/Sprut_AI
• Telegram chat: https://t.me/+eH-qNIDmud8zNDZi
• AI Операционка: https://t.me/tribute/app?startapp=sJyg

License

MIT

---

🇷🇺 Русская версия

Полная документация на русском: README.ru.md

---

Built with OpenClaw - the open-source AI agent platform.