io.github.fieldcure/assiststudio-runner

AssistStudio Runner

A Windows-only headless LLM task automation engine that executes natural language tasks on schedule and delivers results through configured channels. Built as a Model Context Protocol (MCP) server with the official MCP C# SDK.

Features

• Dual-mode operation — MCP server (serve) for task management, headless CLI (exec) for scheduled execution
• 7 MCP tools — create_task, update_task, delete_task, list_tasks, run_task, get_task_history, get_execution_status
• Windows Task Scheduler integration — cron expressions automatically mapped to schtasks entries
• Shared AgentLoop — LLM execution powered by Ai.Execution (same loop used by SubAgentExecutor)
• Multi-provider LLM support — Claude, OpenAI, Gemini, Ollama, Groq via Ai.Providers
• MCP server orchestration — tasks can bootstrap any MCP servers (Outbox, RAG, Filesystem, custom)
• Flexible tool control — AllowedTools null = all tools permitted; explicit list for fine-grained control; empty list = safe tools only
• Secure credentials — API keys in Windows Credential Manager (DPAPI), shared with AssistStudio
• Execution logging — DB summary + detailed JSON logs with full conversation history
• One-time scheduling — schedule_once with ISO 8601 datetime for single-execution tasks (“in 5 minutes”, “tomorrow at 9am”)
• Result delivery — send results via Outbox channels (Slack, Telegram, Email, KakaoTalk, Discord)

Installation

dotnet tool (recommended)

dotnet tool install -g FieldCure.AssistStudio.Runner

After installation, the assiststudio-runner command is available globally. The published package is Windows-only because scheduling is implemented via Windows Task Scheduler and credentials are stored in Windows Credential Manager.

From source

git clone https://github.com/fieldcure/fieldcure-assiststudio-runner.git
cd fieldcure-assiststudio-runner
dotnet build

Requirements

• .NET 8.0 Runtime or later
• Windows (required for Task Scheduler and Credential Manager)

Configuration

Auto-configuration (recommended)

When launched in serve mode with no runner.json, Runner automatically scans Windows Credential Manager for known provider API keys and generates the config file. If you use AssistStudio, API keys are already stored — no manual setup needed.

Manual Setup

# Create runner.json config template
assiststudio-runner config init

# Set API key for a provider model
assiststudio-runner config set-credential "Claude" sk-ant-api03-...

# Verify (displays masked value)
assiststudio-runner config get-credential "Claude"

The config file is created at %LOCALAPPDATA%/FieldCure/AssistStudio/Runner/runner.json:

{
  "defaultModelName": "Claude",
  "models": {
    "Claude": {
      "providerType": "Claude",
      "modelId": "claude-sonnet-4-20250514"
    }
  },
  "fallbackChannel": "runner-alerts",
  "logRetentionDays": 30
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "runner": {
      "command": "assiststudio-runner",
      "args": ["serve"]
    }
  }
}

VS Code (Copilot)

Add to .vscode/mcp.json:

{
  "servers": {
    "runner": {
      "command": "assiststudio-runner",
      "args": ["serve"]
    }
  }
}

From source (without dotnet tool)

{
  "mcpServers": {
    "runner": {
      "command": "dotnet",
      "args": [
        "run",
        "--project", "C:\\path\\to\\fieldcure-assiststudio-runner\\src\\FieldCure.AssistStudio.Runner",
        "--", "serve"
      ]
    }
  }
}

Tools

Usage

Conversation Example

User: "Summarize competitor news every morning at 9 AM and send it to Slack"
  LLM → create_task (schedule: "0 9 * * 1-5", mcp_servers: [outbox, rag])

User: "Run a test"
  LLM → run_task (wait: true) → reports result

User: "Exclude weekends"
  LLM → update_task (schedule: "0 9 * * 1-5")

User: "What were yesterday's results?"
  LLM → get_task_history (limit: 1)

Execution Modes

Exit Codes (exec mode)

Scheduling

Cron expressions are automatically mapped to Windows Task Scheduler entries:

Scheduled tasks are created with schtasks /IT, so they run in the interactive user context and require the user to be logged in at trigger time.

The schtasks command line uses dnx (NuGet's npx-equivalent, .NET 10+) to fetch and run the worker — dnx FieldCure.AssistStudio.Runner@<major>.* --yes exec <id>. Stateless MCP servers consumed by the worker (Essentials, Outbox) are spawned the same way, pinned at their current major range. Set RunnerConfig.ToolPath to override with a concrete executable when an offline-from-NuGet workflow is required.

Data Storage

Project Structure

src/FieldCure.AssistStudio.Runner/
├── Program.cs                    # Dual-mode entry point (serve/exec/config)
├── Models/                       # RunnerTask, TaskExecution, RunnerConfig, ExecutionLog
├── Storage/TaskStore.cs          # SQLite storage with WAL mode
├── Credentials/                  # ICredentialService + Windows PasswordVault
├── Scheduling/                   # CronToSchtasks parser, SchedulerService (schtasks)
├── Execution/                    # TaskExecutor (AgentLoop-based), McpServerPool
├── Tools/                        # 7 MCP tools for serve mode
└── Configuration/ConfigRunner.cs # CLI config subcommands

Development

# Build
dotnet build

# Test
dotnet test

# Pack
dotnet pack -c Release

Designed for AssistStudio

Runner is purpose-built for the AssistStudio ecosystem. Tasks are typically created through natural language conversations in AssistStudio, which handles workflow design, MCP server selection, and tool permissions automatically.

While Runner can be used standalone with Claude Desktop or VS Code (via serve mode), you'll need to construct task parameters (prompt, MCP servers, allowed tools) manually. For the full experience, use AssistStudio.

See Also

Part of the AssistStudio ecosystem.

License

MIT