Lightweight Plugin Distribution¶

Complete guide for installing Nova AI without cloning the full 2.6GB repository.

Overview¶

Nova AI provides lightweight installation via pre-built wheels that exclude development files, tests, and large data files. Install the 3.4MB wheel instead of cloning the full repository.

Method	Size	Contents	Use Case
Wheel (Recommended)	3.4MB	Python runtime + plugin assets	Users, production
Plugin Marketplace	3.4MB	Same as wheel	Claude Code users
Git Clone	50MB+	Source only (with `--depth 1`)	Contributors
Full Repo	2.6GB	Everything (KB, tests, scripts)	Core maintainers

Installation Methods¶

Method 1: GitHub Release Wheel (Recommended)¶

Perfect for private repositories with GitHub releases.

# Step 1: Download wheel from latest release
pip install https://github.com/Jaureguy760/nova-core/releases/download/v2.19.0/nova_ai-2.19.0-py3-none-any.whl

# Step 2: Initialize plugin assets
nova-ai init

Requirements: - GitHub access to the private repository - Python 3.11+ - 6GB free disk space (for knowledge base)

Authentication:

# Option A: GitHub CLI (recommended)
gh auth login
pip install $(gh release view --json assets -q '.assets[] | select(.name | endswith(".whl")) | .url')

# Option B: Personal access token
export GITHUB_TOKEN=ghp_your_token_here
pip install https://github.com/Jaureguy760/nova-core/releases/download/v2.19.0/nova_ai-2.19.0-py3-none-any.whl

Method 2: Claude Code Plugin Marketplace¶

Uses the GitHub wheel automatically.

# Step 1: Add marketplace (one-time)
/plugin marketplace add Jaureguy760/nova-core

# Step 2: Install plugin
/plugin install nova-ai

# Step 3: Restart Claude Code, then initialize
/init

Behind the scenes, this runs:

pip install <wheel-from-github-release>
nova-ai init

Method 3: Shallow Git Clone¶

For contributors who need source access but don't want the full history.

# Clone only latest commit (50MB vs 2.6GB)
git clone --depth 1 https://github.com/Jaureguy760/nova-core.git

# Install in editable mode
cd nova_ai
pip install -e .

# Initialize
nova-ai init

Pros: Editable install, always latest Cons: Still downloads source (50MB), not as lightweight

Method 4: Private PyPI (AWS CodeArtifact)¶

For organizations with private package infrastructure.

# Step 1: Configure private index (one-time)
pip config set global.index-url https://aws:TOKEN@your-domain.d.codeartifact.region.amazonaws.com/pypi/nova-ai/simple/

# Step 2: Install normally
pip install nova-ai

# Step 3: Initialize
nova-ai init

Setup Guide: See AWS CodeArtifact Setup below.

What Gets Installed¶

Wheel Contents (3.4MB)¶

nova_ai-2.19.0-py3-none-any.whl
├── src/nova_ai/               # Python runtime (90+ modules)
│   ├── orchestrator/          # Core orchestration
│   ├── tools/                 # MCP servers
│   ├── cli.py                 # Entry point
│   └── plugin_assets/         # Commands, skills, agents (3.5MB)
│       ├── commands/          # 27 slash commands
│       ├── skills/            # 65 skills
│       ├── agents/            # 15 agent definitions
│       └── hooks/             # Quality gate hooks
└── README.md, LICENSE, etc.

Excluded from Wheel¶

The following are NOT included in the wheel (saving 2.5GB):

.nova/ - Knowledge base data (5.4GB, downloaded on nova-ai init)
tests/ - Test suite
scripts/ - Development scripts
docs/ - Full documentation
.github/ - CI/CD workflows
Git history and metadata

Post-Install: Initialize¶

After installing the wheel, run nova-ai init to complete setup:

nova-ai init

This command:

Installs plugin assets to ~/.claude/plugins/nova-ai/
Commands → ~/.claude/plugins/nova-ai/commands/
Skills → ~/.claude/plugins/nova-ai/skills/
Agents → ~/.claude/plugins/nova-ai/agents/
Hooks → ~/.claude/plugins/nova-ai/hooks/
Downloads knowledge base (5.4GB) to ~/.local/share/nova-ai/kb/
FAISS vector index
Semantic search data
37 domain knowledge sets
Configures MCP servers
Registers 6 in-process servers
Sets up ~/.nova-ai.env credentials
Verifies installation
Checks Python environment
Tests agent availability
Validates MCP connections

