spacemolt

README

Spacemolt Multi-Agent System

An autonomous multi-agent system and development toolkit for the SpaceMolt game. Build AI agents that explore, mine, trade, craft, and interact with the game universe using LLM-powered decision making, or control the game programmatically through MCP (Model Context Protocol) integration with Claude.

Table of Contents

• Overview
• Key Features
• Recent Additions
• Quick Start
• Running Autonomous LLM Agents
• Database Backends
• Architecture
• How It Works
• Agent Personalities
• Example Sessions
• Claude Integration via MCP
• Automated Specialized Agents
• Web Interface
• REST API
• Development
• Troubleshooting
• Contributing
• License

Overview

The Spacemolt Multi-Agent System is a comprehensive development toolkit and automation platform that provides:

Autonomous Agent Framework

• Explore the universe independently using LLM-driven decision making
• Learn from experiences and build knowledge over time
• Collaborate by sharing information through a persistent knowledge base
• Play autonomously with specialized agent types (explorers, miners, traders, fighters, pirates, craftsmen, salvagers, prophets, random)
• Persist all discoveries automatically to SQLite storage
• Customize agent personalities and behaviors through JSON configuration

Claude AI Integration (MCP)

• Direct Control - Play SpaceMolt through Claude using Model Context Protocol
• 151 Game Commands - Auto-generated tools from OpenAPI spec covering the entire game API
• Crafting Intelligence - Query recipes and plan crafting based on inventory
• Real-time Updates - WebSocket and SSE bridges for live game state
• Multiple Bridges - Choose between WebSocket, SSE, or service-based architectures

Development Tools

• Web UI - React/TypeScript frontend for monitoring and controlling agents
• REST API - Programmatic control and status monitoring
• Knowledge Analytics - Query system for mining discoveries, market data, and routes
• Automated Agents - Pre-built specialized bots for common tasks

Each agent has a unique personality that drives their behavior, making decisions based on current situation, past experiences, and cumulative knowledge.

Key Features

🤖 Multiple Integration Modes

• LLM-Powered Agents - Autonomous agents with personality-driven decision making
• Claude Integration - Direct control via MCP (Model Context Protocol)
• Automated Bots - Pre-built specialized agents for specific tasks
• Programmatic API - REST API for custom integrations

🎮 Comprehensive Game Coverage

• 151 Game Commands - Auto-generated from OpenAPI spec, covering entire game API
• All Game Systems - Navigation, combat, mining, trading, crafting, factions, bases
• Real-time Updates - WebSocket and SSE support for live game state
• Version Tracking - Automatic API version compatibility checking

🧠 Knowledge & Learning

• Shared Knowledge Base - SQLite database with discoveries from all agents
• Advanced Analytics - Rich deposits, depleting resources, danger zones, market trends
• Experience Tracking - Complete action history for learning and improvement
• Route Optimization - Fuel cost and travel time learning

🛠️ Crafting System

• Recipe Database - Complete recipe and skill tree data
• Material Planning - Calculate requirements for any craftable item
• Profit Analysis - Find profitable crafting opportunities
• MCP Integration - Query crafting data through Claude

📊 Monitoring & Control

• React Web UI - Modern frontend for monitoring and control
• REST API - Programmatic access to agent status and control
• Agent Registry - Centralized status and coordination

🔐 Flexible Storage

• Multiple Backends - File, encrypted SQLite, OS keyring for credentials
• Knowledge Persistence - Long-term accumulation across sessions
• Market Data Capture - Historical price and listing tracking
• Captain's Log - In-game logging and note-taking

Recent Additions

Claude AI Integration (MCP)

Play SpaceMolt directly through Claude with the Model Context Protocol. Three bridge implementations (WebSocket, SSE, Service) provide 151 auto-generated tools covering the entire game API.

Automated Specialized Agents

Ten pre-built automated agents (explorer, miner, trader, fighter, pirate, salvager, craftsman, prophet, random, llm-miner) provide task-specific automation without requiring LLM setup. Perfect for focused farming, exploration, or testing.

Web-Based Monitoring

React/TypeScript frontend provides modern UI for monitoring agent activity, viewing knowledge base, and controlling agents. Includes real-time dashboards, map views, and analytics.

Advanced Crafting System

Complete crafting database with recipe queries, material requirements calculation, and profit analysis. Integrated with both MCP and agent decision-making.

Enhanced Knowledge Base

Upgraded analytics for market trends, danger zones, route optimization, and resource depletion tracking. Agents share discoveries and learn from collective experience.

Playbook System

Strategic playbooks guide agents in specialized roles (explorer, miner, trader, fighter, etc.) with proven tactics and decision patterns.

MCP Integration - Play Through Claude

Use Claude AI to play SpaceMolt directly through the Model Context Protocol:

