AtomLane

Parallelize only what is proven safe.

Universal safety core. Platform-native execution. Workload-tailored acceleration.

AtomLane is a cross-platform parallelism compiler and runtime for coding agents. Its shared typed core proves dependencies and preserves task semantics; its adapters tailor discovery, containment, and resource budgets to each supported workload and execution realm. macOS is Stable. Native Windows is a scoped, fail-closed Preview.

中文说明 · Live report · Report first run · Share a benchmark

Open source under MPL-2.0—free for personal, research, educational, and commercial use. The current community release requires no AtomLane account or payment. Possible future alternative commercial licensing or separately licensed capabilities will not change the terms of code already released under MPL-2.0. Licensing details

Install in two commands

codex plugin marketplace add cloudguo123/atomlane
codex plugin add atomlane@atomlane

Open a new Codex task after installation or upgrade. Codex will list AtomLane's bundled task-assessment hook in Hooks and require a one-time review of its exact definition before it can run. Once trusted, every submitted task shows one of three advisory preflight results: direct path, inspect at the execution boundary, or likely parallel candidate. The hook reads only the submitted prompt; it does not scan the project, execute commands, block the prompt, or claim that parallelism is safe. The skill and atomic planner make that decision later from real entrypoints, effects, dependencies, platform, and resources. See the Hooks and live indicator guide.

You can then ask explicitly:

Use $accelerate-local-work to inspect this project and run the safe parts in parallel.
Keep progress visible and report time saved for this run and cumulatively.

For a long-running Python program, ask instead:

Use $optimize-python-parallelism to inspect scripts/job.py. Do not run or modify
the target while analyzing it; show proof obligations and a hash-bound preview.

Requirements: macOS Stable, or the scoped native Windows Preview, Codex with plugin and MCP support, and Python 3.10+ available as the python3 command on PATH (python3 --version must succeed). The current Python Install Manager includes this compatibility alias on Windows. Ruby is only needed for Compose YAML analysis on macOS; Node.js 20+ is only needed to rebuild the browser indicator. Windows release evidence currently comes from the windows-2025 CI image; it does not establish Windows 11 Desktop UI integration. See the Windows Preview guide before using Windows workflows. The pytest native-worker route additionally requires pytest and pytest-xdist in the selected runner environment; AtomLane never installs them automatically. Version 0.16 is release-gated on macos-14 and windows-2025, CPython 3.10–3.13, pytest 8.4.2, and pytest-xdist 3.8.0. Other dependency versions and host images are not claimed as release-verified by this version.

The installable package is Codex-native: .codex-plugin/plugin.json, .mcp.json, skills/, and hooks/hooks.json ship as one unit. The root mcp.json remains an optional vendor-neutral local-stdio configuration. This release intentionally does not include a root Agent Plugins manifest because current Codex releases classify that format separately and suppress bundled lifecycle hooks when it is present.

One core, tailored at three layers

“Universal” does not mean guessing that every task or platform is supported. It means every admitted task passes the same typed safety contract. “Tailored” means the route, containment, and concurrency budget change with the real platform and workload.

Layer	Universal contract	Tailored behavior
Safety	Typed Atom IR, immutable plan hash, effect/conflict checks, authorization boundaries, live progress, and savings accounting	Unsupported semantics fail closed instead of being translated approximately
Platform	One planner and scheduler across supported native realms	macOS uses POSIX process groups and Apple-silicon probes/backends; native Windows Preview uses NT path rules, Job Objects, UTF-8 pipes, optional ConPTY, and whole-file PowerShell atoms
Workload	The same proof gate for independence, ordering, outputs, and resources	Build/test tools keep semantic ownership; Docker uses daemon/VM budgets; research keeps timing fences; Python routing distinguishes CPU, blocking I/O, native kernels, existing pools, and unsafe effects

WSL, native Windows, macOS, and Docker are distinct execution realms. AtomLane recompiles for the active realm and never presents one host's proof or resource budget as portable evidence for another.

