NX

OpenSpace CLI Mastery: Run Self-Evolving Agents Without Code — Multi-Profile & Agent Integration Guide

Technology News x/technology ·
OpenSpace CLI Mastery: Run Self-Evolving Agents Without Code — Multi-Profile & Agent Integration Guide

OpenSpace CLI Mastery: Run Self-Evolving Agents Without Code — Multi-Profile & Agent Integration Guide

In my last piece on OpenSpace, I showed you the big picture: 4.2× income improvement, 45.9% token reduction, and skills that evolve from your actual work. Today, I'm going deeper — specifically on how to use OpenSpace entirely from the CLI, how to run multiple isolated profiles, and how to integrate with your existing agents like Claude Code, nanobot, and OpenClaw.

I cracked open the source code. Here's everything you actually need.

The Two Paths: Your Agent vs. Your Co-Worker

OpenSpace gives you two distinct usage patterns:

Path What It Is Best For
Path A: For Your Agent Plug OpenSpace into Claude Code, nanobot, Codex, Cursor, OpenClaw as skills Users who already have an agent workflow
Path B: As Your Co-Worker Use OpenSpace directly via CLI or Python API Developers who want standalone CLI access, custom integrations

Path B is where we focus today — running OpenSpace purely from the command line, no code required.

Path B: CLI-Only Usage (No Code Required)

Here's the full picture from the actual __main__.py source code:

Installation (One-Line Setup)

git clone --filter=blob:none --sparse https://github.com/HKUDS/OpenSpace.git
cd OpenSpace
git sparse-checkout set ' /* ' ' !assets/ '
pip install -e .

The sparse checkout skips the 50MB assets folder. Installation verified.

Interactive Mode

openspace

This drops you into a live REPL:

>>> Build a monitoring dashboard for my Docker containers

>>> Create a GitHub PR review script

>>> status  # Check system status

>>> help    # Show available commands

>>> exit    # Quit

Inside __main__.py, the interactive loop is straightforward:

async def interactive_mode(openspace: OpenSpace, ui_manager: UIManager):
    CLIDisplay.print_interactive_header()
    while True:
        query = input(">>> ").strip()
        if query.lower() in ['exit', 'quit', 'q']:
            break
        if query.lower() == 'status':
            _print_status(openspace)
        if query.lower() == 'help':
            CLIDisplay.print_help()
        result = await openspace.execute(query)

Single Query Mode

openspace --model "anthropic/claude-sonnet-4-5" \
         --query "Create a monitoring dashboard for my Docker containers"

The --model flag overrides the default (which is openrouter/anthropic/claude-sonnet-4.5).

All CLI Arguments (From argparse)

openspace [command] [options]

Commands:
  refresh-cache    Refresh MCP tool cache (starts all servers once)

Options:
  --config, -c     Configuration file path (JSON)
  --query, -q      Single query mode
  --model, -m      LLM model name
  --log-level     DEBUG, INFO, WARNING, ERROR
  --max-iterations  Maximum iteration count
  --timeout       LLM API call timeout (seconds)
  --interactive, -i  Force interactive mode
  --no-ui         Disable visualization UI
  --ui-compact    Use compact UI layout

MCP Server Mode (For Agent Integration)

openspace-mcp --help

This spawns an MCP server exposing 4 tools:

Tool What It Does
execute_task Run multi-step grounding agent loop
search_skills Search local + cloud skills
fix_skill Repair a broken SKILL.md
upload_skill Push evolved skill to cloud community

Cloud CLI Commands

# Download a skill from the community cloud
openspace-download-skill <skill_id>

# Upload your evolved skill to share
openspace-upload-skill /path/to/skill/dir

Local Dashboard

# Terminal 1: Backend API
openspace-dashboard --port 7788

# Terminal 2: Frontend
cd frontend && npm install && npm run dev

This gives you:

  • Skill browsing with lineage graphs
  • Execution history and metrics
  • Cloud skill discovery

Multi-Profile Architecture: Multiple Isolated Workspaces

Here's the key insight from tool_layer.py:

@dataclass
class OpenSpaceConfig:
    # Workspace Configuration
    workspace_dir: Optional[str] = None
    
    # Skill Evolution
    evolution_max_concurrent: int = 3
    
    # LLM Configuration
    llm_model: str = "openrouter/anthropic/claude-sonnet-4.5"
    llm_enable_thinking: bool = False
    llm_timeout: float = 120.0

OpenSpace is single-instance per workspace — but you can run multiple instances with different configurations.

Profile Strategy: Workspace Isolation

Create separate profiles by workspace:

# Profile 1: Web Development
mkdir -p ~/.openspace/profiles/web-dev
cat > ~/.openspace/profiles/web-dev/.env << EOF
OPENSPACE_WORKSPACE=/home/jack/projects/web
OPENSPACE_LLM_MODEL=anthropic/claude-sonnet-4-5
EOF

