convez.ai
Agente
Babitdor

NovaCode

Babitdor/NovaCode

Ver no GitHub
InicialPluginScore · de 0 a 100

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/NovaCode

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 1 dia
Versão
v1.2.38
Issues abertas
0
Contribuidores
1

README

A tradução para o português deste README ainda está na fila.

Nova CLI Banner

NOVA : Agentic Coding Tool

Version License: MIT Python

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 .gitignore enforcement, command injection detection, URL sanitization, and input validation
  • File Recovery: Automatic snapshots before destructive operations — restore deleted or overwritten files via /restore or 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

IssueSolution
Python version mismatchpython --version → specify version: uv venv --python 3.11
Virtual env not activating (Windows)Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser then retry
Package installation failsuv cache clean && uv sync --reinstall
Missing dependenciesuv sync --all-extras
Import errorsuv 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

CommandDescription
nova initInitialize project or global configuration
nova listList all available agents
nova helpShow help information
nova reset --agent <name>Reset an agent's memory/store
nova skillsManage agent skills (list, create, add, remove, find, update)
nova mcpManage MCP servers (add, remove, list, install)
nova configView or edit configuration (show, set, get)
nova secretsManage API keys securely (set, list, delete)
nova doctorValidate configuration and connections
nova pathsManage approved file system paths (list, revoke, clear)
nova migrateMigrate to new directory structure

Flags

FlagDefaultDescription
--agent"nova-agent"Agent identifier for separate memory stores
--auto-approveoffAuto-approve tool usage (disables HITL)
--sandboxnoneSandbox provider: none, modal, daytona, runloop, docker
--no-sandboxoffForce local execution (disables default Docker sandbox)
--sandbox-idNoneReuse an existing sandbox (skips create/cleanup)
--sandbox-setupNonePath to setup script to run in sandbox after creation
--portsNonePort forwarding for Docker sandbox (comma-separated)
--no-splashoffDisable the startup splash screen
--tui / --legacy-uioffUse classic Rich REPL instead of Textual TUI
--continue / -coffContinue last session (optionally specify session ID)
--resume / -roffInteractively select and resume a session
--version—Show version number and exit

Interactive Slash Commands

CommandDescription
/helpShow interactive help
/exit / /quit / /qExit the CLI
/clearClear conversation history and reset session
/tokensDisplay token usage for the session
/contextDisplay current context window status
/verboseToggle verbose mode (show internal agent context)
/steerSet persistent steering instructions for the agent
/saveSave current session
/compactCompact conversation history with optional focus
/sessionsList, select, or delete saved sessions
/restoreRestore a previous file version from snapshots
CommandDescription
/initGenerate/update project documentation and graph
/mcpInteractive MCP server management menu
/modelDisplay current model configuration
/hooksManage lifecycle hooks (list, add, remove, enable, disable)
/skillsInteractive skills manager
/agentsCustom agent management (view, create, delete)
/plugins / /pluginNova plugin management (list, enable, disable)
/planInvoke plan-mode agent for investigation & approval
/traceLangSmith tracing management (status, enable, projects)
/ralphAutonomous looping mode (background task execution)
/councilLaunch local Council web UI (multi-agent debate)
/chatLaunch local browser-based chat UI
/trelloBrowser-based task board server
/researchMulti-agent research swarm (academic/market/stocks/technical/general)
/dreamRun memory consolidation
/browser-useAI-powered browser automation
/serversShow active server processes
/testsRun test suites
/killKill a process by PID
/filesShow file operation summary for the session
/imagesManage tracked image references
/notificationsReview and manage notifications
/logShow workspace log files
/skill:<name>Directly invoke a skill by name (e.g., /skill:api-testing)
/remoteManage remote sandbox connections
/reindexRebuild semantic code search index

Built-in Tools