Capability	macOS Stable	Native Windows Preview
Shared core	Atom IR, hashes, effect/conflict checks, scheduler, live progress, savings ledger	The same core and proof rules
Automatic entrypoints	Supported shell, package, Make, Compose, test, and build frontends	Exact argv and declared whole-file .ps1; shell/package/Make/Compose/.cmd/.bat automatic lowering is not yet supported
Process boundary	POSIX session/process group	Staged kill-on-close Job Object for the supervisor and normally inherited target tree
Terminal/output	Bounded pipes and live runner	Separate UTF-8 pipes or output-only ConPTY; ConPTY stdin is rejected
Published evidence	macOS 14 CI and retained five-minute benchmark	Windows Server 2025 CI and separate five-minute benchmark; not Windows 11 Desktop UI proof

Why this exists

Most “parallel” wrappers split command text and hope for the best. That can reorder &&/||, race .next, JUnit, database, Docker volume, or Git state, multiply nested worker pools, and hide failures until the end.

AtomLane first compiles the requested work into a typed Atom IR. Only atoms proven independent are admitted concurrently. Unknown effects, ambiguous writers, stale source snapshots, unsupported lifecycle events, and changed plans fail closed.

shell · package scripts · Make · Compose · tests · builds · declared work
                              │
                              ▼
             static frontends → typed Atom IR
                              │
                              ▼
        conflict checks → resource-aware event scheduler
                              │
                              ▼
              exact verified execution + live savings

What it accelerates

Project situation	Optimization target	Platform route	Safety boundary
Web / TypeScript	Quality gates, package graphs, browser matrices	macOS automatic frontends; Windows explicit argv/PowerShell atoms	Preserves success gates; isolates .next, coverage, JUnit, and caches
Docker / Compose	Multi-image builds, health DAGs, test matrices	macOS Compose frontend; Windows Preview exposes Linux-daemon resource advice but not native Compose lowering	Honors VM CPU/memory envelope, ports, volumes, readiness, and migrations
Research / papers	Data preparation, validation, figures, document builds	macOS frontends; Windows explicit stage atoms	Infers data edges and preserves formal timing/provenance fences
Native builds / tests	Make, compiler drivers, test runners	Platform-supported frontends or exact native argv	Delegates to semantic owners and budgets nested workers
Batch media / data / ML	Independent inputs and deterministic merges	Exact isolated argv on both native realms; Apple-only backends stay advisory off macOS	Requires disjoint outputs, bounded resources, and explicit merge semantics
Long-running Python	Ordered CPU maps, blocking reads, native kernels, subprocess batches	Static advisor supports both; CPU previews use explicit portable spawn	Never imports or executes targets; unknown effects, shared state, stale hashes, and unsafe spawn paths fail closed

The scenario catalog includes more than 50 presets covering software, research, containers, media, ML, release, database, and low-level CPU/GPU/I/O work.

Native pytest worker pool

For a suite with, for example, 100 independent pytest cases, AtomLane keeps collection, fixtures, case scheduling, and worker lifecycle inside one pytest-xdist native worker pool. It does not explode the suite into 100 unrelated subprocesses. test_suite_plan is a convenience frontend for this route and returns the same immutable compiled_plan and plan_hash consumed by atomic_exec.

AtomLane owns the outer safety contract: exact runner argv, declared effects, configuration and source snapshots, per-run temporary paths and hash-bound report paths, one CPU and memory budget across outer work and inner workers, timeout containment, live progress, and final test/savings reporting. The selected xdist distribution remains part of the hashed plan. worksteal is the default for independent case-level sharding; opt into loadfile, loadscope, or loadgroup when fixture or shared-resource affinity requires grouping.

The boundary is intentionally explicit:

