Skip to content

About

VELUNE CLI is an open-source AI engineering CLI that unifies local LLMs (Ollama), cloud AI providers, MCP servers, tools, memory, and project context into a single developer workflow. Build, code, automate, and orchestrate AI with one extensible, provider-agnostic command-line interface.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

15 stars

Watchers

1 watching

Forks

Velune CLI

Local-first multi-model AI developer CLI. Council-based agents. Persistent memory. Repository cognition.

No cloud required. No quota. No lock-in.

PyPI - Version Python License CI PyPI Downloads

Quickstart · Commands · Architecture · Docs · Contributing


Project identity

Velune CLI is an open-source project originally created and maintained by Surya HA. This repository is the canonical Velune CLI repository; official releases are the tags and GitHub Releases published here and the velune-cli package on PyPI.

  • Source code: Apache-2.0. You are free to use, modify, fork, and redistribute it under the terms of the license (keep the copyright and NOTICE attributions).
  • Project identity. The Velune name, wordmark, logo, and branding are not licensed by Apache-2.0 (see NOTICE and the License section). Forks are welcome; they are simply not the canonical project.

See AUTHORS.md, GOVERNANCE.md, and docs/project-origin.md.


Contents


What it does

Velune CLI is a terminal-first AI coding assistant that runs a council of specialized agents (Planner, Coder, Reviewer, Challenger, Synthesizer) on your local machine using Ollama, or on free cloud tiers via Groq, OpenRouter, and others.

Velune CLI Copilot / Cursor
Runs fully offline ✅ Yes, via Ollama — no API key ❌ Always cloud-dependent
Remembers your codebase ✅ 5-tier persistent memory across sessions ⚠️ Per-session context only
Reviews its own output ✅ Multi-agent council debates before you see a diff ❌ Single model, single pass
Editor required ✅ None — any terminal, any project ❌ IDE extension
Your code leaves the machine ✅ Never, in local mode ⚠️ Depends on provider

60-second quickstart

1. Install Velune CLI

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/Surya-Hariharan/Velune-CLI/main/scripts/install.sh | sh

Windows (PowerShell)

irm https://raw.githubusercontent.com/Surya-Hariharan/Velune-CLI/main/scripts/install.ps1 | iex

The installer puts Velune in its own isolated environment using uv. It doesn't need Python already installed: if Python is missing or too old, uv downloads a private copy. It can't conflict with packages other tools have installed, and it adds velune to your PATH. Run the same command again to upgrade.

Prefer pipx, uv or pip?

Any of these works. The first two give you the same isolation as the installer:

pipx install velune-cli          # isolated, auto-managed PATH
uv tool install velune-cli       # isolated, auto-managed PATH
python -m pip install velune-cli # into the current Python environment

Use python -m pip, not bare pip. That way the package goes into the same Python you'll run it with, which matters on machines with several Pythons (common on Windows). Plain pip needs Python 3.10+ and installs into whatever environment is active. The usual problems with it:

  • ERROR: Could not find a version that satisfies the requirement velune-cli (with a note about Requires-Python): your Python is older than 3.10. Check with python --version. Install a newer Python, or use the one-line installer, which brings its own.

  • error: externally-managed-environment (Debian/Ubuntu, Homebrew Python): the OS won't let pip write to the system Python. Use the installer, pipx or uv tool above, or a virtualenv.

  • Another tool needs different versions of the same libraries: pip has only one copy of each package per environment, so two tools can break each other. An isolated install avoids this. If Velune detects an incompatible dependency at startup, it names the package and gives you the fix command.

  • velune: command not found / "'velune' is not recognized…": the install worked, but your Python scripts directory isn't on PATH. Use python -m velune (always works), or reinstall with pipx/the installer, which manage PATH for you.

Every dependency ships prebuilt wheels for CPython 3.10–3.14 on Windows, macOS and Linux (x86-64 and ARM64), so no compiler or build step is needed. CI checks this for the lowest version of each dependency.

