nexussy

nexussy is a local software-delivery harness for turning one project request into a built project or feature. It takes a plain-language idea, clarifies requirements, designs and validates an approach, creates a development plan, assigns work to AI workers, merges their code, and leaves behind reports, changed-file manifests, and handoff documents that another agent or human can continue from without needing the original chat history.

It is the fifth-generation Ussyverse coding harness lineage:

devussy -> swarmussy -> ralphussy -> geoffrussy -> nexussy

Quick Start

Prerequisites: Python 3.11+, Bun 1.x+, git, and curl.

git clone https://github.com/mojomast/nexussy.git
cd nexussy
./install.sh --non-interactive
./nexussy.sh cli

On first launch, the CLI checks whether a provider API key is configured. If not, it offers guided setup inside the launch flow:

No provider API key is configured yet. nexussy needs one for Ask mode and pipeline stages.
Run provider setup now? [Y/n]:

The setup flow lets you choose a provider, enter the API key with hidden input, choose a model, and then drops you into the TUI.

Useful explicit setup commands:

./nexussy.sh cli --setup              # choose provider, key, and model
./nexussy.sh cli --setup-openrouter   # OpenRouter shortcut
./nexussy.sh cli --set-key OPENAI_API_KEY
./nexussy.sh doctor                   # verify config, provider keys, ports, Pi worker

Use It

Use the same CLI for lightweight help or a full build pipeline.

Ask a normal question:

How should I structure a tiny FastAPI app with SQLite?

That stays in Ask mode and uses the configured provider through core /assistant/reply.

Describe something buildable:

Build a tiny FastAPI app with SQLite and pytest tests

nexussy will not silently start expensive work. It offers a confirmation path:

This looks buildable. Reply `Yes, run it` to start the full pipeline...

Then:

Yes, run it

Or start deliberately:

/new Build a tiny FastAPI app with SQLite and pytest tests

The full pipeline then runs interview, design, validate, plan, review, and develop, streams progress into the TUI/web UI, merges worker output, and writes artifacts.

What You Get

For a successful run, the primary deliverable is the updated project worktree:

~/nexussy-projects/<project_slug>/main/

The trace lives beside it:

~/nexussy-projects/<project_slug>/main/.nexussy/artifacts/

Key artifacts include design_draft.md, devplan.md, review_report.json, develop_report.json, merge_report.json, and changed_files.json.

What nexussy is good at:

Need	Use
Ask architecture or implementation questions	Plain text in ./nexussy.sh cli
Shape a vague idea before building	Ask mode, then confirm when ready
Build a full project or feature	/new <description> or Yes, run it
Watch/steer a running build	/status, /workers, /artifacts, /steer ...
Continue later without chat history	Anchored devplan.md, phase files, and handoff.md

What It Does

nexussy is not a chat app. It is a local control plane for staged software delivery.

The core workflow is:

1. Interview the project owner when requirements are incomplete.
2. Generate design and complexity artifacts.
3. Validate the design and retry corrections when needed.
4. Generate an anchored devplan.md, phase files, and handoff.md.
5. Review the plan and route feedback back to planning when needed.
6. Run role-based development workers in isolated git worktrees.
7. Merge worker output serially, extract changed files, and write reports.
8. Stream every important state transition over SSE to local UIs.

The intended result is the completed code in the project worktree. The artifacts are the trace: they explain what was asked, what was designed, what was planned, what was built, what changed, and how the run finished.

From Idea To Built Project

A user can start with only a simple idea:

Build a small web app where I can track books I want to read, mark them as finished, and see simple reading stats.

In the TUI, that becomes an explicit pipeline request:

/new Build a small web app where I can track books I want to read, mark them as finished, and see simple reading stats.

nexussy then walks the idea through the delivery pipeline:

1. Interview asks or synthesizes missing requirements.
2. Design describes the product behavior, UX, architecture, and constraints.
3. Validate checks the design and routes corrections back when needed.
4. Plan writes anchored implementation tasks and phase files.
5. Review checks the plan and can send feedback back to planning.
6. Develop assigns tasks to workers, runs tool calls in worker worktrees, merges output, and records changed files.

For a successful run, the main deliverable is the updated project directory. Supporting artifacts such as design_draft.md, devplan.md, develop_report.json, merge_report.json, and changed_files.json show how the result was produced.