Available Bridges:

• mcp-ws-bridge - WebSocket bridge with 151 auto-generated game commands
• mcp-sse-bridge - Server-Sent Events bridge for streaming updates
• mcp-bridge-service - Service-based architecture for persistent connections

Claude Integration Features:

• Full game API access (navigation, combat, mining, trading, crafting, missions, factions)
• Recipe and skill tree queries for crafting decisions
• Real-time game state updates
• Market data and price analysis
• Faction management and warfare
• Base building and management

See cmd/mcp-ws-bridge/README.md and docs/MCP_TOOLS_IMPLEMENTATION.md for details.

Automatic Knowledge Persistence & Analytics

All agent discoveries are automatically saved to a SQLite knowledge base with advanced analytics:

• Systems: Names, positions, security levels, factions, connections
• POIs: Stations, asteroid belts, planets with resources
• Resources: Mining locations with richness, depletion tracking, and trend analysis
• Experiences: Complete action history for learning
• Anomalies: Automatic detection of rich deposits, depleting resources, and opportunities
• Routes: Optimization through learning fuel costs and travel times
• Markets: Price analytics and best buy/sell identification
• Danger Zones: Hostile activity tracking and risk assessment

Query Tools:

./scripts/query-knowledge.sh systems          # View discovered systems
./scripts/query-analytics.sh rich-deposits    # Find best mining spots
./scripts/query-analytics.sh anomalies        # View detected opportunities

Quick Start

Prerequisites

Core Requirements:

• Go 1.24 or later
• SpaceMolt Account - Register at spacemolt.com

For LLM-Powered Agents:

• Ollama running locally with the llama3.2 model (or other LLM provider)

For Claude Integration:

• Claude Desktop or Claude API access for MCP functionality

For Web UI:

• Node.js 18+ and npm (for frontend development)

Installing Ollama (Optional - for LLM agents)

# Install Ollama
curl -fsSL https://ollama.com/install.sh | sh

# Start Ollama service
ollama serve

# Pull the required model (in another terminal)
ollama pull llama3.2

Building

# Clone the repository
git clone https://github.com/rsned/spacemolt.git
cd spacemolt

# Build core binaries
make build

# Or build specific tools
go build -o bin/agent-server ./cmd/agent-server
go build -o bin/mcp-ws-bridge ./cmd/mcp-ws-bridge

Core Executables:

• bin/agent-server - Main server for running autonomous LLM agents
• bin/mcp-ws-bridge - MCP bridge for Claude integration

Specialized Automated Agents (legacy — migrating to overmind roles):

• bin/auto-explorer - Automated exploration bot
• bin/auto-trader - Automated trading bot
• bin/auto-fighter - Automated combat bot
• bin/auto-prophet - Automated prophet bot
• bin/auto-random - Automated random-action bot

Quick Start Guides

Choose your path:

1. LLM-Powered Autonomous Agents - Continue reading below for full agent setup
2. Claude Integration (MCP) - See cmd/mcp-ws-bridge/README.md
3. Automated Bots - See Automated Specialized Agents for pre-built automation
4. Web UI Development - See frontend/README.md

Running Autonomous LLM Agents

The agent-server is the primary way to run autonomous agents. It handles agent spawning, game connections, credential management, and graceful shutdown.

Basic Usage

# Start all agents found in data/agents/
bin/agent-server

# Start specific agents (highest priority method)
bin/agent-server --agents=explorer-7,miner-2

# Use environment variable
export SPACEMOLT_AGENTS=explorer-7,miner-2
bin/agent-server

# Use configuration file (see agents_config.yaml.example)
bin/agent-server --config=agents_config.yaml

The server will:

1. Discover agents based on your selection method
2. Load each agent's personality from data/agents/<id>/personality.json
3. Check for existing credentials (login) or register new agents
4. Connect to the game server with retry logic
5. Start the autonomous decision loop for each agent
6. Run until you press Ctrl+C for graceful shutdown

Test Agent Setup

Test an agent's personality and LLM connection without connecting to the game:

# Test the explorer-7 personality
bin/test-agent data/agents/explorer-7/personality.json

# Test with SQLite storage (default)
bin/test-agent data/agents/miner-2/personality.json --db-backend=sqlite --db-path=test-knowledge.db

# Test with in-memory storage
bin/test-agent data/agents/pirate-1/personality.json --db-backend=memory

Database Backends

The system supports two knowledge base backends:

SQLite (Default)

Persists all agent knowledge to disk, allowing discoveries to accumulate across sessions:

# Use SQLite (default)
bin/agent-server --db-backend=sqlite --db-path=spacemolt-knowledge.db

Benefits:

