NexusLoop

Architecture status: This README still contains historical workflow text from the legacy Python-orchestrator/dashboard direction. For the current target architecture, treat docs/ARCHITECTURE.md, docs/TUI_UX.md, docs/SPEC_BACKEND.md, and docs/RESEARCH_BACKEND.md as canonical. Do not implement new primary runtime features against the legacy dashboard or Python orchestrator except as compatibility shims.

Autonomous DRL research workflow manager with orchestrator-led agent loops, hard-rule guardrails, structured logs, and a local dashboard.

Project Lineage

This repository is forked from Karpathy AutoResearch and keeps the original AutoResearch training-loop spirit as the core.
The main research/training orchestration logic remains centered on the original local, iterative AutoResearch workflow; this fork adds DRL-focused operational features around init, environment handling, mode control, plugin scaffolding, and dashboard visibility.

Core Principles

• Local-first, file-based workflow in your own project directory.
• Safety and policy enforcement before risky actions.
• Reproducible experiment tracking via logs and state files.
• Token-aware orchestration: compact planning/research artifacts and controlled refresh behavior.

Feature Overview

1. Orchestrator-controlled agent loop

• nxl run is orchestrator-first and continuous by default.
• run launches Codex or Claude Code as the execution backend for each cycle.
• Orchestrator selects the next experiment candidate.
• If orchestrator cannot produce one, local fallback generation is used.
• Phase and loop state are persisted in .nxl/state.json.

2. Init mode selection (build vs improve)

During init, users choose one project mode:

