Skip to content

TomOstt/AtlasColonyTUI

BranchesTags

Repository files navigation

AtlasColony

AtlasColony

Multi-agent AI coding with zero infrastructure.
No databases. No message queues. No APIs between agents. Just git.

Configure a colony of Claude Code agents. Write your goals. Walk away.
They decompose, implement with TDD, review every line, and merge to main.

Setup time Agents Infrastructure License GitHub stars


AtlasColony in action — 5 agents building a REST API
5 agents autonomously building a REST API with auth. Real terminal. Real time. No edits.

What is this?

You write a goals file describing what you want built. AtlasColony spins up a team of AI agents that autonomously decompose your goals into tasks, implement them with TDD, review every line of code, and merge to main.

No human intervention. No babysitting. No copy-pasting between chat windows.

You write GOALS.md
  → CEO pivots strategy if needed
    → ATLAS breaks goals into tasks
      → 5 coders race to implement (TDD, git worktrees, isolated branches)
        → AUDIT reviews every diff, runs tests, merges or rejects
          → BETA-TESTER validates everything against goals, files bugs
            → Repeat until done

Everything is coordinated through git. No message queues. No databases. No APIs. No infrastructure. Just git commits and file moves.

Why?

Problem AtlasColony
AI coding assistants need constant hand-holding Agents work autonomously in loops — no prompting
One AI instance = one thread of work N parallel coders racing through your task queue
No quality control on AI-generated code Dedicated AUDIT agent reviews every line before merge
Context lost between sessions Persistent memory via git history, task files, and reports
Complex infrastructure to coordinate agents Zero infra — git is the only message bus
One-size-fits-all agent setups Fully configurable — define any agents, any roles, any team structure

How It Compares

AtlasColony Claude Agent Teams Roo Code OpenHands
Orchestration Git only — zero infra Built into Claude Code VS Code extension Runtime + sandbox
State management Git commits Session state Editor state Runtime containers
Agent isolation Git worktrees Subprocess sandboxes Single context Docker sandboxes
Setup time 2 min, zero deps Built into Claude Code VS Code install Docker + config
Audit trail git log — every decision, every line Session logs Editor history Sandbox logs
Self-healing Watchdog with lease-based recovery Manual restart — Health checks
Fully open source MIT Anthropic feature MIT MIT
Custom agent roles Any role via templates Fixed patterns Single agent Predefined agents

AtlasColony's bet: You don't need databases, message queues, or custom runtimes to coordinate AI agents. Git already solves distributed coordination — we just use it.

Quick Start

# 1. Clone AtlasColony
git clone https://github.com/TomOst-Sec/atlas-colony.git
cd atlas-colony

# 2. Initialize your project
./bin/colony init https://github.com/you/your-project.git

# 3. Write your goals
vim the-project/_colony/GOALS.md

# 4. Launch the colony
./bin/colony start all

# 5. Watch it build
./bin/colony dashboard

That's it. Your agents are now autonomously building your project.

What People Build With This

  • SaaS MVPs — Write goals for a full-stack app, come back to a working prototype
  • Open source maintenance — Point it at your issue backlog, let it grind through bugs
  • Code migrations — "Migrate this Express app to Fastify" as a single goal
  • Research projects — Non-coding colonies that research, synthesize, and write reports
  • Refactoring sprints — "Add TypeScript types to all 200 files" with 10 parallel coders

How It Works

The Agent Hierarchy

        ┌──────────┐
        │   CEO    │  Strategic oversight, goal pivots
        └────┬─────┘
             │
        ┌────┴─────┐
        │  ATLAS   │  Decomposes goals → tasks
        └────┬─────┘
             │
    ┌────────┼────────┐
    │        │        │
┌───┴──┐ ┌──┴───┐ ┌──┴───┐
│ALPHA │ │ALPHA │ │BRAVO │  5 parallel coders (TDD)
│  1   │ │ 2,3  │ │ 1,2  │
└───┬──┘ └──┬───┘ └──┬───┘
    │        │        │
    └────────┼────────┘
             │
    ┌────────┼────────┐
    │        │        │
┌───┴──┐ ┌──┴───┐ ┌──┴───┐
│AUDIT │ │ BETA │ │ DOCS │  Review + test + document
│      │ │TESTER│ │      │
└───┬──┘ └──┬───┘ └──┬───┘
    │        │        │
    └────────┼────────┘
             │
          [ main ]

The Task Lifecycle

