Systemprompt Code Orchestrator

🚀 SystemPrompt Coding Agent

The SystemPrompt Coding Agent transforms your workstation into a remotely accessible AI coding assistant. It allows any MCP client to connect to your MCP server, enabling seamless AI - powered coding from anywhere.

🚀 Quick Start

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)

Installation and Running

# 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

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

✨ 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 →
• Resource Management: Expose task data as MCP resources - Tools & Resources →
• Interactive Prompts: AI agents can ask for clarification
• Progress Notifications: Real - time status updates
• Structured Data: Full schema validation - MCP Server →

📦 Installation

The installation process involves cloning the repository, installing dependencies, and running the setup script. Refer to the Quick Start section for detailed steps.

💻 Usage Examples

Basic Usage

# 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

Advanced Usage

# Start with internet tunnel (requires Cloudflare)
npm run tunnel

📚 Documentation

Core Architecture

• Daemon - The host - side bridge that executes commands and manages Claude processes
• Docker Architecture - How the Docker container and host machine interact
• MCP Server - The Model Context Protocol server implementation

AI Agent Systems

• Agent Manager - Central orchestrator for all AI agent sessions
• Claude Code Integration - How Claude Code CLI is integrated and managed
• Task Management - Task lifecycle, persistence, and state management

Protocol & API

• Tools and Resources - MCP tools and resources implementation
• Event System and Logging - Real - time event streaming and structured logging

Additional Features

• Testing Framework - E2E testing setup and best practices
• Tunnel and Remote Access - Cloudflare tunnel setup for internet access
• State Persistence - How tasks and sessions persist across restarts
• Push Notifications - Mobile push notification integration
• Prompt Templates - Pre - built prompt system for common tasks

🔧 Technical Details

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

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"
  }
}

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

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

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

Tool Reference

→ Full Tools and Resources Documentation

Task Orchestration

System Management

Pre - Built Prompts

🐛 Bug Fixing

{
  "prompt_template": "bug_fix",
  "variables": {
    "bug_description": "Login fails after password reset",
    "error_logs": "401 Unauthorized at auth.js:42"
  }
}

⚛️ React Components

{
  "prompt_template": "react_component",
  "variables": {
    "component_name": "UserDashboard",
    "features": ["data visualization", "real - time updates", "export functionality"]
  }
}

🧪 Unit Testing

{
  "prompt_template": "unit_test",
  "variables": {
    "target_files": ["src/auth/*.js"],
    "framework": "jest",
    "coverage_target": 85
  }
}

Performance Optimizations

1. Streaming Output: Agent output streamed in chunks, not buffered
2. Lazy Resource Loading: Resources fetched on - demand
3. Connection Pooling: Reused TCP connections to daemon
4. Efficient State Persistence: Only changed fields written to disk

Development

Project Structure

systemprompt-coding-agent/
├── src/
│   ├── server.ts           # MCP server setup
│   ├── handlers/           # Protocol handlers
│   ├── services/           # Agent services
│   ├── constants/          # Tool definitions
│   └── types/              # TypeScript types
├── docker-compose.yml
└── package.json

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

For security issues, email security@systemprompt.io

Support

• Documentation: docs.systemprompt.io
• GitHub Issues: Report bugs
• Discord: Join our community
• Twitter: @tyingshoelaces_

Future Roadmap

1. Multi - Agent Orchestration: Coordinate multiple AI agents on complex tasks
2. Incremental Computation: Cache and reuse AI outputs
3. Distributed Execution: Spread tasks across multiple machines
4. Web UI Dashboard: Browser - based monitoring and control

MCP Client Options

While this server works with any MCP - compatible client, for a mobile voice - controlled experience, check out SystemPrompt.io - still early, but a native iOS/Android app designed specifically for voice - driven AI coding workflows. We want to create these tasks and interact with them asynchronously with our voice!

📄 License

MIT License - see LICENSE