Time: ~5-10 minutes (depending on network speed)

Private Repository Authentication¶

GitHub CLI (Recommended)¶

# Authenticate once
gh auth login
# → Select: GitHub.com → HTTPS → Browser

# Install directly
pip install $(gh release view --json assets -q '.assets[] | select(.name | endswith(".whl")) | .url')

Personal Access Token¶

# Generate token with 'repo' scope at:
# https://github.com/settings/tokens/new

# Set environment variable
export GITHUB_TOKEN=ghp_your_token_here

# Install with authentication
pip install https://${GITHUB_TOKEN}@github.com/Jaureguy760/nova-core/releases/download/v2.19.0/nova_ai-2.19.0-py3-none-any.whl

SSH Keys¶

# If using SSH for git
git clone git@github.com:Jaureguy760/nova-core.git --depth 1
cd nova_ai
pip install .

AWS CodeArtifact Setup¶

For organizations wanting a private PyPI mirror:

1. Create CodeArtifact Repository¶

# Create domain
aws codeartifact create-domain \
  --domain nova-ai \
  --region us-east-1

# Create repository
aws codeartifact create-repository \
  --domain nova-ai \
  --repository nova-ai-packages \
  --region us-east-1

2. Upload Wheel¶

# Get auth token
export CODEARTIFACT_AUTH_TOKEN=$(aws codeartifact get-authorization-token \
  --domain nova-ai \
  --query authorizationToken \
  --output text)

# Upload wheel
twine upload \
  --repository-url https://nova-ai-ACCOUNT.d.codeartifact.us-east-1.amazonaws.com/pypi/nova-ai-packages/ \
  --username aws \
  --password $CODEARTIFACT_AUTH_TOKEN \
  dist/nova_ai-2.19.0-py3-none-any.whl

3. Configure pip¶

# One-time setup
pip config set global.index-url https://aws:$CODEARTIFACT_AUTH_TOKEN@nova-ai-ACCOUNT.d.codeartifact.us-east-1.amazonaws.com/pypi/nova-ai-packages/simple/

# Or per-project
pip install --index-url https://aws:TOKEN@... nova-ai

4. Team Installation¶

Share this with your team:

# Get token (expires every 12 hours)
aws codeartifact login \
  --tool pip \
  --domain nova-ai \
  --repository nova-ai-packages

# Install
pip install nova-ai
nova-ai init

Size Comparison¶

Component	Full Repo	Shallow Clone	Wheel	Post-Init
Source code	2.6GB	50MB	3.4MB	3.4MB
Plugin assets	(included)	(included)	3.5MB	→ `~/.claude/`
Knowledge base	5.4GB	5.4GB	(downloads)	→ `~/.local/share/`
Tests/scripts	✅	✅	❌	❌
Git history	✅	❌	❌	❌
Total download	8GB	55MB	3.4MB	9MB
Total on disk	8GB	5.5GB	5.4GB	5.4GB

Verification¶

After installation, verify everything works:

# Check installation
nova-ai --version
# → nova-ai v2.19.0

# Check plugin assets
ls ~/.claude/plugins/nova-ai/
# → commands/ skills/ agents/ hooks/

# Check knowledge base
ls ~/.local/share/nova-ai/kb/
# → faiss.index embeddings.npy metadata.json

# Run health check
nova-ai doctor
# → ✅ All systems operational

# Test in Claude Code
/novaai say hello
# → Should respond with orchestrator

Updating¶

Update Wheel¶

# Get latest version
LATEST=$(gh release view --json tagName -q .tagName)

# Install new version
pip install --upgrade https://github.com/Jaureguy760/nova-core/releases/download/${LATEST}/nova_ai-${LATEST#v}-py3-none-any.whl

# Re-initialize (updates plugin assets)
nova-ai init --force

Update via Plugin Marketplace¶

# Check for updates
/novaai-update

# Reinstall if update available
/plugin uninstall nova-ai
/plugin install nova-ai

Troubleshooting¶

"Repository not found"¶

You need collaborator access to the private repository.

Fix: 1. Ask repo owner to add you at: https://github.com/Jaureguy760/nova-core/settings/access 2. Accept the invitation email 3. Verify access: gh repo view Jaureguy760/nova-core

"Could not find a version that satisfies the requirement"¶

The wheel URL is incorrect or release doesn't exist.

Fix:

# List available releases
gh release list -R Jaureguy760/nova-core

