NovaCode
Babitdor/NovaCode
A powerful open-source terminal-based AI coding assistant that runs in your terminal, similar to Claude Code. Built on top of the deepagents library which provides the core agent architecture.
Instalação
npx convez-ai Babitdor/NovaCode1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
README
A tradução para o português deste README ainda está na fila.

NOVA : Agentic Coding Tool
An open-source, terminal-based AI coding assistant built on LangGraph and the deepagents framework. NOVA runs entirely in your terminal with both a Rich console REPL and a Textual TUI — similar to Claude Code, but extensible and transparent.
Features
Core Intelligence
- LangGraph Agent Loop: Deep agent architecture with planning, subagents, filesystem access, and tool-calling — all orchestrated through a shared async event loop
- Multi-Provider LLM Support: OpenAI, Anthropic, Ollama, Google Gemini — configure any provider via environment variables or the onboarding wizard
- Autonomous Learning System (Hermes): Periodically reviews tool usage patterns, extracts lessons, and autonomously creates reusable skills — the agent improves itself over time without user intervention
- Memory System: Two-tier persistent memory — auto-maintained markdown files (
USER.md/MEMORY.md) plus a LangGraph key/value store (remember/recall) for cross-session facts - Steering Instructions: Persistent user-defined directives injected into every model call — set once, always respected
UI & Interaction
- Rich Console REPL: Full-featured interactive shell with
prompt-toolkit— syntax highlighting, tab completion, command history - Textual TUI: Modern terminal UI with chat messages, modals, animations, keyboard shortcuts, condensed tool groups, and click-to-copy
- Condensed Tool UI: Consecutive tool calls grouped into collapsible sections — full diffs shown for code edits; reads, searches, and other calls stay compact
- Modal Animations: Entrance effects (fade/slide/zoom) for all modal dialogs, pulsing borders, and a shimmer status bar
- Web Chat UI: Launch a local browser-based chat interface via
/chat— dark-themed, Claude-inspired, with Markdown rendering and code highlighting
Tools & Capabilities
- 25+ Built-in Tools: File operations, shell commands, web search (Tavily + DuckDuckGo), docs search, HTTP fetch, subagent delegation, semantic code search, project graph queries, and more
- Web Scraping: GitHub trending repos, Hacker News headlines, LinkedIn jobs, Reddit posts — no external API keys required
- Semantic Code Search: Find code by description or meaning, not just exact text matches (
code_search,find_related_code) - LSP Integration: Language Server Protocol support for go-to-definition, find references, rename, diagnostics, and more
- Project Graph: Visualize and query your codebase architecture — 5000+ nodes, community detection, dependency analysis, blast radius tracking
Extensibility
- MCP Support: Extend capabilities with Model Context Protocol servers (12+ presets) — tools eagerly discovered with server-prefixed names to avoid collisions
- Skills System: 50+ built-in skills with progressive disclosure — domain-specific workflows loaded on demand. Install skills from any public GitHub repo
- Plugin System: Python entry-point based plugins that can register slash commands, add middleware at defined slots, and extend the agent
- Custom Subagents: 20+ built-in specialized subagents (code review, security audit, refactoring, testing, research swarm, browser automation, frontend/backend/docker engineering, and more)
- Async Subagents: Background task execution on remote LangGraph servers — documentation updates, code reviews, test generation, dependency audits, refactoring
Sandbox & Safety
- Sandbox Execution: Run code safely in remote sandboxes — Modal, Runloop, Daytona, Docker, E2B. Default Docker sandbox with workspace binding
- Security-First: Automatic
.gitignoreenforcement, command injection detection, URL sanitization, and input validation - File Recovery: Automatic snapshots before destructive operations — restore deleted or overwritten files via
/restoreor agent tools (list_trash,restore_file) - Human-in-the-Loop (HITL): Configurable interrupt system requiring user approval before destructive or external operations
- Path Approval: Path-based operation approval for filesystem access outside the project root
Infrastructure
- Session Management: Save, restore, auto-save, and resume sessions. Compact conversation history via
/compact - Remote Bridges: Discord and Telegram integration for remote agent interaction
- Vixie Desktop Companion: Background server for desktop notifications and system tray integration
- Hooks System: Lifecycle hooks at key points (pre/post tool call, on message, on error) — shell commands or Python scripts
- Process Manager: Subprocess lifecycle, health checks, and cleanup for dev servers and background tasks
- LangSmith Tracing: Built-in LangSmith integration for debugging, monitoring, and evaluating agent runs
- Doctor Command: System diagnostics to verify your environment, API keys, and dependencies
- Onboarding System: Interactive first-run setup with secure API key management via OS keychain
- Configuration Migration: Migrate from legacy directory structure to Claude Code-compatible layout
Installation
Prerequisites
- Python 3.11 or higher
- Git for cloning the repository
- uv (recommended) or pip for package management
Step-by-Step Installation
Option 1: Install with uv (Recommended)
# 1. Clone the repository
git clone https://github.com/Babitdor/NovaCode.git
cd NovaCode
# 2. Create a virtual environment with Python 3.11+
uv venv --python 3.11
# 3. Activate the virtual environment
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Windows (Command Prompt):
.venv\Scripts\activate.bat
# On macOS/Linux:
source .venv/bin/activate
# 4. Install dependencies
uv sync
# 5. Install the package in editable mode
uv pip install -e .
Option 2: Install with pip
# 1. Clone the repository
git clone https://github.com/Babitdor/NovaCode.git
cd NovaCode
# 2. Create a virtual environment
python -m venv .venv
# 3. Activate the virtual environment
# On Windows (PowerShell):
.venv\Scripts\Activate.ps1
# On Windows (Command Prompt):
.venv\Scripts\activate.bat
# On macOS/Linux:
source .venv/bin/activate
# 4. Upgrade pip
pip install --upgrade pip
# 5. Install dependencies
pip install -e .
Verify Installation
# Check if nova is installed
nova --version
# Run system diagnostics
nova doctor
# Start the CLI
nova
API Keys Setup
Configure your preferred LLM provider by setting environment variables:
Option 1: Environment Variables (Recommended)
# OpenAI (default)
export OPENAI_API_KEY="your-openai-api-key"
# Or Anthropic
export ANTHROPIC_API_KEY="your-anthropic-api-key"
# Optional: Web search (Tavily)
export TAVILY_API_KEY="your-tavily-api-key"
Option 2: .env File
Create a .env file in your project root or home directory:
# .env file
OPENAI_API_KEY=your-openai-api-key
ANTHROPIC_API_KEY=your-anthropic-api-key
TAVILY_API_KEY=your-tavily-api-key
Option 3: Configuration File (Secure Keychain)
# Store keys securely via OS keychain
nova secrets set openai_api_key
nova secrets set anthropic_api_key
Troubleshooting
| Issue | Solution |
|---|---|
| Python version mismatch | python --version → specify version: uv venv --python 3.11 |
| Virtual env not activating (Windows) | Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser then retry |
| Package installation fails | uv cache clean && uv sync --reinstall |
| Missing dependencies | uv sync --all-extras |
| Import errors | uv pip install -e . --force-reinstall |
Development Setup
# Install development dependencies
uv sync --all-extras
# Run tests
pytest tests/
# Format and lint code
make format
make lint
# Type checking
mypy novacode_cli/
Quick Start
# Start the CLI
nova
# Use a specific agent configuration
nova --agent mybot
# Auto-approve tool usage (skip HITL prompts)
nova --auto-approve
# Execute in a remote sandbox
nova --sandbox modal
# Use the classic Rich REPL (instead of Textual TUI)
nova --legacy-ui
# Skip the splash screen
nova --no-splash
# Continue from a previous session
nova --continue
nova --continue <session-id>
# Interactively select a session to resume
nova --resume
# Force local execution (disable default Docker sandbox)
nova --no-sandbox
# Docker sandbox with port forwarding
nova --sandbox docker --ports 8080:8080,3000:3000
# Run system diagnostics
nova doctor
CLI Reference
Top-Level Subcommands
| Command | Description |
|---|---|
nova init | Initialize project or global configuration |
nova list | List all available agents |
nova help | Show help information |
nova reset --agent <name> | Reset an agent's memory/store |
nova skills | Manage agent skills (list, create, add, remove, find, update) |
nova mcp | Manage MCP servers (add, remove, list, install) |
nova config | View or edit configuration (show, set, get) |
nova secrets | Manage API keys securely (set, list, delete) |
nova doctor | Validate configuration and connections |
nova paths | Manage approved file system paths (list, revoke, clear) |
nova migrate | Migrate to new directory structure |
Flags
| Flag | Default | Description |
|---|---|---|
--agent | "nova-agent" | Agent identifier for separate memory stores |
--auto-approve | off | Auto-approve tool usage (disables HITL) |
--sandbox | none | Sandbox provider: none, modal, daytona, runloop, docker |
--no-sandbox | off | Force local execution (disables default Docker sandbox) |
--sandbox-id | None | Reuse an existing sandbox (skips create/cleanup) |
--sandbox-setup | None | Path to setup script to run in sandbox after creation |
--ports | None | Port forwarding for Docker sandbox (comma-separated) |
--no-splash | off | Disable the startup splash screen |
--tui / --legacy-ui | off | Use classic Rich REPL instead of Textual TUI |
--continue / -c | off | Continue last session (optionally specify session ID) |
--resume / -r | off | Interactively select and resume a session |
--version | — | Show version number and exit |
Interactive Slash Commands
| Command | Description |
|---|---|
/help | Show interactive help |
/exit / /quit / /q | Exit the CLI |
/clear | Clear conversation history and reset session |
/tokens | Display token usage for the session |
/context | Display current context window status |
/verbose | Toggle verbose mode (show internal agent context) |
/steer | Set persistent steering instructions for the agent |
/save | Save current session |
/compact | Compact conversation history with optional focus |
/sessions | List, select, or delete saved sessions |
/restore | Restore a previous file version from snapshots |
| Command | Description |
|---|---|
/init | Generate/update project documentation and graph |
/mcp | Interactive MCP server management menu |
/model | Display current model configuration |
/hooks | Manage lifecycle hooks (list, add, remove, enable, disable) |
/skills | Interactive skills manager |
/agents | Custom agent management (view, create, delete) |
/plugins / /plugin | Nova plugin management (list, enable, disable) |
/plan | Invoke plan-mode agent for investigation & approval |
/trace | LangSmith tracing management (status, enable, projects) |
/ralph | Autonomous looping mode (background task execution) |
/council | Launch local Council web UI (multi-agent debate) |
/chat | Launch local browser-based chat UI |
/trello | Browser-based task board server |
/research | Multi-agent research swarm (academic/market/stocks/technical/general) |
/dream | Run memory consolidation |
/browser-use | AI-powered browser automation |
/servers | Show active server processes |
/tests | Run test suites |
/kill | Kill a process by PID |
/files | Show file operation summary for the session |
/images | Manage tracked image references |
/notifications | Review and manage notifications |
/log | Show workspace log files |
/skill:<name> | Directly invoke a skill by name (e.g., /skill:api-testing) |
/remote | Manage remote sandbox connections |
/reindex | Rebuild semantic code search index |
Built-in Tools
| Tool | Description |
|---|---|
ls | List files and directories |
read_file | Read contents of a file |
write_file | Create or overwrite a file |
edit_file | Make targeted edits to existing files |
glob | Find files matching a pattern (e.g., **/*.py) |
grep | Search for text patterns across files |
shell | Execute shell commands (local mode) |
execute | Execute commands in remote sandbox (sandbox mode) |
task | Delegate work to subagents for parallel execution |
write_todos | Create and manage task lists for complex work |
think | Structured reasoning and reflection before acting |
web_search | Search the web using Tavily API |
duckduckgo_search | Web search using DuckDuckGo (no API key required) |
docs_search | Search official documentation sites |
fetch_url | Fetch and convert web pages to markdown (covers all HTTP methods) |
github_trending | Scrape GitHub trending repositories by language/time range |
hacker_news | Scrape Hacker News front page headlines |
linkedin_jobs | Search LinkedIn job listings (Playwright-based, no login) |
reddit_posts | Scrape Reddit posts by subreddit, user, or search query |
package_info | Get package version and dependency info (PyPI / npm) |
read_memory / write_memory | Read and write persistent markdown agent memories |
remember / recall | Store and fetch durable cross-session facts by key |
list_memories / forget | List and delete stored durable memory facts |
list_trash | List file snapshots available for recovery |
restore_file | Restore a deleted or overwritten file from snapshots |
query_project_graph | Query the project graph for architectural information |
code_search | Semantic code search by description or symbol name |
find_related_code | Find code semantically similar to a known location |
start_async_task | Start a background task on a remote LangGraph server |
check_async_task | Check status and result of a background task |
update_async_task | Send updated instructions to a running background task |
cancel_async_task | Cancel a running background task |
list_async_tasks | List all tracked background tasks |
Note: Potentially destructive operations require user approval. Use
--auto-approveto skip prompts.
Trello Task Board
NOVA includes a browser-based task board for managing and processing tasks visually. Start it with /trello.
/trello Start the task board server and open browser
/trello stop Stop the task board server
/trello status Show current task board state
Task Lifecycle
| Status | Description |
|---|---|
| Loaded | Task added, waiting to be processed |
| Processing | Agent is currently working on the task |
| Done | Task completed by the agent |
Web Chat UI
Launch a local browser-based chat interface with /chat:
/chat Start the chat server and open browser
/chat stop Stop the chat server
/chat status Show chat server status
- Dark-themed UI: Claude-inspired design with red accents
- Markdown Rendering: Full Markdown + syntax highlighting via
marked+highlight.js - Typing Indicator: Animated bouncing dots while the agent responds
- Same Agent: Connects to the same LangGraph agent — no separate config
Web Scraping Tools
Built-in tools that work with public data — no API keys required:
| Tool | Data Source |
|---|---|
github_trending | GitHub trending repositories |
hacker_news | Hacker News front page |
linkedin_jobs | LinkedIn job listings (Playwright) |
reddit_posts | Reddit posts by subreddit/user/search |
Standalone CLI scripts also available in scripts/scraper/.
Autonomous Learning System (Hermes)
NOVA includes Hermes, an autonomous learning system that runs in the background:
- Self-Review: Every ~10 tool calls, Hermes reviews tool usage patterns and extracts lessons
- Self-Improving Memory: Automatically maintains two memory tiers:
USER.md— User model: communication style, preferences, workflows, recurring frustrationsMEMORY.md— Cross-session memory: architecture decisions, reusable patterns, key facts
- Skill Creation: Analyzes repeated successful tool sequences and autonomously creates reusable skills with deterministic naming and refinement
- No Interruption: Reviews run out-of-band in the background — no pause in agent operation
- Live Indicator: Visible indicator in the TUI status line when Hermes is reviewing
Middleware Stack
Every model call passes through this middleware chain (in order):
| Layer | Module | Purpose |
|---|---|---|
SteeringMiddleware | bootstrap/steering.py | Injects persistent user instructions |
GraphContextMiddleware | bootstrap/graph_context.py | Injects project graph legend summary |
ShellMiddleware | shell.py | Shell tool + interactive prompt detection |
AgentMemoryMiddleware | memory/ | Agent memory loading |
SecurityMiddleware | security/ | URL sanitization, unicode attack prevention |
FileTrackerMiddleware | tracking/ | Read-before-edit enforcement |
MCPMiddleware | mcp/middleware.py | MCP tool provisioning |
NovaLearningMiddleware | hermes/middleware.py | Hermes learning system — tool call review |
Project Graph
The project graph (.nova/project-graph.json, ~5000 nodes, ~13000 edges) is built by the /init pipeline. It provides:
- Community Detection: Tightly coupled module clusters identified via graph analysis
- Central Hubs: High-degree nodes — files with wide blast radius (e.g.,
Settingswith 502 connections) - Dependency Analysis: Cross-module connections and architectural seams
- Queryable: Ask the agent
query_project_graph("Settings")to find connected modules and community structure
Refresh with /init (full rebuild) or /init --update (incremental).
Configuration
Directory Structure
Global Configuration (~/.nova/):
~/.nova/
├── agents/
│ └── default/
│ └── agent.md
├── skills/
│ └── web-research/
│ └── SKILL.md
├── hooks/
│ ├── pre_tool_call.py
│ └── post_tool_call.sh
└── trash/
└── <session-id>/
├── manifest.json
└── <snapshots>
Project Configuration (in your project root):
my-project/
├── .nova/
│ ├── NOVA.md # Project-specific context and conventions
│ ├── config.json # Project configuration
│ ├── hooks.json # Project-specific hooks
│ └── skills/ # Project-specific skills
├── .claude/ # Also supported (Claude Code compatible)
└── .nova.config.json # Project-level config (scoped)
Agent Memory
- Global (
~/.nova/agents/default/agent.md): Your personality, style, and universal preferences - Project (
.nova/NOVA.md): Project-specific context, conventions, and architecture
Skills
Manage skills with:
# List all skills
nova skills list
# Create a new skill
nova skills create my-skill
# Create a project-specific skill
nova skills create my-skill --project
# View skill details
nova skills info web-research
Installing Skills from GitHub
# Install a skill from a GitHub repo
nova skills add https://github.com/owner/repo
# Install a specific named skill from a multi-skill repo
nova skills add https://github.com/livekit/agent-skills --skill livekit-agents
# Install from a specific branch
nova skills add https://github.com/owner/repo/tree/main/my-skill
# Install as project-scoped
nova skills add https://github.com/owner/repo --project
# Overwrite an existing skill
nova skills add https://github.com/owner/repo --skill my-skill --force
What gets installed:
| Directory | Contents |
|---|---|
scripts/ | Shell scripts, automation helpers |
examples/ | Usage examples and sample code |
assets/ | Templates, config files, static resources |
references/ | Docs, cheat sheets, reference material |
prompts/ | Prompt templates |
templates/ | Code or file templates |
data/ | Data files used by the skill |
If the repository has no SKILL.md, Nova auto-generates one from the repo's README.
Built-in Subagents
NOVA includes 20+ specialized subagents, each loaded with domain-relevant skills:
Code Quality Agents
| Subagent | Description | Auto-loaded Skills |
|---|---|---|
code-explorer | Navigate, understand, and query large codebases | codebase-explorer/, graphify/ |
code-doc-Agent | Generate README, API docs, docstrings | code-documentation/ |
code-simplifier-agent | Simplify and refine code for clarity | code-review-expert/ |
reviewer-agent | Code review for correctness, security, SOLID | code-review-expert/ |
security-auditor-agent | OWASP Top 10, secrets, dependency vulns | web-research/ |
refactoring-specialist-agent | Code smells, technical debt, design patterns | improve-codebase-architecture/ |
bug-fix-agent | Systematic bug diagnosis and fix | systematic-debugging/ |
Test Agents
| Subagent | Description | Auto-loaded Skills |
|---|---|---|
test-writer-agent | Comprehensive tests (happy, edge, error) | test-driven-development/ |
testing-agent | Execute tests in sandboxes, report failures | testing-skills/, webapp-testing/ |
Browser Automation
| Subagent | Description | Auto-loaded Skills |
|---|---|---|
browser-automation-agent | Web testing, forms, screenshots, data extraction | agent-browser/, browser-use/ |
Engineering Agents
| Subagent | Description | Auto-loaded Skills |
|---|---|---|
frontend-agent | React, HTML/CSS, design systems, animations | frontend-design/, expert-css-skills/ |
backend-agent | API design, databases, auth, async patterns | backend-dev-guidelines/, async-python-patterns/ |
docker-agent | Optimized Dockerfiles, Compose stacks | docker-deploy/ |
Research Swarm Agents
| Subagent | Description | Auto-loaded Skills |
|---|---|---|
web-researcher | General web research — search, fetch, synthesize | web-research/, arxiv-search/ |
fact-checker | Verify critical claims via web search | web-research/ |
research-synthesizer | Synthesize findings into final report | — (inline only) |
literature-reviewer | Academic search (arXiv, Scholar, PubMed) | arxiv-search/, web-research/ |
market-analyst | Market sizing, competitive landscape | web-research/ |
financial-analyst | Financial statements, SEC filings, risk | web-research/, xlsx/ |
technical-researcher | Docs, GitHub repos, RFCs, version-accurate | web-research/, codebase-explorer/ |
Async Background Agents (Remote LangGraph)
| Subagent | Description |
|---|---|
documentation-update-agent | Auto-synchronize project docs and changelogs with git commits |
code-review-agent | Review uncommitted/recent changes asynchronously |
test-generation-agent | Generate/maintain test suites in the background |
dependency-audit-agent | Audit dependencies for updates and security vulnerabilities |
refactoring-agent | Analyze and improve code quality in the background |
Start any with start_async_task(), check status with check_async_task().
Hooks System
Lifecycle hooks for customizing agent behavior:
| Hook | When It Fires | Use Case |
|---|---|---|
pre_tool_call | Before a tool is executed | Validate inputs, log, modify params |
post_tool_call | After a tool completes | Process results, log, trigger notifications |
on_message | When a message is received | Filter content, add context |
on_error | When an error occurs | Custom error handling, recovery |
# List all hooks
/hooks list
# Add a hook
/hooks add pre_tool_call my_hook --command "echo 'Tool called'"
# Add a hook from a file
/hooks add post_tool_call logger --file hooks/logger.py
# Enable/disable hooks
/hooks enable my_hook
/hooks disable my_hook
Hooks can be Python scripts (full access to internals), shell commands, or any executable.
MCP Integration
Extend the agent with Model Context Protocol servers:
# Add from preset
nova mcp add brave-search --preset brave-search
nova mcp add postgres --preset postgres
nova mcp add playwright --preset playwright
# Custom HTTP transport
nova mcp add my-server --transport http --url https://example.com/mcp
# Custom stdio transport
nova mcp add my-server --transport stdio --command "python -m my_mcp_server"
Available Presets: brave-search, memory, postgres, google-drive, playwright, fetch, time, sqlite, stripe, everything, serena, context7
MCP Management:
nova mcp list # List all configured servers
nova mcp remove my-server # Remove a server
Sandbox Execution
NOVA supports multiple sandbox providers for safe code execution:
# Docker (default, with workspace binding)
nova --sandbox docker
# Modal (cloud)
nova --sandbox modal
# Runloop (cloud)
nova --sandbox runloop
# Daytona (cloud)
nova --sandbox daytona
# Force local execution
nova --no-sandbox
# Reuse an existing sandbox
nova --sandbox-id <id>
# Port forwarding (Docker)
nova --sandbox docker --ports 8080:8080
The default sandbox image is python:3.11-slim.
Plugin System
NOVA supports Python entry-point based plugins that can register slash commands and add middleware at defined slots. Plugins are discovered via the nova.plugins entry point group and can contribute:
- Slash Commands: Custom interactive commands
- Middleware: Add behavior at named slots in the middleware stack
- Skills: Domain-specific workflows
# List plugins
/plugins
# Enable/disable a plugin
/plugins enable my-plugin
/plugins disable my-plugin
File Recovery
NOVA automatically snapshots files before destructive operations:
- Files targeted by
rmshell commands — captured before deletion - Files overwritten by
write_file— previous content saved - Files modified by
edit_file— pre-edit content saved
# Interactive restore
/restore
# Restore by index
/restore 1
# Restore by path
/restore src/utils.py
Agent tools: list_trash() to see snapshots, restore_file("path") to restore.
Snapshots stored in ~/.nova/trash/<session-id>/. Files over 10 MB skipped.
Vixie Desktop Companion
NOVA includes Vixie, a background desktop companion server:
- Desktop Notifications: Task completion and status alerts
- System Tray Integration: Quick access to Nova status
- WebSocket Server: Real-time event streaming
Testing
# Run unit tests
make test
# Run all tests (including integration)
make test_all
# Run with coverage
make test_cov
# Run specific test file
make test TEST_FILE=tests/unit_tests/test_specific.py
# Watch mode
make test_watch
Test suite includes:
| Directory | What it tests |
|---|---|
tests/test_hermes/ | Hermes learning system — middleware, memory, skill discovery |
tests/test_tui_app.py | Textual TUI — animations, chat, modals, tool groups |
tests/test_workdir_grep.py | Sandbox-backed grep path-rebased execution |
tests/test_notifications.py | Notification system integration |
tests/test_context_breakdown_tokens.py | Token budget and context optimization |
Makefile Commands
| Command | Description |
|---|---|
make test | Run unit tests |
make test_integration | Run integration tests |
make test_all | Run all tests |
make test_watch | Watch mode testing |
make test_cov | Run tests with coverage |
make run | Run uv run nova |
make sync | Sync dependencies |
make lock | Lock dependencies |
make tree | Show dependency tree |
make outdated | Show outdated packages |
make add PACKAGE=<name> | Add a dependency |
make add-dev PACKAGE=<name> | Add a dev dependency |
make remove PACKAGE=<name> | Remove a dependency |
make reinstall | Full reinstall of novacode-cli + deepagents |
make run_reinstall | Reinstall then run nova |
make lint | Check formatting and linting |
make format | Auto-format code |
make clean | Clean caches |
Architecture
User Input → CLI Entry (main.py) → Agent Loop (core/agent_loop.py) → UI Renderer
Core Flow
- CLI Entry (
main.py→cli_main()) — parses args, initializesSessionState, runs optional onboarding, enters interactive REPL - Agent Loop (
core/agent_loop.py→iterate_agent_events()) — the single canonical async generator driving the LangGraph agent stream - UI Events (
ui_events.py) — dataclass instances decoupled from rendering; both Rich console and Textual TUI consume the same event types - Middleware Stack — wraps every model call (Steering → GraphContext → Shell → AgentMemory → Security → FileTracker → MCP → NovaLearning)
Module Structure
Core:
main.py— Entry point, CLI loop, argument parsingcli_session.py— Session management, auto-save, display helpersinput.py— prompt_toolkit input handling, completers, image paste, keybindings
Agent:
agents/core_agent.py— Agent creation, configuration, middleware wiringagents/default_subagents/— 20+ built-in specialized subagentsagents/plan_agent/— Plan mode agent with planning middleware
Commands:
commands/— 20+ CLI command handlers (commands/__init__.pyaggregates viaCommandRegistry)commands/chat_handler.py—/chatcommand — local web chat UI
Configuration:
config/config.py— Settings hub (502 connections), color scheme, model factory, console initconfig/nova_config.py— Persistent JSON config (~/.nova/Nova.config.json)config/model_create.py— Model instantiation for all providersconfig/model_manager.py— Model provider management
Context & Memory:
context/— Context budget tracking, eviction, optimization, growth monitoringmemory/store.py— Durable LangGraph key/value store with stdlib-fallbackprompts/— Jinja2 template rendering
Learning (Hermes):
hermes/middleware.py— NovaLearningMiddlewarehermes/memory_tiers.py— USER.md / MEMORY.md managementhermes/skill_discovery.py— Autonomous skill creation from repeated patterns
UI (Rich REPL):
ui/ui_elements.py— Token tracking, help, diff rendering, todosui/execution.py— Tool execution orchestration and approval flowui/streaming.py— Real-time output streamingui/tool_processing.py— Tool call formatting and displayui/hitl_approval.py— Human-in-the-loop approval UIui/subagent_tracking.py— Subagent progress visualization
TUI (Textual):
tui/app.py— NovaApp: chat messages, modals, keyboard shortcuts, condensed tool groups, historytui/animations.py— Fade/slide/zoom, pulsing borders, shimmer, thinking dots
Tools:
tools/— HTTP fetch, search, web scraping, package info, git, LSP, browser, memory, reflection, project graph, code search, plan mode
Integrations:
integrations/— Sandbox providers and workdir backendmcp/— MCP client, config, middleware, presetsremote/— Discord and Telegram bridge
Infrastructure:
session/— Session persistence, restore, summarization, prompt buildingstates/slices/— 5 state slices (UISettings, AgentRuntime, RemoteBridge, BackgroundTask, Notifications)states/Session.py— SessionState composite dataclassserver_runner/— Dev server and test runner lifecycleprocess_manager.py— Subprocess lifecycle, health checks, cleanuptracking/— File tracking, run logging, LangSmith, workspace anchoring
Safety & Recovery:
errors/— Error taxonomy (14 categories) and recovery handlerssecurity/— Unicode security and input validationgit_safety.py— Dangerous command detection and injection preventionfile_ops.py— File operation tracking, diff, approval previewsrecovery.py— File recovery snapshotspath_approval.py— Path-based operation approval
Specialized:
bootstrap/— Environment snapshots, project graph context, steering instructionsinit/— Project initialization (detect → extract → generate → graph)skills/— Skill loading, creation, locking, system prompt generationhitl/— Human-in-the-loop interrupt configurationvision/— Vision model supportvixie/— Desktop companion server (notifications, system tray)plugins/— Plugin systemhooks.py— Lifecycle hook dispatchcompaction.py— Conversation summarization via LLMplans.py— Plan management and persistenceonboarding.py— Interactive first-run setupdoctor.py— System diagnosticsmigrate.py— Configuration migration
Optional Dependencies
# Graph visualization
pip install novacode-cli[graphify]
# Code search
pip install novacode-cli[code-search]
# Discord bridge
pip install novacode-cli[remote-discord]
# Voice agent
pip install novacode-cli[voice]
Docker
NOVA ships with a Dockerfile and docker-compose.yml for containerized deployment:
# Build and run with docker-compose
docker-compose up --build
# Or build manually
docker build -t novacode-cli .
docker run -it --rm -v "$(pwd):/workspace" novacode-cli
Dependencies
This package depends on the deepagents library for core agent functionality, which is automatically installed as a dependency. Core dependencies include LangChain ecosystem (LangGraph, LangSmith), Rich, Textual, prompt-toolkit, and various integration libraries.
License
MIT License — see LICENSE file for details.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request