Verify the install

velune --version
velune doctor

velune doctor shows your Velune version, Python interpreter, OS, and where Velune is installed and keeps its data. It then checks the installation and ends with "✓ Core installation is healthy" or a list of what's broken. Optional integrations (provider keys, a local Ollama, extras such as [rag]) are reported but never count as installation failures. The exit code is non-zero only when the core installation has a problem. velune doctor --json gives the same report as JSON for scripts and bug reports.

2a. Local models (Ollama, free, no key)

# Install Ollama, then pull a model
curl -fsSL https://ollama.com/install.sh | sh
ollama pull qwen2.5-coder:7b

cd your-project
velune init
velune

Ollama on another machine or port? Set OLLAMA_HOST (for example OLLAMA_HOST=192.168.1.20:11434); Velune uses it for setup, discovery, health checks and chat alike.

Models on an external drive. Run /model locate (or /model register <path>) on the Ollama store folder (the one containing manifests/ and blobs/). Velune remembers it. If the drive is unplugged, the model stays listed as unavailable with the reason. Plug it back in at the same path and /model recheck (or just your next message) picks it up again. If the drive comes back under a different path, use /model relocate <model> <new-path>. A single .gguf file or a safetensors model folder can be registered with /model register <path>. That imports it into Ollama, which copies the file, so Velune shows the size and asks first.

2b. Cloud free tier (Groq, fastest, no GPU needed)

velune init --provider groq
velune setup        # enter your free Groq key
velune

Get a free Groq key at https://console.groq.com/keys, no credit card needed.

Check your setup any time with velune doctor.


Hardware requirements

RAM Accelerator Local LLM? Recommended setup
< 8 GB Any ❌ No Use Groq free tier
8 GB Integrated ⚠️ 3B models only Groq + phi3-mini local
16 GB Integrated (no dGPU) ⚠️ Slow, 3B only Groq + 3B local
16 GB 6+ GB VRAM ✅ 7B comfortable qwen2.5-coder:7b
16 GB Apple Silicon ✅ 13B comfortable Full council, Metal accel
32 GB 12+ GB VRAM ✅ 13B comfortable Full council local
36 GB+ Apple Silicon ✅ 70B comfortable Max power, Metal accel
64 GB 24+ GB VRAM ✅ 70B capable Max power mode

Velune CLI detects your hardware on startup and prints tier, GPU, and recommendations. On underpowered machines, it routes tasks to cloud providers automatically.


Startup flow

Velune CLI starts instantly and does no work until you ask for it. Repository cognition (indexing) is explicit and on-demand — it never runs automatically on launch.

flowchart TD
    Start([velune]) --> CLI[CLI opens instantly]
    CLI --> Connect[Connect a model]
    Connect -.-> C1("`/connect`")
    Connect -.-> C2("`/model connect`")
    Connect -.-> C3("`/model use`")
    Connect --> Open[Open a project]
    Open -.-> O1("`/project open`")
    Open -.-> O2("`/project status`")
    Open --> Cog[Index the codebase]
    Cog -.-> R1("`/index quick`")
    Cog -.-> R2("`/index standard`")
    Cog -.-> R3("`/index deep`")

    classDef action fill:#0a3d62,stroke:#3c6382,stroke-width:2px,color:#fff;
    classDef cmd fill:#079992,stroke:#38ada9,stroke-width:1px,color:#fff;
    class Start,CLI,Connect,Open,Cog action;
    class C1,C2,C3,O1,O2,R1,R2,R3 cmd;
Loading

Interface

  • Startup banner shows your hardware tier, active model, and available providers
  • Responsive prompt with intelligent context indicators (only displays when relevant)
  • Restrained, single-accent color palette — clarity over decoration
  • Tab-completion for every / command and for model IDs
  • Session modes for balancing speed vs. quality (/fast · /normal · /max)
  • Live dashboard (/dashboard) — background jobs, proactive alerts, provider health in one view

