OpenNova

OpenNova v0.4.3 is a terminal AI coding agent built in Python around a Textual TUI.

English | 简体中文

Quickstart | Tutorial | API Reference

Overview

OpenNova combines a focused agent runtime with a full-screen terminal workbench:

• OpenAI, Anthropic, and DeepSeek providers
• Streaming Textual TUI with chat and Context, Tasks, and Activity panels
• Persistent sessions with a resume picker and complete transcript replay
• Plan/Act workflows, TodoWrite, sub-agents, and worktrees
• 40 built-in tools plus Skills, trusted project plugins, hooks, and MCP
• Context compression and layered project memory
• Three permission modes, parameter rules, secret redaction, audit logs, and sandboxes
• A headless Python SDK for scripts and services

The legacy interactive command-line interface and standalone opennova tui command are not part of the current product. Run opennova with no subcommand to open the Textual TUI. Command options remain available for setup, automation, and one-shot tasks.

What is new in v0.4.3

Version 0.4.3 improves runtime efficiency and reliability for repository-scale coding workflows:

• executes independent read-only tools concurrently while preserving deterministic result order
• protects edits from stale file snapshots and stores oversized tool output as retrievable artifacts
• adds deferred tool discovery, shared gitignore handling, bootstrap profiles, and diagnostics
• expands MCP lifecycle support, checkpoint safety, session forking, and layered memory controls
• improves model routing with token budgets, retries, fallbacks, and circuit breakers

Installation

Requirements: Python 3.11+ and uv.

git clone https://github.com/Wardell-Stephen-CurryII/OpenNova.git
cd OpenNova
uv sync
uv run opennova init

For a globally available command:

uv tool install .
opennova

Configuration

Configuration is merged in this order: defaults, ~/.opennova/config.yaml, project .opennova/config.yaml, then environment variables.

default_provider: deepseek
default_model: deepseek-v4-pro

providers:
  openai:
    api_key: ${OPENAI_API_KEY}
    default_model: gpt-4o
  anthropic:
    api_key: ${ANTHROPIC_API_KEY}
    default_model: claude-sonnet-4
  deepseek:
    api_key: ${DEEPSEEK_API_KEY}
    base_url: https://api.deepseek.com/v1
    default_model: deepseek-v4-pro

agent:
  max_iterations: 20
  compression:
    enabled: true
    threshold: 0.55
    keep_last_pairs: 6
    max_tool_result_tokens: 8000

security:
  permission_mode: auto  # request | auto | full
  sandbox_mode: true
  allow_network: true
  strict_shell_parsing: false
  read_only: false

mcp:
  enabled: true
  servers: []

skills:
  enabled: true
  dirs: []
  exclude: []

API keys may also be supplied through OPENAI_API_KEY, ANTHROPIC_API_KEY, and DEEPSEEK_API_KEY.

Usage

# Open the Textual TUI
uv run opennova

# Open the session picker
uv run opennova --resume

# Continue the newest session
uv run opennova --continue

# Choose the approval mode for this run
uv run opennova --permission-mode request

# Execute a one-shot task without opening the TUI
uv run opennova run "Read README.md"

# Generate a plan for a one-shot task
uv run opennova run --plan "Refactor the authentication module"

# Select a provider or model for a one-shot task
uv run opennova run --provider deepseek -m deepseek-v4-pro "Review src/"

Other setup and inspection commands are opennova init, opennova list-tools, opennova config, and opennova --version.

TUI controls

Clipboard copying first uses Textual/OSC 52 and then the native platform command (pbcopy, clip, wl-copy, or xclip) when available.

Slash commands

The main commands available inside the TUI are:

Run /help for the registry generated by the installed version.

Built-in capabilities

OpenNova currently registers 40 built-in tools across these groups. Core schemas stay visible; tool_search discovers deferred Git, diagnostics, background, MCP, and worktree tools on demand:

• files: read, write, create, edit, multi-edit, delete, and directory listing
• search and diagnostics: glob, grep, Python syntax, symbols, definitions, and references
• shell and Git: guarded command execution, status, diff, log, branch, and commit
• tasks: background tasks, TodoWrite, planning, sub-agents, and user questions
• integrations: Skills, web fetch/search surface, project guide, MCP resources, and worktrees

web_search intentionally returns an unconfigured result unless a search backend is provided; it does not fabricate search results.

Sessions and memory

Sessions are persisted under ~/.opennova/sessions/. --resume and /resume open a newest-first picker whose titles come from the first user message. Resuming restores both backend context and the visible TUI transcript, then continues writing to the original session instead of creating a duplicate.

/fork [id] creates an independent copy of a session timeline. Layered memory under .opennova/memory/ supports provenance, scope, expiry, normalized deduplication, and /memory management; existing plain Markdown memory files remain compatible.

Context compression starts at 55% utilization by default. Older complete message pairs are summarized while recent messages, tool-call boundaries, and compression markers remain recoverable.

Extensions

Skills use a directory-based SKILL.md format:

~/.opennova/skills//SKILL.md
.opennova/skills//SKILL.md

MCP supports stdio and SSE transports. Project plugins can add trusted tools and slash commands; plugin lock, drift, warning, and audit operations are exposed through /plugins. Plugin trust is stored outside the repository and is bound to the workspace path and plugin content digest. Project Python hooks are disabled until the current hook digest is approved with /hooks trust.

Security model

• request: asks before every otherwise allowed tool call
• auto: automatically runs routine development calls, including elevated-risk commands, and asks only for high-risk actions such as deletion, force operations, private-network access, secret writes, or untrusted MCP tools
• full: skips approval prompts but does not bypass hard blocks

Hard blocks, explicit deny rules, plan approval, path/network policy, secret handling, and the optional OS process sandbox remain active in every mode.

Configuration display, canonical tool events, tool observations, and persisted transcripts redact detected secrets by default. The process sandbox limits reads to system/runtime roots and explicit project paths; when an optional backend is unavailable and enforcement is disabled, command output shows a visible fallback warning. Use security.process_sandbox.enforce: true to fail closed.

Python SDK

import asyncio

from opennova import OpenNovaClient
from opennova.config import load_config

async def main() -> None:
    async with OpenNovaClient(load_config()) as client:
        session_id = client.create_session()
        result = await client.submit_message(session_id, "Summarize this project")
        print(result)

asyncio.run(main())

Development

uv sync --dev
LC_ALL=en_US.UTF-8 LANG=en_US.UTF-8 PYTHONUTF8=1 uv run pytest
uv run ruff check src/ tests/
uv run mypy src/opennova

See AGENTS.md for the current architecture and contributor workflow. Historical implementation plans under docs/develop/ are retained as archived design records rather than user documentation.

License

OpenNova is released under the MIT License.