MATLAB Runner

A Claude Code plugin for managing MATLAB job execution with resource-aware scheduling, a terminal TUI dashboard, and Simulink support.

Features

• Resource-aware scheduling — Bin-packing scheduler tracks CPU cores and memory, auto-analyzes .m files for parpool/parfor/gpuArray usage
• Terminal TUI dashboard — Live status bar with job list, CPU/memory/GPU bars, and interleaved color-coded log stream
• Simulink support — Auto-generates .m wrappers for .slx models with proper JVM handling
• Process control — Pause/resume (SIGSTOP/SIGCONT), cancel, kill via keyboard shortcuts or IPC
• Memory pressure management — Auto-pauses jobs when system memory drops below threshold
• DAG dependencies — Chain jobs with --depends for ordered execution
• Persistent history — SQLite-backed run history across daemon restarts
• Hook integration — Auto-detects .m/.slx file writes and queues them for execution

Architecture

Claude Code (pane 0)  ──── Unix socket ────  MATLAB Runner TUI (pane 1)
      │                                              │
  PostToolUse hook                          Daemon + Scheduler
  detects .m/.slx                           + Resource Monitor
  writes                                    + MATLAB processes

Two processes: the daemon (scheduler + TUI + IPC server) and ephemeral hook scripts that send one JSON message via Unix socket.

Quick Start

# Start the TUI dashboard (in tmux)
./scripts/ensure_daemon.sh

# Submit a job
cd scripts && python3 -m matlab_runner submit path/to/script.m

# Submit with resource overrides
cd scripts && python3 -m matlab_runner submit heavy_sim.m --cores 8 --mem 16384

# Submit with dependencies
cd scripts && python3 -m matlab_runner submit analysis.m --depends 1 2

# Check status
cd scripts && python3 -m matlab_runner status

# Control jobs
cd scripts && python3 -m matlab_runner pause 3
cd scripts && python3 -m matlab_runner resume 3
cd scripts && python3 -m matlab_runner cancel 3

TUI Keyboard Shortcuts

Key	Action
0-9	Focus on job N (0 = show all)
p / r	Pause / resume focused job
c / k	Cancel / kill focused job
P / R / C	Pause / resume / cancel all
d	Clear completed jobs
q	Detach (jobs keep running)
Q	Quit and kill all jobs

Progress Reporting

MATLAB scripts can report progress to the TUI:

fprintf('##PROGRESS:%d##\n', percent);

Configuration

Edit .matlab-config.json:

{
  "matlab_path": "matlab",
  "default_cores": 1,
  "default_memory_mb": 2048,
  "timeout_seconds": 3600,
  "cpu_reserve": 2,
  "mem_fraction": 0.85,
  "mem_pressure_pause": 10.0,
  "mem_pressure_resume": 20.0
}

Running Tests

python3 -m unittest discover tests/ -v