The status bar shows bg:N for active background jobs, alerts:N for unread proactive alerts, and mcp connected/total when MCP servers are configured. Alerts drain automatically after each prompt and render above the input line.


Providers

Provider Type Cost Models Setup
Ollama 🏠 Local Free Any pulled model Install Ollama, pull a model
LM Studio 🏠 Local Free Any GGUF / MLX model Launch LM Studio server
llama.cpp 🏠 Local Free In-process GGUF models Point at a local .gguf file
OpenAI-compatible 🏠 Local Free vLLM, LocalAI, text-generation-webui, … Point at your server's base URL
Groq ☁️ Cloud Free tier Whatever your key can use (e.g. GPT-OSS, Qwen), read live from Groq /connect groq
OpenRouter ☁️ Cloud Pay-per-token 100+ models /connect openrouter
OpenAI ☁️ Cloud Pay-per-token GPT-4o family, o-series, GPT-5: chat models your key can use /connect openai
Anthropic ☁️ Cloud Pay-per-token Claude Opus, Sonnet, Haiku (live list) /connect anthropic
xAI (Grok) ☁️ Cloud Pay-per-token Grok 2, Grok 2 Mini /connect xai
Google ☁️ Cloud Free quota Gemini 2.5 Pro/Flash, 2.0 Flash (live list) /connect google
Together AI ☁️ Cloud Pay-per-token Llama 3.3 70B, Qwen 2.5, DeepSeek R1 /connect together
Fireworks AI ☁️ Cloud Pay-per-token DeepSeek R1, Qwen 2.5, Mixtral 8x22B /connect fireworks
Mistral ☁️ Cloud Pay-per-token Mistral Large, Codestral, Mixtral /connect mistral
DeepSeek ☁️ Cloud Pay-per-token DeepSeek R1, DeepSeek Coder /connect deepseek
Cohere ☁️ Cloud Pay-per-token Command R+, Command R /connect cohere
Meta (Llama API) ☁️ Cloud Pay-per-token First-party Llama models /connect meta
NVIDIA NIM ☁️ Cloud Free credits / paid Chat models from build.nvidia.com (Llama, Mistral, DeepSeek, Nemotron, …), read live /connect nvidia with an nvapi-… key from https://build.nvidia.com/settings/api-keys (or NVIDIA_API_KEY)
HuggingFace ☁️ Cloud Free/paid Open models via Inference API /connect huggingface

Keys are stored AES-GCM-encrypted in your user config directory; the encryption key lives in your OS keyring (or is derived from VELUNE_MASTER_PASSPHRASE on headless machines). Never plain text, never in git. velune setup, velune provider add <id> and the REPL's /connect all walk you through it. Model lists for OpenAI, Anthropic, Gemini, Groq and NVIDIA NIM are read live from the provider, so retired models drop out automatically. If a listing fails (offline, rate limit, a key without list permission), Velune keeps the last known list and tells you why instead of shrinking it.

A key you save through Velune is the key Velune uses, even if an older OPENAI_API_KEY (etc.) is set in your shell. Set VELUNE_PREFER_ENV_KEYS=1 if you want environment variables to win instead. /model status shows which key is in effect. If the provider can't be reached when you add a key, the key is still saved and re-checked automatically later. Only a key the provider actually rejects is refused.


Commands

CLI (terminal, before the REPL)

Every top-level command below is grouped exactly as velune --help groups it. Most groups take subcommands — run velune <command> --help for the full signature.