• Knowledge persists across restarts
• Agents remember systems, POIs, and connections from previous sessions
• Experience history is maintained
• Enables long-term learning and accumulation

Database location:

• Default: spacemolt-knowledge.db in current directory
• Custom path via --db-path flag

Query the database:

# View all discovered systems
sqlite3 spacemolt-knowledge.db "SELECT id, name, visit_count, last_visited FROM systems;"

# View agent experiences
sqlite3 spacemolt-knowledge.db "SELECT agent_id, type, description, time FROM experiences ORDER BY time DESC LIMIT 20;"

# View registered agents
sqlite3 spacemolt-knowledge.db "SELECT id, name, role, faction FROM agents;"

In-Memory

All knowledge is lost when the program exits:

# Use in-memory backend
bin/agent-server --db-backend=memory

Use cases:

• Testing and development
• Fresh start each session
• No database file management

Architecture

System Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                          SpaceMolt Game Server                          │
│                         (game.spacemolt.com)                            │
│                                                                         │
│  WebSocket API │ HTTP API │ OpenAPI Spec                               │
└────────┬────────────┬─────────────┬──────────────────────────────────┘
         │            │             │
         │            │             │ (sync spec)
         │            │             ▼
         │            │        ┌──────────────────┐
         │            │        │ generate-mcp-    │
         │            │        │ tools            │
         │            │        └────────┬─────────┘
         │            │                 │
         │            │                 ▼ (generates 151 tools)
    ┌────┴────────────┴──────────────────────────────────────┐
    │                                                         │
┌───▼────────────┐  ┌──────────────┐  ┌────────────────────┐│
│ Agent Server   │  │ MCP Bridges  │  │  Web UI / API      ││
│                │  │              │  │                    ││
│ ┌────────────┐ │  │• ws-bridge   │  │• React Frontend    ││
│ │Agent Mgr   │ │  │• sse-bridge  │  │• REST API Server   ││
│ │            │ │  │• service     │  │• Agent Registry    ││
│ │┌──────────┐│ │  │              │  │                    ││
│ ││Runner 1  ││ │  └──────┬───────┘  └─────────┬──────────┘│
│ ││Explorer  ││ │         │                    │            │
│ │└──────────┘│ │         │                    │            │
│ │┌──────────┐│ │         ▼                    ▼            │
│ ││Runner 2  ││ │  ┌──────────────┐   ┌────────────────┐   │
│ ││Miner     ││ │  │ Claude AI    │   │   Monitoring   │   │
│ │└──────────┘│ │  │              │   │   Dashboard    │   │
│ │┌──────────┐│ │  │• Desktop     │   │                │   │
│ ││Runner 3  ││ │  │• API         │   │                │   │
│ ││Fighter   ││ │  │              │   │                │   │
│ │└──────────┘│ │  └──────────────┘   └────────────────┘   │
│ └────────────┘ │                                           │
└────────┬───────┘                                           │
         │                                                   │
         │                                                   │
    ┌────┴─────────────────────┐    ┌──────────────────────┐│
    │                          │    │                      ││
┌────────────────────▼────▼──┐  ┌───────────────┐           ││
│  Knowledge Base            │  │  Credentials  │           ││
│  (SQLite)                  │  │  Storage      │           ││
│                            │  │               │           ││
│• Systems/POIs              │  │• file         │           ││
│• Experiences               │  │• sqlite       │           ││
│• Market Data               │  │• keyring      │           ││
│• Routes                    │  │               │           ││
│• Danger Zones              │  │               │           ││
└────────────────────────────┘  └───────────────┘           ││
                                                            ││
    ┌───────────────────────────────────────────────────────┘│
    │                                                         │
┌───▼────────────┐  ┌──────────────┐                        │
│ Automated      │  │ Ollama LLM   │                        │
│ Agents         │  │              │                        │
│                │  │• llama3.2    │                        │
│• auto-explorer │  │• mistral     │                        │
│• auto-trader   │  │• other       │                        │
│• auto-fighter  │  │  models      │                        │
│• auto-prophet  │  │              │                        │
│• auto-random   │  └──────────────┘                        │
└────────────────┘                                           │
                                                             │
└─────────────────────────────────────────────────────────────┘

Key Components:

1. Agent Server - Core autonomous agent framework with LLM integration
2. MCP Bridges - Connect Claude AI to the game (WebSocket, SSE, Service)
3. Knowledge Base - Shared SQLite database for discoveries and analytics
4. Web UI - React frontend for monitoring and control
5. API Server - REST API for programmatic agent control
6. Automated Agents - Specialized pre-built bots for specific tasks
7. Credentials - Flexible storage (file, encrypted SQLite, OS keyring)

Command-Line Options

Agent Server

bin/agent-server [options]