queue/  ──→  active/  ──→  review/  ──→  done/
  ↑                           │
  └────── rejected ───────────┘  (+ bug report)
  ↑                                      │
  └──── beta-tester finds regression ────┘
  1. ATLAS reads your goals and generates detailed task files in queue/
  2. Coders race to claim tasks (atomic, first-come-first-served)
  3. Each coder creates an isolated git worktree, implements with TDD, pushes a branch
  4. AUDIT checks out the branch, runs the full test suite, reviews every line of the diff
  5. If clean → merge to main. If problems → reject with bug report back to queue
  6. BETA-TESTER validates all merged commits against GOALS.md — files bug tasks if something breaks or drifts from the vision
  7. ATLAS reads bug reports and generates fix tasks. Repeat.

Coordination = Git

All agent communication happens through files in _colony/:

_colony/
├── GOALS.md           ← You write this
├── ROADMAP.md         ← ATLAS maintains this
├── CEO-DIRECTIVE.md   ← CEO writes strategic pivots
├── queue/             ← Pending tasks
├── active/            ← Tasks being worked on
├── review/            ← Awaiting AUDIT review
├── done/              ← Completed and merged
├── bugs/              ← Bug reports (AUDIT/BETA-TESTER → ATLAS)
├── reports/           ← Hourly status + daily + beta-test reports
└── logs/              ← Per-agent activity logs

No Redis. No Kafka. No PostgreSQL. Just git add, git commit, git push.

Configure Your Colony

AtlasColony is fully configurable via colony.yml. Run 3 agents or 30. Define custom roles. Mix models. Create any team structure.

Default: 10-Agent Colony

# colony.yml
teams:
  alpha:
    task_ratio: 60
  bravo:
    task_ratio: 40

agents:
  ceo:
    type: overseer
    model: opus
    cycle: 60
    skills: [strategic-oversight]

  atlas:
    type: planner
    model: opus
    cycle: 30
    skills: [task-generation]

  audit:
    type: reviewer
    model: opus
    cycle: 15
    skills: [code-review]

  beta-tester:
    type: tester
    model: opus
    cycle: 45
    skills: [beta-testing]

  docs:
    type: documenter
    model: sonnet
    cycle: 120
    skills: [documentation]

  alpha-1:
    type: coder
    team: alpha
    model: opus
    skills: [tdd-coding]

  alpha-2:
    type: coder
    team: alpha
    model: opus
    skills: [tdd-coding]

  alpha-3:
    type: coder
    team: alpha
    model: opus
    skills: [tdd-coding]

  bravo-1:
    type: coder
    team: bravo
    model: opus
    skills: [tdd-coding]

  bravo-2:
    type: coder
    team: bravo
    model: opus
    skills: [tdd-coding]

Minimal: 3-Agent Colony

teams:
  dev:
    task_ratio: 100

agents:
  planner:
    type: planner
    model: opus
    cycle: 30
    skills: [task-generation]

  coder:
    type: coder
    team: dev
    model: opus
    skills: [tdd-coding]

  reviewer:
    type: reviewer
    model: opus
    cycle: 15
    skills: [code-review]

Research Colony (non-coding)

teams:
  research:
    task_ratio: 60
  writing:
    task_ratio: 40

agents:
  director:
    type: overseer
    model: opus
    cycle: 60
    skills: [strategic-oversight]

  researcher-1:
    type: coder
    team: research
    model: opus
    skills: [research]

  researcher-2:
    type: coder
    team: research
    model: opus
    skills: [research]

  writer:
    type: coder
    team: writing
    model: opus
    skills: [technical-writing]

  editor:
    type: reviewer
    model: opus
    cycle: 20
    skills: [code-review]

Scale to 20 Coders

teams:
  frontend:
    task_ratio: 30
  backend:
    task_ratio: 40
  infra:
    task_ratio: 30

agents:
  ceo:
    type: overseer
    model: opus
    cycle: 60
  atlas:
    type: planner
    model: opus
    cycle: 20          # faster cycles for more coders
  audit:
    type: reviewer
    model: opus
    cycle: 10

  # 6 frontend coders
  fe-1: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }
  fe-2: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }
  fe-3: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }
  fe-4: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }
  fe-5: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }
  fe-6: { type: coder, team: frontend, model: sonnet, skills: [tdd-coding] }

  # 8 backend coders
  be-1: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-2: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-3: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-4: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-5: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-6: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-7: { type: coder, team: backend, model: opus, skills: [tdd-coding] }
  be-8: { type: coder, team: backend, model: opus, skills: [tdd-coding] }

  # 6 infra coders
  ops-1: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }
  ops-2: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }
  ops-3: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }
  ops-4: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }
  ops-5: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }
  ops-6: { type: coder, team: infra, model: sonnet, skills: [tdd-coding] }

Create Custom Agents

Custom Agent Types