Core
velune                    # Start the interactive REPL session
velune chat                # Older line-based chat mode (the full-screen REPL is bare `velune`)
velune run "<task>"        # Run a task non-interactively and exit
velune ask "<question>"    # Ask a one-shot question and exit
velune init                 # Set up Velune CLI in the current project
velune onboard              # Run (or resume) the first-time setup wizard
Workspace & Sessions
velune project init|status|graph|tree|list|open|resume|explain|forget
velune session list|resume|show|delete|import|rename|search|archive|unarchive|export
Setup & Models
velune setup                          # Configure providers and models interactively
velune models scan|list|refresh|pull|delete|assign|use|benchmark|health|show
velune provider list|add|remove|test|models|status|api|edit|inspect|default|backup|restore|repair
velune config show|set|get
velune trust add|list|forget
Analytics & Monitoring
velune usage      # Token usage and estimated cost for recent sessions
velune quota      # Provider rate-limit and quota status
velune health     # Provider reachability and response time
Diagnostics
velune doctor                         # Diagnose the installation (alias: doctor check)
velune doctor providers|network
velune logs [recent|live]
velune status                         # Index freshness + workspace health
velune pipeline trace "<query>"       # Trace a query through the retrieval pipeline
velune daemon start|stop|status
velune mcp serve|connect <url> <name>
velune memory stats|inspect|clear|compact
Trust & Recovery
velune backup [--output <path>] [--include a,b] [--with-secrets]   # Snapshot all Velune CLI state to one archive
velune restore <archive> [--include a,b] [--overwrite] [--dry-run] # Restore state from a backup archive
velune recover [id] [--all] [--all-workspaces] [--discard <id>]   # Recover an unsaved session after a crash

Inside the REPL

52 slash commands across 11 categories (the full table is in docs/slash-commands.md). The essentials:

CategoryCommands
Session/help · /exit · /clear · /new · /fork
AI/run <task> · /council <task> · /jobs · /dashboard · /fast · /max · /normal · /mode · /retry
Projects/project [open|close|status|list|add] · /index [quick|standard|deep|status|rebuild] (alias /cognition)
Providers/connect [provider-id]
Models/model [discover|connect|use|list|status|locate] · /pull · /delete · /roles · /bench
Memory/memory [clear|stats] · /context · /graph
Git/diff · /undo · /hunk · /push · /pr · /issue · /sandbox
Tools/lint · /refactor · /types · /plugin · /hooks
MCP/mcp [servers|tools|resources|connect|disconnect]
Resources/resource [list|discover|connect|status] — Docker, PostgreSQL, MySQL, Supabase
Settings/settings · /config · /approve [safe|ask|block] · /theme · /crashreports
System/history · /stats · /session · /doctor · /trace · /backup · /restore · /recover

Run /help in the REPL for every alias, shortcut, and usage string.


Architecture

