What is This?

This is the SystemPrompt Coding Agent - a cutting-edge project that converts your workstation into a remotely-accessible MCP (Model Context Protocol) server that any MCP client can connect to. It's part of the SystemPrompt.io ecosystem, which is pioneering native mobile voice-controlled AI orchestration for developers.

About SystemPrompt.io

SystemPrompt is an experimental, community-driven project (currently at v0.01) that enables developers to interact with AI and execute complex workflows using natural language voice commands. The project is:

• Self-funded and indie - Built by a single founder with the community
• Rapidly iterating - "Visceral, raw, cutting edge software" that's evolving quickly
• Mobile-first - Native iOS and Android apps for voice-controlled development
• Transparent about its stage - Early but functional, "like having a very eager but slightly confused robot"

How This Coding Agent Works

Send coding tasks from anywhere, and AI agents (Claude out of the box, extendable for any) execute directly on your actual machine. Your code never leaves your computer, but you can control it from anywhere through:

• Voice commands via the SystemPrompt mobile app
• Any MCP-compatible client
• The included inspector tool

This project exposes your local machine as an MCP server that can be remotely controlled. The AI agents run directly on your machine with access to your real development environment and tools.

Why This Exists

The SystemPrompt mobile app users kept asking "but what do I do with it?" The answer: manage your own development environment and agents remotely. This coding agent is THE killer use case at this stage of the adoption curve for MCP servers - enabling developers to code from anywhere using just their voice.

Quick Start [Requires Claude Code, Docker]

# Clone and setup
git clone https://github.com/systempromptio/systemprompt-code-orchestrator
cd systemprompt-code-orchestrator

# Install and run
npm i 
npm run setup
npm run start

# Test with the inspector
npm run inspector

The created tasks which can be exectued with the inspector should tunnel to your Claude Code installation, save structured logs inside the Docker container (exposed as MCP resources), and enable execution through the inspector (and any MCP client).

Prerequisites

The setup script will check for these automatically:

• Node.js 18+ (required)
• Docker & Docker Compose (required)
• Claude Code CLI (optional but recommended - the setup script will guide you)

Essential Commands

npm run start    # Start all services (daemon + Docker)
npm run stop     # Stop all services gracefully
npm run status   # Check service health
npm run logs     # View real-time logs
npm run tunnel   # Start with internet tunnel (requires Cloudflare)

Essential Configuration

# Required (setup will prompt for this)
PROJECT_ROOT=/path/to/your/code  # ⚠️ AI agents have FULL access here

# Optional (with defaults)
PORT=3000
COMPOSE_PROJECT_NAME=systemprompt-coding-agent

# Optional (for additional features)
CLOUDFLARE_TOKEN=your_token  # For tunnel access
PUSH_TOKEN=your_token        # For mobile notifications

Technical Architecture

MCP Client (Mobile/Desktop)
    |
    v
Docker Container (MCP Server)
    - Handles MCP protocol
    - Resource subscriptions
    - Event streaming
    |
    v
Host Bridge Daemon (TCP Socket)
    - Command routing
    |
    v
Host Machine
    - AI agent execution
    - File system access

Key Technical Innovations

1. Real-Time Resource Subscription Model

The server implements the MCP SDK's listChanged pattern for resource subscriptions. When a task state changes:

// Client subscribes to task resources, notified by listChanged notifications
client.listResources()
client.getResource({ uri: "task://abc-123" })

// When task updates, server automatically:
// 1. Saves task to disk (JSON persistence)
await this.persistence.saveTask(updatedTask);

// 2. Emits internal event
this.emit("task:updated", updatedTask);

// 3. Sends MCP notification to subscribed clients
await sendResourcesUpdatedNotification(`task://${taskId}`, sessionId);
// This triggers: { method: "notifications/resources/updated", params: { uri: "task://abc-123" } }

// Client receives notification and can re-fetch the updated resource

This enables real-time task monitoring without polling - clients stay synchronized with task state changes as they happen.

2. Push Notifications for Task Completion

Integrated Firebase Cloud Messaging (FCM) support sends push notifications to mobile devices when tasks complete:

// Task completes → Push notification sent
{
  notification: {
    title: "Task Complete",
    body: "Your refactoring task finished successfully"
  },
  data: {
    taskId: "abc-123",
    status: "completed",
    duration: "45s"
  }
}

Perfect for long-running tasks - start a task, go about your day, get notified when it's done.

3. Stateful Process Management

• Tasks persist to disk as JSON with atomic writes
• Process sessions maintained across daemon restarts
• Comprehensive state machine for task lifecycle:

  pending → in_progress → waiting → completed
                      ↓
                    failed
  

Event-Driven Architecture

All operations emit events consumed by multiple subsystems:

• Logger: Structured JSON logs with context
• State Manager: Task status updates
• Notifier: Push notifications to mobile clients
• Metrics: Performance and usage analytics

Remote Access Options

🌐 Internet Access via Cloudflare Tunnel

More complex options like opening a Cloudflare tunnel to expose an HTTPS URL to your local machine are documented, but not included by default (do at your own risk).

npm run tunnel

This will:

• Create a secure HTTPS tunnel to your local server
• Display both the public URL and local network addresses
• Enable access from anywhere (including mobile devices)

→ Full Tunnel Documentation

🏠 Local Network Access

If you prefer to keep everything on your local network:

1. Start the server normally:

   npm start
   

2. Access from devices on the same network:

   • Find your machine's IP address
   • Connect using: http://YOUR_IP:3000/mcp

Core Features

🤖 AI Agent Orchestration

• Multi-Agent Support: Claude Code CLI out of the box, extendable for any agent
• Task Management: Create, track, and manage coding tasks - Task Management →
• Session Isolation: Each task runs in its own context - Claude Integration →
• Real-time Streaming: Watch AI agents work in real-time - Event System →

📱 Mobile-First Design

• Voice Commands: "Create a login form with validation"
• Push Notifications: Get alerts when tasks complete - Push Notifications →
• Quick Actions: Pre-defined templates for common tasks - Prompt Templates →
• Remote Control: Manage your dev environment from anywhere

🔧 MCP Protocol Features

• Persistent State: Tasks survive server restarts - [State Persistence →](