• Planning never runs a hidden pytest --collect-only and never imports or executes project tests. The caller must completely declare test effects and set independence_declared=true before a multi-worker run is eligible.
• runner_argv must be an exact Python module invocation such as [python, -m, pytest] (or a version-qualified equivalent); direct pytest and py.test console scripts are rejected. AtomLane hash-binds and revalidates the selected interpreter, forces PYTHONPATH, PYTHONHOME, and PYTHONOPTIMIZE empty, and rejects project/config-pythonpath files that could shadow the trusted pytest or xdist modules. Clearing PYTHONOPTIMIZE prevents inherited -O semantics from silently removing ordinary assertions in test helpers. The selected Python environment remains caller-trusted and must already contain those packages.
• AtomLane resolves and snapshots the effective project-local pytest config, binds it with -c, and preserves valid config addopts and PYTEST_ADDOPTS while including their exact tokens in the selection fingerprint. When pytest 8.4 selects a plain pyproject.toml only as its root-directory fallback, AtomLane separately hash-binds that selection as fallback_pyproject and accepts it at runtime only while it remains free of pytest configuration. Conflicting worker/output controls, non-executing modes, and xdist/cache-provider plugin overrides fail closed. Positional selectors and config testpaths/pythonpath must already exist inside project_path, use a direct non-symlink spelling, and are revalidated before execution. Explicit snapshot_paths follow the same rule. AtomLane injects and hash-binds --confcutdir=project_path, so pytest cannot execute a parent-directory conftest.py outside the declared project boundary. When discovery is ambiguous, provide config_path; parsing pyproject.toml on Python 3.10 requires the tomli package to be importable. Pass unknown third-party pytest options that take a value as --option=value, so the value cannot be mistaken for a positional selector.
• AtomLane explicitly loads its xdist plugin and injects worker, distribution, temporary-directory, and JUnit options, so the pool still works when pytest plugin autoloading is disabled. It disables pytest's shared cache provider and rejects cache-dependent selection flags. The JUnit and base-temp paths must not overlap a snapshotted input, the selected config, the runner executable, or each other. An explicit JUnit path must also stay outside every selected collection directory, including collection roots owned by another suite in the same plan; leave it unset to use the unique system-temp default. An existing report must be a non-link, single-hardlink regular file, and its parent identity is rechecked while the output lease is held. Collection overlap uses a conservative case-folded, Unicode-normalized identity plus physical ancestor/file identities, so macOS firmlinks, mount aliases, and Windows aliases cannot bypass the boundary. AtomLane does not install pytest-xdist, which is required by both the single-worker baseline and multi-worker routes. On Windows, an explicit report path also rejects lossy Win32 aliases such as trailing spaces or dots, alternate data streams, device names, and extended device namespaces.
• JUnit and base-temp paths receive sorted, non-blocking cross-process leases from the final preflight through report parsing. Concurrent reuse fails fast instead of letting one run consume another run's evidence; recompile for new generated paths or provide a distinct explicit junit_path. Each output locks its normalized path, physical parent-plus-basename, and any existing target identity; those keys are rechecked while held. On Windows, the lease root is constructed from the profile directory bound to the current process token rather than mutable profile environment variables.
• worker_count=auto is capped by the host resource budget and any supplied case-count hint; the hint is not treated as proof of independence. A worker count is a bounded capacity decision, not CPU affinity. pytest-xdist and the operating system schedule worker processes; AtomLane does not pin a worker to a physical or performance core.
• native_workers_configured is configuration evidence, while outer_peak_concurrency is observed by AtomLane. It does not report configured workers as observed; native_workers_observed remains unavailable without compatible runtime instrumentation. Native-pool parallel efficiency likewise remains unavailable until inner worker activity can be observed.
• To obtain a measured comparison, first execute the same selection with worker_count=1, then pass the returned session-attested serial_baseline_evidence to the multi-worker run. Every suite must set baseline_source_closure_declared=true and use snapshot_paths to cover every semantically relevant selected test, source, helper, project-local plugin, and conftest; AtomLane separately binds the effective pytest config snapshot. AtomLane performs bounded static coverage checks for selectors, configured paths, and conftest files. A symbolic link or reparse point anywhere in the audited collection tree makes that run ineligible to issue a serial baseline, because its target can be retargeted without changing the lexical selection. Only the caller can declare closure over dynamic imports and dynamically loaded plugins. The attestation therefore records a caller-declared source closure; it does not prove complete semantic closure. A bare serial_baseline_seconds value is rejected for native pytest pools. Installed pytest/xdist distributions and plugins outside project_path are not content-attested; the caller must keep that trusted environment unchanged between the serial and parallel runs.
• The parallel run still needs a fresh, non-empty, passing, counter-consistent JUnit report whose testcase identities match the attested baseline. Without a compatible attestation, complete and runtime-plausible testcase timings from that fresh JUnit can provide an explicitly labeled per-run estimate. An estimate is recorded only in the separate estimated bucket and never enters the primary credited cumulative total. Without either form of evidence, per-run savings remain pending baseline.

