Conductor

[Tests] [License: MIT]

Conductor

Claude's hands for local automation — with a web dashboard for the humans who watch it.

Conductor gives Claude direct, persistent control of a local task runner. Tell Claude what you want automated; it creates the scheduled workers, builds multi-step pipelines, wires up email reports, fires test runs, and reads back the logs when something fails — all through conversation. A web dashboard at 127.0.0.1:5000 runs alongside it for humans who want to peek at status, click pause, or hand-edit a worker.

Originally built to automate warehouse reporting workflows (the daily ShipExec metrics pull) and now general-purpose: any Python / batch / shell script, any schedule, any chain.

The MCP server lives in this repo (server.py) — the thin layer that exposes Conductor's REST API as Claude tools. It's bundled and auto-registered on install, so most users won't need to touch it directly. The separate conductor-mcp repo is deprecated — it holds an older copy without the auto-launch race protection.

[Conductor Dashboard]

Claude Integration

Conductor registers itself as an MCP server in Claude Desktop on first launch. After restarting Claude Desktop once, Claude has 21 tools for full control:

Example conversation:

You: Run my metrics script every night at 8:30 PM and email me the report

Claude: I'll set that up using the Run + Email template. (creates the worker, configures the schedule, wires up Gmail, fires it to test) Done — worker "Daily Metrics Report" is live. Check your email for the test run.

You: That uptime check keeps failing. What's going on?

Claude: (pulls the last 10 runs, reads the error logs) The site returned a 503 three times in the last hour. The SSL certificate expired yesterday. Here's the full error from the last run...

You: Chain my backup script and cleanup script together. Run backup first, then cleanup after it finishes. Every day at 2 AM.

Claude: *(creates a chain with stage 0 = backup, stage 1 = cleanup, cron schedule "0 2 * * ") Chain "Nightly Maintenance" created with 2 steps. Backup runs first, cleanup runs after it succeeds.

How it works:

1. Install Conductor (Windows installer or from source)
2. Conductor writes its MCP entry to Claude Desktop's config on first launch
3. Restart Claude Desktop once
4. Claude now controls Conductor through natural language — create workers, build chains, fire tasks, check logs, send emails

Features

• Claude-Controlled — 21 MCP tools let Claude create workers, chains, groups, templates, and more. Non-technical users can automate anything through conversation.
• Flexible Scheduling — Fixed times (09:00, 14:30), intervals (2h 30m), or cron expressions (0 9 * * 1-5 with plain-English preview).
• Task Support — Python (.py), batch (.bat, .cmd), and shell (.sh) scripts. Selenium and GUI scripts run in a visible terminal window via new_console.
• Built-in Email — configure Gmail once, then any template or worker can send emails. Run + Email template for automated reports. Folder Watcher emails files on arrival. Uptime Check sends DOWN alerts. Worker notifications on success/failure.
• Task Chains — multi-step pipelines with parallel execution. Same stage number = run in parallel. Stop-on-failure toggle.
• Worker Groups — collapsible named groups for organization. Bulk pause/delete per group.
• Run History — per-worker/chain history with status, duration, and error details. Colored dots show last run status at a glance.
• Built-in Templates — Folder Backup, File Cleanup, Folder Watcher, Uptime Check, Open URL, Run + Email. Generated scripts are stdlib-only and self-contained.
• Per-worker Environment Variables — inject KEY=VALUE pairs into subprocess environments.
• Worker Timeout — kill and log workers that run over a set number of minutes.
• Email Notifications — per-worker/chain email alerts: Always, On Failure, or On Success.
• Import / Export — portable JSON snapshot of all workers, chains, and groups.
• Saved Profiles — save and load named worker configurations.
• Auto-start on Login — one-click Registry Run key install. No admin required.
• Auto-update Check — modal dialog when a newer release is available.
• System Tray Icon — right-click for Open Dashboard or Stop.
• AI Error Analysis — send error logs to Claude for diagnosis directly in the dashboard.
• Persistent State — SQLite database. Workers and chains restore on restart.

Add Workers Form

[Add Workers form]

Built-in Templates

[Template picker modal]

Task Chains

