Atlas

Containerized autonomous agent system powered by Claude Code.

Atlas turns Claude Code into a persistent, event-driven agent that sleeps until needed, processes messages from multiple channels, manages its own memory, and wakes up automatically when new work arrives — no polling, no wasted compute.

How It Works

External Event → Inbox (SQLite) → .wake file touched → inotifywait → Claude resumes
                                                                         ↓
                                                              Process message, write memory
                                                                         ↓
                                                              Stop Hook checks inbox
                                                                         ↓
                                                   More messages? → Continue : Sleep

Atlas uses an inbox-based communication model: all triggers (cron jobs, webhooks, web chat, internal tasks) write messages to a SQLite inbox. A filesystem watcher detects the wake signal and resumes the Claude session. After processing, a stop hook checks for more pending messages — if none, Claude sleeps until the next event.

Quick Start

1. Build

git clone https://github.com/mxzinke/atlas.git
cd atlas
docker compose build

2. Authenticate

Atlas needs Claude Code credentials. Choose one:

Option A: OAuth (recommended)

docker run -it --rm -v $(pwd)/atlas-home:/root atlas claude login

Option B: API Key Uncomment ANTHROPIC_API_KEY in docker-compose.yml:

environment:
  - ANTHROPIC_API_KEY=sk-ant-...

3. Start

docker compose up -d

The Web-UI is available at http://localhost:8080.

4. Send a Message

Open the Web-UI chat at /chat, or POST directly:

curl -X POST http://localhost:8080/chat \
  -d "content=Hello Atlas, what can you do?"

Claude wakes up, processes the message, and the response appears in the inbox.

Architecture

Atlas runs entirely in a single Docker container managed by supervisord:

Component	Port	Purpose
nginx	8080	Reverse proxy to web-ui
web-ui	3000	Hono.js + HTMX dashboard
inbox-mcp	stdio	MCP server for Claude's inbox tools
qmd	8181	Memory search (BM25/vector/hybrid)
watcher	—	inotifywait loop, resumes Claude on .wake
supercronic	—	Cron job runner

See docs/Architecture.md for component overview, docs/inbox-mcp.md for MCP tools, and docs/qmd-memory.md for memory search.

Triggers

Atlas supports three trigger types to wake Claude:

Type	How It Works	Example
Cron	Scheduled via supercronic	0 9 * * 1-5 — weekdays at 9am
Webhook	HTTP endpoint receives external POST	GitHub push events, Slack commands
Manual	Button click in web-ui or MCP tool call	On-demand tasks

Claude can create triggers itself via MCP tools:

"Check my GitHub repos every hour"
→ trigger_create(name: "github-check", type: "cron", schedule: "0 * * * *", prompt: "...")

External services send webhooks to /api/webhook/<name>:

curl -X POST http://localhost:8080/api/webhook/deploy-notify \
  -H "X-Webhook-Secret: your-secret" \
  -H "Content-Type: application/json" \
  -d '{"repo": "myapp", "branch": "main", "status": "success"}'

See docs/Triggers.md for the full guide and docs/watcher.md for the wake system.

Directory Structure

atlas/
├── app/                          # Core application (read-only in container)
│   ├── hooks/                    # Claude Code lifecycle hooks
│   │   ├── session-start.sh      # Loads identity + memory on wake
│   │   ├── stop.sh               # Checks inbox, continues or sleeps
│   │   ├── pre-compact-auto.sh   # Memory flush before compaction
│   │   └── subagent-stop.sh      # Quality gate for team results
│   ├── inbox-mcp/                # MCP server (inbox + trigger tools)
│   ├── web-ui/                   # Hono.js + HTMX dashboard
│   ├── triggers/                 # Trigger runner scripts
│   │   ├── trigger.sh            # Generic trigger runner
│   │   ├── sync-crontab.ts       # Crontab auto-generation from DB
│   │   └── cron/                 # Cron-specific scripts
│   ├── watcher.sh                # inotifywait event loop
│   └── init.sh                   # Container bootstrap
├── docker-compose.yml
├── Dockerfile
└── supervisord.conf

Workspace (mounted as volume, persists across restarts):

workspace/
├── memory/                       # Long-term memory + daily journals
│   ├── MEMORY.md                 # Persistent knowledge base
│   └── YYYY-MM-DD.md             # Daily journal entries
├── inbox/                        # SQLite database + wake file
├── triggers/                     # Custom trigger prompts
├── IDENTITY.md                   # Agent personality
├── SOUL.md                       # Agent soul (core values)
├── config.yml                    # System configuration
└── user-extensions.sh            # Custom package installs

See docs/directory-structure.md for complete layout.

Configuration

IDENTITY.md

Defines who Atlas is — personality, language, capabilities, restrictions. Edit via web-ui at /settings or directly in the workspace.

config.yml

System settings for memory search, cleanup behavior, and web-ui. Claude reads this file when needed (not injected into context).

memory:
  qmd_search_mode: search     # search | vsearch | query
  qmd_max_results: 6
  load_memory_md: true

daily_cleanup:
  enabled: true
  max_turns: 5

web_ui:
  port: 8080
  bind: "127.0.0.1"

user-extensions.sh

Runs on every container start. Use it to install custom tools:

#!/bin/bash
apt-get install -y signal-cli
pip install some-package

MCP Tools

Claude has access to these tools via the inbox-mcp server:

Inbox:

• inbox_list — List inbox messages by channel
• inbox_write — Create new message (triggers wake)
• inbox_stats — Inbox and task statistics

Channel CLI Tools (external communication):

• signal send|contacts|history — Send Signal messages, list contacts, view history
• email reply|send|threads|thread — Reply to email threads, send emails, list threads

Triggers:

• trigger_list — List all triggers
• trigger_create — Create cron/webhook/manual trigger
• trigger_update — Modify trigger settings
• trigger_delete — Remove trigger

Memory (QMD):

• qmd_search — BM25 text search
• qmd_vector_search — Semantic vector search
• qmd_deep_search — Combined hybrid search

See docs/inbox-mcp.md for inbox/trigger tools, docs/qmd-memory.md for memory tools, and docs/hooks.md for lifecycle hooks.

Logs

# All logs
docker compose logs -f

# Specific components
docker compose exec atlas tail -f /atlas/logs/session.log
docker compose exec atlas tail -f /atlas/logs/init.log

Development

# Rebuild after code changes
docker compose build && docker compose up -d

# Access container shell
docker compose exec atlas bash

# Check service status
docker compose exec atlas supervisorctl status

See docs/development.md for more development commands.

Documentation

• docs/Architecture.md — Component overview
• docs/inbox-mcp.md — Inbox system and MCP tools
• docs/hooks.md — Lifecycle hooks
• docs/watcher.md — Event-driven wake system
• docs/qmd-memory.md — Memory and search
• docs/web-ui.md — Dashboard and API
• docs/directory-structure.md — Filesystem layout
• docs/development.md — Developer guide
• docs/Triggers.md — Triggers guide
• docs/Integrations.md — Signal and Email

License

MIT