Create a new template in templates/agents/:

<!-- templates/agents/security-auditor.md.tmpl -->
---
name: ${AGENT_NAME}
model: ${MODEL}
allowedTools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebSearch]
---

# ${AGENT_NAME} — Security Auditor

You are a security-focused reviewer. You scan every diff for vulnerabilities
before code reaches main.

## Your Cycle
Every ${CYCLE_MINUTES} minutes:
1. Pull latest
2. Scan review/ for tasks
3. Run SAST tools on each branch
4. Check OWASP Top 10
5. Flag or approve

Then reference it in colony.yml:

agents:
  sec-check:
    type: security-auditor    # matches your template filename
    model: opus
    cycle: 20
    skills: [security-analysis]

Custom Skills

Create a new skill in templates/skills/:

<!-- templates/skills/security-analysis.md -->
---
description: "Security analysis skills — OWASP, SAST, dependency scanning"
---

# Security Analysis Skills

## OWASP Top 10 Checklist
- [ ] Injection (SQL, command, LDAP)
- [ ] Broken authentication
- [ ] Sensitive data exposure
...

Commands

colony init <remote>          # Initialize a new colony project
colony start [agent|all]      # Start agent(s)
colony stop [agent|all]       # Stop agent(s)
colony status                 # Show colony status
colony dashboard              # Live auto-refreshing dashboard
colony pause                  # Pause all agents
colony resume                 # Resume all agents
colony logs [agent]           # Tail agent logs
colony add-agent <name> <type> [team] [model]  # Add agent to config
colony nuke --confirm         # Remove ALL colony files, leave clean source code

colony nuke — Clean Exit

When your project is done and ready to ship, run colony nuke --confirm to strip all colony infrastructure from your project repo. It removes _colony/, .claude/, CLAUDE.md, worktrees, and all remote task branches — leaving only your clean source code. Reports and completed task history are archived to a timestamped backup folder before deletion.

Your project goes from "managed by a robot army" to "clean professional repo" in one command.

Dashboard

The live dashboard shows everything at a glance:

╔════════════════════════════════════════════════════════════════╗
║  ATLAS COLONY DASHBOARD                   2026-03-15 14:30   ║
╠════════════════════════════════════════════════════════════════╣
║                                                               ║
║  AGENTS                                                       ║
║  Strategy:                                                    ║
║    ● CEO        — Strategic oversight (60min)                 ║
║  Management:                                                  ║
║    ● ATLAS      — Task generation (30min)                     ║
║    ● AUDIT      — Code review (15min)                         ║
║  Testing:                                                     ║
║    ● BETA-TESTER — Goal validation (45min)                    ║
║  Documentation:                                               ║
║    ● DOCS        — README & docs sync (120min)                ║
║  Alpha Team (3 coders):                                       ║
║    ● ALPHA-1    — Coder (continuous)                          ║
║    ● ALPHA-2    — Coder (continuous)                          ║
║    ● ALPHA-3    — Coder (continuous)                          ║
║  Bravo Team (2 coders):                                       ║
║    ● BRAVO-1    — Coder (continuous)                          ║
║    ● BRAVO-2    — Coder (continuous)                          ║
║                                                               ║
║    10/10 agents running                                         ║
║                                                               ║
╠════════════════════════════════════════════════════════════════╣
║                                                               ║
║  PIPELINE                                                     ║
║    queue/  ──▶  active/  ──▶  review/  ──▶  done/            ║
║      5           3             1            12                ║
║                                                               ║
╚════════════════════════════════════════════════════════════════╝

Reports

Hourly status — _colony/reports/hourly-STATUS.md Quick snapshot: pipeline depth, tasks merged, active work, health check.

Daily report — _colony/reports/YYYY-MM-DD.md Full analysis: velocity, quality metrics, team performance, roadmap progress, recommendations.

Beta test report — _colony/reports/beta-test-YYYYMMDD-HHMM.md Commit-level validation against goals, regression detection, and auto-filed bug tasks.

Both generated automatically by AUDIT and BETA-TESTER agents. Zero human effort.

Architecture

┌─────────────────────────────────────────────────────────┐
│                    Your Machine                          │
│                                                          │
│  ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐ ┌──────┐         │
│  │ tmux │ │ tmux │ │ tmux │ │ tmux │ │ tmux │  ...     │
│  │ CEO  │ │ATLAS │ │AUDIT │ │ α-1  │ │ β-1  │         │
│  └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘ └──┬───┘         │
│     │        │        │        │        │               │
│     └────────┴────────┴────────┴────────┘               │
│                       │                                  │
│              ┌────────┴────────┐                        │
│              │   git repo      │                        │
│              │  _colony/       │                        │
│              │  ├── queue/     │  ← tasks flow through  │
│              │  ├── active/    │    these directories    │
│              │  ├── review/    │    via git commits      │
│              │  ├── done/      │                        │
│              │  └── ...        │                        │
│              └────────┬────────┘                        │
│                       │                                  │
│              ┌────────┴────────┐                        │
│              │  GitHub Remote  │                        │
│              └─────────────────┘                        │
└─────────────────────────────────────────────────────────┘