[New Task Chain modal]

Debug Log

[Debug log panel]

Installation (Windows)

Download and run Conductor_Setup.exe from the latest release.

• Requires Python 3 on the machine (see note below) — Conductor runs your .py workers with it
• Installs to %AppData%\Conductor — no admin/UAC required
• Adds Start Menu shortcut and optional desktop shortcut
• Optional auto-start at login
• Uninstaller included

Python is required for Python workers. Conductor itself ships as a self-contained executable, but it runs your .py scripts with a real interpreter found on your system (the py launcher, PATH, or the Windows registry). If none is found, workers fail loudly with instructions — they are never reported as successful. Set CONDUCTOR_PYTHON to a full path to pin a specific interpreter. .bat / .cmd / .sh workers do not need Python.

Setup from Source

Requirements

• Python 3.10+

git clone https://github.com/jarmstrong158/conductor.gitcd conductorpip install -r requirements.txtpython launch.py

The dashboard opens at http://127.0.0.1:5000. Press Ctrl+C to stop.

Building the Installer

.\build.bat

Forces a full rebuild:

.\build.bat --rebuild

Output: Output\Conductor_Setup.exe. Requires Inno Setup.

Task File Format

Python (.py)

Scripts run as subprocesses:

if __name__ == "__main__":    print("Task executed!")

Batch / Shell (.bat, .sh, .cmd)

Executed as subprocesses. The worker's output directory (if set) is used as the working directory.

Schedule Formats

Task Chains

Chains run multiple scripts in sequence. Each step has a stage number — steps with the same stage run in parallel, stages execute in order. Stop on failure halts the chain when any step fails.

Stage 0: backup.py  ──┐Stage 0: cleanup.py ──┤  (both run at once)                      ↓Stage 1: report.py    (runs after both finish)

Templates

All generated scripts use Python stdlib only.

Architecture

conductor/├── launch.py          # Entry point — Flask, browser, tray, MCP registration├── app.py             # Flask backend + APScheduler + SQLite├── server.py          # MCP server for Claude Desktop├── CLAUDE.md          # Context file for Claude Code / Desktop├── static/│   └── index.html     # Frontend — HTML + CSS + JS (no frameworks)├── tasks/│   └── example_task.py├── templates/│   └── generated/     # Auto-generated template scripts├── build.bat          # One-click installer build├── build_icon.py      # Generates conductor.ico├── conductor.spec     # PyInstaller spec├── installer.iss      # Inno Setup script└── conductor.db       # SQLite database (auto-created)

AI Error Analysis

The debug log includes an Analyze Errors button. When ERROR entries are present, click it to send them to Claude for diagnosis. Requires an Anthropic API key in .env:

ANTHROPIC_API_KEY=sk-ant-...

Example — before / after:

Raw error in the debug log:

[ERROR] worker "Daily Metrics Report" exit code 1Traceback (most recent call last):  File "C:\scripts\metrics.py", line 142, in <module>    driver.find_element(By.ID, "report-table").click()  File ".../selenium/.../webdriver.py", line 830, in find_element    raise NoSuchElementException(message)selenium.common.exceptions.NoSuchElementException: Message: no such element:Unable to locate element: {"method":"css selector","selector":"[id="report-table"]"}

Claude's diagnosis (one click later):

The script is failing on a find_element call before the page has finished loading — Selenium is racing the DOM. The element #report-table is rendered after an XHR completes. Two fixes, in order of preference:

1. Wrap the lookup in a WebDriverWait(driver, 10).until(EC.presence_of_element_located((By.ID, "report-table"))) so it polls until the element exists.
2. If you don't want to import the wait helpers, a time.sleep(2) before the click will work but is brittle. The traceback shows this happened on the first run after a ShipExec UI change yesterday — they may have also renamed the element. Verify the ID is still report-table in DevTools before adding the wait.

Email Setup

Click 📧 Email in the header to configure Gmail credentials. Requires a Gmail App Password (2-Step Verification must be enabled first). Credentials are stored locally in .env and never transmitted except to Gmail's SMTP server.

Once configured, all templates and worker notifications can send email.

API

License

MIT