# Profile 2: Data Science
mkdir -p ~/.openspace/profiles/data-science
cat > ~/.openspace/profiles/data-science/.env << EOF
OPENSPACE_WORKSPACE=/home/jack/projects/data
OPENSPACE_LLM_MODEL=openai/gpt-4o
EOF

# Profile 3: DevOps
mkdir -p ~/.openspace/profiles/devops
cat > ~/.openspace/profiles/devops/.env << EOF
OPENSPACE_WORKSPACE=/home/jack/projects/infra
OPENSPACE_LLM_MODEL=anthropic/claude-opus-4
EOF

Switching Profiles

# Method 1: Environment variable
OPENSPACE_WORKSPACE=/home/jack/projects/web openspace

# Method 2: Config file per profile
openspace --config ~/.openspace/profiles/web-dev/config.json

# Method 3: Python API (for scripted workflows)
from openspace import OpenSpace, OpenSpaceConfig

config = OpenSpaceConfig(
    workspace_dir="/home/jack/projects/web",
    llm_model="anthropic/claude-sonnet-4-5",
    evolution_max_concurrent=3
)

Real-World Profile Use Cases

Profile Workspace Model Use Case
web-dev ~/projects/web claude-sonnet-4-5 Fast iteration, React/Next.js
data-science ~/projects/data gpt-4o Analysis, visualization, pandas
devops ~/projects/infra claude-opus-4 Complex infrastructure, Terraform
writing ~/projects/content claude-sonnet-4-5 Documentation, blogs

Each profile accumulates its own skills. The web-dev profile evolves skills for React patterns; the data-science profile evolves pandas and visualization patterns. They're isolated but can share via the cloud community.

Path A: Integrate with Existing Agents

This is where OpenSpace gets interesting. You can plug it into Claude Code, nanobot, OpenClaw, Codex, or Cursor.

MCP Integration Architecture

From host_skills/README.md:

Your Agent (nanobot / openclaw / Claude Code / ...)
│
│ MCP protocol (stdio)
▼
openspace-mcp ← 4 tools exposed
├── execute_task     ← multi-step grounding agent loop
├── search_skills   ← local + cloud skill search
├── fix_skill       ← repair a broken SKILL.md
└── upload_skill     ← push skill to cloud community

Integration for Claude Code

  1. Add to your Claude Code config (.claude.json or MCP settings):
{
  "mcpServers": {
    "openspace": {
      "command": "openspace-mcp",
      "toolTimeout": 600,
      "env": {
        "OPENSPACE_HOST_SKILL_DIRS": "/path/to/claude-code/skills",
        "OPENSPACE_WORKSPACE": "/path/to/OpenSpace",
        "OPENSPACE_API_KEY": "sk-xxx"
      }
    }
  }
}
  1. Copy host skills:
cp -r OpenSpace/openspace/host_skills/delegate-task/ /path/to/your/agent/skills/
cp -r OpenSpace/openspace/host_skills/skill-discovery/ /path/to/your/agent/skills/

These two skills teach your agent when and how to use OpenSpace — no additional prompting needed.

Integration for nanobot

# Copy skills
cp -r host_skills/skill-discovery/ ~/.nanobot/skills/
cp -r host_skills/delegate-task/ ~/.nanobot/skills/

# Add to nanobot config (~/.nanobot/config.json)
{
  "tools": {
    "mcpServers": {
      "openspace": {
        "command": "openspace-mcp",
        "toolTimeout": 1200,
        "env": {
          "OPENSPACE_HOST_SKILL_DIRS": "~/.nanobot/skills",
          "OPENSPACE_WORKSPACE": "/path/to/OpenSpace",
          "OPENSPACE_API_KEY": "sk-xxx"
        }
      }
    }
  }
}

Integration for OpenClaw

OpenClaw uses mcporter for MCP runtime:

mcporter config add openspace \
  --command "openspace-mcp" \
  --env OPENSPACE_HOST_SKILL_DIRS=/path/to/openclaw/skills \
  --env OPENSPACE_WORKSPACE=/path/to/OpenSpace \
  --env OPENSPACE_API_KEY=sk-xxx

Python API: Programmatic Control

For advanced use cases, here's the full Python API from __init__.py:

from openspace import (
    OpenSpace,
    OpenSpaceConfig,
    GroundingAgent,
    GroundingClient,
    LLMClient,
    RecordingManager,
    RecordingViewer
)

# Minimal setup
config = OpenSpaceConfig(
    llm_model="anthropic/claude-sonnet-4-5",
    workspace_dir="/path/to/workspace",
    grounding_max_iterations=20,
    evolution_max_concurrent=3
)

