Mivia 🤖

An AI coding agent for your terminal. Chat, tools, workflows, and multi-agent orchestration, while you keep your editor, your git, and your workflow.

Mivia reads, searches, and edits files in your project. It runs commands, such as your test suite. It streams model responses as they generate, and you can select and copy transcript text with the mouse. It can also run multi-step workflows in an isolated worktree, with a durable run record for every step.

Mivia works with Anthropic, OpenAI-compatible providers such as OpenRouter, DeepSeek, ZAI, Ollama, and MiniMax. If you have used Claude Code, Codex CLI, or Aider: Mivia runs in the same terminal, works with any of the built-in providers, and adds durable workflows and lifecycle hooks on top.

Your files stay on your machine by default. Mivia sends prompts and selected context to the AI provider you configure. Web search, configured MCP servers, lifecycle hooks, and workflow delivery can also contact external services or run configured local programs. Review those settings before use. See Integrations for the full list.

mivia is built on mivia-ai-sdk, our open-source, product-agnostic Go SDK for AI providers, tools, workflows, and hooks. Building your own agent? Start there.

🚀 Quick start

Requires Go 1.25+ to build from source, or use a prebuilt binary. You also need an API key for a supported provider. See Supported providers below.

Install

Tagged GitHub Releases provide archives for Linux, macOS, and Windows. Each release supports amd64 and arm64. See the release guide for release checks and pinned installs.

Piping a script into bash runs it with your shell's privileges. Inspect it first, or pin an exact tag, with:

curl -fsSL https://raw.githubusercontent.com/MiviaLabs/mivia-agent/v0.2.0/scripts/install.sh -o /tmp/mivia-install.sh
sed -n '1,240p' /tmp/mivia-install.sh
sh /tmp/mivia-install.sh v0.2.0

Install the latest stable release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/MiviaLabs/mivia-agent/main/scripts/install.sh | bash

Open a new shell, or source the profile that the installer reports. Then run mivia --version.

Install the latest stable release in Windows PowerShell:

irm https://raw.githubusercontent.com/MiviaLabs/mivia-agent/main/scripts/install.ps1 | iex
mivia --version

The installers verify the archive checksum before extraction. They use a user-owned directory and do not require administrator rights. Unix installs update a shell profile. A child bash process cannot update the parent shell, so open a new shell or source the reported profile. PowerShell also updates the current process when it can.

Use MIVIA_NO_PATH_UPDATE=1 on Unix or -NoPathUpdate in PowerShell to skip PATH changes. Latest installation requires at least one published stable release. Pre-release tags require an explicit version.

From source with Go 1.25+:

go install github.com/MiviaLabs/mivia-agent/cmd/mivia@latest

This method requires a published semantic version tag. Use a release archive when Go is not installed.

Or build the latest source:

git clone https://github.com/MiviaLabs/mivia-agent.git
cd mivia-agent
make build              # produces ./mivia

First run

mivia chat

mivia chat configures itself on first use: it writes a minimal config to ~/.mivia/mivia.toml (the shipped default provider, openrouter) and, if no API key is set yet, prompts for one once and writes it to ~/.mivia/.env (0600). Answer the prompt and you land in a working chat session - no other command needed.

For scripted or non-interactive setup (CI, no TTY), run mivia setup first so mivia chat finds a key already in place:

mivia setup             # writes your provider API key to ~/.mivia/.env (0600)
mivia doctor            # verify the key is visible; never prints it
mivia chat

mivia setup writes the key to an env file with owner-only permissions. It never prints the key value. For scripting, set the key as an environment variable and pass --provider. Avoid --key because shell history and process inspection can expose command arguments.

One-shot mode:

./mivia chat -p "what does this project do?"

Shell completions: mivia completion bash|zsh|fish prints a completion script for your shell.

Supported providers

Mivia is a local-first agent: prompts and selected context go to exactly one configured AI provider. Eight providers are built in:

Provider	Default model	Default API base URL
OpenRouter (default)	openai/gpt-5.6-luna	https://openrouter.ai/api/v1
Anthropic	claude-sonnet-5	https://api.anthropic.com/v1
DeepSeek	deepseek-v4-flash	https://api.deepseek.com/v1
ZAI (z.ai)	glm-5.2	https://api.z.ai/api/paas/v4
Ollama	gpt-oss:120b	https://ollama.com/v1
LLM Gateway	deepseek-v4-pro	https://api.llmgateway.io/v1
LLM Proxy CLI	claude-sonnet-5	http://127.0.0.1:8317/v1
MiniMax	MiniMax-M3	https://api.minimax.io/v1

