Skip to content
Back to search

systemprompt-code-orchestrator

[DEPRECATED] Superseded by systempromptio/systemprompt-template and systempromptio/systemprompt-core. MCP server for orchestrating AI coding agents (Claude Code CLI & Gemini CLI).

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/systempromptio--systemprompt-code-orchestrator/badge.svg)](/listings/systempromptio--systemprompt-code-orchestrator)

HTML

<a href="/listings/systempromptio--systemprompt-code-orchestrator"><img src="/api/listings/systempromptio--systemprompt-code-orchestrator/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

# 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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 435 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > ## ⚠️ Deprecated — no longer maintained
  2. >
  3. > This repository has been superseded. All new development and support lives in:
  4. >
  5. > - **[systempromptio/systemprompt-template](https://github.com/systempromptio/systemprompt-template)** — start here. Self-hosted evaluation of the full systemprompt.io AI governance infrastructure.
  6. > - **[systempromptio/systemprompt-core](https://github.com/systempromptio/systemprompt-core)** — the underlying Rust library (MCP, A2A, OAuth 2.1, audit, compile-time extensions).
  7. >
  8. > Learn more at [systemprompt.io](https://systemprompt.io).
  9. >
  10. > _The original README is preserved below for historical reference._
  11. ---
  12. <div align="center">
  13. # 🚀 SystemPrompt Coding Agent
  14. ### Turn Your Workstation into a Remotely Accessible AI Coding Assistant
  15. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  16. [![Twitter Follow](https://img.shields.io/twitter/follow/tyingshoelaces_?style=social)](https://twitter.com/tyingshoelaces_)
  17. [![Discord](https://img.shields.io/discord/1255160891062620252?color=7289da&label=discord)](https://discord.com/invite/wkAbSuPWpr)
  18. **[Website](https://systemprompt.io)** • **[Documentation](https://docs.systemprompt.io/coding-agent)** • **[Watch Demo Video](https://www.loom.com/share/8e4b8631d1a149d9801f2b96235dcd0b)**
  19. </div>
  20. ---
  21. <div align="center">
  22. ### 💯 100% Free and Open Source
  23. **We appreciate your support!** If you find this project useful, please consider:
  24. ⭐ **Star** this repo • 📢 **Share** with your network • 🐛 **Report issues** • 🤝 **Contribute** code
  25. *Every star, share, and contribution helps us improve this tool for the community!*
  26. </div>
  27. ---
  28. <div align="center">
  29. ### 📱 Works with Any MCP Client
  30. **This server is 100% free and open source** and works with any MCP-compatible client.
  31. We also offer a **paid subscription** native mobile app (SystemPrompt) designed for voice-first interactions with this server.
  32. The mobile app is still in early development but provides a native mobile experience for controlling your coding agent from anywhere.
  33. <a href="https://apps.apple.com/us/app/systemprompt-mcp-client/id6746670168">
  34. <img src="https://tools.applemediaservices.com/api/badges/download-on-the-app-store/black/en-us" alt="Download on App Store" height="50">
  35. </a>
  36. <a href="https://play.google.com/store/apps/details?id=com.systemprompt.mcp">
  37. <img src="https://upload.wikimedia.org/wikipedia/commons/7/78/Google_Play_Store_badge_EN.svg" alt="Get it on Google Play" height="50">
  38. </a>
  39. </div>
  40. ---
  41. ## 📋 Quick Navigation
  42. **Getting Started**: [Quick Start](#quick-start) | [Security](#-security-notice) | [Remote Access](#remote-access-options)
  43. **Documentation**: [Architecture](#technical-architecture) | [Tools](#tool-reference) | [Templates](#pre-built-prompts)
  44. **Components**: [Daemon](docs/daemon.md) | [Docker](docs/docker-architecture.md) | [MCP Server](docs/mcp-server.md) | [Agent Manager](docs/agent-manager.md)
  45. **Features**: [Tunnel Access](docs/tunnel-remote-access.md) | [Push Notifications](docs/push-notifications.md) | [State Persistence](docs/state-persistence.md)
  46. ## What is This?
  47. 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](https://systemprompt.io/documentation) ecosystem, which is pioneering native mobile voice-controlled AI orchestration for developers.
  48. ### About SystemPrompt.io
  49. 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:
  50. - **Self-funded and indie** - Built by a single founder with the community
  51. - **Rapidly iterating** - "Visceral, raw, cutting edge software" that's evolving quickly
  52. - **Mobile-first** - Native iOS and Android apps for voice-controlled development
  53. - **Transparent about its stage** - Early but functional, "like having a very eager but slightly confused robot"
  54. ### How This Coding Agent Works
  55. 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:
  56. - **Voice commands** via the SystemPrompt mobile app
  57. - **Any MCP-compatible client**
  58. - **The included inspector tool**
  59. 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.
  60. ### Why This Exists
  61. 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.
  62. ## Quick Start [Requires Claude Code, Docker]
  63. ```bash
  64. # Clone and setup
  65. git clone https://github.com/systempromptio/systemprompt-code-orchestrator
  66. cd systemprompt-code-orchestrator
  67. # Install and run
  68. npm i
  69. npm run setup
  70. npm run start
  71. # Test with the inspector
  72. npm run inspector
  73. ```
  74. 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).
  75. ### Prerequisites
  76. The setup script will check for these automatically:
  77. - Node.js 18+ (required)
  78. - Docker & Docker Compose (required)
  79. - Claude Code CLI (optional but recommended - the setup script will guide you)
  80. ### Essential Commands
  81. ```bash
  82. npm run start # Start all services (daemon + Docker)
  83. npm run stop # Stop all services gracefully
  84. npm run status # Check service health
  85. npm run logs # View real-time logs
  86. npm run tunnel # Start with internet tunnel (requires Cloudflare)
  87. ```
  88. ### Essential Configuration
  89. ```env
  90. # Required (setup will prompt for this)
  91. PROJECT_ROOT=/path/to/your/code # ⚠️ AI agents have FULL access here
  92. # Optional (with defaults)
  93. PORT=3000
  94. COMPOSE_PROJECT_NAME=systemprompt-coding-agent
  95. # Optional (for additional features)
  96. CLOUDFLARE_TOKEN=your_token # For tunnel access
  97. PUSH_TOKEN=your_token # For mobile notifications
  98. ```
  99. ## Technical Architecture
  100. ```
  101. MCP Client (Mobile/Desktop)
  102. |
  103. v
  104. Docker Container (MCP Server)
  105. - Handles MCP protocol
  106. - Resource subscriptions
  107. - Event streaming
  108. |
  109. v
  110. Host Bridge Daemon (TCP Socket)
  111. - Command routing
  112. |
  113. v
  114. Host Machine
  115. - AI agent execution
  116. - File system access
  117. ```
  118. ### Key Technical Innovations
  119. **1. Real-Time Resource Subscription Model**
  120. The server implements the MCP SDK's `listChanged` pattern for resource subscriptions. When a task state changes:
  121. ```typescript
  122. // Client subscribes to task resources, notified by listChanged notifications
  123. client.listResources()
  124. client.getResource({ uri: "task://abc-123" })
  125. // When task updates, server automatically:
  126. // 1. Saves task to disk (JSON persistence)
  127. await this.persistence.saveTask(updatedTask);
  128. // 2. Emits internal event
  129. this.emit("task:updated", updatedTask);
  130. // 3. Sends MCP notification to subscribed clients
  131. await sendResourcesUpdatedNotification(`task://${taskId}`, sessionId);
  132. // This triggers: { method: "notifications/resources/updated", params: { uri: "task://abc-123" } }
  133. // Client receives notification and can re-fetch the updated resource
  134. ```
  135. This enables real-time task monitoring without polling - clients stay synchronized with task state changes as they happen.
  136. **2. Push Notifications for Task Completion**
  137. Integrated Firebase Cloud Messaging (FCM) support sends push notifications to mobile devices when tasks complete:
  138. ```typescript
  139. // Task completes → Push notification sent
  140. {
  141. notification: {
  142. title: "Task Complete",
  143. body: "Your refactoring task finished successfully"
  144. },
  145. data: {
  146. taskId: "abc-123",
  147. status: "completed",
  148. duration: "45s"
  149. }
  150. }
  151. ```
  152. Perfect for long-running tasks - start a task, go about your day, get notified when it's done.
  153. **3. Stateful Process Management**
  154. - Tasks persist to disk as JSON with atomic writes
  155. - Process sessions maintained across daemon restarts
  156. - Comprehensive state machine for task lifecycle:
  157. ```
  158. pending → in_progress → waiting → completed
  159. ↓
  160. failed
  161. ```
  162. ### Event-Driven Architecture
  163. All operations emit events consumed by multiple subsystems:
  164. - **Logger**: Structured JSON logs with context
  165. - **State Manager**: Task status updates
  166. - **Notifier**: Push notifications to mobile clients
  167. - **Metrics**: Performance and usage analytics
  168. ## Remote Access Options
  169. ### 🌐 Internet Access via Cloudflare Tunnel
  170. 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).
  171. ```bash
  172. npm run tunnel
  173. ```
  174. This will:
  175. - Create a secure HTTPS tunnel to your local server
  176. - Display both the public URL and local network addresses
  177. - Enable access from anywhere (including mobile devices)
  178. [→ Full Tunnel Documentation](docs/tunnel-remote-access.md)
  179. ### 🏠 Local Network Access
  180. If you prefer to keep everything on your local network:
  181. 1. **Start the server normally:**
  182. ```bash
  183. npm start
  184. ```
  185. 2. **Access from devices on the same network:**
  186. - Find your machine's IP address
  187. - Connect using: `http://YOUR_IP:3000/mcp`
  188. ## Core Features
  189. ### 🤖 AI Agent Orchestration
  190. - **Multi-Agent Support**: Claude Code CLI out of the box, extendable for any agent
  191. - **Task Management**: Create, track, and manage coding tasks - [Task Management →](docs/task-management.md)
  192. - **Session Isolation**: Each task runs in its own context - [Claude Integration →](docs/claude-code-integration.md)
  193. - **Real-time Streaming**: Watch AI agents work in real-time - [Event System →](docs/event-system-and-logging.md)
  194. ### 📱 Mobile-First Design
  195. - **Voice Commands**: "Create a login form with validation"
  196. - **Push Notifications**: Get alerts when tasks complete - [Push Notifications →](docs/push-notifications.md)
  197. - **Quick Actions**: Pre-defined templates for common tasks - [Prompt Templates →](docs/prompt-templates.md)
  198. - **Remote Control**: Manage your dev environment from anywhere
  199. ### 🔧 MCP Protocol Features
  200. - **Persistent State**: Tasks survive server restarts - [State Persistence →](docs/state-persistence.md)
  201. - **Resource Management**: Expose task data as MCP resources - [Tools & Resources →](docs/tools-and-resources.md)
  202. - **Interactive Prompts**: AI agents can ask for clarification
  203. - **Progress Notifications**: Real-time status updates
  204. - **Structured Data**: Full schema validation - [MCP Server →](docs/mcp-server.md)
  205. ## Tool Reference
  206. [→ Full Tools and Resources Documentation](docs/tools-and-resources.md)
  207. ### Task Orchestration
  208. | Tool | Description | Example |
  209. |------|-------------|---------|
  210. | `create_task` | Start new AI coding session | `{"title": "Add auth", "tool": "CLAUDECODE", "instructions": "..."}` |
  211. | `update_task` | Send additional instructions | `{"process": "session_123", "instructions": "..."}` |
  212. | `end_task` | Complete and cleanup | `{"task_id": "task_123", "status": "completed"}` |
  213. | `report_task` | Generate task reports | `{"task_ids": ["task_123"], "format": "markdown"}` |
  214. ### System Management
  215. | Tool | Description | Example |
  216. |------|-------------|---------|
  217. | `check_status` | Verify agent availability | `{"test_sessions": true, "verbose": true}` |
  218. | `update_stats` | Get system statistics | `{"include_tasks": true}` |
  219. | `clean_state` | Cleanup old tasks | `{"keep_recent": true, "dry_run": true}` |
  220. ## Pre-Built Prompts
  221. SystemPrompt includes powerful prompt templates for common coding tasks. [→ Full Prompt Templates Documentation](docs/prompt-templates.md)
  222. ### 🐛 Bug Fixing
  223. ```javascript
  224. {
  225. "prompt_template": "bug_fix",
  226. "variables": {
  227. "bug_description": "Login fails after password reset",
  228. "error_logs": "401 Unauthorized at auth.js:42"
  229. }
  230. }
  231. ```
  232. ### ⚛️ React Components
  233. ```javascript
  234. {
  235. "prompt_template": "react_component",
  236. "variables": {
  237. "component_name": "UserDashboard",
  238. "features": ["data visualization", "real-time updates", "export functionality"]
  239. }
  240. }
  241. ```
  242. ### 🧪 Unit Testing
  243. ```javascript
  244. {
  245. "prompt_template": "unit_test",
  246. "variables": {
  247. "target_files": ["src/auth/*.js"],
  248. "framework": "jest",
  249. "coverage_target": 85
  250. }
  251. }
  252. ```
  253. ## 📚 Comprehensive Documentation
  254. ### Core Architecture
  255. - **[Daemon](docs/daemon.md)** - The host-side bridge that executes commands and manages Claude processes
  256. - **[Docker Architecture](docs/docker-architecture.md)** - How the Docker container and host machine interact
  257. - **[MCP Server](docs/mcp-server.md)** - The Model Context Protocol server implementation
  258. ### AI Agent Systems
  259. - **[Agent Manager](docs/agent-manager.md)** - Central orchestrator for all AI agent sessions
  260. - **[Claude Code Integration](docs/claude-code-integration.md)** - How Claude Code CLI is integrated and managed
  261. - **[Task Management](docs/task-management.md)** - Task lifecycle, persistence, and state management
  262. ### Protocol & API
  263. - **[Tools and Resources](docs/tools-and-resources.md)** - MCP tools and resources implementation
  264. - **[Event System and Logging](docs/event-system-and-logging.md)** - Real-time event streaming and structured logging
  265. ### Additional Features
  266. - **[Testing Framework](docs/testing-framework.md)** - E2E testing setup and best practices
  267. - **[Tunnel and Remote Access](docs/tunnel-remote-access.md)** - Cloudflare tunnel setup for internet access
  268. - **[State Persistence](docs/state-persistence.md)** - How tasks and sessions persist across restarts
  269. - **[Push Notifications](docs/push-notifications.md)** - Mobile push notification integration
  270. - **[Prompt Templates](docs/prompt-templates.md)** - Pre-built prompt system for common tasks
  271. ## Performance Optimizations
  272. 1. **Streaming Output**: Agent output streamed in chunks, not buffered
  273. 2. **Lazy Resource Loading**: Resources fetched on-demand
  274. 3. **Connection Pooling**: Reused TCP connections to daemon
  275. 4. **Efficient State Persistence**: Only changed fields written to disk
  276. ## Development
  277. ### Project Structure
  278. ```
  279. systemprompt-coding-agent/
  280. ├── src/
  281. │ ├── server.ts # MCP server setup
  282. │ ├── handlers/ # Protocol handlers
  283. │ ├── services/ # Agent services
  284. │ ├── constants/ # Tool definitions
  285. │ └── types/ # TypeScript types
  286. ├── docker-compose.yml
  287. └── package.json
  288. ```
  289. ### Contributing
  290. 1. Fork the repository
  291. 2. Create a feature branch
  292. 3. Make your changes
  293. 4. Submit a pull request
  294. For security issues, email security@systemprompt.io
  295. ## Support
  296. - **Documentation**: [docs.systemprompt.io](https://systemprompt.io/documentation)
  297. - **GitHub Issues**: [Report bugs](https://github.com/systempromptio/systemprompt-code-orchestrator/issues)
  298. - **Discord**: [Join our community](https://discord.com/invite/wkAbSuPWpr)
  299. - **Twitter**: [@tyingshoelaces_](https://twitter.com/tyingshoelaces_)
  300. ## Future Roadmap
  301. 1. **Multi-Agent Orchestration**: Coordinate multiple AI agents on complex tasks
  302. 2. **Incremental Computation**: Cache and reuse AI outputs
  303. 3. **Distributed Execution**: Spread tasks across multiple machines
  304. 4. **Web UI Dashboard**: Browser-based monitoring and control
  305. ## MCP Client Options
  306. While this server works with any MCP-compatible client, for a mobile voice-controlled experience, check out [SystemPrompt.io](https://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!
  307. ## License
  308. MIT License - see [LICENSE](LICENSE)
  309. ---
  310. <div align="center">
  311. <strong>Built with love by <a href="https://systemprompt.io">SystemPrompt.io</a></strong><br>
  312. <em>AI-Powered Development from Anywhere</em>
  313. </div>

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.