• build mode:
  • For empty or incomplete training projects.
  • System performs deep research and creates compact plan steps in implementation_plan/*.md before build/training loop starts.
  • After bootstrap completes successfully, the plan folder is removed and a compact summary is logged to keep future context short.
• improve mode:
  • For existing working models.
  • System starts optimization-focused iteration directly.

Both modes support stuck-driven research/plan refresh without disabling existing capabilities.

3. Skill-pack strategy selection (drl vs custom)

During init, users choose one skill-pack strategy:

• drl:
  • Keep the provided compact DRL skill pack in project scope.
• custom:
  • Remove bundled DRL skills in the target project.
  • Install .nxl/backend/skill_generator.md to generate domain-specific compact skills from user spec/rules.

Skill generation policy for custom pack:

• Keep generated skills compact (token-efficient).
• Keep skills general/basic technique-level (like DRL pack style).
• Avoid heavy, overly detailed implementation plans inside skills.

4. Onboarding questionnaire + policy capture

Init onboarding captures key inputs including:

• project/task basics (domain, objective, constraints)
• other information (quirks, known issues, extra context)
• hardware and runtime assumptions
• Python environment preferences
• permission policy
• hard rules and non-negotiables

These settings are saved into .nxl/ and reused by init/run/doctor flows.

5. Automatic compact spec indexing (token-saving)

After init, the system auto-generates:

• .nxl/spec_compact.md (compact navigator)
• .nxl/spec_index.json (machine-readable pointer index)

Design intent:

• structure is source-driven (derived from the actual spec/rules document structure), not a fixed hard-coded schema
• compact file is for fast navigation only
• original source files remain the source of truth for detailed clarification
• entries include line pointers (for example USER_SPEC.md:300) so agents can jump directly to relevant details without loading whole files

6. Environment doctor with auto-fix path

• nxl doctor validates runtime health.
• nxl doctor --fix attempts remediation automatically:
  • uses onboarding env preferences
  • creates/uses project venv when needed
  • installs missing dependencies
  • includes fallback handling for externally-managed Python environments (PEP 668)
• Init triggers best-effort remediation so setup issues are handled early.

7. Stuck refresh with cooldown (token saving)

• Stuck detection can trigger research/plan refresh when progress stalls.
• Refresh trigger is orchestrator-first, with local fallback heuristics.
• Cooldown state prevents repeated refresh loops that waste tokens.
• State includes mode/bootstrap/refresh metadata for observability.

8. Dashboard workflow visibility

Dashboard includes workflow snapshot fields such as:

• current mode
• loop running / idle state
• active run id
• current agent backend
• bootstrap started/completed state
• refresh cooldown remaining runs
• last refresh reason

This is in addition to normal training/registry status views.

Installation

Requirements

• Python 3.10+
• Linux recommended (macOS partial support)
• GPU optional (CPU works, typically slower)

Install from source

git clone https://github.com/Ian747-tw/autoresearch-RL
cd autoresearch-RL
pipx install --force .

This installs nxl once for your user account so it can be run from any directory.

Verify CLI:

which nxl
nxl --help

If which nxl returns nothing after install, open a new shell once or run source ~/.bashrc.

Recommended verification that the installed command is using the expected package:

PIPX_PY="$(head -n 1 "$(which nxl)" | sed 's/^#!//')"
"$PIPX_PY" - <<'PY'
import nxl, nxl.core.onboarding as ob
print(nxl.__file__)
print(ob.__file__)
PY

Use plain python3 -c 'import nxl' only if you installed the package into that same Python environment. A cloned repo and an installed CLI are separate copies.

Alternative if you prefer a repo-linked editable install instead of a global pipx app:

git clone https://github.com/Ian747-tw/autoresearch-RL
cd autoresearch-RL
python3 -m pip install --user -e .

Update existing local clone (no re-download)

cd ~/autoresearch-RL
git fetch origin
git checkout master
git pull --ff-only origin master
pipx install --force .

If you use the editable install path instead of pipx, update with:

cd ~/autoresearch-RL
git fetch origin
git checkout master
git pull --ff-only origin master
python3 -m pip install --user -e .

End-to-End Workflow

Step 0: Prepare a project folder

• Create or choose your training project directory.
• Put project spec/rules/constraints in place (or provide them during onboarding).

Step 1: Initialize project

cd /path/to/your-project
nxl init

Init flow:

1. Creates baseline structure (.nxl/, logs/, skills/, config files).
2. Runs onboarding questionnaire (unless skipped).
3. Captures skill-pack choice (drl or custom).
4. Captures project mode (build or improve).
5. Installs selected plugin assets (cc, codex, both, none).
6. Auto-generates compact spec/index artifacts with source line pointers.
7. Runs best-effort environment remediation.
8. Persists startup state for orchestrator and dashboard.

Non-interactive examples:

nxl init --auto
nxl init --project-mode build --skill-pack custom --plugin codex --skip-onboarding
nxl init --refresh

Refresh behavior:

• nxl init --refresh removes NexusLoop-managed config, runtime state, skill-pack files, and plugin scaffolding from the target project, then runs init again from scratch.
• It does not delete your source code or arbitrary project files.

Step 2: Validate/fix environment

nxl doctor
nxl doctor --fix

Use --fix if dependencies/interpreter setup are not healthy.

Step 3: Start orchestrated loop

nxl run

Behavior summary:

• In build mode:
  • bootstrap research + compact implementation plan happens first
  • then the controller keeps launching agent-driven coding/training cycles
  • bootstrap plan folder is removed after build bootstrap completion
  • compact summary is written to project log/journal
• In improve mode:
  • immediate continuous agent-driven optimization loop

Runtime notes:

• run now stays alive until interrupted, convergence is reached, or a hard policy block stops it.
• The controller launches Codex or Claude Code in autonomous mode for each cycle.
• Use --once if you want a single cycle and exit.
• Use --agent-backend codex or --agent-backend claude to force one backend.
• Autonomous runs require onboarding permission policy open, project-only, or bootstrap-only.
• During autonomous cycles, risky actions must go through nxl check.
• Registry/journal/incidents/handoffs are expected to be written through the project helper APIs, not raw file edits.

Step 4: Monitor and intervene when needed

E2E Release Gate

User-simulation end-to-end tests live under tests/e2e_user/. These are local/release-gate scenarios that install NexusLoop into a fresh sandbox and exercise the real nxl CLI. They are intentionally not part of the default pull-request CI workflow in .github/workflows/ci.yml.

Run them locally from a clean checkout with the same dependency order used by the release-gate workflow:

uv sync
(cd agentcore/server-fork && bun install)
uv run pytest tests/e2e_user/ -v --tb=short

GitHub runs the same suite only in .github/workflows/e2e.yml, which is triggered manually via workflow_dispatch and automatically on version tags matching v*.

nxl status
nxl plan --refresh
nxl research

If your agent session drops or you start a new session, use one-line resume:

nxl resume --project-dir .

This performs compact sync (status + tail windows of registry/journal/handoffs) and then continues the run loop automatically.

Agents decide whether each run is a full baseline/real local eval or only a temporary, partial, or specific test. Only full baseline/local eval results should be promoted to registry/dashboard; the rest should keep raw outputs in logs/runs/<run_id>/ without adding registry/dashboard entries.

If you want to add fresh guidance during resume, pass a one-shot message:

nxl resume --project-dir . --message "Keep the current plan, but prioritize fixing the data loader first."

The resume message is merged as additional guidance unless it conflicts with stale queued intent, in which case the new human instruction wins.

Step 5: Open dashboard

nxl dashboard --port 8765

Open http://localhost:8765.

If you want to blank dashboard backend data while preserving all logs:

nxl dashboard --project-dir . --clear-offline

Plugin Artifacts Installed by Init

Claude Code plugin (--plugin cc or both)

Installs to .claude/commands/:

• drl-init.md
• drl-run.md
• drl-plan.md
• drl-diagnose.md
• drl-research.md

Codex plugin (--plugin codex or both)

• Installs AGENT.md in project root.
• Codex integration is file-based; no separate project-side codex/ directory is required.

Command Reference

Init

nxl init \
  [--project-dir DIR] \
  [--skip-onboarding] \
  [--auto] \
  [--plugin {cc,codex,both,none}] \
  [--skill-pack {drl,custom}] \
  [--project-mode {build,improve}]

Doctor

nxl doctor [--project-dir DIR] [--fix]

Run

nxl run [--project-dir DIR] [--parallel N] [--dry-run] [--once] [--agent-backend {auto,codex,claude}]

Resume

nxl resume [--project-dir DIR] [--parallel N] [--dry-run] [--no-run] [--message TEXT]

Other core commands

nxl status    [--project-dir DIR]
nxl plan      [--project-dir DIR] [--refresh]
nxl research  [--project-dir DIR]
nxl resume    [--project-dir DIR] [--parallel N] [--dry-run] [--no-run] [--message TEXT]
nxl check     --action ACTION [--details JSON] [--project-dir DIR]
nxl dashboard [--project-dir DIR] [--port PORT] [--clear-offline]

Token-Efficiency and Stability Notes

• Build bootstrap plans are intentionally compact and temporary.
• Stuck refresh is cooldown-controlled to prevent repetitive research churn.
• Custom skills are designed to be concise and technique-oriented, not verbose implementation documents.
• Existing backbone files remain the source of truth: .nxl/, logs/, skills/, compact spec files, dashboard artifacts, and NON_NEGOTIABLE_RULES.md.

Known Limits

• doctor --fix is best-effort and depends on package index/network reachability.
• Checks reflect the interpreter context used to run the CLI.
• Dashboard is local HTTP and intended for local/private usage.
• Continuous autonomous runs depend on a working codex or claude CLI being installed on the machine.