🐶SparkECoder🐶

A powerful coding agent CLI with HTTP API. Built with the Vercel AI SDK.

Features

• 🤖 Multi-Agent Sessions - Run multiple agents simultaneously with isolated contexts
• 🧭 Personal Orchestrator - Built-in supervisor agent that spawns workers, posts to Slack, fires on cron schedules, accepts webhooks, and edits its own config. See docs/ORCHESTRATOR.md.
• 🔌 MCP support - Add Model Context Protocol servers via the Settings UI or by editing the config file. Hot-reloads on next agent turn.
• 💬 Slack integration - Signed events, per-user/per-channel allowlist, canned denied-reply, in-thread responses. Setup wizard with copy-paste manifest in the Settings UI.
• 🪝 Inbound webhooks - Token-protected URLs (/api/inbox/<token>) so external services can ping the orchestrator. Templated formatting.
• ⏰ Cron schedules - Recurring prompts that wake the orchestrator with catch-up window.
• 🧠 Long-term memory - Every turn mirrored to local JSONL files; orchestrator can grep across sessions via the search-conversations skill.
• 🔄 Streaming Responses - Real-time SSE streaming following Vercel AI SDK data stream protocol
• 🔧 Powerful Tools - Bash execution, file operations, planning, and skill loading
• ✅ Tool Approvals - Configurable approval requirements for dangerous operations
• 📚 Skills System - Load specialized knowledge documents into context
• 💾 Persistence - Full session and message history storage (remote MongoDB by default)
• 🌐 HTTP API - RESTful API with auto-generated OpenAPI specification
• 🎯 Context Management - Automatic summarization for long conversations

Installation

# Global install (recommended)
npm install -g sparkecoder
# or
pnpm add -g sparkecoder

From Source

git clone https://github.com/gostudyfetchgo/sparkecoder.git
cd sparkecoder
pnpm install
pnpm dev

Quick Start (Personal Orchestrator)

sparkecoder server

That's it — no API key to configure. On first boot sparkecoder auto-registers with the remote inference server. The first boot also:

• Starts the API at http://127.0.0.1:3141 and the web UI at http://localhost:6969
• Auto-creates the orchestrator session (always visible in the left sidebar)
• Starts the per-orchestrator inbox, the daemon that drains it, the cron scheduler, and the MCP client pool

Open http://localhost:6969 and you'll see:

• Orchestrator in the sidebar — your long-lived supervisor chat
• Agents — kanban of worker agents the orchestrator spawns
• Settings — 6 tabs (General · Integrations · MCP · Schedules · Webhooks · Models · API Keys)

For end-to-end setup (Slack, cloudflared, MCP, schedules, webhooks, personality, long-term memory): see docs/ORCHESTRATOR.md.

One-off task mode (no orchestrator)

If you just want a one-shot autonomous task:

sparkecoder task --prompt "Refactor src/foo.ts to use async/await" \
  --schema '{"type":"object","properties":{"summary":{"type":"string"}},"required":["summary"]}' \
  --wait

See docs/TASK-MODE.md.

Direct API call

curl -X POST http://localhost:3141/agents/quick \
  -H "Content-Type: application/json" \
  -d '{"prompt": "List the files in the current directory"}'

API Reference

Sessions

| Endpoint | Method | Description | |----------|--------|-------------| | /sessions | GET | List all sessions | | /sessions | POST | Create a new session | | /sessions/:id | GET | Get session details | | /sessions/:id | DELETE | Delete a session | | /sessions/:id/messages | GET | Get session messages | | /sessions/:id/clear | POST | Clear session context |

Agents

| Endpoint | Method | Description | |----------|--------|-------------| | /agents/:id/run | POST | Run agent with streaming (SSE) | | /agents/:id/generate | POST | Run agent without streaming | | /agents/:id/approve/:toolCallId | POST | Approve pending tool | | /agents/:id/reject/:toolCallId | POST | Reject pending tool | | /agents/:id/approvals | GET | Get pending approvals | | /agents/quick | POST | Create session and run in one request |

OpenAPI

Full OpenAPI specification available at /openapi.json.

Configuration

Create a sparkecoder.config.json file:

{
  "defaultModel": "gpt-5.5",
  "workingDirectory": ".",
  "toolApprovals": {
    "bash": true,
    "write_file": false,
    "read_file": false
  },
  "skills": {
    "directory": "./skills"
  },
  "context": {
    "maxChars": 200000,
    "autoSummarize": true
  },
  "server": {
    "port": 3141,
    "host": "127.0.0.1",
    "publicUrl": "http://your-server:3141"
  }
}

Configuration Options

| Option | Description | Default | |--------|-------------|---------| | defaultModel | LiteLLM model id | gpt-5.5 | | workingDirectory | Base directory for file operations | Current directory | | toolApprovals | Which tools require user approval | { bash: true } | | skills.directory | Directory containing skill files | ./skills | | context.maxChars | Max context size before summarization | 200000 | | context.autoSummarize | Enable automatic summarization | true | | server.port | HTTP server port | 3141 | | server.host | HTTP server host | 127.0.0.1 | | server.publicUrl | Public URL for web UI (Docker/remote) | Auto-detected |