Agent Selection:
  --agents string
        Comma-separated list of agent IDs (highest priority)
  --agents-dir string
        Directory containing agent personalities (default "data/agents")
  --config string
        Path to configuration file (default "agents_config.yaml")

Server Configuration:
  --server-url string
        Game server WebSocket URL (default "wss://game.spacemolt.com/ws")
  --max-agents int
        Maximum concurrent agents (default 10)
  --decision-interval duration
        Decision interval for agents (default 5s)

Knowledge Base:
  --db-backend string
        Backend: "sqlite" or "memory" (default "sqlite")
  --db-path string
        Path to SQLite database (default "data/spacemolt-knowledge.db")

LLM Configuration:
  --llm-url string
        LLM server URL (default "http://localhost:11434")
  --llm-model string
        LLM model name (default "llama3.2")

Credentials:
  --creds-backend string
        Backend: "file", "sqlite", or "keyring" (default "file")
  --creds-path string
        Path for credentials storage (default "data/credentials")

Environment Variables:

• SPACEMOLT_AGENTS - Comma-separated agent IDs (medium priority)
• SPACEMOLT_PASSPHRASE - Passphrase for SQLite credential encryption

See cmd/agent-server/README.md for detailed documentation.

Agent Test Utility

bin/test-agent [options] personality.json

Options:
  --db-backend string
        Database backend: "sqlite" or "memory" (default "sqlite")
  --db-path string
        Path to SQLite database file (default "spacemolt-knowledge.db")

How It Works

System Architecture

The agent server manages multiple autonomous agents, each with their own:

• WebSocket connection to the game server (required by game architecture)
• Personality defining behavior, traits, and motivations
• Memory for tracking experiences and discoveries
• Decision loop making autonomous choices every 5-10 seconds

Agent Lifecycle

1. Discovery - Server finds agents using priority order:

   • CLI flags (--agents=id1,id2) → Environment (SPACEMOLT_AGENTS) → Config file → Auto-discover

2. Initialization - For each agent:

   • Load personality from data/agents/<agent-id>/personality.json
   • Check for existing credentials in provider or data/agents/<agent-id>/credentials.json

3. Connection & Authentication - Each agent independently:

   • First time (no credentials):
     • Connects to game server
     • Registers new account with sanitized username
     • Receives authentication token
     • Saves credentials to provider (with fallback to file)
   • Returning agent (has credentials):
     • Connects to game server
     • Logs in with username and token
     • Resumes previous session
   • Both include retry logic: up to 3 attempts with exponential backoff (2s, 4s, 8s)

4. Autonomous Play Loop - Each agent continuously:

   • Receives game state updates every 10 seconds (tick)
   • Examines current situation (location, fuel, cargo, nearby objects)
   • Queries past experiences from knowledge base
   • Consults personality traits and motivations
   • Uses LLM to decide next action
   • Executes action through game client
   • Learns from the result (success/failure)
   • Updates knowledge base with discoveries

5. Graceful Shutdown - On Ctrl+C:

   • Server stops all agent decision loops
   • Closes all WebSocket connections
   • Commits knowledge to database
   • Exits cleanly

Tick-Based Action System

The game server operates on a 10-second tick cycle:

• Action commands (mine, travel, attack, etc.): Limited to 1 per tick
• Query commands (get_status, get_system, etc.): Unlimited

Agents respect this by:

• Tracking the last tick when an action was executed
• Only sending action commands on new ticks
• Using queries freely between ticks for information gathering
• Retrying immediately if an action fails (failures don't consume tick)

Credential Management

The system supports flexible credential storage:

Backends:

• file - Store in <creds-path>/<agent-id>.json (default)
• sqlite - Encrypted SQLite database (requires SPACEMOLT_PASSPHRASE)
• keyring - OS keyring/keychain integration

Fallback mechanism:

1. Try primary provider (configured backend)
2. If provider fails, fall back to data/agents/<agent-id>/credentials.json
3. Load also checks fallback location if provider has no credentials

This ensures agents can always save/load credentials even if the primary backend fails.

Supported Actions

Navigation:

• undock - Leave the current station
• dock - Dock at a station in the current system
• travel - Travel to a POI within the system
• jump - Jump to another star system

Resource Gathering:

• mine - Mine resources at the current location

Queries (no tick cost):

• get_status - Current player/ship state
• get_system - Current system details
• get_ship - Detailed vessel specifications
• get_skills - Full skill tree

See docs/api_commands_reference.md for the complete list of action and query commands.

Knowledge Persistence

With SQLite backend (default), agents accumulate knowledge over time:

• Systems - Discovered star systems with visit counts and timestamps
• Connections - Known jump routes between systems
• POIs - Points of interest (stations, asteroids, anomalies)
• Experiences - Agent action history and outcomes (last 100 per agent)
• Agents - Registered agent metadata
• Shared knowledge - All agents see each other's discoveries

Agent Personalities

The system includes diverse agent personalities, each specialized for different playstyles:

• Explorers - Curiosity-driven agents who document discoveries
• Miners - Resource-focused industrial miners
• Traders - Commerce-focused merchants maximizing profits
• Fighters - Combat specialists and bounty hunters
• Pirates - Aggressive raiders plundering trade routes
• Salvagers - Scavengers finding value in debris
• Craftsmen - Builders and manufacturers
• Engineers - Technical specialists and researchers

See data/agents/README.md for detailed documentation on creating and customizing agent personalities.

Creating New Agents

1. Create a new directory: mkdir -p data/agents/my-agent
2. Add a personality.json file with the agent's configuration
3. Run the agent server: bin/agent-server --agents=my-agent

Example personality structure:

{
  "name": "My Agent",
  "id": "my-agent",
  "role": "Explorer",
  "faction": "Independent",
  "traits": {
    "curiosity": 0.8,
    "risk_tolerance": 0.5,
    "altruism": 0.7,
    "patience": 0.6,
    "aggression": 0.2
  },
  "motivations": {
    "primary": "explore_unknown",
    "secondary": "help_others",
    "tertiary": "document_findings"
  },
  "skills": {
    "navigation": "intermediate",
    "scanning": "basic",
    "combat": "novice"
  },
  "biography": "A newly independent explorer seeking to make their mark."
}

Example Sessions

Scenario 1: Starting from Scratch (First Agent)

Create and register your first autonomous agent:

# 1. Make sure you have an agent personality
ls data/agents/explorer-7/personality.json

# 2. Start the agent server (will auto-register)
bin/agent-server --agents=explorer-7

# Output:
# === Spacemolt Agent Server ===
# Found 1 agent(s) to start: [explorer-7]
# ✓ Knowledge base initialized (sqlite)
# ✓ LLM client initialized (llama3.2 @ http://localhost:11434)
# ✓ Credentials provider initialized (file)
# ✓ Agent manager created (max agents: 10)
#
# === Spawning Agents ===
# [explorer-7] Spawning agent: Deep Space Seven (Explorer)
# [explorer-7] Registering new agent
# [explorer-7] ✓ Connected successfully
# [explorer-7] ✓ Registered as explorer-7-Deep_Space_Seven
# [explorer-7] ✓ Saved credentials to data/agents/explorer-7/credentials.json
# ✓ [explorer-7] Started successfully (faction: Terran)
#
# === Agent Server Started ===
# ✓ Successfully started: 1/1 agents
# Press Ctrl+C to stop all agents and exit

# The agent is now:
# - Registered in the game with a new account
# - Credentials saved to data/agents/explorer-7/credentials.json
# - Autonomously exploring and making decisions
# - Building knowledge in data/spacemolt-knowledge.db

# Let it run for 5-10 minutes, then stop with Ctrl+C
# Credentials are saved - next time it will log in automatically!

Scenario 2: Running with Existing Agents

Restart agents that have already been registered (they log in automatically):

# Start the same agent - it will login instead of register
bin/agent-server --agents=explorer-7

# Output:
# [explorer-7] Spawning agent: Deep Space Seven (Explorer)
# [explorer-7] Logging in with existing credentials
# [explorer-7] ✓ Connected successfully
# [explorer-7] ✓ Logged in successfully
# ✓ [explorer-7] Started successfully (faction: Terran)

# The agent:
# - Found existing credentials
# - Logged in with saved username/token
# - Resumed from its last position in the game
# - Remembers all previous discoveries from knowledge base

Scenario 3: Multi-Agent Fleet

Run multiple agents simultaneously with diverse specializations:

# Start a diverse fleet
bin/agent-server --agents=explorer-7,miner-2,trader-1,fighter-1

# Output shows each agent starting:
# [explorer-7] ✓ Logged in successfully (has credentials)
# [miner-2] ✓ Registered as miner-2-Ore_Crusher (first time - no credentials)
# [trader-1] ✓ Logged in successfully (has credentials)
# [fighter-1] ✓ Registered as fighter-1-Steel_Fang (first time - no credentials)
#
# ✓ Successfully started: 4/4 agents

# Watch as they collaborate:
# - Explorer-7: Maps new systems and reports discoveries
# - Miner-2: Focuses on resource extraction
# - Trader-1: Moves goods between stations
# - Fighter-1: Patrols for threats
#
# All agents share the same knowledge base!
# Explorer's discoveries help Miner find resources
# Trader benefits from both Explorer and Miner's intel

Scenario 4: Persistent Knowledge Accumulation

Demonstrate how knowledge persists across sessions:

# Session 1: Initial exploration
bin/agent-server --agents=explorer-7
# Let run for 5 minutes, then Ctrl+C

# Check what was discovered
sqlite3 data/spacemolt-knowledge.db "SELECT id, name, visit_count FROM systems;"
# Output:
# Sol|Sol|3
# Alpha-Centauri|Alpha Centauri|2
# Sirius|Sirius|1

# Session 2: Add more explorers
bin/agent-server --agents=explorer-7,explorer-8,explorer-9

# All three explorers:
# - Share knowledge of the 3 systems already discovered
# - Don't waste time re-exploring known territory
# - Can branch out in different directions
# - Build on each other's discoveries

# Session 3: Bring in specialists after exploration
bin/agent-server --agents=explorer-7,miner-2,miner-3,trader-1

# Specialists benefit from exploration:
# - Miners know which systems have rich asteroids
# - Traders know which stations buy/sell what
# - No wasted exploration time for specialists

Scenario 5: Different Configuration Methods

Use different methods to select agents:

# Method 1: CLI flags (highest priority)
bin/agent-server --agents=miner-2,miner-3

# Method 2: Environment variable
export SPACEMOLT_AGENTS=explorer-7,trader-1
bin/agent-server

# Method 3: Configuration file
cat > agents_config.yaml <<EOF
agents:
  enabled:
    - explorer-7
    - explorer-8
    - miner-2
    - miner-3
    - trader-1
EOF
bin/agent-server --config=agents_config.yaml

# Method 4: Auto-discover (all agents with personality.json)
bin/agent-server --agents-dir=data/agents
# Starts ALL agents found in data/agents/

Scenario 6: Custom Configuration

Run with custom backends and settings:

# Use SQLite for everything with encryption
export SPACEMOLT_PASSPHRASE=my-secure-password
bin/agent-server \
  --agents=explorer-7,miner-2 \
  --db-backend=sqlite \
  --db-path=data/game-knowledge.db \
  --creds-backend=sqlite \
  --creds-path=data/secure-creds.db \
  --llm-model=mistral \
  --decision-interval=3s

# Use memory mode for testing (no persistence)
bin/agent-server \
  --agents=test-agent \
  --db-backend=memory \
  --creds-backend=file

# Connect to custom game server
bin/agent-server \
  --agents=explorer-7 \
  --server-url=ws://localhost:8080/ws

Scenario 7: Handling Failures

The server continues if some agents fail:

bin/agent-server --agents=valid-agent,missing-agent,explorer-7

# Output:
# ❌ [missing-agent] Failed to load personality: file not found
# ✓ [valid-agent] Started successfully
# ✓ [explorer-7] Started successfully
#
# ⚠ Failed to start: 1 agents: [missing-agent]
# ✓ Successfully started: 2/3 agents
# Server continues running with 2 agents

# If ALL agents fail, server exits with error:
bin/agent-server --agents=nonexistent1,nonexistent2
# ❌ FATAL: All agents failed to start
# Check your configuration and credentials
# (exits with code 1)

Claude Integration via MCP

Play SpaceMolt through Claude AI using the Model Context Protocol.

Quick Start with MCP

# Build the MCP bridge
go build -o bin/mcp-ws-bridge ./cmd/mcp-ws-bridge

# Configure Claude Desktop
# Add to ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "spacemolt": {
      "command": "/path/to/bin/mcp-ws-bridge",
      "args": ["--username", "your-username", "--token", "your-token"]
    }
  }
}