Savings ledger v2 keeps provenance explicit. time_saved_seconds remains the best valid per-run comparison for compatible clients; measured_time_saved_seconds and estimated_time_saved_seconds identify its source. ledger_credit_eligible, ledger_credit_recorded, and credited_time_saved_seconds distinguish a valid measurement from a successful write. The primary cumulative_saved_seconds contains new measured credits plus any pre-v2 value retained as legacy_unclassified; estimates accumulate only in cumulative_estimated_saved_seconds. Invalid existing ledger files fail closed and are never silently overwritten.

Python parallel refactor advisor

$optimize-python-parallelism adds a program-level analysis lane before task execution. The python_parallel_advisor MCP tool parses bounded project-local UTF-8 source with Python's AST; it does not import the module, execute target code, install packages, or edit files.

The first supported rewrite shape is deliberately narrow: same-module, ordered worker(item) maps expressed as a list comprehension, returned list comprehension, or append loop. For each candidate AtomLane propagates effects through the local call graph, checks loop control and observable ordering, requires a portable __main__ import path and an explicit spawn context for CPU process pools, detects existing/native parallelism, budgets nested workers, and returns one of:

• reviewable_rewrite: pure CPU candidate with a syntax-checked unified diff;
• advisory_only: I/O or externally constrained work needing human design;
• prefer_native: vectorize or use a library's own GIL-releasing workers;
• already_parallel: coordinate existing pools instead of nesting another;
• blocked: keep serial until every reported hazard is resolved.

Every preview is bound to the exact source SHA-256 and is never applied automatically. A measured serial hotspot may produce a modeled projection, clearly labeled as not being a benchmark. Acceptance still requires serial vs parallel differential tests, deterministic fixtures under explicit spawn, exception/output checks, memory measurement, and a repeatable performance win. See the Python Candidate IR and proof gates.

Live execution—not a blank spinner

Long runs use the live runner and continuously show lifecycle counts, elapsed time, and any comparison that is already valid. Native pytest savings remain pending until its fresh JUnit or compatible baseline evidence exists:

elapsed 2m 15s · running 4 · ready 2 · completed 7 · failed 0
estimated saved so far 4m 31s

At completion AtomLane confirms the labeled per-run saving, cumulative credited saving, and separate cumulative estimate together with each atom's status, return code, timeout, skip reason, output truncation, and observed peak concurrency.

On Windows, the live surface shows scheduler lifecycle counts and savings; captured task stdout/stderr is returned with the completed result. Ordinary commands drain through separate byte pipes, while commands needing terminal-shaped output may opt into ConPTY and one combined VT stream. A waiting supervisor is added to the Job Object by PID before it receives the launch record and creates the target. This is staged supervision, not atomic target creation. Job CPU and memory budgets include the supervisor plus the normally inherited target tree. Work created through WSL, Docker, WMI, services, scheduled tasks, or another broker is explicitly outside that Job boundary.

Windows Preview contract

The Preview shares the same Atom IR, immutable plan hash, effect checks, scheduler, live progress, and savings ledger as macOS. The platform adapter adds Windows-native CPU/memory/power probes, NT path conflict rules, staged Job Object supervision, optional ConPTY, and a conservative pwsh file frontend.

