virusimmortal00/nelos

What is Nelos?

Nelos is a plugin for Codex that combines a task-management skill, an MCP orchestration server, and a dedicated official Codex app-server child process for native task control.

A little Nelos vocabulary:

From a normal task to a Nelos web

1. Start exactly as you always have. Open a normal Codex task and describe the work.
2. A dedicated planner decomposes it. When a web would help, Nelos launches one fresh, bounded, read-only Sol / medium planning subagent. That route is fixed and verified regardless of the model or reasoning level selected in the original task, so planning never silently inherits a cheaper starting configuration. A task started on Luna or Terra still gets Sol for decomposition.
3. Your original task becomes the queen. It stays right where it is as the coordinator. When the plan uses durable spinoffs, its title receives the 👑 marker and a permanent web ID; each spinoff receives 🕷️ and a monotonic child suffix under that ID.
4. The orchestrator chooses the workers—not just their prompts. A plan may use only joined Codex subagents for bounded work, durable spinoff tasks for work that should remain independently visible and steerable, or a mix of both. Subagents report directly within the queen task; spinoffs live in the sidebar and report home through Nelos.

The efficiency play: Nelos spends consistent high intelligence once on the plan, then routes every execution slice independently. Straightforward work can use faster, cheaper models at lower reasoning levels; difficult work still gets more — reducing time and credit use without weakening the decomposition.

Example: mixed intelligence, on purpose

Suppose Add Codex functionality checker starts on Terra / max. The fixed Sol / medium planner returns an execution plan with one joined subagent and four durable spinoffs. Nelos does not copy one setting to every worker:

One objective now uses seven different model/reasoning combinations. Nelos puts deeper intelligence where judgment matters, uses faster profiles for bounded or repeatable work, and verifies every launched route before accepting its result.

Together, those three layers turn work into a web of parallel, dependency-aware Codex tasks, with capabilities you don't get from Codex alone, its native subagents, or hand-run parallel chats:

• Smart Model + Reasoning Router: The right model and effort for every slice — verified after launch. Nelos routes each slice to a fit-sized model and reasoning level, then confirms the task actually ran with that exact route and stops the moment it does not match. No silent downgrades, no burning max-effort reasoning on trivial work. How routing works →
• Dependency-Aware Work Scheduler: Parallel work that understands prerequisites. Slices launch in ordered waves — a later one starts only after the upstream work it needs has been accepted, not fire-and-hope.
• Durable Task Orchestrator: Workers you can still see, steer, and hear back from. Spinoffs remain ordinary Codex tasks in the desktop sidebar, and completed work reports back to the queen even when it is idle.
• Native Codex App-Server Bridge: Native tasks, not a separate task universe. The MCP server lazily starts one official codex app-server --stdio child, uses a narrow version-checked control surface, and exposes no prompts or transcripts.
• Visible Execution Map: MCP Apps-compatible hosts render an inline receipt after planning, dispatch, and spin-off cleanup, showing every task's lifecycle, exact model, reasoning level, authorization, launch, and archive status in independently collapsible status rollups. Expanded groups use compact worker rows, retain their disclosure state across compatible updates, and offer a compact active-status bulk toggle; aggregate counts remain in the structured receipt for non-UI clients without duplicating the visible roster, and protocol tools publish their exact model-visible result schemas.

Nelos in action

Dependencies wait for accepted work

Nelos can run independent slices in parallel, but it does not release downstream work merely because an upstream task stopped. The result must pass the queen's acceptance gate first, and the orchestration state survives restarts.

Why "Nelos"?

Nelos comes from Anelosimus, a genus of cosmopolitan cobweb spiders — many of them social, cooperating on one shared web. That behavior inspired Nelos's name and vocabulary.

Quick start

Codex only · macOS / Linux · Node.js 20+ · Windows not yet supported.

Install the plugin:

codex plugin marketplace add virusimmortal00/nelos --ref marketplace/stable
codex plugin add nelos@nelos-marketplace

marketplace/stable advances only to a published, validated stable release. To upgrade later, refresh that marketplace snapshot and reinstall the plugin:

codex plugin marketplace upgrade nelos-marketplace
codex plugin add nelos@nelos-marketplace

Enable its bundled tools — Codex keeps plugin MCP servers off until you opt in — by adding this to ~/.codex/config.toml:

[plugins."nelos@nelos-marketplace".mcp_servers."nelos"]
enabled = true

Then restart Codex, open a fresh task, and ask:

Use Nelos to plan this feature into safe parallel slices.

No installer, no manual copying, no PATH changes. Exact release tags remain available for reproducible installs and rollback; see Installation and distribution trust.