The strongest local proof path is scripts/smoke_integration.sh: with core/web running, provider credentials configured, a git repo supplied through NEXUSSY_SMOKE_PROJECT_DIR, and a Pi-compatible worker command supplied through NEXUSSY_PI_COMMAND, it starts a real pipeline, waits for done final_status=passed, and verifies non-empty changed files plus passing develop and merge reports.

What this does not guarantee: nexussy cannot guarantee that every vague idea becomes production-quality software without human review. Output quality still depends on the configured model/provider, the worker executor, project constraints, available tests, and the clarity of the requirements. The system is designed to make that process observable, steerable, resumable, and auditable rather than opaque.

Main Capabilities

• Six-stage pipeline: interview -> design -> validate -> plan -> review -> develop.
• Provider-backed stages through LiteLLM-compatible models.
• Explicit mock/fake provider modes for deterministic local testing.
• Manual or auto-approved interview flow.
• Anchored devplan.md, phaseNNN.md, and handoff.md generation.
• Stage retry loops for validation and review feedback.
• SQLite WAL-backed run, event, artifact, worker, blocker, and memory state.
• SSE event stream with replay, heartbeat, slow-client handling, and typed payloads.
• Git worktree isolation for worker execution.
• Pi RPC subprocess adapter for live worker execution, with a bundled deterministic fallback for local tests.
• Pause, resume, skip, cancel, inject, blocker, and worker controls.
• Terminal UI for setup and day-to-day control.
• Web dashboard for observing and controlling health, runs, artifacts, workers, graph data, config, secrets, and SSE/chat activity.
• MCP-compatible tool surface for external agents.
• Root installer and launcher scripts with dry-run, doctor, logs, status, update, and optional systemd-user support.

Architecture

tui/ nexussy-tui
  TypeScript + Bun + OpenTUI default, Pi TUI opt-in control surface
  Uses only core HTTP and SSE APIs

core/ nexussy-core
  Python + Starlette + SQLite + LiteLLM + Pi subprocess adapter
  Owns pipeline state, artifacts, providers, workers, checkpoints, and SSE

