🧪 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 v18+
• 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

	Minimum	Recommended
RAM	2 GB	4 GB (8 agents)
Disk	500 MB	2 GB (with logs/memory)
OS	macOS 11+, Ubuntu 20.04+, Windows 11 (WSL2)	macOS 13+ or Ubuntu 22.04+
Node.js	18.x	20.x+
Network	Required (LLM API calls)	Broadband

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?

Feature	Heisenberg Team	AutoGPT	CrewAI	MetaGPT
Setup	5-min wizard	Manual YAML	Python code	Python code
Crash recovery	File-based board survives restarts	In-memory, lost on crash	In-memory	In-memory
Agent coordination	Board-First protocol + sessions_send	Shared memory	Sequential/hierarchical	SOP-based
Self-healing	Built-in (cron-based)	No	No	No
Skills library	34 ready-to-use	Plugin ecosystem	Build your own	Build your own
Personality	Persistent SOUL.md per agent	Generic	Role description	Role description
Memory	SQLite + vector search + file-based	Vector DB	Short-term only	Shared memory
Monitoring	Heartbeat + health checks	Logs only	Logs only	Logs only
Multi-platform	macOS + Linux + WSL	Docker	Python	Python

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["🧪 Heisenberg<br/>Boss & Coordinator<br/><i>Opus</i>"]
        
        subgraph specialists["Specialists"]
            Saul["💼 Saul Goodman<br/>Producer<br/><i>Sonnet</i>"]
            Walter["👨‍🔬 Walter White<br/>Tech Lead<br/><i>Sonnet</i>"]
            Jesse["🎯 Jesse Pinkman<br/>Marketing<br/><i>Sonnet</i>"]
            Skyler["💰 Skyler White<br/>Finance<br/><i>Sonnet</i>"]
            Hank["🔫 Hank Schrader<br/>Security<br/><i>Sonnet</i>"]
            Gus["🎯 Gus Fring<br/>Kaizen/Goals<br/><i>Sonnet</i>"]
            Twins["👥 Salamanca Twins<br/>Research<br/><i>Sonnet</i>"]
        end
        
        Board["📋 Team Board<br/><i>File-based state</i>"]
        Memory["🧠 Memory<br/><i>SQLite + Vectors</i>"]
        Skills["⚡ 34 Skills<br/><i>PDF, XLSX, Research...</i>"]
    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

Agent	Character	Role	Key Skills
Heisenberg	Walter White	Boss, user-facing	Delegation, delivery
Saul	Saul Goodman	Coordinator	Pipeline management, briefings
Walter	Walter White (lab)	Team Lead	Code, PDF, GitHub, skills
Jesse	Jesse Pinkman	Marketing	Funnels, campaigns, analytics
Skyler	Skyler White	Admin/Finance	DOCX, XLSX, contracts
Hank	Hank Schrader	Security/QA	Audits, monitoring
Gus	Gus Fring	Kaizen	Crons, self-improvement
Twins	Salamanca Twins	Research	Deep research, web analysis

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.

---

TalentDelta provenance record (added at packaging - upstream tree otherwise unchanged)

• Packaged for: TalentDelta catalogue (draft; gated by review)
• Upstream: https://github.com/AlekseiUL/heisenberg-team
• Pinned commit: 77093f12f34f204947631b6ff8b6f88de347e400 (2026-06-06)
• Licence: MIT - the upstream LICENSE file ships unchanged
• Upstream author credit: Aleksei Ulianov / Sprut_AI
• Runtime: An OpenClaw-compatible agent runtime (attach to an existing install via SETUP.md / scripts/setup.sh); ANTHROPIC_API_KEY
• Changes made at packaging: this section was appended to README.md. No files were added, removed or renamed; every other file is byte-identical to the pinned commit.
• Safety read of the packaged archive (packaging time, 2026-09-30): no live secrets or credentials. Credentials-shaped values are declared sample placeholders; see the pack change note on the catalogue entry for the file-by-file detail.