Tools

bash

Execute shell commands in the working directory.

{
  "command": "ls -la"
}

read_file

Read file contents with optional line range.

{
  "path": "src/index.ts",
  "startLine": 1,
  "endLine": 50
}

write_file

Write or edit files. Supports two modes:

Full write:

{
  "path": "new-file.ts",
  "mode": "full",
  "content": "// New file content"
}

String replacement:

{
  "path": "existing-file.ts",
  "mode": "str_replace",
  "old_string": "const x = 1;",
  "new_string": "const x = 2;"
}

todo

Manage task lists for complex operations.

{
  "action": "add",
  "items": [
    { "content": "Step 1: Analyze code" },
    { "content": "Step 2: Implement fix" }
  ]
}

load_skill

Load specialized knowledge into context.

{
  "action": "load",
  "skillName": "Debugging"
}

Skills

Skills are markdown files with specialized knowledge. Place them in your skills directory:

---
name: My Custom Skill
description: Description of what this skill provides
---

# My Custom Skill

Detailed content that will be loaded into context...

Built-in skills:

• Debugging - Systematic debugging approaches
• Code Review - Code review checklists and best practices
• Refactoring - Safe refactoring patterns and techniques

CLI Commands

sparkecoder server              # Start the API + Web UI + orchestrator daemon + scheduler
sparkecoder chat                # Interactive REPL chat with an agent
sparkecoder task --prompt ... --schema ...   # Run a one-off autonomous task
sparkecoder init                # Create a sparkecoder.config.json in cwd
sparkecoder slack-setup         # Interactively configure Slack creds
sparkecoder cloudflared-setup --hostname X --team Y   # Print public-tunnel + CF Access recipe
sparkecoder sessions            # List all sessions on the running server
sparkecoder status              # Check if the server is running
sparkecoder config              # Show resolved configuration
sparkecoder info                # Show version and environment

Interactive Chat

Start an interactive chat session with the agent:

# Start a new chat session
sparkecoder chat

# Resume an existing session
sparkecoder chat --session <session-id>

# Start with custom options
sparkecoder chat --name "My Project" --model "gpt-5.5"

In-chat commands:

• /quit or /exit - Exit the chat
• /clear - Clear conversation history
• /session - Show current session info
• /tools - List available tools

Streaming Protocol

The API uses Server-Sent Events (SSE) following the Vercel AI SDK data stream protocol.

Compatible with useChat from @ai-sdk/react:

import { useChat } from '@ai-sdk/react';

const { messages, sendMessage } = useChat({
  api: 'http://localhost:3141/agents/SESSION_ID/run',
});

Tool Approvals

Configure which tools require approval:

{
  "toolApprovals": {
    "bash": true,      // Requires approval
    "write_file": true // Requires approval
  }
}

When approval is required:

1. The agent pauses and streams an approval-required event
2. Call /agents/:id/approve/:toolCallId to approve
3. Call /agents/:id/reject/:toolCallId to reject

Environment Variables

| Variable | Description | |----------|-------------| | AI_GATEWAY_API_KEY | Vercel AI Gateway API key (required) | | SPARKECODER_MODEL | Override default model | | SPARKECODER_PORT | Override server port | | DATABASE_PATH | Override database path |

Docker / Remote Access

When running SparkECoder in Docker or exposing it to remote clients, you need to configure the public URL so the web UI can connect to the API from the browser.

CLI Option

sparkecoder start --public-url http://your-server:3141

Config File

{
  "server": {
    "port": 3141,
    "host": "0.0.0.0",
    "publicUrl": "http://your-server:3141"
  }
}

Notes:

• Set host to 0.0.0.0 to bind to all interfaces (required for Docker/remote access)
• Set publicUrl to the URL the browser will use to reach the API
• The web UI detects this URL automatically on first load and stores it in localStorage

Development

# Run in development mode with hot reload
pnpm dev

# Type check
pnpm typecheck

# Build for production
pnpm build

# Run production build
pnpm start

Testing

SparkECoder includes comprehensive end-to-end tests that make actual API calls to the LLM.

# Run all E2E tests (requires AI_GATEWAY_API_KEY)
pnpm test:e2e

# Run tests in watch mode
pnpm test:watch

The tests cover:

• Health & server endpoints
• Session management (CRUD operations)
• Agent text generation (streaming & non-streaming)
• File operations (create, read, edit)
• Bash command execution
• Todo management
• Multi-turn conversations with context
• Tool approvals workflow

Note: E2E tests require a valid AI_GATEWAY_API_KEY and will make real LLM calls. They create a temporary .test-workspace directory that is cleaned up after tests complete.

License

Proprietary - All rights reserved.