Quick Start

Get up and running with Nexus in minutes.

About Nexus

Nexus is the AI-powered development orchestration system that combines:

• Conductor: Deterministic TypeScript orchestration engine (workflow automation)
• AI Learning Service: Captures and applies development patterns over time

Together they form a self-improving system that automates software development from Jira ticket to merged PR.

Try It First

Watch Nexus Demo - See AI-powered development orchestration in action

Prerequisites

• Node.js 18.0.0 or higher
• Redis 6.0 or higher (for Conductor state management)
• Claude Code CLI installed (claude command available)
• Jira account with API access
• Git repository for your project
• AI Learning Service (optional but recommended - enables continuous improvement)

Installation

1. Access Nexus

Contact us about accessing Nexus for your organization.

2. Install dependencies

npm install

3. Start Redis

# macOS with Homebrew
brew services start redis

# Linux
sudo systemctl start redis

# Docker
docker run -d -p 6379:6379 redis:latest

4. Configure environment variables

Create .env file:

# Anthropic API Key (required)
ANTHROPIC_API_KEY=your-key-here

# Redis (defaults shown)
REDIS_HOST=localhost
REDIS_PORT=6379

# Jira (required for ticket polling)
JIRA_TOKEN=your-jira-token
JIRA_EMAIL=your-email@example.com

# Claude Code (optional, defaults to 'claude' in PATH)
CLAUDE_CODE_PATH=claude

First Run

1. Configure your first project

Create config/my-project.yaml:

project:
  id: my-project
  name: My Project
  working_directory: /path/to/your/project

jira:
  instance: https://your-company.atlassian.net
  project_key: MYPROJ
  auth_token_env: JIRA_TOKEN
  email: you@company.com
  query_ready: status = "Ready for Dev" AND project = MYPROJ
  status_in_progress: In Progress
  status_in_review: In Review
  status_done: Done

workflow:
  checklist: ai-native-checklist.yaml
  claude_config:
    builder_model: claude-sonnet-4-5-20250929
    validator_model: claude-3-haiku-20240307  # 90% cheaper
    use_sdk_agents: true  # Use modern SDK mode
    budget:
      enabled: true
      max_cost_per_ticket: 10.00

2. Start Nexus

# Development mode (Conductor + dashboard)
npm run dev

# Production mode
npm run build
npm start

3. Access the Conductor dashboard

Open http://localhost:3000 in your browser

4. (Optional) Start AI Learning Service

cd ../learning-service
npm install
npm run dev
# Runs on http://localhost:8000

When enabled, Nexus will:

• Query learnings before each ticket
• Capture new patterns after completion
• Improve success rates over time

What Happens Next?

Nexus (Conductor + AI Learning) will:

1. Poll Jira for tickets matching your query
2. Query AI learnings for relevant patterns (if Learning Service enabled)
3. Validate paths to ensure working directory exists
4. Spawn builder agents with accumulated knowledge
5. Monitor progress in real-time via dashboard
6. Validate automatically with fresh Reality Validator
7. Self-heal if validation finds issues (up to 2 retries)
8. Create PRs when validation passes
9. Capture learnings from completed tickets (if Learning Service enabled)
10. Update Jira to "In Review" and "Done"

Verify Installation

Check that everything is working:

# Health check
curl http://localhost:3000/health

# Expected response:
# {
#   "status": "healthy",
#   "redis": { "connected": true }
# }

# Check Redis
redis-cli ping
# Expected: PONG

# Check Claude Code
which claude
# Expected: /path/to/claude

Next Steps

You're Ready!

Nexus is now running and monitoring your Jira project.

Explore Nexus capabilities:

• Learn about self-healing
• Optimize costs
• Enable worker pools for parallel processing
• Explore development patterns
• View API reference

Enable AI Learning (Recommended):

• Configure ai_learning.enabled: true in your project config
• Start the Learning Service on port 8000
• Watch as Nexus improves with each completed ticket

Common Issues

Redis Connection Failed

# Check if Redis is running
redis-cli ping

# Start Redis if not running
brew services start redis  # macOS

Claude Code Not Found

# Install Claude Code CLI
npm install -g @anthropic-ai/claude-code

# Or set custom path in .env
CLAUDE_CODE_PATH=/path/to/claude

Jira Authentication Failed

1. Generate API token: https://id.atlassian.com/manage-profile/security/api-tokens
2. Ensure JIRA_TOKEN environment variable is set
3. Verify email matches your Jira account

Path Validation Warning

Dashboard shows red alert for invalid paths:

1. Go to http://localhost:3000/config
2. Click "Validate Path" for your project
3. Update working directory if incorrect
4. Ensure directory exists and is not empty

Quick Commands Reference

# Nexus (Conductor) Commands
npm run dev                          # Start development server
npm run build                        # Build for production
npm run conductor -- run my-project  # Run for specific project (note: -- required)
npm run conductor -- run-all         # Run for all projects
curl http://localhost:3000/health    # Health check

# AI Learning Service Commands (optional)
cd ../learning-service
npm run dev                          # Start learning service
curl http://localhost:8000/health    # Learning service health

# Development
npm run typecheck                    # Type checking
npm test                             # Run tests
npm run docs:dev                     # Documentation server