mivia

A local CLI coding agent. Chat, tools, workflows, and multi-agent orchestration, in your terminal.

mivia reads, searches, and edits files in your project. It runs commands, such as your test suite. It can also run multi-step workflows in an isolated worktree, with a durable run record for every step.

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.

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 (DeepSeek by default).

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.

Install the latest stable release on Linux or macOS:

curl -fsSL https://raw.githubusercontent.com/MiviaLabs/mivia-agent/master/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/master/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.

For a pinned release, inspect the script before you run it:

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

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

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.
• Web search.
• Durable project and organization memory, with an optional SQLite file that you can commit with the project.
• 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.
• Agents and skills: named specialists you can route work to.
• Lifecycle hooks: your own scripts run on PreToolUse, PostToolUse, and Stop - gate, format, or log every tool call, deterministically.

Architecture

flowchart LR
    You["you"] --> Chat["mivia chat"]
    Chat --> Files["project files"]
    Chat --> Config["config"]
    Chat --> Agents["agents & skills"]
    Chat --> Workflows["workflows"]
    Workflows --> Worktree["worktree"]
    Workflows --> Ledger["run record"]
    Chat --> Provider["AI provider"]

Loading

Most work under mivia chat runs locally. The provider, web search, configured MCP servers, lifecycle hooks, and workflow delivery are separate data or execution paths. Review their settings before use.

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
Architecture	System design
Contributing	Build, test, and PR process

License

MIT