Agent-Nexus

Experimental multi-agent orchestration platform for local-first AI software delivery.

Give it one prompt. It decomposes the task, runs multiple AI agents in parallel inside isolated Git worktrees, validates the output through QA and merge gates, and delivers the result — without you babysitting each step.

What It Does

1. Decomposes your task into parallel subtasks (backend, frontend, ops)
2. Assigns each subtask to a Claude or OpenAI agent
3. Runs them in isolated Git worktrees — no file conflicts
4. Validates with QA gates — tests must pass before merge
5. Handles failures — auto-fix loop, retries, dead letter queue
6. Keeps you in control — local dashboard, operator approval flows

Status

Experimental. Not production-ready. Human supervision recommended for meaningful code changes.

What works:

• Task orchestration with persistent state and restart recovery
• Parallel agents in isolated Git worktrees
• QA gates, merge policy, retry logic, dead letter queue
• Local web dashboard for real-time visibility

What is still limited:

• Task decomposition is rule-based, not LLM-planned
• Test coverage is light relative to codebase size
• Production hardening is incomplete

Quick Start

Prerequisites: Node.js 20+, Git, an Anthropic or OpenAI API key (or the local CLI)

git clone https://github.com/your-username/agent-nexus.git
cd agent-nexus
npm install
cp .env.example .env
# Edit .env — add your API key and PROJECT_ROOT
npm run build
npm run daemon

Open the dashboard:

http://127.0.0.1:7821/dashboard

Run a task:

agent ask "add user authentication with JWT"
agent run "fix the login bug in src/auth"
agent team "build dashboard, API, and tests in parallel"

Configuration

Minimal .env:

AGENT_HUB_PORT=7821
PROJECT_ROOT=/absolute/path/to/your/repo

# Pick one or both
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Use local CLI instead of API key
CLAUDE_RUNNER=cli        # or: api
CLAUDE_CLI_COMMAND=claude

WORKER_CONCURRENCY=2
REDIS_URL=redis://127.0.0.1:6379   # optional, SQLite fallback built-in

Full variable list: .env.example

Architecture

src/
├── orchestrator/     # task decomposition, routing, delivery pipeline, state
├── agent/            # Claude + OpenAI providers, model routing
├── worker/           # Git worktree lifecycle per subtask
├── queue/            # Redis queue + SQLite fallback, worker pool, DLQ
├── policy/           # merge gate, approval flows, policy rules
├── qa/               # QA runner, auto-fix loop, secret scanner
├── prompt-registry/  # system prompts per role
├── daemon/           # local HTTP/WebSocket server
├── dashboard/        # web UI (real-time task status, DLQ, logs)
├── cli/              # command-line interface
└── cost/             # token and API cost tracking

CLI Reference

agent ask "your task"         # single-agent task
agent run "your task"         # orchestrated multi-agent task
agent team "your task"        # parallel team mode
agent status                  # system status
agent task list               # list all tasks
agent dlq list                # dead letter queue
agent dlq replay <id>         # retry a failed task
agent approval list           # pending human approvals

Docker

docker compose up

Includes: Agent-Nexus daemon, Redis, Prometheus, Grafana.

Development

npm run typecheck
npm run build
npm test
npm run lint

License

MIT — see LICENSE.