Skip to content

About

A local AI agent powered by Ollama — real tool use, file access, OS control, git operations, web search, and verified task execution

Resources

Stars

4 stars

Watchers

0 watching

Forks

Latest commit

 

History

1,002 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

✦ Nova — Local-First AI Agent

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

Python Ollama Remote API License: MIT Tests Release

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.

Contents

What Nova can do

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.

Architecture

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.

Core components

  • 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.

Task execution flow

  1. Receive: Nova receives the request and prepares relevant conversation, memory, and live tool-registry context.
  2. Choose: the model decides whether it can answer directly or needs one or more registered tools.
  3. Validate: Nova checks each requested tool against the live registry, JSON schema, and session capability permissions.
  4. Execute: the registered Python handler runs locally. Calls requested together are executed serially.
  5. 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.
  6. Continue: the model chooses the next tool call or provides its final response. The loop is bounded to prevent unending tool cycles.
  7. 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.

Model providers

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.

Local: Ollama

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 ps hint instead of a raw error dump.
  • The local server always bypasses system proxies: Nova adds localhost, 127.0.0.1 and ::1 to 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 while ollama run works 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 list

This is only an example model. You can use another model supported by your Ollama installation.

Remote: OpenAI-compatible API

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.

Remote: Anthropic Messages API

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.

Provider selection

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.

Model settings in the desktop GUI

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.

Tools and permissions

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.

Capability groups

  • 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 and terminal

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.

GitHub integration

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.

NoviqX GitHub App

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.

What you set up

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 .pem GitHub 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.

First-run wizard

When you launch the desktop UI and NoviqX isn't configured yet, a setup wizard appears automatically. It walks you through:

  1. Creating a GitHub App (with the exact permission checklist: Contents + Pull requests = Read & write, Metadata = Read-only, Webhook = off)
  2. Entering your App ID, installation ID, and selecting the .pem
  3. Testing the connection for real (signs a JWT, exchanges for a token, reads one repository) before saving
  4. 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.

Manual setup

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.pem

Run the bundled smoke test to verify the pipeline end-to-end against real GitHub:

python scripts/noviqx_smoke_test.py --repo owner/scratch-repo --write

How to use it

Once 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.

Security model

  • Your .pem never 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 0600 and never contains the .pem content 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

Standalone MCP server

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_server

Set the same three NOVIQX_* variables, then point your MCP client at the command above. Full walkthrough: docs/noviqx-mcp.md.

Memory system

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.

Interfaces

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.

Downloads & SmartScreen

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 SHA256

The 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.

Requirements

  • 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.

Quick start

1. Clone the repository

git clone https://github.com/sepehrtaji-dev/Nova-agent.git
cd Nova-agent

2. Create a virtual environment

Windows PowerShell

py -3.11 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip

Linux / macOS

python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip

3. Install dependencies

python -m pip install -r requirements.txt

For the optional desktop GUI and integrations:

python -m pip install -r requirements-optional.txt

Install 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.

4. Configure a model

Local Ollama

Install and start Ollama, then download a model:

ollama pull qwen2.5:3b
ollama list

Remote 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.

5. Launch Nova

python main.py

The 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.

Configuration

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.

Choose a different local model

Windows PowerShell

$env:NOVA_PROVIDER = "local"
$env:NOVA_MODEL = "your-installed-ollama-model"
python main.py

Linux / macOS

export NOVA_PROVIDER=local
export NOVA_MODEL=your-installed-ollama-model
python main.py

Use a model actually installed in your Ollama instance. Performance and memory requirements depend on model size, quantization, context length, and available hardware.

Commands

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.

Project structure

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.

Development and tests

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.py

Smoke-test the terminal UI imports:

python -c "from ui.textual_app import NovaTextualApp; from ui.prompt_cli import main; print('UI imports OK')"

CI workflow

GitHub Actions currently:

  1. Checks out the repository.
  2. Sets up Python 3.11.
  3. Compiles all Python sources, including integrations/noviqx.
  4. Installs core dependencies, the NoviqX MCP SDK, and PySide6 (plus Qt runtime libraries on Linux).
  5. Smoke-tests the PySide6 desktop shell offscreen and both terminal UI imports.
  6. Runs the unit/regression test suite via unittest discover.
  7. 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.

Repository snapshot

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

Latest reviewed changes and CI

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.

Docker

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 ollama

Download a model into the Ollama container:

docker compose exec ollama ollama pull qwen2.5:3b

Run Nova:

docker compose run --rm nova

The 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 down

Remove named volumes too (this deletes persisted model and memory data):

docker compose down --volumes

Do not mount sensitive host directories or the Docker socket into the container. Isolation depends on the mounts, privileges, networking, and runtime configuration you choose.

Security and privacy

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.

Roadmap

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.

License

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.

About

A local AI agent powered by Ollama — real tool use, file access, OS control, git operations, web search, and verified task execution

Resources

Stars

4 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages