⚓ Navy AI

A general-purpose AI-first terminal agent with built-in pentest, recon, vision, and system tools.
Supports Ollama · LM Studio · Groq · OpenAI · Gemini · Anthropic · any OpenAI-compatible endpoint.

---

What's New in 4.3.0

• Ollama native tool calling — modern models (llama3.1+, qwen2.5+, mistral-nemo+) now use Ollama's OpenAI-compatible /v1 endpoint for reliable parallel tool calling, with automatic fallback to the JSON loop for older models
• Actionable API error messages — authentication failures, rate limits, quota exhaustion, context overflow, and network errors now each show a clear cause and fix instead of a raw exception trace
• Accurate token cost tracking — both input and output tokens are counted and priced for all providers; session cost accumulates correctly across turns
• Full streaming display — the live panel now shows the complete response as it arrives; no more truncation to the last 500 characters
• /rollback confirmation gate — the destructive git reset --hard + git clean -fd now requires explicit arrow-key confirmation before running
• Silent auto-commit removed — Navy no longer runs git add . automatically after file writes (which could silently stage .env files and secrets)
• Read-only pentest tools unblocked — http_probe, ssl_check, and whois_lookup no longer require confirmation; only truly destructive tools do
• grep_code display limit raised — tool output now shows up to 3 000 characters (was 700), reducing truncation on code searches
• write_file_overwrite_threshold configurable — the 200-line overwrite guard can now be tuned in config.json
• Memory-efficient read_file — large files are no longer loaded entirely into RAM; only the requested line range is read using itertools.islice

---

Features

• Interactive & argument mode — chat in a session or fire a one-liner from your terminal
• Multi-provider — Ollama, LM Studio, Groq, OpenAI, Gemini, Anthropic, and any OpenAI-compatible endpoint
• Local AI first — Ollama and LM Studio with live server route switching via /route
• Ollama native tool calling — modern Ollama models use /v1 for parallel tool calls; older models fall back gracefully
• Vision / image input — attach screenshots or images to any query; auto-detected from message paths
• Streaming responses — live token-by-token preview for all providers, full text always visible
• Token + cost display — input and output tokens tracked per turn; session total and estimated cost shown
• 3-phase agent loop — Gather → Act → Verify keeps the agent structured and on-task
• Reasoning engine — extracts <plan> blocks from thinking, tracks steps visually
• Git tools — git_status, git_diff, git_log, git_commit, git_branch built in
• Smart query routing — simple greetings answered instantly without tool overhead
• Arrow-key approval — confirm or decline tool calls with ← → keys
• Headless browser — Playwright integration for JavaScript-heavy pages
• Codebase tools — AST map, symbol definition finder, symbol usage search
• Subagent delegation — spawn background Navy instances for parallel tasks
• Built-in pentest tools — port scanner, SSL checker, HTTP prober, subdomain enum, WHOIS
• Plugin system — drop .py files in tools/ directory, auto-loaded as MCP tools
• Session management — save, load, and export conversations as Markdown
• Multi-line input — type """ to open a paste buffer, close with """
• Autonomous mode — /goal <description> runs without confirmation for up to 50 turns
• Audit log — every command and response logged locally
• Loop & dead-command detection — stops runaway loops; auto-switches to WSL for missing tools
• Actionable API errors — auth failures, rate limits, quota, context overflow, network errors each show a clear fix

---

Install

pip install navy-ai

Install with your preferred AI provider:

pip install "navy-ai[ollama]"      # local models via Ollama
pip install "navy-ai[openai]"      # GPT-4o, o3, o4-mini — also required for LM Studio and Groq
pip install "navy-ai[gemini]"      # Gemini 1.5 / 2.0
pip install "navy-ai[anthropic]"   # Claude Sonnet / Opus / Haiku
pip install "navy-ai[all]"         # every provider at once

---

Usage

Interactive mode

navy

⚓ ~ ❯ what ports are open on 10.0.0.1?
⚓ ~ ❯ summarise the files in this folder
⚓ ~ ❯ /image screenshot.png what is wrong here?
⚓ ~ ❯ show me the git diff

Argument mode (single-shot)

navy "what is the name of this computer"
navy --model gpt-4o "scan ports on 10.0.0.1"
navy --yes "what processes are using the most CPU"

Options

Flag	Description
--model <name|alias>	Override the model (name or alias from models.json)
--ctx <int>	Context window size (default: 32768)
--yes / -y	Skip all confirmation prompts

In-session commands

Command	Description
model <alias>	Switch model mid-session
/models	List all model aliases and providers
/route [target] [url]	Show or change local AI server URL (ollama / lms / compat)
/system [prompt|clear]	Set or clear a custom system prompt prefix
/undo	Remove the last exchange from memory
"""	Open multi-line input — paste freely, close with another """
/image <path> [question]	Attach an image to the next query (auto-detected from message too)
/goal <description>	Run autonomously without confirmation (up to 50 turns)
/rollback	Revert last auto-commit or all local changes (asks for confirmation)
continue	Give the agent +10 more turns
/save [name]	Save the current session
/load <name>	Load a saved session
/sessions	List saved sessions
/export [file]	Export transcript as Markdown
/reset	Clear conversation memory
exit / quit	Exit Navy

---

Providers

Model prefixes

Prefix	Provider	Example
name:tag	Ollama (local)	qwen2.5:14b
lms:	LM Studio (local)	lms:phi-4
groq:	Groq (cloud)	groq:llama-3.3-70b-versatile
compat:	Any OpenAI-compatible endpoint	compat:my-model
gpt-* / o3 / o4-*	OpenAI	gpt-4o
gemini-*	Google Gemini	gemini-2.0-flash
claude-*	Anthropic	claude-sonnet-4-5

Built-in presets

model flash      # Gemini 2.0 Flash
model gpt4o      # GPT-4o
model sonnet     # Claude Sonnet
model groq70     # Groq Llama 3.3 70B
model groq8      # Groq Llama 3.1 8B (fastest)
model qwen14     # Ollama Qwen 2.5 14B
model lms        # LM Studio local model

---

Configuration

On first run Navy auto-creates ~/.config/navy/models.json. Edit it to set your default model and API keys.

models.json

{
  "default": "qwen2.5:14b",
  "providers": {
    "openai":    { "api_key": "" },
    "gemini":    { "api_key": "" },
    "anthropic": { "api_key": "" },
    "groq":      { "api_key": "" },
    "ollama":    { "host": "http://127.0.0.1:11434" },
    "lmstudio":  { "host": "http://localhost:1234/v1" },
    "compat":    { "host": "http://localhost:8080/v1", "api_key": "no-key" }
  },
  "presets": {
    "gpt4o":   "gpt-4o",
    "flash":   "gemini-2.0-flash",
    "sonnet":  "claude-sonnet-4-5",
    "groq70":  "groq:llama-3.3-70b-versatile",
    "groq8":   "groq:llama-3.1-8b-instant",
    "qwen14":  "qwen2.5:14b",
    "lms":     "lms:local-model"
  }
}

API keys can also be set via environment variables:

export OPENAI_API_KEY=sk-...
export GEMINI_API_KEY=AIza...
export ANTHROPIC_API_KEY=sk-ant-...
export GROQ_API_KEY=gsk_...

config.json — timeouts and tool limits

{
  "server": {
    "command_timeout": 120,
    "max_command_timeout": 1800,
    "write_file_overwrite_threshold": 200,
    "read_file_block_lines": 50,
    "fetch_url_max_chars": 8000
  },
  "cli": {
    "max_turns": 15,
    "max_response_tokens": 4096
  }
}

Key	Default	Description
command_timeout	120	Max seconds a shell command may run
max_command_timeout	1800	Hard cap for long-running commands
write_file_overwrite_threshold	200	Lines above which write_file blocks overwriting without overwrite=True
read_file_block_lines	50	Lines returned per read_file page
fetch_url_max_chars	8000	Max characters returned by fetch_url
max_turns	15	Agent loop turns per request
max_response_tokens	4096	Max tokens per model response

---

Local AI

Ollama

ollama pull qwen2.5:14b
navy

Modern models (llama3.1+, qwen2.5+, mistral-nemo+) automatically use Ollama's native tool-calling API for faster, more reliable tool use. Older models fall back to the JSON parsing loop transparently.

Change server address:

/route ollama http://192.168.1.10:11434

LM Studio

1. Open LM Studio → Local Server tab → load a model → Start Server
2. Install the openai package: pip install "navy-ai[openai]"
3. Use the lms: prefix with the model name shown in LM Studio:

model lms:phi-4
/route lms http://192.168.1.10:1234/v1

Groq

pip install "navy-ai[openai]"

Set GROQ_API_KEY and use the groq: prefix:

model groq:llama-3.3-70b-versatile
model groq8    # alias for 8B instant model

Generic OpenAI-compatible endpoint

/route compat http://my-server:8080/v1
model compat:my-model-name

---

Vision / Image Input

Navy can analyze images with any vision-capable model (GPT-4o, Claude 3+, LLaVA, Gemini, etc.).

Auto-detection — just mention the path in your message:

⚓ ❯ what's wrong in this screenshot? C:\Users\you\Desktop\error.png

Explicit command:

⚓ ❯ /image C:\screens\ui_bug.png is the layout broken?

Supported formats: PNG, JPG, JPEG, GIF, WebP, BMP, TIFF — up to 4 images per turn.

Fast vision models:

model groq8          # Groq 8B — fastest cloud
model gpt4o          # GPT-4o — best quality
model flash          # Gemini Flash — nearly free
ollama pull llava-phi3   # fast local vision

---

Built-in Tools

Tool	Description
execute_command	Persistent shell — cd works across turns
patch_file	Surgical search-and-replace with diff output
edit_line_range	Edit exact line ranges
read_file / write_file	Local file read/write (memory-efficient streaming)
search_files	Find files by name or content
fetch_url	Fetch and parse web pages (SSRF-protected)
fetch_url_headless	Playwright headless browser for JS-heavy pages
search_web	DuckDuckGo search
get_codebase_map	AST map of all Python classes, methods, imports
find_symbol_definition	Find where a class/function is defined
find_symbol_usages	Find all usages of a symbol
delegate_task	Spawn a background Navy subagent
git_status	Branch, changed files, recent commits
git_diff	Show uncommitted changes
git_log	Recent commit history
git_commit	Create a commit (only when asked)
git_branch	List, create, or switch branches
scan_ports	TCP port scanner (supports ranges: 1-65535)
http_probe	HTTP status + response headers
ssl_check	TLS certificate validity, expiry, ciphers
check_security_headers	Security header grading (A–F)
dns_lookup	DNS resolution
whois_lookup	Domain registrar, expiry, nameservers
subdomain_scan	DNS-based subdomain enumeration
get_system_specs	GPU / RAM / CPU information
get_security_logs	Windows Security & Defender events

---

Pentest Workflow

scan_ports → http_probe → ssl_check → subdomain_scan → whois_lookup

Important: Only use pentest tools against targets you are authorized to test.

---

License

MIT © Zrnge