Nova AI Headless Mode Guide

Version: 1.0.0 Last Updated: October 2025

Overview

Nova AI headless mode enables programmatic, non-interactive execution of AI-powered workflows for automation, CI/CD pipelines, scheduled tasks, and batch processing.

Key Capabilities: - Zero user interaction with pre-configured permissions - Structured output (JSON, Stream-JSON, plain text) - Session management and resumption - Batch processing with parallel execution - CI/CD integration ready

---

Quick Start

Installation

# 1. Install Nova AI
pip install nova-ai

# 2. Authenticate with Claude
claude /login

# 3. Verify installation
python -m src.orchestrator.auto_orchestrator --help

Hello World Example

# Simple headless execution
python -m src.orchestrator.auto_orchestrator \
  "Add type hints to authentication.py" \
  --output-format json \
  --no-pr

# With PR creation
python -m src.orchestrator.auto_orchestrator \
  "Implement rate limiting for API endpoints" \
  --pr

---

CLI Reference

Main Orchestrator

python -m src.orchestrator.auto_orchestrator "<goal>" [OPTIONS]

Arguments: - <goal> (required): Natural language task description

Options: - --pr / --no-pr: Auto-create GitHub PR (default: --no-pr) - --output-format {json|text|stream-json}: Output format (default: text) - --session-id <id>: Resume existing session - --use-kb / --no-kb: Query knowledge base for context (default: --use-kb) - --max-iterations <n>: Max refinement iterations per step (default: 3) - --model-dev <model>: Model for implementation (default: claude-sonnet-4-5-20250929) - --model-review <model>: Model for code review (default: claude-haiku-4-5-20251001) - --verbose: Enable detailed logging

Exit Codes: - 0: All steps succeeded - 1: One or more steps failed - 2: Partial success (some steps completed)

---

GitHub Actions Setup

.github/workflows/nova-code-review.yml:

name: Nova AI Code Review

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install Nova AI
        run: |
          pip install nova-ai

      - name: Authenticate Claude
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: |
          echo "$ANTHROPIC_API_KEY" | claude /login --api-key

      - name: Run Code Review
        id: review
        run: |
          python -m src.orchestrator.auto_orchestrator \
            "Review all changed files for security and correctness" \
            --output-format json \
            --no-pr \
            > review_result.json

          echo "success=$(cat review_result.json | jq -r '.success')" >> $GITHUB_OUTPUT

      - name: Post Review Comment
        uses: actions/github-script@v7
        with:
          script: |
            const fs = require('fs');
            const result = JSON.parse(fs.readFileSync('review_result.json', 'utf8'));

            const body = `## Nova AI Code Review\n\n${
              result.success ? 'Review Passed' : 'Review Failed'
            }\n\n**Cost:** $${result.metrics.total_cost_usd.toFixed(4)}`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: body
            });

      - name: Fail if review failed
        if: steps.review.outputs.success != 'true'
        run: exit 1

---

Key Automation Examples

Example 1: Security Scan

python -m src.orchestrator.auto_orchestrator \
  "Security scan: Check all API endpoints for SQL injection, XSS, and CSRF vulnerabilities" \
  --output-format json \
  --no-pr \
  > security_scan.json

Example 2: Batch File Review

# scripts/batch_review.py
import asyncio
from pathlib import Path
from src.orchestrator.claude_sdk_executor import ClaudeSDKExecutor

async def review_files(files: list[Path]) -> dict:
    executor = ClaudeSDKExecutor(
        project_root=Path.cwd(),
        agent_name="code-reviewer-autonomous",
        model="claude-haiku-4-5-20251001"
    )

    tasks = [
        executor.run_task_async(
            f"Review {file} for security and correctness",
            context=f"File: {file}"
        )
        for file in files
    ]

    results = await asyncio.gather(*tasks)
    return results

# Usage
files = list(Path.cwd().glob("src/**/*.py"))
results = asyncio.run(review_files(files))

---

Troubleshooting

Common Issues

1. "Claude Agent SDK not installed"

Solution:

pip install claude-agent-sdk
claude /login

2. "Session not found"

Solution:

# Don't use --session-id for new tasks
python -m src.orchestrator.auto_orchestrator "Add logging"

# Only use --session-id to resume
python -m src.orchestrator.auto_orchestrator \
  "Continue previous task" \
  --session-id orchestration-abc123

3. "Rate limit exceeded"

Solution:

# Reduce concurrency in batch scripts
python scripts/batch_review.py --max-concurrent 5

4. "Permission denied"

Solution:

# Check agent permissions in .claude/agents/autonomous/
# Ensure required tools are in the allow list

# Or run with elevated permissions in Docker
docker run --rm \
  -v $(pwd):/app \
  --user $(id -u):$(id -g) \
  nova-ai:headless

Debug Mode

# Enable verbose logging
export NOVA_LOG_LEVEL=DEBUG

python -m src.orchestrator.auto_orchestrator \
  "Add logging" \
  --verbose

---

Support

• Documentation: docs/
• Issues: https://github.com/Jaureguy760/nova_ai/issues
• Examples: examples/automation/

---

Version: 1.0.0 | Lines: 200 | Reduction: 87%