async with OpenSpace(config) as os:
    result = await os.execute("Build a REST API with FastAPI")
    
    # Check evolved skills
    for skill in result.get("evolved_skills", []):
        print(f"Evolved: {skill['name']} from {skill['origin']}")

Advanced Configuration Options

config = OpenSpaceConfig(
    # LLM Configuration
    llm_model="anthropic/claude-sonnet-4-5",
    llm_enable_thinking=True,  # Claude extended thinking
    llm_timeout=120.0,
    llm_max_retries=3,
    
    # Separate models for specific tasks
    tool_retrieval_model="openai/gpt-4o-mini",
    skill_registry_model="anthropic/claude-haiku",
    execution_analyzer_model="anthropic/claude-haiku",
    
    # Backend Configuration
    backend_scope=["shell", "gui", "mcp", "web", "system"],
    
    # Workspace
    workspace_dir="/path/to/workspace",
    
    # Recording
    enable_recording=True,
    enable_screenshot=False,
    recording_log_dir="./logs/recordings"
)

The Self-Evolution Engine: How It Actually Works

Inside skill_engine/, OpenSpace tracks every execution and evolves skills automatically:

Three Evolution Modes (Verified from GDPVal paper)

Mode Trigger Action Token Savings
FIX Skill execution fails Auto-repair SKILL.md Prevents repeated failures
DERIVED Successful pattern found Extract reusable pattern Reuse without re-reasoning
CAPTURED Novel workflow succeeds Create new skill Build skill library from scratch

GDPVal Benchmark Results (Phase 1 → Phase 2)

The benchmark ran 50 professional tasks in two phases:

Category Tasks Income Δ Token Δ
📝 Documents 7 71→74% (+3.3pp) −56%
📋 Compliance 11 51→70% (+18.5pp) −51%
🎬 Media 3 53→58% (+5.8pp) −46%
🛠️ Engineering 4 70→78% (+8.7pp) −43%
📊 Spreadsheets 15 63→70% (+7.3pp) −37%
💻 Programming 10 68→75% (+7.6pp) −33%

Bottom line: Phase 2 (warm rerun with evolved skills) dramatically outperformed Phase 1 (cold start, no prior knowledge).

Cloud Skill Community: Share Evolved Skills

Register at open-space.cloud to get your OPENSPACE_API_KEY.

Without API Key (Local Only)

  • ✅ execute_task — works
  • ✅ search_skills — local results only
  • ✅ fix_skill — works
  • ❌ upload_skill — fails

With API Key (Cloud Enabled)

  • ✅ All local capabilities
  • ✅ Cloud skill search
  • ✅ Upload evolved skills to share
  • ✅ Download others' evolved skills

Browse Skills Without Installing

Visit open-space.cloud to:

  • Browse community skills
  • See evolution lineage
  • Preview skill content

No installation needed — it's a web interface.

When to Use Each Approach

Scenario Recommended Approach
Quick task, one-off openspace --query "..."
Ongoing project work Interactive mode + dedicated profile
Already using Claude Code/nanobot Path A integration (MCP)
Custom automation pipeline Python API
Team skill sharing Cloud community + API key
Solo developer, multi-project Multiple profiles, one OpenSpace install

Quick Start Commands Reference

# 1. Install
git clone --filter=blob:none --sparse https://github.com/HKUDS/OpenSpace.git
cd OpenSpace && pip install -e .

# 2. Verify
openspace-mcp --help

# 3. Interactive mode
openspace

# 4. Single query
openspace --query "Build a FastAPI todo app"

# 5. Specific model
openspace --model "anthropic/claude-opus-4" --query "Complex task"

# 6. Download community skill
openspace-download-skill <skill_id>

# 7. Refresh MCP cache
openspace refresh-cache

# 8. Dashboard (requires Node.js ≥ 20)
openspace-dashboard --port 7788
# Then: cd frontend && npm run dev

Conclusion

OpenSpace is not just a research prototype — it's a production-ready CLI tool with:

  • ✅ Full interactive REPL
  • ✅ Single-query batch mode
  • ✅ MCP server for agent integration
  • ✅ Python API for programmatic control
  • ✅ Multi-profile workspace isolation
  • ✅ Cloud skill community sharing
  • ✅ Local dashboard for skill lineage tracking

Whether you're a solo developer with multiple project profiles or a team lead integrating with Claude Code, OpenSpace adapts to your workflow. The self-evolution engine means every task you run makes the system smarter for the next one.

GitHub: HKUDS/OpenSpace (1.5k stars)
Cloud Community: open-space.cloud
Benchmark Paper: GDPVal on arXiv

All benchmark data verified against the official GDPVal paper and GitHub repository. CLI commands verified against __main__.py and tool_layer.py source code.

Back to Technology News
·