Maximus
Define, coordinate, and monitor hierarchical teams of Claude agents with encrypted credentials, persistent memory, and real-time observability.
How It Works Overview
Agents are Markdown files. Skills are YAML files. Credentials are encrypted. The runtime orchestrates everything — delegation, tool execution, memory, and events — while the dashboard shows it all in real time.
reportsTo. Models: Sonnet, Opus, Haiku.Dive Deeper Topics
Quick Start
Init wizard, first agent, server & dashboard setup in 5 minutes.
↓ Jump to sectionCredential Vault
AES-256-GCM encryption, the Proxy pattern, and output sanitization.
↓ Jump to sectionDelegation Engine
Hierarchy enforcement, circuit breakers, task lifecycle, and agent locking.
↓ Jump to sectionMemory & Knowledge Graph
Dual-database engine, deep sleep consolidation, scope promotion, briefings.
↓ Jump to sectionMission Control
7 dashboard views, WebSocket streaming, Canvas org chart, SSE chat.
↓ Jump to sectionCLI & API Reference
All commands, TUI slash commands, REST endpoints, and event types.
↓ Jump to sectionQuick Start Setup
Install
Requires Node.js 22+ and pnpm 10+.
git clone https://github.com/sancag/maximus.git
cd maximus && pnpm install && pnpm build
Initialize Your Project
The init wizard creates ~/.maximus/ with everything you need. It prompts for your agent name, OAuth token, and vault encryption key. It generates your orchestrator agent, a memory-extractor agent for deep sleep, config, env file, and reference docs.
maximus init
Start the Server & Dashboard
maximus server start # Background, port 4100
The dashboard is bundled with the server at http://localhost:4100. Or just chat from the terminal: maximus chat "Hello" — or launch the full interactive TUI: maximus
Credential Vault Security
Agents need API keys to call external services, but you don't want raw secrets in context windows where they could be logged, leaked, or hallucinated back. Maximus takes a zero-knowledge approach — credentials are encrypted at rest and only decrypted inside the tool execution boundary, never in agent-visible code paths.
All credentials use AES-256-GCM authenticated encryption. The key is derived from MAXIMUS_VAULT_KEY via scrypt with a 32-byte salt. Each credential gets a unique 16-byte IV from crypto.randomBytes. GCM's authentication tag detects tampering.
Agent cannot access credentials programmatically — no vault API is exposed to agents. Credentials never in context window — agents see {{TOKEN}}, never values. Output sanitized — PostToolUse hook catches Anthropic keys (sk-ant-*), GitHub tokens (ghp_*), AWS keys (AKIA*), Bearer tokens, connection strings, and long hex strings. Authenticated encryption — tampered vault files detected by GCM tag.
Delegation Engine Multi-Agent
When a parent agent needs work done, it calls the delegate tool — an MCP server injected into every session. Delegation is non-blocking: the parent gets a taskId immediately and continues working. Later, check_task polls for results, or wait_for_tasks awaits multiple in parallel.
reportsTo must match the sender. Agents can only delegate to direct reports.Task Lifecycle
created → assigned → in-progress → completed
→ failed
Each transition emits an event to WebSocket clients and JSONL traces. The AgentLock serializes execution per agent — one run at a time per agent name, with a queue for subsequent requests. This prevents concurrent context corruption while allowing parallel delegation to different agents.
Memory & Knowledge Graph Persistence
Without memory, an agent that spent two sessions learning how to reliably paginate a particular API will rediscover that same lesson in session three. The memory system solves this at the swarm level with three jobs: record what agents experience, consolidate into a queryable knowledge graph overnight, and inject relevant facts back into each agent's system prompt.
Two storage backends: Kuzu (embedded graph database) for entities and relationship triples; SQLite for episodes, cached briefings, strategy registry, and metrics. Both are file-local and open lazily.
The pipeline runs during deep sleep (default 3 AM daily) so zero overhead touches live sessions. Each stage is independently error-handled — a failure in extraction doesn't block briefing generation.
Reads JSONL traces and extracts structured episodes: summary, outcome (success/failure/partial), lessons from tool pair analysis, effective strategies (3+ consecutive successes), failure patterns, and regression detection (task that previously succeeded but now fails). No LLM involved — pure parsing.
Sends episodes to Claude Haiku in parallel. Returns typed entities and relationship triples with confidence scores (0.9 for confirmed facts, 0.7 for patterns, 0.5 for inferences). Entities deduplicated by name; attributes merged across extractions. Uses the memory-extractor agent created by init.
Agent→Team: when 2+ teammates share a fact, or retrieval count exceeds threshold (adjusted by success rate — high-success agents promote at 60% of base). Team→Global: 2+ distinct team evidence tags. Orchestrator knowledge auto-promoted to global.
Assembles prioritized markdown within briefingTokenBudget. Strict priority: failure lessons first, then performance trends (7-day window), then high-confidence graph facts, then proven strategies (usage ≥2). When content exceeds budget, strategies trimmed before knowledge, knowledge before lessons.
Temporal Supersession
The knowledge graph is an append-only fact log. When a new fact contradicts an existing one (same source, predicate, target), the old triple's validTo is timestamped and a new triple is inserted. History is never deleted. Every belief change is recorded — you can inspect exactly what changed in an agent's knowledge graph and which episode caused it.
Full Knowledge Graph documentation with interactive SVG diagrams →
Mission Control Dashboard
Next.js 16 + React 19 + Zustand + Tailwind CSS v4. Connects via WebSocket (auto-reconnect with exponential backoff, 1s to 30s) and REST. All URLs are relative — no env vars needed.
CLI & API Reference
Running maximus with no arguments launches the interactive TUI — branded ASCII logo, persistent chat with streaming, status bar (server state, agents, tasks, uptime), and slash commands (/start, /stop, /vault set, /new, /help).