web/ nexussy-web
  Python + Starlette single-page dashboard
  Proxies /api/* and SSE to core

Default local ports:

• Core: http://127.0.0.1:7771
• Web dashboard: http://127.0.0.1:7772
• TUI: terminal process only, no port

The TUI uses the OpenTUI renderer by default. Set NEXUSSY_TUI_RENDERER=pi-tui when launching nexussy-tui or ./nexussy.sh start-tui to use the Pi TUI compatibility renderer.

Repository Layout

core/      Python core API, pipeline, providers, artifacts, SQLite, swarm, MCP
tui/       TypeScript/Bun terminal UI and tests
web/       Starlette dashboard and proxy
install.sh User-space installer
nexussy.sh Runtime launcher and diagnostics
SPEC.md    Authoritative implementation contract

SPEC.md is the source of truth for contracts. SPEC_COVERAGE.md tracks implementation evidence and remaining gaps.

Install Details

Prerequisites:

• Python 3.11+
• Bun 1.x+
• git
• curl

Install in user space:

./install.sh --non-interactive

Preview dependency checks and intended actions without creating config, env, venv, PID, package, or service files:

./install.sh --non-interactive --dry-run

Generate optional systemd user units:

./install.sh --systemd-user

The installer creates these only when absent:

• ~/.nexussy/
• ~/.nexussy/run/
• ~/.nexussy/logs/
• ~/.nexussy/nexussy.yaml
• ~/.nexussy/.env
• ~/.nexussy/venv on PEP 668 distributions

Reruns preserve existing config, env, and generated systemd user unit files.

Start, Stop, And Diagnose

⚠️ Important: nexussy must run with --workers 1. The pipeline engine holds in-memory state (active run queues, interview waiters, pause flags) that is not replicated across processes. Multi-worker deployments will silently lose run state. Use the provided Dockerfile which enforces this constraint.

./nexussy.sh cli        # start services if needed and open the TUI
./nexussy.sh start      # start core and web
./nexussy.sh status     # show config path, ports, PID files, and health
./nexussy.sh stop       # stop TUI, web, and core from PID files
./nexussy.sh doctor     # check dependencies, config, ports, Pi, and provider keys
./nexussy.sh update     # git pull, reinstall core/web, run bun install for TUI

Start core/web, verify health, and print TUI instructions:

./launch_verify.sh

Logs:

./nexussy.sh logs core
./nexussy.sh logs web
./nexussy.sh logs tui
./nexussy.sh logs --no-follow core

TUI

Start the interactive terminal UI, automatically starting core/web if needed:

./nexussy.sh cli

tui and start-tui are compatibility aliases for the same launcher path:

./nexussy.sh tui
./nexussy.sh start-tui

The TUI is a control surface over the core API. It does not own provider secrets or pipeline state.

On first launch, if no provider key is configured, the CLI prompts to run provider setup before opening the TUI. Setup is still available explicitly:

./nexussy.sh cli --setup
./nexussy.sh cli --setup-openrouter
./nexussy.sh cli --set-key OPENAI_API_KEY

Inside the TUI:

• /secrets refreshes provider-key status.
• /setup prints the guided setup command if you skipped first-run setup.
• /delete-key NAME deletes a configured provider key.
• /new DESCRIPTION starts an explicit pipeline run.
• /pause, /resume, /cancel, /skip, /stage, /spawn, /inject, and /export control active runs.
• /memory, /graph, /config, and /events open data overlays backed by the core API.
• /steer, /steer @worker-id, /steer list, and /steer clear manage orchestrator/worker steering.

Ordinary chat-like text stays in Ask mode unless an explicit action command is used, so the same CLI can be used as a regular coding assistant for questions and tradeoffs or as the full build pipeline when you type /new DESCRIPTION.

Web UI

A built-in pipeline control surface is served at http://localhost:7771/ui when the core server is running. No build step required - plain HTML/CSS/JS, no npm, no CDN.

Features:

• Session browser with status badges
• New pipeline wizard (project name, description, optional model override)
• Live 6-stage pipeline stepper with real-time SSE updates
• Active workers table
• Blocker management (view + resolve)
• Interview question form rendered dynamically from SSE events
• Pause / Resume / Cancel pipeline controls
• API key support: run localStorage.setItem('NEXUSSY_API_KEY', 'your-key') in the browser console to authenticate requests

No external dependencies - works offline, no CDN, no npm.

The packaged web dashboard runs separately at http://localhost:7772 through ./nexussy.sh start or python3 -m nexussy_web.app. It proxies /api/* and SSE to core, applies request-size limits and upstream timeouts, streams proxied responses instead of buffering them, and adds browser security headers. The dashboard includes:

• Live chat/event stream with tool rows and cost badge.
• SVG graph visualization backed by /api/graph.
• Pipeline pause, resume, skip, cancel, and inject controls.
• Worker inject and stop controls.
• Config, secrets, artifacts, DevPlan, swarm, and file-lock panels.

Starting A Pipeline Run

Automated run with interview auto-approval:

curl -s http://127.0.0.1:7771/pipeline/start \
  -H 'Content-Type: application/json' \
  -d '{
    "project_name":"HabitTrack",
    "description":"A Python REST API for tracking habits",
    "auto_approve_interview":true
  }'

Manual interview flow:

1. Start a run with auto_approve_interview omitted or false.
2. Read the interview artifact from GET /pipeline/artifacts/interview?session_id=<session_id>.
3. Submit answers to POST /pipeline/<session_id>/interview/answer.

Example answer request:

curl -s http://127.0.0.1:7771/pipeline/<session_id>/interview/answer \
  -H 'Content-Type: application/json' \
  -d '{
    "answers": {
      "q_name":"HabitTrack",
      "q_lang":"Python",
      "q_desc":"A REST API for tracking habits",
      "q_type":"API"
    }
  }'

Manual interview waits time out according to stages.interview.answer_timeout_s; timeout cleanup clears paused state before the run is marked failed.

Provider Modes

Production provider execution uses configured provider keys. Standard providers run through the LiteLLM-compatible path; AgentRouter tokens use its Anthropic-compatible Claude Code-shaped /v1/messages?beta=true route so requests present like Claude Code rather than generic OpenAI-compatible traffic.

Supported key names include:

OPENAI_API_KEY, ANTHROPIC_API_KEY, AGENTROUTER_API_KEY, AGENT_ROUTER_TOKEN, OPENROUTER_API_KEY, GROQ_API_KEY, GEMINI_API_KEY, MISTRAL_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, XAI_API_KEY, GLM_API_KEY, ZAI_API_KEY, REQUESTY_API_KEY, AETHER_API_KEY, and OLLAMA_BASE_URL.

For AgentRouter, the fastest observed stage model is openai/deepseek-v4-flash. Use a stronger worker model such as openai/gpt-5.4 for bundled worker tool calls when reliability matters. A live end-to-end wordcount-tool proof used that split and produced wordcount.py, tests/test_wordcount.py, and README.md with passing pytest and CLI checks.

Local development modes:

• Request metadata {"mock_provider": true} enables explicit mock output for a run.
• NEXUSSY_PROVIDER_MODE=fake exercises the production path with deterministic fake provider output.
• Missing provider credentials fail explicitly with provider/model errors; core does not silently fall back to mock mode.

NEXUSSY_MOCK_PROVIDER=1 is for local development only. Do not use it in production.

Pi Worker Execution

The develop stage uses the Pi-compatible JSON-RPC subprocess adapter for workers. Fresh installs default to the bundled nexussy-pi shim (pi.command: "nexussy-pi", pi.args: []), so no separate npm install is required for local workstation operation.

nexussy-pi is a convenience worker for local development. It strips the child environment and applies local time/output caps, but it is not a security boundary for untrusted code. For a small trusted team on a LAN or private VPN, set NEXUSSY_PI_COMMAND or pi.command to an operator-managed sandboxed executor. That executor can wrap the installed Pi CLI, a container runner, a VM/jail, or another local policy layer that your team trusts.

Worker behavior:

• Workers spawn and run in parallel.
• Git merges happen serially to keep conflict handling deterministic.
• Worker JSON-RPC error responses fail the worker task and pipeline instead of being counted as successful output.
• Workers that produce no git changes fail develop instead of creating placeholder success files.
• With one worker and multiple devplan tasks, develop passes the whole task list to that worker; with multiple configured roles, each role still receives a worker assignment.
• Local worker tool calls execute through core with role permissions, path checks, write-lock enforcement, structured tool_output, and tool_progress events.
• The bundled AgentRouter worker adapter handles streamed tool arguments that arrive as incremental, cumulative, or concatenated fragments.
• Worker RPC resume is guarded at max depth 3.
• Worker output is streamed into SSE events.
• Changed files are extracted into artifacts after merge.

Using the real Pi CLI:

Step	Command
Install Pi	npm install -g @mariozechner/pi-coding-agent
Select Pi CLI	Add NEXUSSY_PI_COMMAND=pi to ~/.nexussy/.env, or set pi.command: "pi" in ~/.nexussy/nexussy.yaml
Runtime mode	Core launches the real CLI as pi --mode rpc and writes .pi/agent/settings.json in the worker worktree

Using a sandbox wrapper for trusted LAN/VPN use:

NEXUSSY_PI_COMMAND=/usr/local/bin/nexussy-worker-sandbox

The wrapper must speak the same newline-delimited JSON-RPC contract as Pi RPC mode. ./nexussy.sh doctor warns when the bundled nexussy-pi worker is selected while core or web is bound to a non-localhost address.

Set provider keys through /secrets, the TUI setup flow, or environment variables. Core passes configured provider environment into the worker subprocess without hardcoding keys.

Artifacts

Pipeline artifacts are written under the project main worktree, typically:

~/nexussy-projects/<project_slug>/main/.nexussy/artifacts/

Important artifacts include:

• interview.json
• complexity_profile.json
• design_draft.md
• validated_design.md
• validation_report.json
• devplan.md
• handoff.md
• phaseNNN.md
• review_report.json
• develop_report.json
• merge_report.json
• changed_files.json

Anchored devplan.md, phaseNNN.md, and handoff.md files are designed for safe continuation by another agent.

MCP Tools

Core exposes an MCP-compatible tool surface over HTTP and stdio JSON-RPC:

• GET /mcp/tools lists registered tools and their inputSchema values.
• POST /mcp/call invokes a tool by name with arguments.
• nexussy_start_pipeline starts a pipeline run.
• nexussy_get_status returns pipeline status.
• nexussy_list_sessions lists recent sessions.
• nexussy_get_artifacts returns an artifact manifest for a run.
• nexussy_interview_answer submits interview answers for a session.
• nexussy_pause pauses a run.
• nexussy_resume resumes a run.
• nexussy_cancel cancels a run.
• nexussy_inject injects guidance into a run.
• nexussy_worker_spawn creates a worker record.
• nexussy_worker_assign assigns a task to a worker.
• nexussy_list_workers lists workers for a run.

The stdio JSON-RPC MCP path supports initialization, notifications/initialized, tool listing, tool calls, and JSON-RPC parse/invalid/unknown/internal error codes.

Security

Secrets:

• Core resolves provider secrets from OS keyring first, process/environment variables second, and the configured env file last.
• Guided setup stores keys in the OS keyring when available.
• If keyring is unavailable or times out, core falls back to the env file and logs a plaintext-storage warning.
• UI/API summaries report configured/missing status and never return secret values.

CORS:

core:
  cors_allow_origins:
    - "http://127.0.0.1:7772"
    - "https://your-dashboard.example"

• The installer-generated default is core.cors_allow_origins: ["http://127.0.0.1:7772"] for the local web dashboard.
• For trusted LAN/VPN use, write the exact dashboard origins to core.cors_allow_origins before startup.
• Wildcard CORS is rejected by the trusted-lan deployment profile.

Deployment profiles:

Profile	Use	Behavior
dev	Single-developer workstation	Current defaults: localhost bind, auth optional, bundled nexussy-pi allowed, permissive local development behavior.
trusted-lan	Small trusted team on LAN/VPN	Enables API-key auth, rejects wildcard CORS, requires an explicit pi.command or NEXUSSY_PI_COMMAND, warns if that command is bundled nexussy-pi, and writes service logs under ~/.nexussy/logs/ when defaults are still /tmp.

Set the profile in ~/.nexussy/.env:

NEXUSSY_PROFILE=trusted-lan
NEXUSSY_API_KEY=<shared-team-key>
NEXUSSY_PI_COMMAND=/usr/local/bin/nexussy-worker-sandbox
NEXUSSY_CORS_ALLOW_ORIGINS=http://127.0.0.1:7772,http://team-dashboard.local:7772

There is no cloud or SaaS profile. trusted-lan is for operator-owned machines on a private network.

Rotate the local API key with:

./nexussy.sh rotate-key

The command updates ~/.nexussy/.env, prints the new key once, and does not write the key to service logs. Failed API-key attempts are recorded in ~/.nexussy/audit.log and temporarily rate-limited in SQLite.

Other safeguards:

• Paths are resolved through sanitizer helpers.
• Symlink escapes are rejected when enabled.
• Logs scrub common API key, bearer token, password, private key, and context-guarded secret hash forms.
• Worker writes require file locks.
• Local bash worker tools use exec-based subprocesses with stripped environments, process-group termination, hard timeouts, and output caps.
• SQLite writes are serialized with WAL, busy timeout, retries, and indexed run lookups.

Configuration

Default config lives at:

~/.nexussy/nexussy.yaml

Local environment placeholders live at:

~/.nexussy/.env

Common environment overrides:

• NEXUSSY_HOME
• NEXUSSY_CONFIG
• NEXUSSY_ENV_FILE
• NEXUSSY_PROFILE
• NEXUSSY_PROJECTS_DIR
• NEXUSSY_CORE_HOST
• NEXUSSY_CORE_PORT
• NEXUSSY_WEB_HOST
• NEXUSSY_WEB_PORT
• NEXUSSY_API_KEY
• NEXUSSY_AUTH_ENABLED
• NEXUSSY_DEFAULT_MODEL
• NEXUSSY_PI_COMMAND

Verification

Full local verification:

python3 -m pytest -q core/tests
cd tui && bun install && bun test && bun run typecheck
cd ..
python3 -m pytest -q web/tests
bash -n install.sh nexussy.sh ops_tests.sh launch_verify.sh
./install.sh --non-interactive --dry-run
./ops_tests.sh

Current traceability status is tracked in SPEC_COVERAGE.md and FULL_SPEC_REMAINING.md. At the time of this README update, no rows are blocked on missing external tooling; live provider, live Pi, installer, core, TUI, web, shell, and ops evidence is recorded in the coverage matrix and scripts/evidence/.

The deep code review follow-up report is tracked in DEEP_CODE_REVIEW.md; all critical/high findings and the residual cleanup bucket are closed with regression coverage.

For backup, restore, schema migration, and audit-log operations, see OPERATIONS.md.

Development Notes

• Follow SPEC.md for contracts.
• Follow AGENTS.md for ownership boundaries and handoff protocol.
• Use CIRCULAR_DEVELOPMENT.md when closing coverage gaps sequentially.
• Do not depend on ussycode.
• Do not log secrets.
• Recent fixes include real worker tool execution, shell-safe local bash workers, expanded graph data, interview timeout cleanup, TUI stream cleanup and data commands, web proxy limits/timeouts, dashboard chat/graph/control surfaces, generated phase task content, and expanded regression coverage.

Update

./nexussy.sh update

This runs git pull, reinstalls core and web editable packages, and runs bun install for the TUI.