NovaCode

An open-source terminal coding assistant that reads your project, plans changes, edits files and runs checks. Choose cloud or local models and keep useful project knowledge between sessions.

Built with Python, LangGraph, deepagents and Textual. MIT licensed.

Get started

Requires Python 3.11+, Git and uv, plus a supported model provider or a running Ollama instance with a model installed.

git clone https://github.com/Babitdor/NovaCode.git
cd NovaCode
uv sync
uv run nova

First-run setup guides provider configuration and workspace approval. Hosted models may charge for usage. To install a global nova command from this checkout, run uv tool install ., then launch nova from your project directory.

What Nova can do

• Code and verify: investigate projects, edit files, run commands and checks, and review changes with workspace and tool approvals.
• Plan and delegate: compare Council proposals, use specialist agents and coordinate project tabs with messages and Git worktrees.
• Remember: inspect and maintain a linked Markdown memory wiki, resume sessions and recover supported file snapshots.
• Choose and extend: select hosted or local models, configure an independent vision model, and add skills, plugins and MCP servers.
• Compose tools in Code Mode: toggle it below the composer to combine eligible native and MCP tools in bounded JavaScript workflows.
• Speak and listen: optional speech input and short spoken reply summaries, including lightweight CPU voice choices and model download progress.
• Make it yours: choose from 13 interface styles, including character art and optional animated home scenes.
• Work beyond the terminal: use remote chats, local web workspaces, temporary artifact previews and headless automation.

See FEATURES.md for the full catalog, setup requirements and landing-page copy.

Everyday use

Attach files with @; use Shift+Enter for a new line. For a one-shot task:

uv run nova -p "Summarize the changes in this repository"

New to a project? Start with /onboard. Inspired by Understand Anything, it parses the local workspace with the already installed Graphify language parsers and saves a persistent graph and guide in .nova/onboard/. The local artifact dashboard provides file/symbol search, directory filters, a clickable dependency map, a learning tour and incoming dependency impact tracing. It needs no Node installation, browser credentials or external dashboard assets.

Use /onboard open to reopen the dashboard, /onboard tour for a conversational tour, /onboard ask <question> for source-grounded Q&A, and /onboard impact <symbol or path> before changing code. The dashboard's Ask Nova tab prepares a command to paste into the conversation. Nova explains the architecture and business flows using its normal model and tool permissions; the initial deterministic guide contains structural facts only. Reopen the dashboard after Nova enriches the guide. Model calls use your configured provider.

/onboard refresh rebuilds after changes. File-content fingerprints detect new, edited and deleted inputs; saved analyses display a staleness notice. Scans respect Git ignore rules and skip links, generated directories and common secret filenames. Static parsing can miss dynamic dependencies; directory groups are not semantic architecture layers. Limits: 5,000 source/Markdown files, 1 MiB per file, 64 MiB total input and 32 MiB graph. The parsing deadline scales with file count and input size from two to ten minutes; Escape cancels it. Refresh replaces generated graph/guide files, so copy edited guides elsewhere before rebuilding. This command currently requires a local workspace; Plan Mode prevents building or refreshing the saved analysis.

Optional features

Install selected extras from this checkout, for example:

uv sync --extra voice --extra voice-kokoro

Keep all desired --extra flags when syncing. Speech models download on first use. See setup and usage for global installation, voice providers, browser automation and background-agent requirements.

Local computer preview: the computer extra lets Nova operate a separate Linux QEMU VM with a private live browser preview and pause/resume/stop controls. Requires QEMU, a guest-image download and 4 GiB RAM for the guest. Start with /computer start; see computer setup and limits. The Windows WHPX compatibility fix in this checkout has passed a real desktop boot.

Documentation and contributing

Setup and usage · Feature catalog · Code Mode · Permissions · Sharing · Changelog

For development, run uv sync --group dev and tests relevant to your change. See project instructions for build and check commands. Report bugs or propose changes through repository issues and pull requests.

Compression preferences

The composer selector cycles Off → Caveman → Ponytail → Off. Options saves mode, independent intensities and Caveman feature switches together; Escape discards edits. Preferences persist across restarts. Existing Caveman settings migrate automatically. Mode changes use temporary notifications and never submit your draft.

• /caveman on|off|lite|full|ultra|wenyan-lite|wenyan-full|wenyan-ultra
• /ponytail activates Ponytail without resetting its selected intensity.
• /ponytail lite|full|ultra|off|settings|status
• /ponytail-review [scope], /ponytail-audit [scope], /ponytail-debt [scope], /ponytail-gain, /ponytail-help run the corresponding one-shot helper without changing the selected mode. Review and audit request reports, not edits.
• A standalone stop ponytail or normal mode disables Ponytail. Those phrases inside an ordinary task do not change preferences.

Caveman compresses prose and optionally tool views. Ponytail applies the upstream coding rules: solve the complete problem with the least new code, preserve necessary checks, and name skipped work and risks. Ponytail leaves tool results intact and also applies to delegated model requests. Neither mode changes tool permissions. Savings depend on the task and model; shorter output is not guaranteed.

Ponytail's MIT-licensed skill bodies and JavaScript instruction builder are vendored from DietrichGebert/ponytail at 09c434ab73ca43761c5d8b0c5d341926c2fba710. Nova's Python builder is checked against golden hashes from that JavaScript builder. Nova owns the persistent selector; upstream Claude-specific band, board, install hooks and default-mode files are not used. There is no Node runtime requirement.

To validate every compression intensity against your configured LLM (20 paid/provider calls, concurrency two, 60-second timeout each), run:

uv run python -m scripts.verify_compression_live

This opt-in check preserves exact failure facts/commands and validates generated Python on boundary and invalid-bound cases. It writes synthetic outputs and reported usage (or unknown) to test-results/compression-live.json, without changing your preferences. Offline tests never call an LLM. Golden parity proves prompt equivalence; it cannot guarantee identical stochastic model responses.