ToolDescription
lsList files and directories
read_fileRead contents of a file
write_fileCreate or overwrite a file
edit_fileMake targeted edits to existing files
globFind files matching a pattern (e.g., **/*.py)
grepSearch for text patterns across files
shellExecute shell commands (local mode)
executeExecute commands in remote sandbox (sandbox mode)
taskDelegate work to subagents for parallel execution
write_todosCreate and manage task lists for complex work
thinkStructured reasoning and reflection before acting
web_searchSearch the web using Tavily API
duckduckgo_searchWeb search using DuckDuckGo (no API key required)
docs_searchSearch official documentation sites
fetch_urlFetch and convert web pages to markdown (covers all HTTP methods)
github_trendingScrape GitHub trending repositories by language/time range
hacker_newsScrape Hacker News front page headlines
linkedin_jobsSearch LinkedIn job listings (Playwright-based, no login)
reddit_postsScrape Reddit posts by subreddit, user, or search query
package_infoGet package version and dependency info (PyPI / npm)
read_memory / write_memoryRead and write persistent markdown agent memories
remember / recallStore and fetch durable cross-session facts by key
list_memories / forgetList and delete stored durable memory facts
list_trashList file snapshots available for recovery
restore_fileRestore a deleted or overwritten file from snapshots
query_project_graphQuery the project graph for architectural information
code_searchSemantic code search by description or symbol name
find_related_codeFind code semantically similar to a known location
start_async_taskStart a background task on a remote LangGraph server
check_async_taskCheck status and result of a background task
update_async_taskSend updated instructions to a running background task
cancel_async_taskCancel a running background task
list_async_tasksList all tracked background tasks

Note: Potentially destructive operations require user approval. Use --auto-approve to 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

StatusDescription
LoadedTask added, waiting to be processed
ProcessingAgent is currently working on the task
DoneTask 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:

ToolData Source
github_trendingGitHub trending repositories
hacker_newsHacker News front page
linkedin_jobsLinkedIn job listings (Playwright)
reddit_postsReddit 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 frustrations
    • MEMORY.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):

LayerModulePurpose
SteeringMiddlewarebootstrap/steering.pyInjects persistent user instructions
GraphContextMiddlewarebootstrap/graph_context.pyInjects project graph legend summary
ShellMiddlewareshell.pyShell tool + interactive prompt detection
AgentMemoryMiddlewarememory/Agent memory loading
SecurityMiddlewaresecurity/URL sanitization, unicode attack prevention
FileTrackerMiddlewaretracking/Read-before-edit enforcement
MCPMiddlewaremcp/middleware.pyMCP tool provisioning
NovaLearningMiddlewarehermes/middleware.pyHermes 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., Settings with 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:

DirectoryContents
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

SubagentDescriptionAuto-loaded Skills
code-explorerNavigate, understand, and query large codebasescodebase-explorer/, graphify/
code-doc-AgentGenerate README, API docs, docstringscode-documentation/
code-simplifier-agentSimplify and refine code for claritycode-review-expert/
reviewer-agentCode review for correctness, security, SOLIDcode-review-expert/
security-auditor-agentOWASP Top 10, secrets, dependency vulnsweb-research/
refactoring-specialist-agentCode smells, technical debt, design patternsimprove-codebase-architecture/
bug-fix-agentSystematic bug diagnosis and fixsystematic-debugging/

Test Agents

SubagentDescriptionAuto-loaded Skills
test-writer-agentComprehensive tests (happy, edge, error)test-driven-development/
testing-agentExecute tests in sandboxes, report failurestesting-skills/, webapp-testing/

Browser Automation

SubagentDescriptionAuto-loaded Skills
browser-automation-agentWeb testing, forms, screenshots, data extractionagent-browser/, browser-use/

Engineering Agents

SubagentDescriptionAuto-loaded Skills
frontend-agentReact, HTML/CSS, design systems, animationsfrontend-design/, expert-css-skills/
backend-agentAPI design, databases, auth, async patternsbackend-dev-guidelines/, async-python-patterns/
docker-agentOptimized Dockerfiles, Compose stacksdocker-deploy/

Research Swarm Agents

SubagentDescriptionAuto-loaded Skills
web-researcherGeneral web research — search, fetch, synthesizeweb-research/, arxiv-search/
fact-checkerVerify critical claims via web searchweb-research/
research-synthesizerSynthesize findings into final report— (inline only)
literature-reviewerAcademic search (arXiv, Scholar, PubMed)arxiv-search/, web-research/
market-analystMarket sizing, competitive landscapeweb-research/
financial-analystFinancial statements, SEC filings, riskweb-research/, xlsx/
technical-researcherDocs, GitHub repos, RFCs, version-accurateweb-research/, codebase-explorer/

Async Background Agents (Remote LangGraph)

SubagentDescription
documentation-update-agentAuto-synchronize project docs and changelogs with git commits
code-review-agentReview uncommitted/recent changes asynchronously
test-generation-agentGenerate/maintain test suites in the background
dependency-audit-agentAudit dependencies for updates and security vulnerabilities
refactoring-agentAnalyze 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:

HookWhen It FiresUse Case
pre_tool_callBefore a tool is executedValidate inputs, log, modify params
post_tool_callAfter a tool completesProcess results, log, trigger notifications
on_messageWhen a message is receivedFilter content, add context
on_errorWhen an error occursCustom 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 rm shell 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:

DirectoryWhat it tests
tests/test_hermes/Hermes learning system — middleware, memory, skill discovery
tests/test_tui_app.pyTextual TUI — animations, chat, modals, tool groups
tests/test_workdir_grep.pySandbox-backed grep path-rebased execution
tests/test_notifications.pyNotification system integration
tests/test_context_breakdown_tokens.pyToken budget and context optimization

Makefile Commands

CommandDescription
make testRun unit tests
make test_integrationRun integration tests
make test_allRun all tests
make test_watchWatch mode testing
make test_covRun tests with coverage
make runRun uv run nova
make syncSync dependencies
make lockLock dependencies
make treeShow dependency tree
make outdatedShow 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 reinstallFull reinstall of novacode-cli + deepagents
make run_reinstallReinstall then run nova
make lintCheck formatting and linting
make formatAuto-format code
make cleanClean caches

Architecture

User Input → CLI Entry (main.py) → Agent Loop (core/agent_loop.py) → UI Renderer

Core Flow

  1. CLI Entry (main.py → cli_main()) — parses args, initializes SessionState, runs optional onboarding, enters interactive REPL
  2. Agent Loop (core/agent_loop.py → iterate_agent_events()) — the single canonical async generator driving the LangGraph agent stream
  3. UI Events (ui_events.py) — dataclass instances decoupled from rendering; both Rich console and Textual TUI consume the same event types
  4. Middleware Stack — wraps every model call (Steering → GraphContext → Shell → AgentMemory → Security → FileTracker → MCP → NovaLearning)

Module Structure

Core:

  • main.py — Entry point, CLI loop, argument parsing
  • cli_session.py — Session management, auto-save, display helpers
  • input.py — prompt_toolkit input handling, completers, image paste, keybindings

Agent:

  • agents/core_agent.py — Agent creation, configuration, middleware wiring
  • agents/default_subagents/ — 20+ built-in specialized subagents
  • agents/plan_agent/ — Plan mode agent with planning middleware

Commands:

  • commands/ — 20+ CLI command handlers (commands/__init__.py aggregates via CommandRegistry)
  • commands/chat_handler.py — /chat command — local web chat UI

Configuration:

  • config/config.py — Settings hub (502 connections), color scheme, model factory, console init
  • config/nova_config.py — Persistent JSON config (~/.nova/Nova.config.json)
  • config/model_create.py — Model instantiation for all providers
  • config/model_manager.py — Model provider management

Context & Memory:

  • context/ — Context budget tracking, eviction, optimization, growth monitoring
  • memory/store.py — Durable LangGraph key/value store with stdlib-fallback
  • prompts/ — Jinja2 template rendering

Learning (Hermes):

  • hermes/middleware.py — NovaLearningMiddleware
  • hermes/memory_tiers.py — USER.md / MEMORY.md management
  • hermes/skill_discovery.py — Autonomous skill creation from repeated patterns

UI (Rich REPL):

  • ui/ui_elements.py — Token tracking, help, diff rendering, todos
  • ui/execution.py — Tool execution orchestration and approval flow
  • ui/streaming.py — Real-time output streaming
  • ui/tool_processing.py — Tool call formatting and display
  • ui/hitl_approval.py — Human-in-the-loop approval UI
  • ui/subagent_tracking.py — Subagent progress visualization

TUI (Textual):

  • tui/app.py — NovaApp: chat messages, modals, keyboard shortcuts, condensed tool groups, history
  • tui/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 backend
  • mcp/ — MCP client, config, middleware, presets
  • remote/ — Discord and Telegram bridge

Infrastructure:

  • session/ — Session persistence, restore, summarization, prompt building
  • states/slices/ — 5 state slices (UISettings, AgentRuntime, RemoteBridge, BackgroundTask, Notifications)
  • states/Session.py — SessionState composite dataclass
  • server_runner/ — Dev server and test runner lifecycle
  • process_manager.py — Subprocess lifecycle, health checks, cleanup
  • tracking/ — File tracking, run logging, LangSmith, workspace anchoring

Safety & Recovery:

  • errors/ — Error taxonomy (14 categories) and recovery handlers
  • security/ — Unicode security and input validation
  • git_safety.py — Dangerous command detection and injection prevention
  • file_ops.py — File operation tracking, diff, approval previews
  • recovery.py — File recovery snapshots
  • path_approval.py — Path-based operation approval

Specialized:

  • bootstrap/ — Environment snapshots, project graph context, steering instructions
  • init/ — Project initialization (detect → extract → generate → graph)
  • skills/ — Skill loading, creation, locking, system prompt generation
  • hitl/ — Human-in-the-loop interrupt configuration
  • vision/ — Vision model support
  • vixie/ — Desktop companion server (notifications, system tray)
  • plugins/ — Plugin system
  • hooks.py — Lifecycle hook dispatch
  • compaction.py — Conversation summarization via LLM
  • plans.py — Plan management and persistence
  • onboarding.py — Interactive first-run setup
  • doctor.py — System diagnostics
  • migrate.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.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request
Ver o original no GitHub

Bom para

Relacionados