Skip to content

Configuration

Customize Nova AI behavior through configuration files.

Configuration Files

File Scope Purpose
.claude/settings.json Project Hooks, permissions, MCP servers
.claude/CLAUDE.md Project Agent instructions
~/.claude/CLAUDE.md User Global instructions

settings.json

Project-level configuration.

Hooks

{
  "hooks": {
    "Stop": [{
      "matcher": "*",
      "hooks": [{
        "type": "command",
        "command": "python .claude/hooks/lint_gate.py"
      }]
    }]
  }
}

Hook types: - Stop - End of every turn - PreToolCall - Before tool execution - PostToolCall - After tool execution

MCP Servers

{
  "mcpServers": {
    "kb": {
      "type": "sdk",
      "module": "src.orchestrator.tools.sdk_mcp_kb_server"
    },
    "github": {
      "type": "sdk",
      "module": "src.orchestrator.tools.sdk_mcp_github_server"
    }
  }
}

Permissions

{
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(git *)",
      "Bash(pytest *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)"
    ]
  }
}

CLAUDE.md

Agent instructions in markdown.

Project Instructions

.claude/CLAUDE.md:

# Project Name

## Coding Standards
- Use type hints for all functions
- Write tests for new features

## Quality Gates
- Never skip code review
- All tests must pass

User Instructions

~/.claude/CLAUDE.md:

# My Preferences

## Style
- Prefer functional programming
- Use descriptive variable names

## Tools
- Always use pytest over unittest

Environment Variables

Required

export ANTHROPIC_API_KEY="sk-ant-..."

Optional

# Model selection
export NOVA_MODEL="claude-sonnet-4-5-20250929"

# Logging
export NOVA_LOG_LEVEL="INFO"
export NOVA_LOG_FILE="nova.log"

# Performance
export NOVA_MAX_PARALLEL=4
export NOVA_TIMEOUT=600

# GitHub
export GITHUB_TOKEN="ghp_..."

Agent Configuration

Agents are defined in .claude/agents/:

# .claude/agents/implementer.md
---
name: implementer
description: Writes production code
model: claude-sonnet-4-5-20250929
tools:
  - Read
  - Write
  - Edit
  - Bash
---

# Agent Instructions

You are the Implementer agent...

Available Models

Model ID Use Case
Opus 4.5 claude-opus-4-5-20251101 Complex reasoning
Sonnet 4.5 claude-sonnet-4-5-20250929 Code generation
Haiku 4.5 claude-3-5-haiku-20241022 Mechanical tasks

Quality Gate Configuration

Lint Gate Hook

.claude/hooks/lint_gate.py:

#!/usr/bin/env python3
import subprocess
import sys

# Run ruff on changed files
result = subprocess.run(
    ["ruff", "check", "--format=json"],
    capture_output=True
)

if result.returncode != 0:
    print("LINT_GATE:FAIL", file=sys.stderr)
    sys.exit(2)

sys.exit(0)

Linter Agent

.claude/agents/linter.md:

---
name: linter
model: claude-3-5-haiku-20241022
tools:
  - Bash(ruff *)
  - Edit
---

Knowledge Base

Location

~/.nova-ai/knowledge-base/
├── faiss.index      # Vector index (5.4GB)
├── metadata.json    # Document metadata
└── config.yaml      # KB configuration

Configuration

# ~/.nova-ai/knowledge-base/config.yaml
embedding_model: text-embedding-3-small
chunk_size: 512
overlap: 50
top_k_default: 5
similarity_threshold: 0.7

Parallel Execution

# Max concurrent agents
export NOVA_MAX_PARALLEL=4

# Worktree directory
export NOVA_WORKTREE_DIR="/tmp/nova-worktrees"

Debugging

Enable verbose logging:

export NOVA_LOG_LEVEL="DEBUG"
export NOVA_LOG_FILE="nova-debug.log"

Trace agent communication:

export NOVA_TRACE_AGENTS=true

What's Next?