Each agent runs in its own tmux session as a Claude Code instance with a specialized agent definition. They communicate exclusively through git commits — moving task files between directories, pushing branches, and writing reports.

Zero infrastructure. If your machine can run git and tmux, it can run AtlasColony.

Requirements

  • Claude Code (npm install -g @anthropic-ai/claude-code)
  • Anthropic API key (set ANTHROPIC_API_KEY)
  • git and tmux
  • yq (YAML processor — installed automatically during init)
  • Linux, macOS, or WSL on Windows

FAQ

How much does it cost to run?

Depends on the number of agents and their models. A full 9-agent Opus colony uses significant API credits. Tips:

  • Use sonnet for coders (fast, cheap, excellent at coding)
  • Use opus for CEO, ATLAS, and AUDIT (need deep reasoning)
  • Start with the minimal 3-agent config to test
Can I run this across multiple machines?

Yes! Since coordination is through git, agents can run on any machine that can push/pull from the same repo. Just run colony start <agent> on each machine with the appropriate agent name.

What happens if an agent crashes or stalls?

The watchdog runs every 5 minutes and detects two failure modes:

  1. Crashed (tmux session dead) — restarts the agent with exponential backoff
  2. Stalled (tmux alive but no git activity for 30-45 min) — kills the session, moves stuck tasks back to queue, restarts with fresh context

The watchdog uses lease-based tracking: tasks carry Claimed-At timestamps so stuck tasks are recovered precisely instead of relying on file age. Restart backoff escalates (5m → 10m → 20m → 40m → 60m cap) to avoid hammering a persistently failing agent. Orphaned worktrees are cleaned up automatically.

Can I use this with other AI models?

AtlasColony is built on Claude Code, which currently supports Claude models. The architecture is model-agnostic in principle — the coordination protocol is just git files. Future versions may support other agent runtimes.

How do I stop everything? 
colony pause          # Graceful — agents finish current work and wait
colony stop all       # Kill all tmux sessions immediately
tmux kill-server      # Nuclear option
Can I add or remove agents while the colony is running?

Yes. Edit colony.yml, run colony init to regenerate configs, then colony start <new-agent>. Existing agents don't need to restart — they'll pick up changes on their next git pull.

How is this different from just running Claude Code?

Claude Code is a single agent working in a single thread. AtlasColony is N agents working in parallel with separation of concerns — planners don't write code, coders don't review their own work, and every merge goes through an independent audit. It's the difference between one developer and a development team.

How is this different from Cursor's Background Agents or Codex?

Those are cloud-hosted, closed-source, and vendor-locked. AtlasColony runs on your machine, coordinates through git (which you already understand and can inspect), and is fully open source. You own the entire workflow.

Built-In Agent Types

Type Role Cycle Skills
overseer Strategic direction, goal pivots, directives Periodic Strategic oversight, risk detection
planner Task decomposition, roadmap, bug processing Periodic Architecture, dependency analysis
reviewer Code review, testing, merge/reject, reports Periodic Security analysis, QA, debugging
tester Validates commits against goals, regression detection, bug filing Periodic Functional testing, goal alignment
documenter Keeps README, changelog, and docs in sync with codebase Periodic (2hr) Technical writing, code reading, accuracy verification
coder TDD implementation, branch per task Continuous TDD, debugging, git worktrees

Create custom types by adding .md.tmpl files to templates/agents/.

Contributing

Contributions welcome! See CONTRIBUTING.md.

Areas we'd love help with:

  • New agent type templates (DevOps, security auditor, documentation writer)
  • New skill definitions
  • Example colony.yml configs for different use cases
  • Dashboard improvements
  • Multi-model support (beyond Claude)
  • Performance optimization for large colonies (20+ agents)

Acknowledgments

Built with:

Star this repo if your AI agents should work as hard as you do.

GitHub stars

About

Multi-agent AI coding platform — zero infrastructure. Configure a colony of Claude Code agents, give them goals, walk away. They decompose tasks, implement with TDD, review every line, and merge to main. No databases, no queues, just git.

Topics

ai agi swarm swarms multi colony multi-agent-systems swarm-intelligence ai-agents

Resources

Readme

License

MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages