{"id":50472349,"url":"https://github.com/semcod/nexu","last_synced_at":"2026-06-01T11:03:13.767Z","repository":{"id":361231755,"uuid":"1253648464","full_name":"semcod/nexu","owner":"semcod","description":null,"archived":false,"fork":false,"pushed_at":"2026-05-29T18:48:31.000Z","size":1361,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-29T20:06:58.717Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semcod.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/roadmap.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-29T17:17:13.000Z","updated_at":"2026-05-29T18:48:34.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semcod/nexu","commit_stats":null,"previous_names":["semcod/vico"],"tags_count":7,"template":false,"template_full_name":null,"purl":"pkg:github/semcod/nexu","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnexu","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnexu/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnexu/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnexu/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semcod","download_url":"https://codeload.github.com/semcod/nexu/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semcod%2Fnexu/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33771630,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-01T11:03:11.162Z","updated_at":"2026-06-01T11:03:13.752Z","avatar_url":"https://github.com/semcod.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Nexu\n\nProjects\n![alt text](image.png)\n\nEvolution in scope: functions\n![alt text](image-1.png)\n\n## AI Cost Tracking\n\n![PyPI](https://img.shields.io/badge/pypi-costs-blue) ![Version](https://img.shields.io/badge/version-0.5.29-blue) ![Python](https://img.shields.io/badge/python-3.9+-blue) ![License](https://img.shields.io/badge/license-Apache--2.0-green)\n![AI Cost](https://img.shields.io/badge/AI%20Cost-$7.80-orange) ![Human Time](https://img.shields.io/badge/Human%20Time-15.0h-blue) ![Model](https://img.shields.io/badge/Model-openrouter%2Fqwen%2Fqwen3--coder--next-lightgrey)\n\n- 🤖 **LLM usage:** $7.8017 (36 commits)\n- 👤 **Human dev:** ~$1497 (15.0h @ $100/h, 30min dedup)\n\nGenerated on 2026-06-01 using [openrouter/qwen/qwen3-coder-next](https://openrouter.ai/qwen/qwen3-coder-next)\n\n---\n\n**Nexu** is a **Visual Intent Contract Orchestrator** for controlled code and UI evolution.\n\nIt helps you take a large project, freeze its current state, extract a small isolated slice called a\ncapsule, evolve that capsule through human or LLM-assisted iterations, verify the result against\nintent contracts, and only then promote the changes back into the source project.\n\n```text\ninit -\u003e freeze -\u003e capsule create -\u003e plan/blueprint -\u003e iterate -\u003e verify -\u003e review -\u003e promote\n```\n\nNexu is useful when a task is too risky or too broad for direct edits in the main workspace. Instead\nof asking an LLM to operate on the whole repository, Nexu gives it a smaller, versioned sandbox with\nexplicit files, contracts, evidence, reports and promotion checks.\n\n## Current State\n\nCurrent release: **0.5.17**.\n\nThe project currently provides:\n\n- a Typer-based CLI: `nexu init`, `nexu freeze`, `nexu capsule ...`, `nexu mcp ...`,\n- project snapshots with lightweight file-hash baselines,\n- isolated capsules under `.nexu/capsules/\u003cname\u003e/`,\n- deterministic capsule planning and iteration folders,\n- UI/API/test blueprints generated from capsule metadata and Intract contracts,\n- static runtime previews for capsules,\n- LLM-ready prompt export with hard capsule boundaries,\n- verification reports with contract, drift and evidence checks,\n- human/LLM review packets and portable review bundles,\n- dry-run and apply promotion modes,\n- MCP-compatible stdio tools for IDE/agent clients,\n- Cinema: an interactive browser workspace for visual UI evolution,\n- local quality profile using pytest, Markdown link checks, Intract, redup and ruff.\n\nNetwork LLM calls are disabled by default. They are only used when enabled in `nexu.yaml` and when\nthe required API key environment variable is present.\n\n## Installation\n\nFrom PyPI:\n\n```bash\npython -m venv .venv\n. .venv/bin/activate\npip install nexu\nnexu --help\n```\n\nFor local development:\n\n```bash\ngit clone https://github.com/semcod/nexu.git\ncd nexu\npython -m venv .venv\n. .venv/bin/activate\npip install -e .[dev]\npython -m nexu --help\n```\n\nNexu requires Python **3.10+**.\n\n## What Nexu Creates\n\nAfter `nexu init .`, a project gets:\n\n```text\nnexu.yaml      project configuration\nintract.yaml   project-level intent contracts\n.nexu/         local Nexu state\n```\n\nA capsule stores its own metadata, copied source slice, baseline hashes, contracts, plans, reports\nand generated artifacts:\n\n```text\n.nexu/capsules/\u003cname\u003e/\n  capsule.yaml\n  intract.yaml\n  src/\n  iterations/\n  baseline/\n  plan/\n  blueprints/\n  runtime/\n  evidence/\n  reviews/\n  reports/\n  bundles/\n  cinema/\n```\n\n## Quick Start\n\n```bash\nnexu init .\nnexu freeze . --name baseline\n\nnexu capsule create . \\\n  --name users-api \\\n  --domain backend \\\n  --include \"src/users/**\" \\\n  --endpoint \"POST:/api/users\"\n\nnexu capsule plan users-api --steps 5 --goal \"Improve create-user flow\" --print\nnexu capsule blueprint users-api --print\nnexu capsule iterate users-api --steps 3 --goal \"Improve create-user flow\"\nnexu capsule export-prompt users-api\nnexu capsule verify users-api\nnexu capsule review users-api\nnexu capsule report users-api\nnexu capsule promote users-api --dry-run\n```\n\nWhen the promotion plan is acceptable and verification is clean:\n\n```bash\nnexu capsule promote users-api --apply\n```\n\n## Main Commands\n\nProject setup:\n\n```bash\nnexu init .\nnexu freeze . --name baseline\n```\n\nCapsule lifecycle:\n\n```bash\nnexu capsule create . --name my-slice --include \"src/my_module/**\"\nnexu capsule list\nnexu capsule status my-slice\nnexu capsule plan my-slice --steps 10 --goal \"Evolve the selected workflow\"\nnexu capsule blueprint my-slice --print\nnexu capsule iterate my-slice --steps 3 --goal \"Evolve the selected workflow\"\nnexu capsule runtime my-slice\nnexu capsule export-prompt my-slice\nnexu capsule diff my-slice\nnexu capsule drift my-slice\nnexu capsule verify my-slice\nnexu capsule journal my-slice\nnexu capsule review my-slice\nnexu capsule bundle my-slice\nnexu capsule report my-slice\nnexu capsule promote my-slice --dry-run\nnexu capsule promote my-slice --apply\n```\n\nMCP integration:\n\n```bash\nnexu mcp tools\nnexu mcp serve --path .\n```\n\nUse `python -m nexu ...` instead of `nexu ...` when running directly from an editable checkout\nwithout installing the console script.\n\n## Typical Workflows\n\n### Human-controlled refactor\n\n1. Freeze the project with `nexu freeze`.\n2. Create a capsule containing only the files relevant to the change.\n3. Edit files inside `.nexu/capsules/\u003cname\u003e/src/`.\n4. Run `nexu capsule verify \u003cname\u003e`.\n5. Review `nexu capsule diff \u003cname\u003e` and `nexu capsule report \u003cname\u003e`.\n6. Promote with `--dry-run` first, then `--apply` after review.\n\n### LLM-assisted implementation\n\n1. Create a capsule and run `nexu capsule blueprint`.\n2. Export a constrained prompt with `nexu capsule export-prompt`.\n3. Give the prompt to an IDE agent or external LLM.\n4. Keep the agent working only inside the capsule.\n5. Verify, review and promote through Nexu.\n\n### IDE agent integration\n\nRun the MCP stdio server:\n\n```bash\nnexu mcp serve --path .\n```\n\nThe MCP service exposes conservative tools for capsule creation, status, planning, blueprinting,\niteration, prompt export, runtime generation, verification, review, reports and promotion planning.\n\n## Cinema: Visual UI Evolution\n\nCinema is Nexu's browser-based UI evolution mode. It generates a local player for a capsule with:\n\n- one active workspace frame,\n- three option frames for alternative UI proposals,\n- visual selection and keep/remove marking,\n- a policy ledger backed by Intract-style constraints,\n- restoreable UI history checkpoints,\n- local service publishing for selected stages,\n- Markpact export for portable handoff.\n\nRun the default calculator Cinema example:\n\n```bash\nmake cinema\n```\n\nOpen the URL printed by the command. Do not assume a fixed port.\n\n### Switching example projects in the player\n\nThe Cinema server runs inside one workspace capsule (for example `scientific_calc`), but the\nplayer can load any catalog project (calculator, dashboard, `backend_service`, analytics, …)\nwithout restarting the server:\n\n1. Open the **Projects** tab and pick a card, or use a deep link:\n   `http://127.0.0.1:\u003cport\u003e/cinema_player.html?project=backend_service`\n2. Activation resets the policy ledger for the previous example, seeds goal contracts from the\n   project subtitle, and rebuilds **distinct** Options A–C from that project's stages.\n   In the activation response, `goal_bootstrap.status` is `requires_llm` (goal contracts are ready,\n   option generation is deferred to the LLM iteration step).\n3. Mark elements on the **workspace** frame (drag or review mode), then iterate or promote.\n\n**Import your own project:** on the **Projects** tab use **Upload ZIP**, **Git URL**, or\n**HTTP website**. Each import is converted to a Markpact migration README locally, seeded\ninto stage0–2, and appears in the project catalog. **HTTP imports** show the fetched page\nin stage0 (with a `\u003cbase href\u003e` to the live site and optional local CSS); stage1–2 remain\nthe Markpact migration workspace. Re-select the project in the catalog to refresh stage0\nfrom stored source without re-fetching. Refine in the Editor, then use\n**⬇ Markpact** or **🚀 Publish** to deploy. HTTP import requires\n`llm.allow_network_calls: true` in workspace `nexu.yaml`.\n\n**Scope routing:** visual scopes (`#colors`, `#shapes`, `#display`, `#orientation`, calculator\n`#keypad`) refresh Options A–C via the offline fast path or cache when possible. `#functions`\nalways uses the LLM — enable network calls and an API key in workspace `nexu.yaml` for that\nscope.\n\nThe Intract panel shows **Active example (Cinema UI)** separately from the frozen capsule\nbaseline (`calc.*` contracts stay tied to the workspace capsule).\n\nUseful commands:\n\n```bash\nmake cinema-open\nmake cinema-stop\nmake cinema-restart\nmake cinema-repair\nNEXU_CINEMA_NO_OPEN=1 make cinema\n```\n\nOverride the capsule, workspace path or model:\n\n```bash\nmake cinema \\\n  CINEMA_CAPSULE=scientific_calc \\\n  CINEMA_PATH=examples/web_app_calculator/workspace \\\n  CINEMA_GOAL=\"Convert the calculator into a scientific calculator\"\n\nmake cinema CINEMA_MODEL=openrouter/google/gemini-3.1-flash-lite-preview\n```\n\nTo allow real LLM calls, add an API key and enable network calls in the workspace config:\n\n```bash\nOPENROUTER_API_KEY=...\n```\n\n```yaml\nllm:\n  provider: openrouter\n  model: openrouter/deepseek/deepseek-v4-pro\n  base_url: https://openrouter.ai/api/v1\n  allow_network_calls: true\n  api_key_env: OPENROUTER_API_KEY\n```\n\n## Examples\n\nSmoke-tested examples:\n\n```bash\npython examples/run_examples.py\n```\n\nDirect UI examples:\n\n```bash\npython examples/web_app_calculator/run.py\npython examples/web_app_dashboard/run.py\n```\n\nAdditional examples:\n\n- [Frontend view](examples/frontend_view/README.md)\n- [Backend service](examples/backend_service/README.md)\n- [Vertical slice](examples/vertical_slice/README.md)\n- [Calculator UI evolution](examples/web_app_calculator/README.md)\n- [Dashboard UI evolution](examples/web_app_dashboard/README.md)\n- [Analytics dashboard evolution](examples/web_app_analytics/README.md)\n- [Pactown ecosystem integration](examples/web_app_pactown_ecosystem/run.py)\n- [Event monitor integration](examples/web_app_event_monitor/run.py)\n- [Realtime OpenRouter lane sync](examples/realtime_lane_nexu_sync.py)\n\nPactown examples require `uv`, `pactown` and free local ports:\n\n```bash\npython examples/web_app_pactown_ecosystem/run.py\npython examples/web_app_event_monitor/run.py\ndocker compose -f examples/web_app_event_monitor/docker/docker-compose.yml config --quiet\n```\n\n## Quality Checks\n\nFast project profile:\n\n```bash\nmake quality\n```\n\nIt runs:\n\n- `pytest -q`,\n- local Markdown link validation,\n- `intract check src`,\n- `intract coverage src`,\n- `redup scan src`,\n- the currently clean ruff subset.\n\nOther useful checks:\n\n```bash\nmake test\nmake examples\nmake docs-links\nmake quality-strict\nmake ci-cinema-smoke\n```\n\n`quality-strict` is intentionally broader and may be more useful as a backlog report than as a\nrelease gate.\n\n## Documentation\n\nStart here:\n\n- [Docs index](docs/README.md)\n- [Getting started](docs/getting-started.md)\n- [Commands](docs/commands.md)\n- [Architecture](docs/architecture.md)\n- [Capsule format](docs/capsule-format.md)\n- [Intent contracts](docs/intent-contracts.md)\n- [Verification model](docs/verification.md)\n- [Runtime and reports](docs/runtime-and-reports.md)\n- [LLM review and handoff](docs/llm-review.md)\n- [LLM orchestration](docs/llm-orchestration.md)\n- [MCP service](docs/mcp-service.md)\n- [Examples](docs/examples.md)\n- [Roadmap](docs/roadmap.md)\n\n## Important Project Paths\n\n```text\nsrc/nexu/                       Python package\nsrc/nexu/templates/cinema/      packaged Cinema templates\ndocs/                           documentation\nexamples/                       runnable examples\nscripts/check-doc-links.py      local Markdown link validator\ntests/                          unit tests\npyqual.yaml                     declarative quality profile\nMakefile                        local development commands\n```\n\nThe default `make quality` profile already uses `intract` and `redup`.\n\n## Repatch: Real-Time Live UI Evolution (MCP + WebSockets)\n\nNexu integrates with the **Repatch** package to enable an evolutionary approach to frontend development. Rather than traditional full-page generation and browser reloads, Repatch treats the running page as a **continuous live target** that is mutated in-place via a lightweight WebSocket/SSE streaming protocol.\n\n### Repatch SDK (`./sdk/js/`)\nA pure-JavaScript client-side SDK (`repatch-sdk.js`) connects to the local patch server and parses the surgical **Repatch DSL**:\n- `ADD \u003cselector\u003e \u003chtml_content\u003e`: Appends a child element dynamically.\n- `REPLACE \u003cselector\u003e \u003chtml_content\u003e`: Replaces the inner HTML of a targeted selector.\n- `STYLE \u003cselector\u003e { css_rules }`: Applies visual style updates to targets in real time.\n- `REMOVE \u003cselector\u003e`: Surgically deletes elements from the page.\n\n### Live Evolution Demo (`./examples/mcp_patch_demo/`)\nA premium glassmorphic live preview dashboard:\n- Mounts the local Repatch JS SDK.\n- Streams live UI mutations via a Node.js WebSocket server.\n- Displays an interactive virtual terminal log of received DSL patches.\n- To run, execute: `cd examples/mcp_patch_demo \u0026\u0026 npm install \u0026\u0026 npm start`.\n\n---\n\n## Dual-Mode Intract Support\n\nIntent verification via **Intract** now supports two powerful operation modes:\n1. **Inline Comments (Directly in Code):** Place `@intract.v1` rules directly preceding the classes, functions, or blocks they govern inside source files.\n2. **Standalone Manifest (`intract.toon.yaml`):** An external manifest allowing precise target coordinate addressing:\n   - **`target.file`**: Target file path.\n   - **`target.function`**: Target function name.\n   - **`target.line`**: Target code line number.\n   - **`target.xpath` / `xpatch`**: Target HTML/XML nodes via XPath.\n\nExample `intract.toon.yaml`:\n```yaml\ncontracts:\n  - id: forbid-destructive-updates\n    intent: ensure-no-write\n    forbid: [destructive_write, write]\n    target:\n      file: \"src/calculator.py\"\n      function: \"add_numbers\"\n      line: 45\n  - id: button-style-check\n    intent: validate-element-style\n    validate: [contrast_ratio]\n    target:\n      file: \"index.html\"\n      xpath: \"//button[@id='btn-eq']\"\n```\n\n## License\n\nLicensed under Apache-2.0.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fnexu","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemcod%2Fnexu","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemcod%2Fnexu/lists"}