Conductor: Instructions file for Claude Code

Conductor — Claude Context

Conductor is a local web dashboard for managing scheduled Python and batch workers via APScheduler + SQLite. It runs at http://127.0.0.1:5000 and exposes a REST API that this MCP server wraps.

The MCP server auto-launches the installed Conductor.exe from %APPDATA%/Redis Operator/ if it's not already running.

Redis is not used. It was advertised and bundled but every piece of state lives in SQLite; the client was assigned and never read. Removed.

Running from source is supported (python launch.py) and is how the test suite runs. The old "never run from source" rule was written when the frozen exe was assumed to be the only working mode — in fact it was the broken one (see below). The real caveat is only that source runs default to the repo's conductor.db, not the exe's AppData copy.

Running user scripts — do not use sys.executable

conductor.spec freezes launch.py, so inside the exe sys.executable is Conductor.exe, not a Python. Building a worker command as [sys.executable, task_path] produced Conductor.exe user_script.py; launch.py ignores sys.argv, so it printed a banner, opened a browser tab and exited 0 — and Conductor recorded success for a script that never ran.

Always resolve an interpreter with _resolve_python() and guard the command with _assert_not_self(). _resolve_python() checks CONDUCTOR_PYTHON, a bundled python, the py launcher, PATH, then the Windows registry, and raises InterpreterNotFound rather than ever returning the Conductor binary. Never silently succeed.

What it does

Users register scripts (.py, .bat, .sh, .cmd) and give them a schedule. Conductor fires them on time, logs the results, and shows everything in a browser dashboard. No terminal needed after launch.

Scripts can be chained together into sequential or parallel pipelines. Workers can be grouped for organization. Everything persists in SQLite.

Core concepts

Workers

A worker is one script on one schedule. Key fields:

• task_path — absolute path to the script file
• sched_type — "fixed", "interval", or "cron"
• sched_value — "09:00,14:30" / "2h 30m" / "0 9 * * 1-5"
• timeout_minutes — kills the process after N minutes (0 = no timeout)
• env_vars — KEY=VALUE lines injected into subprocess environment
• requirements — comma-separated pip packages auto-installed before first run
• new_console — opens a new terminal window (Windows only, suppresses stdout capture)
• output_dir — working directory for the subprocess
• group_id — optional group assignment