# Check specific release assets
gh release view v2.19.0 --json assets -q '.assets[].name'

"Permission denied" during `nova-ai init`¶

Plugin assets directory is not writable.

Fix:

# Fix permissions
chmod 755 ~/.claude/plugins/
mkdir -p ~/.claude/plugins/nova-ai
chmod 755 ~/.claude/plugins/nova-ai

Knowledge base download fails¶

Network issues or insufficient disk space.

Fix:

# Check disk space (need 6GB free)
df -h ~

# Retry with verbose logging
nova-ai init --verbose

# Use alternative KB mirror
nova-ai init --kb-mirror https://alternative-cdn.com/kb.tar.gz

Import errors after installation¶

Python path not configured correctly.

Fix:

# Verify installation
pip show nova-ai
# → Should show Location: /path/to/site-packages

# Test imports
python -c "from nova_ai.orchestrator import ClaudeSDKExecutor; print('OK')"

# Reinstall if needed
pip uninstall nova-ai
pip install --no-cache-dir https://github.com/.../nova_ai-VERSION.whl

Best Practices¶

For Users¶

Use GitHub releases - Always install from tagged releases, not branches
Pin versions - Specify exact version in requirements.txt
Verify checksums - Use gh release download with checksum verification
Update regularly - Run /novaai-update weekly

For Organizations¶

Mirror to private PyPI - Use AWS CodeArtifact or JFrog Artifactory
Cache wheels - Keep wheels on internal CDN for faster installs
Automate updates - Use Renovate or Dependabot for version tracking
Audit access - Regularly review who has repository access

For Contributors¶

Use editable install - pip install -e . for development
Full clone - Clone full repo for testing and CI/CD work
Build locally - Test wheel builds: python -m build
Test distributions - Verify wheels in clean virtualenv before releasing

FAQ¶

Can I install without GitHub access?¶

No, the wheel is hosted on GitHub releases. You need either: - Collaborator access to the private repository - A copy of the wheel hosted elsewhere (S3, private PyPI)

Do I need to clone the repo at all?¶

No. The wheel contains everything needed to run Nova AI. Only clone if you're contributing or need the full test suite.

Option A: Add them as collaborators on GitHub Option B: Host wheel on private PyPI (AWS CodeArtifact) Option C: Share wheel file directly (not recommended for updates)

Can I use this in CI/CD?¶

Yes! Example GitHub Actions workflow:

- name: Install Nova AI
  run: |
    pip install https://github.com/Jaureguy760/nova-core/releases/download/v2.19.0/nova_ai-2.19.0-py3-none-any.whl
  env:
    GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

- name: Run tests
  run: nova-ai test --headless

What if I want to contribute?¶

Clone the full repository:

git clone https://github.com/Jaureguy760/nova-core.git
cd nova_ai
pip install -e ".[dev]"
pytest

See CONTRIBUTING.md for the full contributor guide.

Quick Start - First-time setup
Onboarding Guide - Detailed installation walkthrough
Setup Wizard - Credential configuration
Pip Distribution Plan - Technical architecture

Version: 1.0.0 | Updated: 2025-12-15

Lightweight Plugin Distribution¶

Overview¶

Installation Methods¶

Method 1: GitHub Release Wheel (Recommended)¶

Method 2: Claude Code Plugin Marketplace¶

Method 3: Shallow Git Clone¶

Method 4: Private PyPI (AWS CodeArtifact)¶

What Gets Installed¶

Wheel Contents (3.4MB)¶

Excluded from Wheel¶

Post-Install: Initialize¶

Private Repository Authentication¶

GitHub CLI (Recommended)¶

Personal Access Token¶

SSH Keys¶

AWS CodeArtifact Setup¶

1. Create CodeArtifact Repository¶

2. Upload Wheel¶

3. Configure pip¶

4. Team Installation¶

Size Comparison¶

Verification¶

Updating¶

Update Wheel¶

Update via Plugin Marketplace¶

Troubleshooting¶

"Repository not found"¶

"Could not find a version that satisfies the requirement"¶

"Permission denied" during nova-ai init¶

Knowledge base download fails¶

Import errors after installation¶

Best Practices¶

For Users¶

For Organizations¶

For Contributors¶

FAQ¶

Can I install without GitHub access?¶

Do I need to clone the repo at all?¶

How do I share Nova AI with my team?¶

Can I use this in CI/CD?¶

What if I want to contribute?¶

Related Documentation¶

"Permission denied" during `nova-ai init`¶