Package layout
velune/
├── cli/              REPL, full-screen UI, slash commands, palettes, themes, onboarding
│   ├── commands/     Typer subcommands (workspace, session, models, doctor, mcp, memory, ...)
│   ├── handlers/     Slash-command implementations (lazily imported)
│   ├── display/      Live dashboards and the council pipeline view
│   └── rendering/    Markdown (tables, charts, Mermaid), error panels, diff fragments
├── providers/        18 providers: adapters, discovery, credentials/crypto, validation, retry,
│                     endpoint resolution (OLLAMA_HOST, base URLs), local-model import
│   ├── adapters/     Per-provider inference + streaming implementations
│   └── discovery/    Model catalog discovery (live-reconciled for OpenAI/Anthropic/Gemini/Groq)
├── models/           Model registry (non-destructive refresh), local-model registrations,
│                     capability scoring, council role mapping
├── cognition/        Council: Planner -> Coder -> Reviewer -> Challenger -> Synthesizer
│   └── council/      DebateSession, per-role agents, tier classifier, contracts
├── council/          Deliberative Council engine (R0–R3 stages; behind the
│                     `cognition.council_engine` flag, off by default)
├── permissions/      Execution-mode and approval policy (Manual / Plan / Auto)
├── orchestration/    Native tool-calling loop
├── prompt_intelligence/  Provider-aware prompt compiler
├── context/          Context assembly, budgets, token counting, @mentions, prompt caching
├── memory/           working -> episodic -> semantic -> graph -> lineage; SQLite pool, embeddings
├── retrieval/        Hybrid retrieval: BM25 + vector + graph, heuristic reranker
├── repository/       Scanner, AST/symbol index, import graph, blast radius, .veluneignore
├── intelligence/     Repository Intelligence Engine: change detection -> incremental reindex
├── knowledge/        Repository Knowledge Graph: AI-queryable files/symbols/relationships
├── proactive/        Alert store + watcher (CognitiveBus event subscriptions)
├── execution/        Managed execution (allowlist + PATH guard), diff preview, rollback
│   └── edit_formats/ Edit formats: search_replace, udiff, whole_file
├── tools/            File-system, git, web-fetch, and terminal tool implementations
├── mcp/              MCP server + client; stdio / SSE / HTTP / WebSocket transports
├── hooks/            Lifecycle hook dispatcher and executor (pre/post tool events)
├── plugins/          Declarative plugin loader, SKILL.md injection, hook wiring
├── resources/        Resource connectors: Docker, Postgres, MySQL, Supabase (approval-gated)
├── integrations/     GitHub and GitLab REST clients (push, PR, issues)
├── analysis/         Linting, code-smell detection, type inference
├── observability/    Context reports, execution trace log, workspace dependency graph
├── telemetry/        Token tracking, cost estimation, latency profiling
├── recovery/         Unified backup / restore / crash recovery for all persistent state
├── hardware/         Hardware detection, tier classification, GPU probe
├── kernel/ core/     DI container, bootstrap, lifecycle; paths, trust, retry, task registry, errors
├── events.py         The CognitiveBus event bus
└── daemon/           Background service (server + IPC transport)

Memory system

Velune CLI maintains five memory tiers across sessions:

  1. Working — current conversation turns (in-process, TTL-evicted)
  2. Episodic — session history (SQLite, stored per workspace in your user data directory)
  3. Semantic — vector search over past interactions (local LanceDB and Qdrant)
  4. Graph — entities and relationships seen in conversations and executions
  5. Lineage — decision history, what was tried and why

This means "fix the auth issue from yesterday" actually works — Velune CLI retrieves recent sessions, git changes, and related context to reconstruct intent without you explaining it again.


Execution modes

Velune can read, create, edit, move and delete files and folders and run commands in your project. What it may do without asking depends on the execution mode. Press Shift+Tab to cycle, or use the commands:

Mode Command Velune may…
Manual (default) /manual Read and analyze freely; asks before every change. Related changes are shown together for one approval.
Plan /plan [task] Investigate and write a plan to .velune/plans/<name>.md, changing nothing. Revise it as often as you like; reply approve / go ahead to execute it.
Auto /auto Create, edit and delete files and run commands inside the project without asking, iterating (edit → test → fix) until done.

In every mode Velune still asks before:

  • touching anything outside the project folder (allow once / for this task / deny);
  • high-risk operations: git reset --hard, git clean, force-push, recursive deletes, global or system installs, environment/registry/firewall changes;
  • reading or changing secrets (.env, keys, ~/.ssh).

sudo, disk formatting and similar commands never run. These rules are enforced in code at the tool layer, not by instructions to the model, and every decision is logged (velune trace --type permission). Start in a mode with velune --mode manual|plan|auto, or set the default in velune.toml:

[execution]
mode = "manual"   # or "plan" / "auto"

Session modes

Mode Command Council tier Model Context cap
Normal /normal Auto Current 16k tokens
Fast /fast Instant Smallest 4k tokens
Max /max Full Largest 128k tokens

Switch modes at any time mid-session — the prompt badge updates immediately.


MCP integration