# Restart Claude Desktop
# Now Claude can control your SpaceMolt character!

Available MCP Servers

1. mcp-ws-bridge - Full game control (151 commands)

   • Navigation, combat, mining, trading
   • Faction management, base building
   • Market orders, crafting, missions
   • See cmd/mcp-ws-bridge/README.md

2. mcp-sse-bridge - Server-Sent Events variant

   • Alternative architecture for streaming updates
   • Same functionality as WebSocket bridge

Example Claude Interactions

You: "Check my ship status in SpaceMolt"
Claude: *uses get_status tool*

You: "Mine some asteroids"
Claude: *uses mine tool repeatedly*

You: "Travel to the nearest station and sell my cargo"
Claude: *uses travel, dock, and view_market tools*

Auto-Generated Tools

The MCP bridge tools are automatically generated from the game's OpenAPI spec:

# Update tools when game API changes
make update-mcp

# This will:
# 1. Download latest openapi.json from game server
# 2. Regenerate all 151 tool definitions
# 3. Update cmd/mcp-ws-bridge/tools_generated.go

See docs/MCP_TOOLS_IMPLEMENTATION.md for details.

Automated Specialized Agents

Pre-built bots for specific tasks (no LLM required):

Available Automated Agents

• auto-explorer - Systematically explores and maps systems
• auto-trader - Trades goods between stations
• auto-fighter - Engages in combat and bounty hunting
• auto-prophet - Prophet-style agent with strategic foresight
• auto-random - Random-action agent for testing and exploration

Running Agents

Standing/recurring agent behaviors are now run under overmind, which supervises a fleet of worker processes driven by per-role config in data/overmind/roles.yaml (scheduled commands + an idle script per role). This replaces the old one-binary-per-bot model (e.g. mining now runs as the resident role's idle: idle_mine).

# Build the supervisor and worker runtime
make build   # produces bin/overmind and bin/worker

# Edit the fleet roster (data/overmind/fleet.yaml) and roles (data/overmind/roles.yaml),
# then launch the supervised fleet
bin/overmind

The remaining auto-* binaries above are legacy specialized bots not yet migrated to roles; see docs/superpowers/specs/2026-06-22-retire-auto-tools-design.md for the migration roadmap.

Web Interface

React Frontend

Modern web UI for monitoring and controlling agents:

# Setup frontend
cd frontend
npm install

# Development mode
npm run dev

# Production build
npm run build

See frontend/README.md for details.

Simple HTML Dashboard

Lightweight monitoring interface:

# Serve the web directory
cd web
python3 -m http.server 8080

# Visit http://localhost:8080

REST API

Programmatic control and monitoring:

# Start API server (usually part of agent-server)
bin/agent-server --enable-api --api-port 8080

# Query agent status
curl http://localhost:8080/api/agents

# Get specific agent
curl http://localhost:8080/api/agents/explorer-7

# Stream agent events
curl http://localhost:8080/api/stream

See pkg/api/ for API documentation.

Development

Running Linters

golangci-lint run ./...

Running Tests

# Run all tests
go test ./...

# Run specific package tests
go test ./pkg/knowledge/...

# Run tests with verbose output
go test ./pkg/knowledge/... -v

# Run benchmarks
go test ./pkg/knowledge/... -bench=.

Project Structure

spacemolt/
├── cmd/                        # Command-line executables
│   ├── agent-server/           # Main LLM agent server (primary)
│   ├── mcp-ws-bridge/          # MCP WebSocket bridge for Claude
│   ├── mcp-sse-bridge/         # MCP SSE bridge (alternative)
│   ├── mcp-bridge-service/     # MCP service-based architecture
│   ├── generate-mcp-tools/     # Auto-generate MCP tools from OpenAPI
│   ├── update-server-docs/     # Sync API docs from game server
│   ├── auto-explorer/          # Automated exploration bot
│   ├── auto-trader/            # Automated trading bot
│   ├── auto-fighter/           # Automated combat bot
│   ├── auto-prophet/           # Automated prophet bot
│   ├── auto-random/            # Automated random-action bot
│   ├── benchmark/              # Performance benchmarking
│   ├── daily-summary/          # Daily activity summaries
│   ├── skill-tree/             # Skill tree visualization
│   └── ...                     # 20+ additional utilities
├── pkg/                        # Reusable Go packages
│   ├── agent/                  # Agent framework & personality system
│   ├── game/                   # Game client & WebSocket communication
│   ├── credentials/            # Multi-backend credential storage
│   ├── knowledge/              # SQLite knowledge base & analytics
│   ├── llm/                    # LLM client (Ollama/OpenAI compatible)
│   ├── api/                    # REST API server
│   ├── registry/               # Agent status registry
│   ├── prompts/                # Prompt management system
│   ├── config/                 # Configuration management
│   └── version/                # Version compatibility checking
├── internal/                   # Internal packages
│   ├── protocol/               # Internal protocol definitions
│   └── ws/                     # WebSocket utilities
├── server/                     # Agent server implementation
├── frontend/                   # React/TypeScript web UI
│   ├── src/                    # React components & pages
│   ├── public/                 # Static assets
│   ├── package.json            # Node dependencies
│   └── vite.config.ts          # Vite configuration
├── web/                        # Simple HTML/JS monitoring interface
│   ├── index.html              # Dashboard
│   ├── js/                     # JavaScript
│   └── css/                    # Stylesheets
├── data/                       # Data storage (auto-generated)
│   ├── agents/                 # Agent personality configurations
│   │   ├── explorer-7/
│   │   │   ├── personality.json
│   │   │   ├── biography.md
│   │   │   └── credentials.json (auto-generated)
│   │   └── ...
│   ├── spacemolt-knowledge.db  # Shared knowledge base (SQLite)
│   └── credentials/            # File-based credentials
├── diagrams/                   # Architecture and system diagrams
├── docs/                       # Documentation (50+ documents)
│   ├── MCP_TOOLS_IMPLEMENTATION.md
│   ├── api_commands_reference.md
│   └── ...
├── playbook/                   # Strategic playbooks for agents
│   ├── explorer.md
│   ├── miner.md
│   ├── trader.md
│   ├── fighter.md
│   └── ...
├── server_docs/                # Auto-synced API documentation
│   ├── openapi.json            # OpenAPI specification
│   ├── api.md                  # API reference
│   └── skill.md                # Skill tree documentation
├── scripts/                    # Utility scripts
│   ├── query-knowledge.sh      # Query knowledge base
│   ├── query-analytics.sh      # Query analytics
│   └── ...
├── Makefile                    # Build automation
├── agents_config.yaml.example  # Example agent configuration
└── go.mod                      # Go module definition

Troubleshooting

Game Connection Issues

# Test connection to game server
curl https://game.spacemolt.com/api/version

# Verify WebSocket connectivity
# Check firewall rules allow outbound WSS connections

# Test with simple client
go run ./cmd/play-simple --username your-user --token your-token

Ollama Connection Issues (for LLM agents)

# Verify Ollama is running
curl http://localhost:11434/api/tags

# Check if model is available
ollama list

# Pull the required model
ollama pull llama3.2

# Test Ollama directly
curl http://localhost:11434/api/generate -d '{"model":"llama3.2","prompt":"test"}'

MCP Bridge Issues

# Test MCP bridge manually
bin/mcp-ws-bridge --username your-user --token your-token

# Check Claude Desktop logs
# macOS: ~/Library/Logs/Claude/
# Check for MCP server startup errors

# Verify configuration
cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Common issues:
# - Incorrect path to mcp-ws-bridge binary
# - Missing or invalid credentials
# - Firewall blocking game server connection

Agent Not Responding

• Check agent-server logs for errors
• Verify Ollama is running: curl http://localhost:11434/api/tags
• Check agent personality file is valid JSON
• Ensure agent has valid credentials in credentials.json

Database Issues

# Check database contents
sqlite3 data/spacemolt-knowledge.db ".schema"
sqlite3 data/spacemolt-knowledge.db "SELECT * FROM systems;"

# Check for corruption
sqlite3 data/spacemolt-knowledge.db "PRAGMA integrity_check;"

# Reset database (delete and start fresh)
rm data/spacemolt-knowledge.db
bin/agent-server

Agents Not Spawning

• Verify agent directory exists: ls data/agents/explorer-7/
• Check personality.json is valid: jq . data/agents/explorer-7/personality.json
• Verify credentials if reusing existing agent
• Review debug logs for specific errors
• Check agent-server logs for detailed error messages

Frontend Development Issues

# Clear frontend cache
cd frontend
rm -rf node_modules package-lock.json
npm install

# Check for TypeScript errors
npm run type-check

# Verify Vite dev server
npm run dev
# Should start on http://localhost:5173

Build Issues

# Clean build cache
go clean -cache -testcache -modcache

# Update dependencies
go mod tidy
go mod download

# Rebuild everything
make clean
make build

# Check for lint errors
make lint

Contributing

Contributions are welcome! Areas of interest:

Agent Development:

• New agent personalities and behaviors
• Improved decision-making algorithms and strategies
• Enhanced learning and knowledge sharing
• Better prompt engineering for LLM agents

MCP Integration:

• Additional MCP bridges and servers
• Better Claude integration patterns
• Tool improvements and new capabilities
• Enhanced crafting intelligence

Automation:

• New specialized automated agents
• Improved efficiency algorithms
• Better resource management
• Advanced trading strategies

UI/UX:

• React frontend enhancements
• New monitoring dashboards
• Better visualization of agent activity
• Mobile-responsive designs

Infrastructure:

• Performance optimizations
• Better error handling and recovery
• Enhanced testing coverage
• Documentation improvements

Analytics:

• Advanced knowledge base queries
• Better market analysis
• Route optimization
• Profit calculation improvements

See existing code for patterns and conventions. All contributions should:

• Pass make lint and make test
• Include tests for new functionality
• Update documentation as needed
• Follow Go best practices

License

MIT License - See LICENSE file for details

Acknowledgments

Game & Platform:

• SpaceMolt - The game that makes this possible
• SpaceMolt community for testing and feedback

AI & LLM:

• Ollama - Local LLM inference
• Anthropic Claude - MCP integration and AI assistance
• Model Context Protocol - Standardized AI integration

Core Libraries:

• Lipgloss - Terminal styling
• modernc.org/sqlite - Pure Go SQLite
• coder/websocket - WebSocket client

Frontend:

• React - UI framework
• TypeScript - Type safety
• Vite - Build tool
• Tailwind CSS - Styling

Development:

• golangci-lint - Go linting
• Go 1.24 - Programming language
• OpenAPI specification - API documentation and code generation