parallelmap

parallelmap

A test suite or a job pipeline takes as long as it takes — unless some of it can run side by side. parallelmap takes the workload graph — every job's name, its duration, and the names of the jobs that must finish before it starts — and maps out what can safely parallelize:

• Levels — the jobs grouped by depth. Level 0 holds the jobs with no dependencies; every other job sits at one level above its deepest dependency. Everything in a level can run together, once the levels below it are done.
• Sequential vs parallel time — the sum of all durations against the makespan with unbounded workers (the largest earliest finish), and the speedup between them. All reported seconds are rounded to 3 decimals, and the speedup is computed from those rounded values.
• Critical path — the chain that sets the parallel time, in execution order. Ties — for the finishing job and for each step back along the chain — go to the smallest job name, so the path is fully deterministic.
• Worker schedule — pass a worker count and a greedy list schedule assigns the jobs in (level, name) priority order, each to the worker that frees up first (lowest index on a tie), starting no earlier than its dependencies' finishes under that schedule. The schedule reports each job's worker, start, and finish, sorted by (start, worker, job), plus the resulting makespan. Without a worker count there is no schedule and the makespan is the unbounded parallel time.
• Cycle detection — when the jobs cannot be scheduled at all, parallelmap does not error out or guess. It reports ok: false with the exact cycle: a depth-first search over names and dependencies in ascending order returns the first cycle it finds as the list of jobs forming it (a job that depends on itself reports as a one-name cycle), with the time fields null.

The graph must be closed: a depends_on entry naming a job that was not supplied is a validation error, as are a missing or duplicate job name, a missing, negative, or non-finite duration, and a worker count that is not an integer of at least 1. Errors name the offending path (for example jobs[1].depends_on[0] references unknown job "build") and no partial map is produced. The computation is pure and local: no network, no configuration, no files read beyond the input you pass in.

CLI

npx @reneturcios/parallelmap map --input args.json
npx @reneturcios/parallelmap --version

args.json contains the full arguments object:

{
  "jobs": [
    { "name": "compile", "duration_seconds": 30 },
    { "name": "unit", "duration_seconds": 45, "depends_on": ["compile"] },
    { "name": "lint", "duration_seconds": 10, "depends_on": ["compile"] },
    { "name": "package", "duration_seconds": 5, "depends_on": ["unit", "lint"] }
  ],
  "workers": 2
}

depends_on defaults to [] per job and workers is optional overall. The map is printed as JSON:

{
  "ok": true,
  "levels": [["compile"], ["lint", "unit"], ["package"]],
  "sequential_seconds": 90,
  "parallel_seconds": 80,
  "speedup": 1.125,
  "critical_path": ["compile", "unit", "package"],
  "cycle": [],
  "schedule": [
    { "job": "compile", "worker": 0, "start": 0, "finish": 30 },
    { "job": "unit", "worker": 0, "start": 30, "finish": 75 },
    { "job": "lint", "worker": 1, "start": 30, "finish": 40 },
    { "job": "package", "worker": 1, "start": 75, "finish": 80 }
  ],
  "makespan_seconds": 80
}

Exit codes: 0 on success, 1 on a runtime error (including an unreadable or invalid input file, or invalid input), 2 on a usage error.

MCP server

npx -y @reneturcios/parallelmap mcp

MCP client config:

{
  "mcpServers": {
    "parallelmap": {
      "command": "npx",
      "args": ["-y", "@reneturcios/parallelmap", "mcp"]
    }
  }
}

Tools

• map_parallelization — Map which jobs or tests can safely run in parallel.

  • jobs (array, required, at least one) — jobs as {name, duration_seconds, depends_on?} objects; name is unique across the set and each depends_on entry names another supplied job
  • workers (integer, optional, at least 1) — when given, a greedy schedule onto that many workers is included

  Returns {ok, levels, sequential_seconds, parallel_seconds, speedup, critical_path, cycle, schedule, makespan_seconds} — or, on a cycle, {ok: false, cycle, levels: [], sequential_seconds, parallel_seconds: null, speedup: null, critical_path: [], schedule: [], makespan_seconds: null}.

Docker

docker run -i ghcr.io/cloudcorprecords/parallelmap
docker run --rm -v "$PWD:/w" ghcr.io/cloudcorprecords/parallelmap map --input /w/args.json

Development

npm install
npm run build   # tsc -> dist/
npm test        # tsx --test test/*.test.ts (pure local, no network)
npm run dev     # run the CLI from source

License

MIT — Copyright (c) 2026 Rene Turcios