Configuration

Configure Nelos directly in conversation:

Show my Nelos settings.
Set Nelos spin-off cleanup to ask.
Reset my Nelos spin-off cleanup preference.

The installed plugin handles those requests through its bundled MCP tools; the separate contributor CLI is not required. Settings are stored in $XDG_CONFIG_HOME/nelos/config.toml, or ~/.config/nelos/config.toml when XDG_CONFIG_HOME is unset. NELOS_CONFIG can select an explicit absolute file. Repository-local .nelos/ settings are intentionally ignored.

Spin-off cleanup defaults to auto; users can choose ask or keep. Valid manual TOML edits are observed without restarting the plugin. Existing remembered preferences migrate once into TOML; reset returns to the built-in default. A cleanup already underway keeps its per-web policy snapshot. See Configuration for the schema and safety behavior.

Codex compatibility

Nelos is tested against Codex CLI 0.144.5 and Codex Desktop 0.144.6. Codex 0.145.x and later versions are allowed but have not yet been verified against Nelos's full app-server test matrix. The nelos_app_server_health tool reports the observed version, the tested versions, and whether the current version has been tested.

Nelos requires Codex 0.144.5 or newer. It does not block a newer semantic release merely because that release has not been tested yet; instead, the bridge continues to validate every app-server response and reports a focused compatibility error if an operation's actual contract has changed. Prerelease and build identities are reported as untested and remain subject to the same strict per-response validation.

Pull requests use one required, token-free deterministic compatibility gate. Run the identical command locally:

npm run compatibility:required

It compares the current HEAD with the merge base of COMPATIBILITY_BASE_REF, GITHUB_BASE_REF, or origin/main (in that order), removes OPENAI_API_KEY, and blocks network access for the gate and every child test process. Scheduled drift, exact-release evidence, live runtime smokes, and semantic advice run in separate workflows and cannot replace this required status.

What's in the box

Nelos is one Codex plugin with two cooperating parts:

• An MCP orchestration server — plans dependency-safe waves, routes and verifies every launch, persists replay-safe receipts, advances accepted work, coordinates completion and per-web cleanup, composes bounded web inspection, and exposes conversational machine-local configuration.
• A task-management skill — manage-nelos-tasks, the playbook that follows the MCP server's machine-generated next actions independently of whichever model starts as queen.

Spinoffs remain ordinary top-level Codex tasks—visible and steerable in the desktop sidebar while Nelos coordinates. Nelos plans and coordinates; you still own Git branches, merges, and final review.

Learn more

• Configuration — conversational settings, TOML schema, and precedence
• Experimentation framework — contracts, isolation, measurement, and reproducibility for validating Nelos, Codex, plugin versions, code changes, and efficiency claims
• Experimentation contract API — import nelos/experimentation-contract or nelos/experimentation-contract/index.mjs; both expose the same 94 symbols
• Experiment evaluation · Runtime isolation · Runner and operations · Implementation roadmap
• Model & reasoning routing — how each slice is sized and verified
• Isolated-queen routing evaluation — fresh-task scenario prompts and exact-route grading
• Native task orchestration — durable create, title sync, crash-resume
• App Server compatibility contract — minimum and tested-version policy, fallbacks, and hardening gates
• Webs and terminology — the queen / spinoff / web model
• Slice planning — a full worked example
• Worktree coordination — one writer per branch
• Codex capability leverage audit — the ordered, evidence-backed review of native Codex features Nelos should adopt, pilot, defer, or reject
• Installation and trust · Development
• Release and compatibility policy · Changelog

Contributing

The nelos CLI is a separate surface for contributors and automation. From source (Node.js 20+):

npm install
npm run install:distribution
nelos --help

Please read SECURITY.md before reporting a vulnerability.

Upgrading from Fraktik

Nelos was previously published as Fraktik (through 0.2.1). The rename changes the install identity, so remove the old plugin and delete any [plugins."fraktik@fraktik"...] blocks from ~/.codex/config.toml, then follow the Quick start:

codex plugin remove fraktik@fraktik
codex plugin marketplace remove fraktik

Installing from another marketplace

Nelos doesn't have to come from its bundled one-plugin marketplace. Add it to any marketplace's plugins array, then install with nelos@<marketplace-name>:

{
  "name": "nelos",
  "source": { "source": "url", "url": "https://github.com/virusimmortal00/nelos.git", "ref": "v0.4.0" },
  "policy": { "installation": "AVAILABLE", "authentication": "ON_INSTALL" },
  "category": "Developer Tools"
}

Independent open-source project — integrates with Codex, not affiliated with OpenAI. MIT © Nelos contributors.