Mivia does not accept an arbitrary OpenAI-compatible provider name: the provider registry rejects names it does not support, and every provider must declare its model catalog in the settings file (there is no remote model discovery). Configure a provider and its API key under Configuration; see Integrations for the external-service picture. Default provider: OpenRouter, model openai/gpt-5.6-luna; switch with --provider or in [provider] name = ....

Full dev setup (hooks, tests, verify gates): see Contributing. Provider and config options: see Configuration. Successful workflow runs stop at delivery_pending until you pass the explicit --allow-publish flag. See the Workflow guide.

🧩 What it does

• 💬 Chat with tool access: read, search, edit files; run allowed commands.
• ⚡ Streaming responses, with mouse text selection and copy (OSC 52, with a local clipboard fallback) and force-send for queued messages.
• 🔍 Web search.
• 🧠 Durable project and organization memory: committable Markdown files (.agents/memories/*.md) as the source of truth, indexed by a shared local SQLite cache for fast search.
• 🔗 Configurable MCP servers over stdio and Streamable HTTP, scoped per agent.
• 🔁 Workflows: durable, multi-step processes with retries and evidence gates.
• 🌳 Worktrees: isolated checkouts for a workflow run, so your working tree stays clean.
• 🖥️ Worktree sessions in the terminal UI: start a chat in any registered worktree, or resume one that already runs there (see below).
• 🧑‍🤝‍🧑 Agents and skills: named specialists you can route work to, and concurrent sub-agent task fan-out (dispatch_tasks / inspect_agents / join_run / cancel_run).
• 🪝 Lifecycle hooks: your own scripts run on PreToolUse, PostToolUse, and Stop - gate, format, or log every tool call, deterministically.

Worktree sessions

The /resume picker shows worktree state. A ⎇ glyph marks every session that is bound to a worktree. Below the normal rows, one route row per registered worktree starts a fresh chat session inside that worktree:

resume session
> ○ Refactor Storage Engine      [○ IDLE]  14 turns  2h ago
  ○ ⎇ Worktree Work              [○ IDLE]  4 turns   2h ago
-- in worktree --
  ○ ⎇ Worktree · wt2             [○ IDLE]

Rules the picker follows:

1. Select a session row with ⎇ to resume it. The app re-applies its worktree binding before the chat opens.
2. Select a row under -- in worktree -- to start a new session in that worktree. The new session has no transcript.
3. Route rows disappear when a saved session covers their worktree, and they return when no saved session covers it.

Press Ctrl+W anywhere (or inside the picker) to start a new session in a worktree without opening /resume. Type to filter as usual; route rows match by worktree name via their title. The preview pane (←/→) shows the selected row's worktree directory.

🏗️ Architecture

flowchart LR
    You["🧑 you"] --> Chat["mivia chat"]
    Chat --> Files["📁 project files"]
    Chat --> Config["⚙️ config"]
    Chat --> Agents["🧑‍🤝‍🧑 agents & skills"]
    Chat --> MCP["🔗 MCP servers"]
    Chat --> Coordinator["🧵 sub-agent coordinator"]
    Coordinator --> Ledger["🗄️ run ledger"]
    Chat --> Workflows["🔁 workflows"]
    Workflows --> Worktree["🌳 worktree"]
    Workflows --> Ledger
    Chat --> Provider["☁️ AI provider"]

Loading

Most work under mivia chat runs locally; the provider, web search, MCP, hooks, and delivery paths above are the exceptions. See Architecture overview for the coordinator, ledger, and provider-retry design in full.

📚 Docs

Guide	Covers
Product overview	What Mivia is, plain-language walkthrough
Configuration	Providers, keys, settings, and MCP servers
Integrations	External services Mivia can talk to
Coding agent mode	Chat, tools, agents, skills
Memory	Durable project and organization memory
Workflows	Step-by-step processes
Workflow guide	Workflow commands, the built-in workflow
Security and privacy	Data handling
Lifecycle hooks	Your own scripts on tool-call events
Terminal input	Mouse, selection, paste, and clipboard behavior
Architecture	System design
Contributing	Build, test, and PR process

📄 License

GNU AGPL-3.0