Velune CLI works as both an MCP server and an MCP client:

  • Server (velune mcp serve) — exposes Velune CLI's local tool council over stdio so Claude Desktop, VS Code, and other MCP-capable editors can call Velune CLI's models without sending your code to a third party.
  • Client (velune mcp connect <url> <name>, or /mcp connect in the REPL) — connects to any external MCP server, lists its tools, and makes them available inside the REPL.
  • Transports — stdio, SSE, HTTP, and WebSocket (ws:// / wss://) are all supported. Servers can also be declared in .mcp.json and loaded automatically.

Outbound connections to external MCP servers are trust-gated — see MCP trust gating in the security policy.


Windows

Velune CLI runs natively on Windows — native command execution sandboxing, local Ollama integration, and OS keyring credentials. It also runs unmodified under WSL2 if preferred.


Project docs

Doc What's inside
SECURITY.md Security posture, trust boundaries, reporting
CONTRIBUTING.md Dev setup, adding providers/commands/agents, PR workflow
CODE_OF_CONDUCT.md Community standards and enforcement
CHANGELOG.md Full version history
docs/usage-guide.md Day-to-day tips: tiers, memory, extensions, troubleshooting
docs/slash-commands.md Every REPL command, alias and usage string
docs/mcp.md MCP server + client guide, transports, trust gating
docs/development.md Bootstrap/DI layer, module boundaries, testing, CI, extension points
docs/project-origin.md How the project came to be: releases and milestones
AUTHORS.md · GOVERNANCE.md · NOTICE Authorship, governance, licensing notice

Optional extras

The default install is intentionally lean and pure-python-friendly so it resolves fast and cleanly on every platform. Heavy or feature-specific dependencies live in extras — every feature that needs one degrades gracefully when it is absent (e.g. semantic search becomes a no-op, but lexical search and chat keep working).

Extra Installs Enables
[rag] lancedb, pyarrow, qdrant-client Semantic memory + vector retrieval (large compiled wheels)
[parsing] tree-sitter + grammars Tree-sitter source parsing for deep repository cognition
[telemetry] opentelemetry-* Export spans/metrics to an OTLP collector
[git] (no extra deps) Retained for compatibility — git tools (push / PR / issue) now use native git subprocess calls, so nothing extra installs
[gguf] gguf GGUF file metadata reading — safe, no transitive risk
[docker] docker Docker sandbox for isolated code execution
[all] everything above Full-featured install
[dev] Test/lint tools For contributors
pip install velune-cli            # lean base (Ollama, cloud providers, chat, lexical search)
pip install 'velune-cli[rag]'     # + semantic memory & vector retrieval
pip install 'velune-cli[all]'     # + every optional feature

If you used the one-line installer (or uv tool), add extras with uv tool install --force 'velune-cli[rag]'. With pipx, use pipx install --force 'velune-cli[rag]'.

The former [llamacpp] extra has been permanently removed: llama-cpp-python pulls in diskcache ≤ 5.6.3 (unsafe pickle deserialization, no patched version). Install llama-cpp-python manually, in a trusted single-user environment only, if you accept that risk.


Contributing

See CONTRIBUTING.md. This developer setup is only for working on Velune itself. To use Velune, follow the quickstart instead.

Before opening a PR:

pip install -e ".[dev]"
ruff check velune/
ruff format --check velune/
pyright velune/
pytest -q

Report security issues via GitHub Security Advisories — not public issues.


License

Velune CLI is licensed under the Apache License 2.0.

Copyright 2026 Surya HA

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this project except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0, or in the LICENSE file in this repository. Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

The Apache-2.0 license applies to the source code. It does not by itself grant rights to the "Velune" project name, wordmark, or logo — Section 6 ("Trademarks") of the LICENSE reserves those. This is a name/branding reservation for the project, not a claim of registered trademark status.

About

VELUNE CLI is an open-source AI engineering CLI that unifies local LLMs (Ollama), cloud AI providers, MCP servers, tools, memory, and project context into a single developer workflow. Build, code, automate, and orchestrate AI with one extensible, provider-agnostic command-line interface.

Topics

Resources

Code of conduct

Contributing

Security policy

Stars

15 stars

Watchers

1 watching

Forks

Releases

Packages

Used by

Contributors

Languages