• Native Windows, WSL, and Docker's Linux VM are distinct execution realms; plans cannot cross or be replayed between them.
• Exact argv tasks and declared .ps1 files are supported. PowerShell files remain one opaque atom and require complete declared effects.
• POSIX shell, package-script, Make, Compose, .cmd, and .bat lowering fail closed on native Windows in this Preview. Run POSIX workflows inside WSL, or declare exact native atoms instead of relying on shell-text translation.
• Job-wide CPU rate and memory controls cover the supervisor and normally inherited target tree; the memory limit is at least 128 MiB. In pipe mode, max_processes is the exact active-member ceiling for the entire Job and is at least 2; the verified supervisor consumes one slot while it is alive. ConPTY with max_processes fails before target code starts because console-host Job membership is not yet proven; CPU and memory limits remain available. None of these limits constrain brokered work. Windows process-pool advice never exceeds the platform's 61-worker wait limit.
• ConPTY is output-only in this Preview. Explicit ConPTY stdin fails before target creation because a verified terminal-input and EOF contract is not implemented; use pipes for bounded stdin and observable EOF.

The complete boundary and troubleshooting notes are in Windows Preview.

Retained macOS five-minute benchmark

The retained public macOS run executed four isolated low-load workloads through the real parallel executor. Every task ran for at least five minutes. Native Windows Preview evidence is reported separately on the live dashboard.

Evidence	Result
Parallel wall time	5m 10s
Serial equivalent	20m 40s
Time saved	15m 30s
Observed speedup	4.00×
Parallel efficiency	100.0%

The serial equivalent is the sum of the observed independent task runtimes; it is not a separately executed serial run. This demonstrates scheduler overhead and reporting behavior under controlled independent work, not a universal claim that every project will be 4× faster. See the visual report, raw evidence, and benchmark protocol.

Execution contract

The safety handshake is deliberately strict:

atomic_task_plan
  → complete immutable compiled_plan + plan_hash
  → atomic_exec with that exact object and hash

Plans are not translated back into hand-written waves or generic DAG calls. Typed control edges distinguish success, failure, order, data, stream, readiness, health, completion, and cleanup. Artifacts, non-file effects, capacity resources, lifecycle events, and source snapshots remain part of the execution contract.

Privacy and authorization

• Project and optional trace inspection are local and bounded.
• Python advice is static and non-executing; target modules are never imported and rewrite previews never modify files.
• Trace analysis returns aggregate routing signals—not prompts, reasoning, command bodies, or tool outputs.
• Parallelism changes timing, never permission. Planning does not authorize new commands, remote mutations, destructive cleanup, or retries.
• No run result is uploaded automatically. Sharing is explicit and reviewable.
• Timeouts terminate the contained POSIX process group or Windows Job Object; timed-out side effects are treated as unknown and are not automatically retried.

Read SECURITY.md for the threat model and reporting process.

Development

python3 -m compileall -q scripts
python3 -m unittest discover -s scripts -p 'test*.py' -v
python3 scripts/self_test.py
uvx ruff check scripts
npm ci && npm run build:indicator

Generate public verification and sharing assets:

python3 scripts/generate_test_report.py
python3 scripts/generate_growth_assets.py
python3 scripts/render_growth_media.py  # optional PNG/GIF, requires Chrome + ffmpeg

Useful references:

• Architecture and safety invariants
• Atom IR reference
• Windows Preview contract
• Benchmark and external-result protocol
• Brand and compatibility guide
• Contributing
• Release history

Help it grow

Try it on one real task, then share the sanitized result card or submit a benchmark. If the planner blocks work that should be safe, that report is just as valuable as a speedup—it identifies the next missing semantic rule.

Report your first run · Open a benchmark report · Ask a question · View the roadmap

MPL-2.0 · Licensing · Trademarks · Privacy · Terms