Getting Started with Maximus
Step-by-step guide from installation to running your first agent team with the Mission Control dashboard.
Prerequisites
- Node.js 22+ (LTS recommended)
- pnpm 10+ — install globally with
npm install -g pnpm - A Claude API key from console.anthropic.com or a Claude Agent SDK OAuth token
Installation
git clone https://github.com/sancag/maximus.git cd maximus pnpm install pnpm build
The pnpm install step installs dependencies across all workspace packages. The pnpm build step compiles shared types, core engine, vault, and server via Turborepo.
Project Structure 7 packages
Maximus is a pnpm monorepo with seven packages:
Step 1: Initialize Your Project
maximus init
The interactive wizard creates ~/.maximus/ with the full project structure. It prompts for your agent name, OAuth token, and vault key.
Step 2: Configure Credentials
export MAXIMUS_VAULT_KEY="your-secret-key-here"
The vault encrypts all stored credentials at rest using AES-256-GCM. Agents never have direct access to secrets — the tool executor resolves credentials from the vault at call time and sanitizes responses before returning them to the agent.
See Credential Vault for full documentation on storing and managing secrets.
Step 3: Define Your First Agent
Create a Markdown file in agents/ with YAML frontmatter for metadata and Markdown body for the system prompt:
--- name: orchestrator description: Main orchestrator that coordinates the team model: sonnet maxTurns: 25 skills: [] --- You are the orchestrator. You manage a team of agents and delegate tasks to the appropriate team members based on their skills and roles. When given a goal, break it into subtasks and delegate each to the right agent. Report results back to the user as they complete.
The name field is the unique identifier. The model field accepts sonnet, opus, or haiku. An agent without a reportsTo field is treated as the root orchestrator.
See Agent Definition Format for the full schema and all available fields.
Step 4: Start the Server
cd packages/server pnpm start
The server starts on port 4100 and exposes:
Step 5: Open the Dashboard
The dashboard is served from the same server on port 4100. Open http://localhost:4100 in your browser.
Step 6: Using the Dashboard
Once the server is running:
Open the Dashboard
Navigate to http://localhost:4100 — you land on the Operations view (activity feed).
Check the Connection
A green dot in the top-right means the dashboard is connected to the server via WebSocket.
Open Chat
Click the Chat icon (speech bubble) in the sidebar to open the Chat view.
Send a Message
Type a message to your orchestrator agent and press Enter — the response streams in real-time via SSE.
Watch Operations
See real-time events as agents process work (tool calls, delegations, completions).
Explore Org Chart
Click the Org Chart icon (network) to see your agent hierarchy as a top-down tree.
Track Tasks
Click the Tasks icon (checklist) to track all task progress with sortable columns and status filters.
See Dashboard Documentation for detailed view descriptions, event type mappings, and connection handling.
Multi-Agent Setup
To set up a hierarchy, define multiple agents with reportsTo fields:
--- name: orchestrator description: Coordinates the team model: sonnet ---
--- name: research-manager description: Manages research tasks model: sonnet reportsTo: orchestrator ---
--- name: web-researcher description: Searches the web for information model: haiku reportsTo: research-manager skills: - web-search ---
Delegation is code-enforced: agents can only delegate to their direct reports, and the runtime validates hierarchy before spawning child work.
See Multi-Agent Coordination for delegation patterns, task lifecycle, safety mechanisms, and the full API reference.
Memory System
Maximus agents can accumulate structured memory from their sessions. The memory system uses a dual database: Kuzu graph database for knowledge relationships and SQLite for episodes and metrics.
Enabling Agent Memory
Add a memory: block to any agent's frontmatter:
--- name: researcher description: Research specialist model: sonnet memory: episodic: true maxEpisodes: 50 knowledgeScopes: [] briefingEnabled: true briefingTokenBudget: 2000 learningRate: moderate ---
Deep Sleep Consolidation
The deep sleep pipeline runs on a cron schedule (default: 3 AM daily) and performs:
Trace Analysis
Trace analysis and episode distillation
Entity Extraction
Entity extraction into the knowledge graph
Briefing Generation
Briefing generation for each agent
Stale Knowledge Pruning
Stale knowledge pruning
Scope Promotion
Scope promotion of high-value facts
Set the schedule with the MAXIMUS_DEEP_SLEEP_SCHEDULE environment variable (cron syntax).
Performance Trends
Agents with memory enabled automatically receive performance trends in their session briefings. These trends show success rate direction (UP/DOWN/STABLE), cost patterns, and failure concentration over a 7-day sliding window. No configuration needed — if briefingEnabled: true, trends are included.
Knowledge Scopes
Knowledge is organized in three scope levels:
reportsToFacts are automatically promoted up the scope hierarchy during deep sleep based on retrieval frequency and cross-agent relevance.
CLI Commands
# Initialize project maximus init # Check system health maximus doctor # Server management maximus server start maximus server stop # Interactive chat maximus chat # Vault management maximus vault # Memory commands maximus memory status maximus memory inspect <agent-name> maximus memory promote <sourceId> <predicate> <targetId> maximus memory re-extract maximus memory reset