Nexu

Projects

Evolution in scope: functions

AI Cost Tracking

• 🤖 LLM usage: $4.0098 (26 commits)
• 👤 Human dev: ~$1110 (11.1h @ $100/h, 30min dedup)

Generated on 2026-05-31 using openrouter/qwen/qwen3-coder-next

---

Nexu is a Visual Intent Contract Orchestrator for controlled code and UI evolution.

It helps you take a large project, freeze its current state, extract a small isolated slice called a capsule, evolve that capsule through human or LLM-assisted iterations, verify the result against intent contracts, and only then promote the changes back into the source project.

init -> freeze -> capsule create -> plan/blueprint -> iterate -> verify -> review -> promote

Nexu is useful when a task is too risky or too broad for direct edits in the main workspace. Instead of asking an LLM to operate on the whole repository, Nexu gives it a smaller, versioned sandbox with explicit files, contracts, evidence, reports and promotion checks.

Current State

Current release: 0.5.17.

The project currently provides:

• a Typer-based CLI: nexu init, nexu freeze, nexu capsule ..., nexu mcp ...,
• project snapshots with lightweight file-hash baselines,
• isolated capsules under .nexu/capsules/<name>/,
• deterministic capsule planning and iteration folders,
• UI/API/test blueprints generated from capsule metadata and Intract contracts,
• static runtime previews for capsules,
• LLM-ready prompt export with hard capsule boundaries,
• verification reports with contract, drift and evidence checks,
• human/LLM review packets and portable review bundles,
• dry-run and apply promotion modes,
• MCP-compatible stdio tools for IDE/agent clients,
• Cinema: an interactive browser workspace for visual UI evolution,
• local quality profile using pytest, Markdown link checks, Intract, redup and ruff.

Network LLM calls are disabled by default. They are only used when enabled in nexu.yaml and when the required API key environment variable is present.

Installation

From PyPI:

python -m venv .venv
. .venv/bin/activate
pip install nexu
nexu --help

For local development:

git clone https://github.com/semcod/nexu.git
cd nexu
python -m venv .venv
. .venv/bin/activate
pip install -e .[dev]
python -m nexu --help

Nexu requires Python 3.10+.

What Nexu Creates

After nexu init ., a project gets:

nexu.yaml      project configuration
intract.yaml   project-level intent contracts
.nexu/         local Nexu state

A capsule stores its own metadata, copied source slice, baseline hashes, contracts, plans, reports and generated artifacts:

.nexu/capsules/<name>/
  capsule.yaml
  intract.yaml
  src/
  iterations/
  baseline/
  plan/
  blueprints/
  runtime/
  evidence/
  reviews/
  reports/
  bundles/
  cinema/

Quick Start

nexu init .
nexu freeze . --name baseline

nexu capsule create . \
  --name users-api \
  --domain backend \
  --include "src/users/**" \
  --endpoint "POST:/api/users"

nexu capsule plan users-api --steps 5 --goal "Improve create-user flow" --print
nexu capsule blueprint users-api --print
nexu capsule iterate users-api --steps 3 --goal "Improve create-user flow"
nexu capsule export-prompt users-api
nexu capsule verify users-api
nexu capsule review users-api
nexu capsule report users-api
nexu capsule promote users-api --dry-run

When the promotion plan is acceptable and verification is clean:

nexu capsule promote users-api --apply

Main Commands

Project setup:

nexu init .
nexu freeze . --name baseline

Capsule lifecycle:

nexu capsule create . --name my-slice --include "src/my_module/**"
nexu capsule list
nexu capsule status my-slice
nexu capsule plan my-slice --steps 10 --goal "Evolve the selected workflow"
nexu capsule blueprint my-slice --print
nexu capsule iterate my-slice --steps 3 --goal "Evolve the selected workflow"
nexu capsule runtime my-slice
nexu capsule export-prompt my-slice
nexu capsule diff my-slice
nexu capsule drift my-slice
nexu capsule verify my-slice
nexu capsule journal my-slice
nexu capsule review my-slice
nexu capsule bundle my-slice
nexu capsule report my-slice
nexu capsule promote my-slice --dry-run
nexu capsule promote my-slice --apply

MCP integration:

nexu mcp tools
nexu mcp serve --path .

Use python -m nexu ... instead of nexu ... when running directly from an editable checkout without installing the console script.

Typical Workflows

Human-controlled refactor

1. Freeze the project with nexu freeze.
2. Create a capsule containing only the files relevant to the change.
3. Edit files inside .nexu/capsules/<name>/src/.
4. Run nexu capsule verify <name>.
5. Review nexu capsule diff <name> and nexu capsule report <name>.
6. Promote with --dry-run first, then --apply after review.

LLM-assisted implementation

1. Create a capsule and run nexu capsule blueprint.
2. Export a constrained prompt with nexu capsule export-prompt.
3. Give the prompt to an IDE agent or external LLM.
4. Keep the agent working only inside the capsule.
5. Verify, review and promote through Nexu.

IDE agent integration

Run the MCP stdio server:

nexu mcp serve --path .

The MCP service exposes conservative tools for capsule creation, status, planning, blueprinting, iteration, prompt export, runtime generation, verification, review, reports and promotion planning.

Cinema: Visual UI Evolution

Cinema is Nexu's browser-based UI evolution mode. It generates a local player for a capsule with:

• one active workspace frame,
• three option frames for alternative UI proposals,
• visual selection and keep/remove marking,
• a policy ledger backed by Intract-style constraints,
• restoreable UI history checkpoints,
• local service publishing for selected stages,
• Markpact export for portable handoff.

Run the default calculator Cinema example:

make cinema

Open the URL printed by the command. Do not assume a fixed port.

Switching example projects in the player

The Cinema server runs inside one workspace capsule (for example scientific_calc), but the player can load any catalog project (calculator, dashboard, backend_service, analytics, …) without restarting the server:

1. Open the Projects tab and pick a card, or use a deep link: http://127.0.0.1:<port>/cinema_player.html?project=backend_service
2. Activation resets the policy ledger for the previous example, seeds goal contracts from the project subtitle, and rebuilds distinct Options A–C from that project's stages.
3. Mark elements on the workspace frame (drag or review mode), then iterate or promote.

The Intract panel shows Active example (Cinema UI) separately from the frozen capsule baseline (calc.* contracts stay tied to the workspace capsule).

Useful commands:

make cinema-open
make cinema-stop
make cinema-restart
make cinema-repair
NEXU_CINEMA_NO_OPEN=1 make cinema

Override the capsule, workspace path or model:

make cinema \
  CINEMA_CAPSULE=scientific_calc \
  CINEMA_PATH=examples/web_app_calculator/workspace \
  CINEMA_GOAL="Convert the calculator into a scientific calculator"

make cinema CINEMA_MODEL=openrouter/google/gemini-3.1-flash-lite-preview

To allow real LLM calls, add an API key and enable network calls in the workspace config:

OPENROUTER_API_KEY=...

llm:
  provider: openrouter
  model: openrouter/deepseek/deepseek-v4-pro
  base_url: https://openrouter.ai/api/v1
  allow_network_calls: true
  api_key_env: OPENROUTER_API_KEY

Examples

Smoke-tested examples:

python examples/run_examples.py

Direct UI examples:

python examples/web_app_calculator/run.py
python examples/web_app_dashboard/run.py

Additional examples:

• Frontend view
• Backend service
• Vertical slice
• Calculator UI evolution
• Dashboard UI evolution
• Analytics dashboard evolution
• Pactown ecosystem integration
• Event monitor integration
• Realtime OpenRouter lane sync

Pactown examples require uv, pactown and free local ports:

python examples/web_app_pactown_ecosystem/run.py
python examples/web_app_event_monitor/run.py
docker compose -f examples/web_app_event_monitor/docker/docker-compose.yml config --quiet

Quality Checks

Fast project profile:

make quality

It runs:

• pytest -q,
• local Markdown link validation,
• intract check src,
• intract coverage src,
• redup scan src,
• the currently clean ruff subset.

Other useful checks:

make test
make examples
make docs-links
make quality-strict
make ci-cinema-smoke

quality-strict is intentionally broader and may be more useful as a backlog report than as a release gate.

Documentation

Start here:

• Docs index
• Getting started
• Commands
• Architecture
• Capsule format
• Intent contracts
• Verification model
• Runtime and reports
• LLM review and handoff
• LLM orchestration
• MCP service
• Examples
• Roadmap

Important Project Paths

src/nexu/                       Python package
src/nexu/templates/cinema/      packaged Cinema templates
docs/                           documentation
examples/                       runnable examples
scripts/check-doc-links.py      local Markdown link validator
tests/                          unit tests
pyqual.yaml                     declarative quality profile
Makefile                        local development commands

Related Local Tools

Nexu can benefit from sibling Semcod tools when they are installed locally:

• intract for intent contracts and contract coverage,
• redup for duplicate-code scanning,
• regix for regression-oriented quality tracking,
• pyqual for declarative quality pipelines,
• vallm, llx, docval and testless for deeper validation and automation workflows.

The default make quality profile already uses intract and redup.

License

Licensed under Apache-2.0.