Nova is an experimental, tool-using AI agent written in Python. It connects a language model to a real tool system so it can understand a request, plan work, call tools, inspect the results, revise its plan, and verify whether an operation actually succeeded.
Nova is an agent application, not a newly trained foundation model. You choose the model that powers it. Nova provides the orchestration, tools, permissions, memory, interfaces, and verification around that model.
Choose your model · Give it tools · Observe its work · Verify the result
Status: active development / experimental. Features and safety boundaries can change. Nova can execute programs and modify files when those capabilities are enabled. Read the security notes before using it on important data.
- What Nova can do
- Architecture
- Native tool loop
- Model providers
- Task execution flow
- Tools and permissions
- NoviqX GitHub App
- NoviqX MCP server
- Memory system
- Interfaces
- Downloads & SmartScreen
- Requirements
- Quick start
- Configuration
- Commands
- Project structure
- Development and tests
- Repository snapshot
- Docker
- Security and privacy
- Roadmap
- Changelog
- License
Nova's actual capabilities depend on the tools that load, enabled permissions, optional packages, and the configured model.
- Plan tasks: turn natural-language requests into multi-step plans.
- Use tools: work with files, run supported programs, search the web, and use Git.
- Inspect before acting: discover files and read real content instead of assuming what exists.
- Re-plan: use tool results and errors to revise the remaining steps.
- Verify actions: distinguish confirmed, failed, and unverifiable operations.
- Use memory: maintain conversation context, long-term facts, knowledge records, and summaries of previous tool outcomes.
- Inspect itself: report runtime components, model metadata when available, tools, permissions, and diagnostics.
- Show what it is doing: a live activity chip above the composer in the desktop GUI (and the terminal status line) names the current phase in human words — Thinking, Searching the web, Reading the file, Writing — instead of an opaque wait.
- Switch model backends: run a local Ollama model, connect to an OpenAI-compatible API (OpenRouter, Groq, Together, vLLM, LM Studio, ...), or use Anthropic's native Messages API.
- Use different interfaces: Textual terminal UI, prompt_toolkit CLI, legacy Rich UI, and an optional PySide6 desktop GUI.
- Edit GitHub as your own App: the NoviqX integration commits through a GitHub App you own (with a first-run setup wizard), and its tools are also exposed through a local MCP server for other MCP clients.
Nova does not guarantee that every model will plan or use tools correctly. Smaller models may need more retries or produce invalid tool arguments. Review important operations.
Nova separates the language model from the Python application that controls tools and state.
| Layer | Responsibility |
|---|---|
| User interface | Accept requests and display responses, activity, and runtime status |
| NovaCore | Coordinate tasks, memory, tools, permissions, and execution state |
| Model provider | Generate responses through Ollama, an OpenAI-compatible API, or Anthropic |
| Planner | Propose and update task steps |
| Tool router | Interpret model-selected tool calls and route them |
| Tool registry | Store handlers, descriptions, schemas, capabilities, and verifier metadata |
| Permission layer | Control which capability groups are enabled |
| Verifier | Check tool outcomes against observable state |
| Memory services | Maintain conversation and persisted memory |
| NoviqX integration | GitHub App identity (JWT → installation token), repository file tools, and a local MCP server |
| Diagnostics / introspection | Report observable runtime and model information |
The model decides whether to answer directly or request one or more tools. For providers that support native function calling, Nova uses a tool-call loop: it sends the live registry schemas, executes each validated call locally, returns the result in the provider's tool-message format, and asks the model what to do next. Nova executes multiple calls from one model turn serially to preserve predictable ordering. The model does not grant itself permissions or manufacture successful tool results. Nova's Python code enforces session permissions, validates arguments, executes handlers, and attaches verifier evidence before returning the result to the model.
The planner/router path remains available for backends that do not expose native tool calls and for explicit structured planning workflows.
- NovaCore — agent/core.py: creates the configured model backend, memory services, tool registry, planner, router, verifier, diagnostics, and execution state. It coordinates each task.
- Planner — agent/planner.py: asks the model to create and update a structured plan.
- ToolRouter — agent/router.py: extracts structured tool requests from model output and maps them to registered tools.
- ToolRegistry — tools/registry.py: stores tool callables and metadata, including capability groups, input schemas, optional input preparation, and verifier methods.
- Verifier — agent/verifier.py: checks whether operations succeeded using filesystem state, command results, or tool-specific checks where implemented.
- SelfReflection — agent/self_reflection.py: compares plan state with verifier evidence. It is an evidence audit, not a claim that the model's private reasoning is correct.
- SelfKnowledge and introspection: report Nova's components and observed runtime configuration. Unknown metadata should remain unknown rather than guessed.
Tool definitions are data-driven. The manifest at config/tools.json is read by tools/init.py, which imports configured handler classes and registers enabled tools. The live registry is the source of truth for tools available in a particular run.
- Receive: Nova receives the request and prepares relevant conversation, memory, and live tool-registry context.
- Choose: the model decides whether it can answer directly or needs one or more registered tools.
- Validate: Nova checks each requested tool against the live registry, JSON schema, and session capability permissions.
- Execute: the registered Python handler runs locally. Calls requested together are executed serially.
- Verify and return: Nova checks the result where a verifier exists, then returns the real output and verification status to the model as a tool result.
- Continue: the model chooses the next tool call or provides its final response. The loop is bounded to prevent unending tool cycles.
- Report: Nova returns the model's answer while preserving the distinction between confirmed, failed, and unverifiable actions.
A simple conversation may not need planning or tools.
All three bundled providers implement a shared generation interface plus a native tool-call turn interface. This lets the same model-driven tool loop work with local Ollama models, OpenAI-compatible remote APIs, and Anthropic.
The local provider uses the Ollama Python client and an Ollama server.
- Configure the model with NOVA_MODEL.
- If no model name is configured, Nova attempts to discover an installed Ollama model.
- Context and output budgets are configurable.
- Transient server errors are retried automatically: while a model is still loading or every runner is busy, Ollama answers 503, and Nova retries with a growing backoff (1s, 2s, 4s, 8s, 16s — about 31s total). Tune the number of attempts with NOVA_OLLAMA_RETRIES (default 6). Failures past the last retry produce a clear explanation and a
ollama pshint instead of a raw error dump. - The local server always bypasses system proxies: Nova adds
localhost,127.0.0.1and::1to NO_PROXY before the Ollama client is built (the ollama package constructs its httpx client eagerly at import time, baking proxy mounts from the environment), because proxy clients (VPN tools) otherwise intercept requests to the local Ollama server — a live proxy answers with an empty-body 503, a dead one (stale variables after the VPN exits) refuses the connection — even whileollama runworks in a terminal. Remote providers keep using the proxy. Connection-refused failures get a targeted message (check Ollama is running; clear leftover proxy variables). - Model metadata can be queried from Ollama when available.
- When Ollama runs on the same computer, inference can remain on that computer.
Install Ollama: https://ollama.com/download
Example:
ollama pull qwen2.5:3b
ollama listThis is only an example model. You can use another model supported by your Ollama installation.
The remote provider uses the standard chat-completions HTTP protocol. It is intended to work with services exposing an OpenAI-compatible endpoint, such as OpenAI, OpenRouter, Groq, Together, Fireworks, DeepSeek, or compatible self-hosted gateways such as vLLM and LM Studio.
Configure these environment variables:
- NOVA_PROVIDER=remote
- NOVA_API_BASE_URL
- NOVA_API_MODEL
- NOVA_API_KEY
The remote client uses Python's standard library rather than requiring a vendor SDK. It supports JSON-mode requests where accepted by the provider, timeouts, retries for ordinary text generations, rate-limit handling, and API-key redaction in error text. Native tool-call turns use the provider's structured function-call protocol and are not automatically retried, because replaying an ambiguous timed-out call could duplicate a side effect.
Privacy difference: with a remote provider, prompts, tool results, and file contents included in a request are sent to that provider. Nova's tools may still execute locally, but the reasoning model runs remotely. Review the provider's data policy before enabling remote mode.
Claude is also available natively through Anthropic's own protocol, without routing through an OpenAI-compatible gateway:
export NOVA_PROVIDER=remote
export NOVA_API_PROVIDER=anthropic
export NOVA_API_MODEL=claude-sonnet-4
export NOVA_API_KEY=sk-ant-...NOVA_API_PROVIDER defaults to openai; set it to anthropic to switch protocol. The adapter lives in model/anthropic.py, uses the same tool-call loop, the same privacy rules, and the same retry semantics as the OpenAI-compatible client. On Windows, replace export with set.
| NOVA_PROVIDER | Behaviour |
|---|---|
| local | Use Ollama (default) |
| remote | Require a configured remote API; fail clearly if configuration is incomplete |
| auto | Use remote only when a remote model and API key are configured; otherwise use Ollama |
Nova intentionally does not silently switch from a selected remote model to a local model after a provider failure. Silent fallback could hide which model is answering and where prompts are being processed.
The optional PySide6 desktop application includes settings for selecting a local model or entering a remote API base URL, model name, and key. These settings are applied to the same NOVA environment configuration used by the provider layer.
The current implementation stores settings in the Nova settings JSON file, including the API key, and attempts to restrict file permissions on supported systems. This is best-effort protection, not an operating-system credential vault. Keep the settings file private and never commit it.
The default manifest currently defines 12 tools:
| Tool | Capability | What it does |
|---|---|---|
| web_search | web | Search the public web and return result titles, URLs, and snippets |
| list_files | pc | List entries in a workspace directory |
| read_file | pc | Read text files |
| find_files | pc | Discover files by glob pattern and optional age filters |
| edit_file | pc | Replace a specific text block in an existing file |
| write_file | pc | Create or overwrite files with complete content |
| terminal | pc | Run one supported non-interactive program with arguments |
| git | git | Perform supported local Git operations |
| github | git | Read-only GitHub inspection through the authenticated gh CLI |
| noviqx_github_get_file | git | Read a remote GitHub file using the dedicated NoviqX App identity |
| noviqx_github_update_file | git | Update a remote GitHub file with stale-write protection and independent verification |
| desktop | pc | Optional GUI and desktop actions |
A tool being present in the manifest does not guarantee that it loads successfully. Optional dependencies, platform support, authentication, and runtime conditions can affect availability. Check /tools or /self in a running session.
- Web: public web search.
- Git: local Git and read-only GitHub operations.
- PC: filesystem, terminal, and desktop operations.
The default manifest enables all three groups. You can toggle them during a terminal session with /web, /git, and /pc. These switches control Nova's tool access; they are not a replacement for operating-system security or process isolation.
Filesystem tools support workspace locations such as:
- projects: Nova's configured project workspace; the default for most file operations.
- desktop: the user's Desktop directory.
- system: absolute paths, subject to protected-path checks and operation restrictions.
Use each tool's live input schema for exact path rules. The terminal tool is intentionally narrower than a general shell: it accepts a program and arguments, and does not provide arbitrary shell pipelines, redirects, command chaining, or inline interpreter code. Use the dedicated file tools for file operations.
The github tool uses the locally authenticated GitHub CLI and is read-only. It can inspect repositories, issues, pull requests, workflow runs, releases, and code search. It cannot create, modify, merge, or delete GitHub resources. Local Git operations are provided separately by the git tool.
The noviqx_github_get_file and noviqx_github_update_file tools let Nova read and edit GitHub repository files through a GitHub App you own, not via a personal access token. This is the recommended way to give an agent write access to repositories: the App scopes every action to a specific installation, every commit is authored by the App bot (not your user), and the App can be revoked or rotated independently of your account credentials.
Each user creates their own GitHub App. Nova never shares, ships, or brokers a .pem between users. The three pieces you provide:
- App ID — the numeric ID on your App's "General → About" page
- Installation ID — the number at the end of the installation URL (
/settings/installations/<ID>) - Private key path — where you saved the
.pemGitHub generated for the App
The .pem content is never read by Nova beyond the moment GitHubAppAuth signs a short-lived JWT (8-minute lifetime) to exchange for an installation access token. The path is stored in ~/.nova/noviqx.json with mode 0600 (owner-only). The .pem itself stays wherever you put it.
When you launch the desktop UI and NoviqX isn't configured yet, a setup wizard appears automatically. It walks you through:
- Creating a GitHub App (with the exact permission checklist: Contents + Pull requests = Read & write, Metadata = Read-only, Webhook = off)
- Entering your App ID, installation ID, and selecting the
.pem - Testing the connection for real (signs a JWT, exchanges for a token, reads one repository) before saving
- Optionally clicking "Never show this again" to suppress the prompt permanently
You can re-open the wizard any time from Settings → NoviqX GitHub App… in the desktop UI.
If you prefer the terminal or are running Nova headlessly, set the same three values via environment variables (which take priority over the settings file):
export NOVIQX_APP_ID=1234567
export NOVIQX_INSTALLATION_ID=9876543
export NOVIQX_PRIVATE_KEY_PATH=/secure/path/to/your-app.private-key.pemRun the bundled smoke test to verify the pipeline end-to-end against real GitHub:
python scripts/noviqx_smoke_test.py --repo owner/scratch-repo --writeOnce configured, just ask Nova to do something with a repository. It will automatically pick the right tool:
- "Read README.md from owner/repo using the NoviqX GitHub App." — exercises
noviqx_github_get_file - "Update the NOVIQX_SMOKE.md file in owner/repo to say 'verified'." — exercises the full read-then-write loop with expected-SHA optimistic locking
The agent is trained to always read the file first (to obtain its blob SHA) before writing. Stale-write protection rejects updates where the file changed between read and write, and Nova re-reads automatically.
- Your
.pemnever leaves the machine Nova is running on - Each user holds their own App; if one user misbehaves, GitHub suspends their App, not yours
- All token lifetimes are short (≤10 min) and auto-refresh on 401
- The settings file is
0600and never contains the.pemcontent itself — only its path - The wizard's connection test exercises the exact same code path the agent uses at runtime, so a passing test means the agent can talk to GitHub
The NoviqX integration also ships a local MCP server (stdio) that exposes the same GitHub operations to any MCP-capable client — Nova or another agent entirely:
python -m pip install -r requirements-noviqx.txt
python -m integrations.noviqx.mcp_serverSet the same three NOVIQX_* variables, then point your MCP client at the command above. Full walkthrough: docs/noviqx-mcp.md.
Nova uses separate memory components for different kinds of context.
| Component | Purpose |
|---|---|
| Short-term memory | Recent conversation context for the current session |
| Long-term memory | Selected user facts stored for later sessions |
| Knowledge memory | Topic/fact records with source, confidence, verification time, and optional expiry |
| Episodic memory | Bounded summaries of previous tool outcomes |
| Memory extractor | Selects candidate long-term facts from conversation using the configured model |
Episodic memory stores concise task/tool outcome summaries rather than raw tool inputs and full raw tool outputs. Records are bounded and can have statuses such as confirmed, failed, and unverifiable. Secret-like strings are filtered before episodic summaries are saved, but this is a safeguard, not a guarantee.
Short-term memory is sent to the model as real alternating user/assistant chat turns (newest-first, capped at 12 messages / 6,000 characters) rather than a flattened transcript inside the context block. This keeps each provider's native multi-turn format intact and anchors follow-up references like "this" or "it" to the previous topic.
Memory is local application data. Do not ask Nova to store passwords, API keys, access tokens, private keys, or other secrets. Do not commit runtime memory files.
Nova has several front ends over the same agent core.
| Interface | Command | Description |
|---|---|---|
| Textual terminal UI | python main.py | Default full-screen terminal application |
| prompt_toolkit CLI | python main.py --prompt-toolkit | Alternative interactive terminal interface |
| Rich interface | python main.py --rich | Earlier Rich-based terminal interface |
| PySide6 desktop GUI | python App.py | Optional desktop application; requires optional GUI dependencies |
The Textual and prompt_toolkit interfaces use the same core orchestration. The desktop GUI is an optional front end and requires PySide6.
Prebuilt Windows binaries are attached to each GitHub Release and are built automatically by GitHub Actions from this public repository — the exact source you see here is what gets compiled.
"Windows protected your PC" warning? Nova.exe is not code-signed yet (signing certificates cost money that this free project doesn't have). This is a standard SmartScreen warning for any new unsigned app, not a virus detection. To run the installer/app anyway, click More info → Run anyway.
Verify your download before running it. Every release ships a SHA256SUMS.txt file; compare it against your downloaded file in PowerShell:
Get-FileHash .\Nova.exe -Algorithm SHA256The hash must match the value in SHA256SUMS.txt of the same release. If it doesn't match, don't run it — re-download from the official releases page.
Antivirus false positive? Report the file to Microsoft so it gets whitelisted: microsoft.com/wdsi/filesubmission.
- Python 3.11 or newer.
- Ollama and at least one downloaded model for local inference, or credentials for a compatible remote API.
- Git installed for local Git features.
- gh CLI authenticated with gh auth login for read-only GitHub integration.
- Windows, Linux, or macOS for the core terminal agent. Individual optional tools may have narrower platform requirements.
Core dependencies in requirements.txt:
- ollama
- rich
- textual
- prompt_toolkit
- Markdown
- bleach
- pymdown-extensions
- PyJWT[crypto] (NoviqX GitHub App signing)
Optional dependencies in requirements-optional.txt include PySide6, desktop automation, OCR, image processing, and local image-generation packages. Some extras require separate system software or model files. For example, pytesseract also needs the Tesseract OCR application.
requirements-noviqx.txt installs the MCP SDK (mcp) needed only for the standalone NoviqX MCP server.
git clone https://github.com/sepehrtaji-dev/Nova-agent.git
cd Nova-agentWindows PowerShell
py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pipLinux / macOS
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pippython -m pip install -r requirements.txtFor the optional desktop GUI and integrations:
python -m pip install -r requirements-optional.txtInstall optional extras only if you need them. Some packages, especially local image-generation stacks, can be large and may need compatible hardware and separately downloaded model files.
Local Ollama
Install and start Ollama, then download a model:
ollama pull qwen2.5:3b
ollama listRemote API — PowerShell example
$env:NOVA_PROVIDER = "remote"
$env:NOVA_API_BASE_URL = "https://api.openai.com/v1"
$env:NOVA_API_MODEL = "your-model-name"
$env:NOVA_API_KEY = "your-api-key"Use the base URL and model name supplied by your provider. Never put a real API key in a committed file, issue, screenshot, or log.
python main.pyThe default launch opens the Textual terminal interface. See Interfaces for alternatives.
Desktop GUI: python App.py (requires requirements-optional.txt). On first launch, if NoviqX isn't configured yet, the setup wizard appears automatically.
| Variable | Default / behaviour | Purpose |
|---|---|---|
| NOVA_PROVIDER | local | Select local, remote, or auto |
| NOVA_API_PROVIDER | openai | Remote protocol: openai (chat-completions) or anthropic (Messages API) |
| NOVA_MODEL | Auto-detect installed Ollama model if empty | Local model name |
| NOVA_API_BASE_URL | https://api.openai.com/v1 | API base URL (Anthropic default: https://api.anthropic.com) |
| NOVA_API_MODEL | Required for remote mode | Remote model identifier |
| NOVA_API_KEY | Required for remote mode | Remote API credential |
| NOVA_API_TIMEOUT | 120 seconds | Remote request timeout |
| NOVA_NUM_CTX | 8192 | Requested local Ollama context budget |
| NOVA_NUM_PREDICT | 1536 in current Ollama adapter | Requested local output-token budget |
| NOVA_MAX_STEPS | 12 | Maximum task execution steps |
| OLLAMA_HOST | Ollama client default | Ollama server address |
| NOVA_HOME | ~/.nova | Base directory for desktop settings |
| NOVA_SETTINGS_FILE | ~/.nova/settings.json | Override desktop settings file |
| NOVA_TOOL_MANIFEST | config/tools.json | Override tool manifest |
| NOVA_EPISODIC_MEMORY_PATH | memory/episodic.json | Override episodic-memory storage |
| NOVA_IMAGE_MODEL_PATH | Not set | Optional local image model path |
| NOVIQX_APP_ID | Not set | NoviqX GitHub App ID (overrides the settings file) |
| NOVIQX_INSTALLATION_ID | Not set | NoviqX App installation ID |
| NOVIQX_PRIVATE_KEY_PATH | Not set | Path to the App's .pem private key |
Docker Compose supplies its own default model (qwen2.5:3b) and context/output settings. Environment variables can override those values.
Windows PowerShell
$env:NOVA_PROVIDER = "local"
$env:NOVA_MODEL = "your-installed-ollama-model"
python main.pyLinux / macOS
export NOVA_PROVIDER=local
export NOVA_MODEL=your-installed-ollama-model
python main.pyUse a model actually installed in your Ollama instance. Performance and memory requirements depend on model size, quantization, context length, and available hardware.
Use /help inside the running terminal interface to see the commands supported by that UI version.
| Command | Purpose |
|---|---|
| /help | Show available commands |
| /status | Show runtime status |
| /self | Inspect Nova's runtime profile and components |
| /model | Query model metadata when supported by the active backend |
| /tools | List registered tools and capability states |
| /doctor | Run runtime diagnostics |
| /permissions | Show capability permissions |
| /web | Toggle web access |
| /git | Toggle Git and GitHub access |
| /pc | Toggle filesystem, terminal, and desktop access |
| /memory | Inspect long-term memory entries |
| /forget category key | Remove a matching long-term memory entry |
| /clear | Clear the current terminal view |
| /reset | Start a new Nova session |
| /exit | Exit Nova |
Some commands vary between interfaces and may evolve. Runtime /help output is authoritative.
The repository is organized by responsibility instead of placing all agent logic in one file.
Nova-agent/
├── agent/ # Agent orchestration and decision workflow
│ ├── core.py # NovaCore: connects agent services
│ ├── router.py # Parses and routes model-selected tool calls
│ ├── tool_loop.py # Native tool-calling conversation loop
│ ├── planner.py # Creates and updates task plans
│ ├── verifier.py # Verifies observable tool outcomes
│ ├── self_knowledge.py # Nova's self-knowledge component
│ ├── self_reflection.py # Evidence-based completion audit
│ ├── introspection.py # Runtime and model inspection
│ ├── capability_probe.py # Live capability/model probes
│ ├── tool_awareness.py # Builds tool context from the registry
│ ├── diagnostics.py # Runtime diagnostics
│ └── identity.py # Static Nova identity
│
├── model/ # Model provider adapters
│ ├── provider.py # Selects the active backend
│ ├── ollama.py # Local Ollama implementation
│ ├── remote.py # OpenAI-compatible API implementation
│ ├── anthropic.py # Anthropic Messages API implementation
│ └── ... # Shared prompts and model helpers
│
├── tools/ # Executable capabilities
│ ├── __init__.py # Loads tools from the manifest
│ ├── registry.py # Tool registry and metadata
│ ├── filesystem.py # File and directory operations
│ ├── terminal.py # Restricted program execution
│ ├── web.py # Public web search/fetch
│ ├── git.py # Local Git operations
│ ├── github.py # Read-only GitHub CLI integration
│ ├── desktop.py # Optional desktop automation
│ └── ... # Tool-specific helpers
│
├── integrations/ # External-service integrations
│ └── noviqx/ # NoviqX GitHub App (bring-your-own-App)
│ ├── auth.py # JWT → installation-token auth chain
│ ├── github_api.py # Repository read/update with SHA locking
│ ├── mcp_server.py # Local stdio MCP server
│ ├── registry_tools.py # Agent-side tool handlers
│ └── settings.py # Credential store (mode 0600)
│
├── memory/ # Memory and persistence
│ ├── manager.py # Long-term memory manager
│ ├── extractor.py # Candidate fact extraction
│ ├── short_term.py # Conversation context
│ ├── knowledge.py # Topic/fact knowledge store
│ └── episodic.py # Bounded tool-outcome history
│
├── config/
│ ├── tools.json # Declarative tool/capability manifest
│ ├── runtime.py # Loads manifest settings
│ └── model_settings.py # Desktop model settings persistence
│
├── ui/
│ ├── launcher.py # Selects terminal interface
│ ├── textual_app.py # Default Textual UI
│ ├── prompt_cli.py # prompt_toolkit interface
│ ├── figma_desktop.py # PySide6 desktop shell
│ ├── markdown_renderer.py # Safe Markdown rendering for the GUI
│ └── noviqx_setup_wizard.py # First-run NoviqX setup wizard
│
├── utils/ # Shared helpers and utilities
├── scripts/ # Integration and maintenance scripts
│ └── noviqx_smoke_test.py # Real end-to-end NoviqX pipeline test
├── docs/ # Feature deep-dives (tool loop, NoviqX MCP, remote providers)
├── assets/ # Nova logo and UI assets
├── tests/ # Unit and regression tests
├── sandbox/ # Sandbox-related code
├── projects/ # Runtime workspace (normally Git-ignored)
├── App.py # Optional PySide6 desktop GUI
├── main.py # Terminal UI launch entry point
├── requirements.txt # Core dependencies
├── requirements-noviqx.txt # MCP SDK for the standalone server
├── requirements-optional.txt # Optional integrations
├── version.txt # Current version
├── CHANGELOG.md # Release-by-release changes
├── Dockerfile # Container image
├── docker-compose.yml # Nova + Ollama Compose setup
├── .github/workflows/ # CI + Windows EXE release builds
├── LICENSE
└── README.md
The diagram highlights the main modules; individual helper files and tests are omitted.
Run the tests from the repository root:
python -m unittest discover -s tests -p "test_*.py"Compile the Python sources:
python -m compileall -q agent tools memory model ui main.py App.pySmoke-test the terminal UI imports:
python -c "from ui.textual_app import NovaTextualApp; from ui.prompt_cli import main; print('UI imports OK')"GitHub Actions currently:
- Checks out the repository.
- Sets up Python 3.11.
- Compiles all Python sources, including integrations/noviqx.
- Installs core dependencies, the NoviqX MCP SDK, and PySide6 (plus Qt runtime libraries on Linux).
- Smoke-tests the PySide6 desktop shell offscreen and both terminal UI imports.
- Runs the unit/regression test suite via
unittest discover. - Builds the Docker image if earlier steps pass.
A separate workflow (build-exe.yml) builds the Windows Nova.exe with PyInstaller on every release tag and attaches it — together with a SHA256SUMS.txt checksum file — to the GitHub Release.
Tests use controlled test doubles for many model and tool paths. A green test run does not mean every provider, desktop action, or real-world integration has been exercised.
These figures are a source-repository snapshot from the review on 12 November 2026 (v2.3). They exclude runtime memory, downloaded models, virtual environments, and user workspace files.
| Metric | Snapshot |
|---|---|
| Tracked files | 133 |
| Python files | 114 |
| Test files | 48 |
| Tracked file content | ~2.9 MB |
| Tools in default manifest | 12 |
| Default capability groups | 3 (web, git, pc) |
| Model backends | 3 (Ollama, OpenAI-compatible API, Anthropic) |
| Terminal interfaces | 3 |
| Optional desktop GUI | PySide6 |
The latest release is v2.3 (November 2026). It brought the agentic native tool loop, the NoviqX GitHub App integration (MCP server + first-run setup wizard), conversation history passed as real chat turns (the short-term-memory / pronoun fix), math-parser corrections, and automated Windows Nova.exe release builds with published SHA256 checksums. CHANGELOG.md documents the details.
The current regression suite runs 468 passed, 5 skipped on Linux; CI additionally smoke-tests the PySide6 desktop shell offscreen and builds the Docker image. Recent fixes include conversation staying alive when no tools are enabled (a missing manifest or disabled capability no longer mutes the assistant), automatic retries for transient Ollama 5xx replies plus a NO_PROXY loopback bypass applied before the Ollama client is built (an end-to-end subprocess test verifies local chat against a dead proxy environment), a timezone-safe memory-expiry test, and regression tests for the live tool-activity status events. Check the GitHub Actions page for the live state.
Nova can run in Docker with Ollama as a separate service. You need Docker Engine or Docker Desktop with the Compose plugin.
Build the Nova image and start Ollama:
docker compose build
docker compose up -d ollamaDownload a model into the Ollama container:
docker compose exec ollama ollama pull qwen2.5:3bRun Nova:
docker compose run --rm novaThe Compose setup stores Ollama model data and Nova memory in named volumes. It mounts the host projects/ directory into the container workspace, so files created there are available on the host.
The example uses CPU execution by default. GPU passthrough is not configured automatically and depends on the host OS, Docker, and NVIDIA setup.
Stop services:
docker compose downRemove named volumes too (this deletes persisted model and memory data):
docker compose down --volumesDo not mount sensitive host directories or the Docker socket into the container. Isolation depends on the mounts, privileges, networking, and runtime configuration you choose.
Nova can run programs and change files when relevant tools are enabled. Treat it as software with real access, not as a chat-only application.
- Run Nova as a normal user, not as an administrator.
- Enable only the capabilities you need.
- Use a separate test workspace for unfamiliar projects.
- Review plans and tool results before destructive or irreversible operations.
- Never put passwords, API keys, tokens, or private keys in prompts or memory.
- Keep API credentials and settings files private. The desktop settings file currently includes the configured API key; permission restriction is best-effort and is not a secure credential vault.
- A remote provider receives prompts and tool/file context sent to it. Local tools do not make remote inference private.
- Web search and other network-enabled tools contact external services.
- Keep Ollama, Git, Python, and optional dependencies updated.
- Do not expose local model-server ports publicly without understanding the consequences.
Filesystem and terminal restrictions reduce some risks but do not create a hardened security sandbox. Verification can catch certain failures, but cannot guarantee correctness or prevent every unsafe action. Do not use Nova for unattended operation on important systems.
Development is ongoing. Current areas of focus include:
- Fixing cross-platform filesystem path edge cases and keeping CI reliable.
- Improving model-driven planning, tool selection, and recovery.
- Keeping self-knowledge grounded in live runtime evidence.
- Strengthening memory reliability and privacy safeguards.
- Improving provider configuration and credential handling.
- Expanding regression tests for real-world tool behaviour.
- Improving desktop and terminal user experience.
- Windows code signing and installer packaging for Nova.exe.
This roadmap describes areas of work, not features guaranteed to be complete.
Nova-agent source code is distributed under the MIT License. Third-party dependencies, Ollama models, remote model providers, and optional image-generation models have their own licences and terms. The repository's MIT license does not replace those terms.
Made by Sepehr Taji.