Skip to content

Nova AI Documentation

Tests License: MIT Python 3.11+

Production-ready multi-agent orchestration system powered by Claude Code SDK. Automates software development workflows with specialized agents, SDK MCP tools, and intelligent task decomposition.

/novaai implement user authentication with JWT
/novaai review PR #123 and fix security issues

  • Getting Started

    Install Nova AI and run your first task in minutes

    Installation

  • User Guides

    Learn how to use slash commands, headless mode, and SDK

    Guides

  • API Reference

    Complete Python SDK documentation and examples

    API Docs

  • Architecture

    Understand the system design and components

    Architecture

Key Features

  • 6 Specialized Agents - Orchestrator, architect, implementer, code-reviewer, tester, debugger
  • 3 SDK MCP Servers - In-process tools (KB search, GitHub ops, memory) with 10-100x speedup
  • 11GB Knowledge Base - FAISS-indexed expert knowledge across 37 domains
  • API Retry Logic - Exponential backoff + circuit breaker for production reliability
  • Session Management - Resume conversations, 88-95% overhead reduction
  • Cost Optimized - Prompt caching (90% savings), Sonnet 4.5 for all agents

Quick Start

Requirements: Claude Code + ANTHROPIC_API_KEY

git clone https://github.com/Jaureguy760/nova_ai.git
cd nova_ai
export ANTHROPIC_API_KEY="your-key-here"

# Use slash commands in Claude Code
/novaai your task here

Full Setup Guide

Usage Examples

Inside Claude Code, use /novaai for orchestrated workflows:

# Interactive workflow (all tasks)
/novaai implement user authentication with JWT
/novaai review PR #123 and fix security issues
/novaai refactor payment module for performance
/novaai add unit tests for UserService
/novaai fix broken import in auth.py

Workflow: Task → Planning → Implementation → Review → Refinement

Learn More

For programmatic usage:

from src.orchestrator.claude_sdk_executor import ClaudeSDKExecutor

executor = ClaudeSDKExecutor(
    project_root=Path.cwd(),
    agent_name="orchestrator",
    use_sdk_mcp=True  # 10-100x faster
)

result = await executor.run_task("implement user authentication")
print(result.summary)

API Documentation

For CI/CD and automation:

# Security review in JSON format
python scripts/nova_headless.py "review authentication module" \
  --output-format json

# GitHub Actions integration
# Users comment @nova-ai in PRs
# Example: "@nova-ai review this code for security issues"

Headless Guide

Architecture Overview

graph LR
    A[User] --> B[/novaai Command]
    B --> C[Orchestrator Agent]
    C --> D[Specialist Agents]
    C --> E[SDK MCP Tools]
    E --> F[FAISS KB 11GB]
    E --> G[GitHub API]
    E --> H[Memory Store]
    D --> I[Output]
  • Orchestrator Agent - Task decomposition, agent coordination, workflow management
  • Specialist Agents - Code review, testing, debugging, architecture, implementation
  • SDK MCP Servers - In-process tools (KB, GitHub, memory) with 10-100x speedup
  • Knowledge Base - 11GB FAISS-indexed expert knowledge across 37 domains
  • Session Management - Lightweight state compression (150K token max)

Detailed Architecture

Recent Updates

Phase 2.0: MCP Simplification

  • ✅ Deleted all stdio MCP servers - Removed browser, voice, context7 (-2,811 lines)
  • ✅ SDK MCP only architecture - 100% in-process MCP (10-100x speedup)
  • ✅ MCP cleanup - 13 → 3 servers (-77%), removed dead code and configs

Phase 1.8: Agent Consolidation

  • ✅ Agent consolidation - Reduced from 13 → 6 agents (-54%)
  • ✅ Deep audit - 2,219 lines dead code removed, 89 unused imports cleaned
  • ✅ Complete documentation - Developer guide, API reference, coding standards
  • ✅ Dependency updates - 10 GitHub Actions + 6 core dependencies updated
  • ✅ API retry logic - Production-critical reliability

Total cleanup: -5,030 lines, cleaner architecture, maximum performance

MCP Servers

3 SDK MCP Servers (In-Process, 10-100x Faster):

  • kb - FAISS knowledge base (11GB, semantic search across 37 domains)
  • github - GitHub operations (PRs, issues, commits, reviews)
  • memory - Persistent memory across sessions

No stdio/external MCP servers - 100% in-process for maximum performance.

MCP Configuration

Next Steps

License

MIT © 2025 Nova AI Contributors