AssistStudio Runner

![NuGet](https://www.nuget.org/packages/FieldCure.AssistStudio.Runner) ![License: MIT](https://github.com/fieldcure/fieldcure-assiststudio-runner/blob/main/LICENSE)

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

| Tool | Description | Confirmation | |------|-------------|:------------:| | create_task | Create a task with prompt, schedule, and MCP server config | Required | | update_task | Modify task fields — partial update, only changed fields | Required | | delete_task | Delete a task, its executions, and log files | Required | | list_tasks | List tasks with filtering and last execution status | — | | run_task | Start execution (async default, optional 60s wait) | Required | | get_task_history | Query execution history with status filtering | — | | get_execution_status | Check real-time status of an execution | — |

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

| Mode | Command | Purpose | |------|---------|---------| | Serve | assiststudio-runner serve | MCP server (stdio) for task management | | Exec | assiststudio-runner exec <task-id> | Headless execution (called by schtasks) | | Config | assiststudio-runner config init | Create config template | | | assiststudio-runner config set-credential <key> <value> | Store API key or env var | | | assiststudio-runner config get-credential <key> | Retrieve credential (masked) |

Exit Codes (exec mode)

| Code | Meaning | |------|---------| | 0 | Succeeded | | 1 | Failed | | 2 | Timed out | | 3 | Task not found | | 4 | Already running |

Scheduling

Cron expressions are automatically mapped to Windows Task Scheduler entries:

| Schedule | Parameter | schtasks | |----------|-----------|----------| | Once at specific time | schedule_once: "2026-04-07T15:30:00+09:00" | /SC ONCE /SD 2026/04/07 /ST 15:30 | | Every 30 minutes | schedule: "/30 " | /SC MINUTE /MO 30 | | Every 2 hours | schedule: "0 /2 " | /SC HOURLY /MO 2 | | Daily at 9:00 AM | schedule: "0 9 " | /SC DAILY /ST 09:00 | | Weekdays at 9:00 AM | schedule: "0 9 1-5" | /SC WEEKLY /D MON,TUE,WED,THU,FRI /ST 09:00 | | Monthly on the 1st | schedule: "0 9 1 " | /SC MONTHLY /D 1 /ST 09:00 |

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

| Data | Location | |------|----------| | Configuration | %LOCALAPPDATA%/FieldCure/AssistStudio/Runner/runner.json | | Task database | %LOCALAPPDATA%/FieldCure/AssistStudio/Runner/runner.db (SQLite, WAL) | | Execution logs | %LOCALAPPDATA%/FieldCure/AssistStudio/Runner/logs/{id}.json | | API keys | Windows Credential Manager (FieldCure.AssistStudio) |

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.

License

MIT

fieldcure-assiststudio-runner