NEXUS Core — durable multi-agent software tasks
CI License: MIT Python 3.10+ Release Stars
Build your dream with a durable, evidence-driven AI team.
NEXUS coordinates local and cloud agents to research, challenge, build, test, and review ambitious work inside one inspectable workspace.
Repository engineering · Deep research · NEXUS self-improvement · arXiv discovery · Mathematics · X research and social review · Business workflows
Quick start · Proof · Architecture · Deep dives · Safety
NEXUS is compact at its core and expansive in what it can coordinate. It is an inspectable orchestration engine for ambitious work that should survive crashes, continue across model sessions, and never be considered complete merely because an agent says it is.
Give NEXUS a goal and it assembles a coordinated team around it:
- Build, repair, and validate software repositories
- Search, retrieve, and analyze arXiv research
- Investigate mathematical and technical ideas
- Review public posts, discussions, and research signals from X
- Compare findings across local and cloud models
- Improve NEXUS through its own controlled research and implementation loop
- Support business, procurement, and decision-analysis workflows
Work moves through a structured pipeline:
plan → challenge → implement → test → review
Each step is checkpointed. Criteria, artifacts, test results, and reviewer judgments are recorded so work can be resumed, inspected, challenged, and independently verified.
NEXUS can run entirely with deterministic fixtures and mock agents for reproducible evaluation, or connect to separately installed local and cloud model clients. Model names, providers, hardware, and endpoints are configuration—not product requirements.
One workspace. Many models. A real path from idea to evidence.
The main demo reel (multi-LLM self-improve + capability factory). Full MP4 linked below.
NEXUS multi-LLM self-improve and skill factory demo
Demo video (MP4) · Share kit · Hype pack
Requirements: Python 3.10+, Git, Make, and a POSIX shell.
git clone https://github.com/VincentMarquez/nexus-core.git cd nexus-core make install source .venv/bin/activate make demo-all-quick nexus task list
The source checkout is currently the canonical installation. make install
creates .venv and installs NEXUS in editable mode. The quick demo does not need
API keys or Node.js.
Want the shortest proof instead?
make demo
That command simulates a crash after step 3, resumes the same task, and verifies that it reaches step 10 with the expected artifact. See Crash → resume for the checkpoints and event journal.
The runtime stack requires Node.js 18+. This source-checkout command detects installed model CLIs and Ollama, starts the local bus and dashboard, and fills unavailable agent slots with mock bridges:
./run --no-pull
--no-pull prevents an automatic Ollama model download. Add --no-open to keep
the command from opening a browser, or --no-cli to disable installed model
CLIs. Read Getting started and
Model platforms before enabling real providers.
After activating the virtual environment:
nexus do owner/repo --goal "run the checks and repair the failures"
This may clone the target and run its installers, build hooks, Make targets, and tests. That executes repository-controlled code; NEXUS is not a sandbox. Use a trusted commit or an isolated, credential-free environment. The repository-repair cookbook explains the full flow and its boundaries.
make demo-all-quick runs a local, reproducible product check:
| Check | Evidence |
|---|---|
| Unit suite | The current checkout passes its pytest suite |
| Crash recovery | A task is interrupted, loaded from disk, and completed |
| Rubric judging | An artifact-presence claim is rejected until criteria hold |
| Engine smoke cases | Complete, resume, autonomy-block, and human-gate paths run |
| Platform discovery | Available model clients are reported without requiring them |
| Resilience probe | Network diagnosis and heartbeat dry-run paths execute |
Quick mode skips the optional GitHub-auth check and scoreboard. It does not test live model quality, run the real self-improvement loop, or exercise the capability factory. Those require separate configuration and evidence.
Short crash → resume loop (from make demo):
More detail: Demo guide · Judge vs presence · Evidence format · Full product reel (MP4)
| Common failure | NEXUS response |
|---|---|
| A long agent run dies with its process | Atomic checkpoints plus an append-only event journal support resume |
| "The model said it passed" becomes the acceptance test | A separate judge scores declared criteria and artifact evidence |
| One model reinforces its own blind spots | Planner, adversary, implementer, tester, reviewer, and meta-review roles can use different backends |
| Agents repeatedly reopen the same context | Bounded context packs, handoffs, and optional namespaced memory |
| Automation runs without an operator trail | Replay, provenance, integrity, cost, graph, and evidence exports |
NEXUS is intentionally closer to a durable job runner than a model chat room. It provides orchestration primitives; it does not guarantee model correctness, safe execution of untrusted code, or distributed fault tolerance.
NEXUS architecture: task engine, agents, judge, memory, and evidence
The default policy has ten stages:
goal → plan → challenge → implement → test
→ review → log → meta-review → approval → deliver
| Component | Responsibility |
|---|---|
| Step policy | Declares stages, dependencies, capabilities, and approval points |
| Agent resolver | Maps roles to healthy configured backends with fallbacks |
| Runner | Executes the business logic for one stage |
| Judge | Scores success criteria against structured output and artifacts |
| Checkpointer | Writes task state atomically after each accepted stage |
| Event journal | Records steps, decisions, handoffs, failures, and resumes |
| Operator surface | Replays and exports the resulting evidence |
The local engine provides filesystem-backed recovery on one host. It is not a distributed scheduler, an exactly-once execution system, or a tamper-evident ledger. See Architecture and the 10-step pipeline for the contracts and extension points.
Planner, adversary, implementer, tester, reviewer, meta-reviewer, and judge roles can be mapped independently to installed cloud CLIs, an Ollama model, deterministic fixtures, mocks, or a mixture. A human approval stage can accept, reject, or return feedback without discarding the checkpointed task.
Exact provider and model identifiers in historical evidence describe those recorded environments only. Configure identifiers supported by your installed client or provider. See Platforms, Local LLM tool calling, and Connectors and MCP.
After make demo or another durable task, use the task ID shown by
nexus task list:
nexus task list nexus task show <task_id> nexus task replay <task_id> nexus task explain <task_id> nexus task verify <task_id> nexus task evidence <task_id> --out evidence.json
These commands inspect recorded state; they do not rerun agents. The task-operator cookbook covers additional events, cost, provenance, call-graph, DAG, consensus, and context views.
The README is the front door. Use these guides for setup, command details, design rationale, and evidence:
The GitHub community loop, Alive, capability generation, application, activation, commits, and pushes are advanced operations. Read their guides and inspect the effective configuration before enabling them.
NEXUS coordinates tools and executes project workflows; it is not a security sandbox. Read security and trust boundaries before running third-party code or enabling remote/write operations.
- Repository code can execute.
nexus doand GitHub proof/test workflows may run package installers, build hooks, Make targets, and tests from a checkout. A command-name allowlist blocks some obvious commands; it does not make untrusted code safe. Child processes inherit the environment and may reach CLI credential stores. Use trusted commits or an isolated, credential-free container or virtual machine. - Public-fork automation requires isolation. Never execute untrusted pull request code in a job that has write-capable credentials. Separate untrusted, read-only testing from any trusted job that posts or publishes results.
- Runtime state may be sensitive.
.nexus_state/is gitignored, not encrypted. It may contain prompts, outputs, source excerpts, local paths, stdout/stderr, task history, and operator feedback. Inspect it before sharing and never use it as a secret store. - The HTTP tools demo API has no built-in application authentication. It is not the full remote MCP transport described in the connector patterns. Keep it bound to localhost and do not expose it directly to the public internet.
- Path checks are not a complete capability sandbox. Direct file tools
reject paths outside
NEXUS_PROJECT_ROOT, but the wider MCP surface can include write and operational tools. Catalog privilege labels describe tools; they are not call-time authorization. - Publishing acts on the configured repository. Advanced self-improvement paths can modify files, commit, and push when enabled. Use a clean dedicated branch, protect the default branch, review the diff, and keep unrelated changes out of the worktree.
- Offline demos are not live-model evaluations. They prove orchestration, recovery, gates, and evidence handling—not the quality, reliability, or safety of a real model or provider.
Provider credentials belong in the provider's own authenticated CLI or environment. Do not commit API keys, OAuth tokens, cookies, tunnel URLs, or machine-local configuration.
- The source checkout is the supported installation path today. The PyPI distribution is not yet the canonical runtime install.
- The local runtime is single-host and filesystem-backed.
- Real providers, Ollama, GitHub authentication, remote MCP access, and self-publishing are optional integrations with separate setup.
- Missing model clients can be represented by mock bridges; a green offline demo does not imply that a live provider was exercised.
- Historical metrics and exact model names are evidence from a recorded run, not guarantees about the current branch. See the latest recorded snapshot.
See Comparison for fit and tradeoffs and Roadmap for planned work.
Issues and pull requests are welcome. Before submitting a change:
make release-check
That target installs the development environment, runs the unit and smoke suites, validates quality fixtures, and builds the documentation in strict mode. Read CONTRIBUTING.md and the Code of Conduct first.
Security-sensitive findings should follow SECURITY.md, not a public issue.
@software{nexus_core, author = {Vincent Marquez}, title = {NEXUS Core: Durable, evidence-gated multi-agent execution}, url = {https://github.com/VincentMarquez/nexus-core} }