TaskMonitor

TaskMonitor is a lightweight local monitor for long-running tasks such as training, inference, rendering, preprocessing, evaluation, and batch jobs.

It has two interfaces:

• taskmon, a small CLI for humans and AI agents.
• A local web dashboard with progress bars, metrics, process status, and live training loss curves.

TaskMonitor stores metadata only: task ids, process ids, counters, loss points, metrics, notes, and artifact references. It does not copy datasets, model weights, predictions, rendered media, logs, or other project data.

Install

From a checkout:

python -m pip install -e .

Task state is stored in ~/.taskmonitor by default. To use another location:

export TASKMONITOR_HOME=/path/to/taskmonitor-state

You can also pass --home /path/to/taskmonitor-state to every command.

CLI Quick Start

Initialize state:

taskmon init

Register a training task:

taskmon register train-demo \
  --type training \
  --name "Demo training" \
  --pid 12345 \
  --command "python train.py" \
  --param epochs=10 \
  --param batch_size=4

Append live loss points:

taskmon loss train-demo --step 1 --loss 2.4 --lr 0.001 --total-steps 100
taskmon loss train-demo --step 2 --loss 1.9 --lr 0.001 --total-steps 100

Update a render, preprocess, or inference progress bar:

taskmon update render-demo \
  --current 42 \
  --total 100 \
  --unit frames \
  --message "rendering frame 42"

Attach metrics:

taskmon metric infer-demo json_valid=1.0 accuracy=0.92 latency_ms=48

Finish a task:

taskmon finish train-demo --message "done" --metric final_loss=1.9

List and inspect:

taskmon list
taskmon list --active
taskmon show train-demo --json
taskmon snapshot

Run a process and monitor its pid:

taskmon wrap count-files --type preprocess -- find . -type f

Auto-register obvious long-running processes:

taskmon scan --min-age 600

By default, scan only matches command lines that look like training, inference, rendering, preprocessing, or evaluation tasks. Use --all only when you intentionally want a broad local process inventory.

Web Dashboard

Start the local dashboard:

taskmon serve --host 127.0.0.1 --port 8765

Open:

http://127.0.0.1:8765/

The page polls /api/snapshot every few seconds and renders:

• task summary cards,
• progress bars,
• training loss curves,
• metrics and artifacts,
• process liveness and command line,
• recent notes.

AI Agent Interface

Agents can use either the CLI or the Python API.

CLI commands accept structured key=value values and emit JSON with --json:

taskmon register agent-job --type inference --json
taskmon update agent-job --current 5 --total 20 --metric exact_match=0.75 --json
taskmon finish agent-job --message "complete" --json

Python API:

from taskmonitor import TaskMonitor

mon = TaskMonitor()
mon.register("agent-job", "Agent job", "inference", owner="agent")
mon.update(
    "agent-job",
    progress={"current": 5, "total": 20, "unit": "items", "message": "running"},
    metrics={"exact_match": 0.75},
)
mon.finish("agent-job", message="complete")

Data Layout

For each state home:

state/
  jobs/<task_id>.json
  history/<task_id>.jsonl
  snapshot.json

The files are intentionally simple JSON/JSONL so shell scripts, notebooks, and agents can integrate without a database.