mivia

package module

v0.1.3 Latest Latest Go to latest Published: Aug 30, 2026 License: AGPL-3.0 Imports: 0 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/MiviaLabs/mivia-agent

Links

Open Source Insights

README ¶

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.

mivia TUI showcase

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.1.2/scripts/install.sh -o /tmp/mivia-install.sh
sed -n '1,240p' /tmp/mivia-install.sh
sh /tmp/mivia-install.sh v0.1.2

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, 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"]

Most work under mivia chat runs locally; the provider, web search, MCP, hooks, and delivery paths above are the exceptions.

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

Documentation ¶

Overview ¶

Package mivia is the migration record for the session-analysis schema v1 -> v2 change.

WHAT CHANGED (schema v1 -> v2; contract files under .agents/skills/session-analysis/):

queries.py now emits three new report fields: "derivation" (workspace_id algorithm disclosure, hex_chars=16), "store_accounting" (context_sessions lifecycle breakdown: total/tombstoned/alive/never_published_source_sequence_0/ published_source_sequence_gt0), and "admissions_coverage.note" (an empty admitted-tool set deletes the admission row; see internal/storage/session_admissions.go:38-43).
report-template.md grew a Findings "[SOURCES: ...]" column, a MIGRATION note, and a "## Migration" section with the deployment checklist.
The previous workspace_id derivation (8 hex chars) mis-scoped every run against the harness ledger (16 hex chars); the corrected derivation is disclosed in the output under "derivation".

WHY NO go.mod REPLACE: nothing in this module imports the skill package, so a fake "replace" directive would be an inert footgun that silently redirects any future real dependency on that path. The migration is recorded here and in report-template.md instead; queries.py, this file, and report-template.md together form the v1->v2 contract.

Consumers: findings templates and dashboards reading report JSON should move to the v2 field names; v1 field names keep parsing (nothing was removed or rekeyed).

Source Files ¶

View all Source files

mivia.go

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
mivia command Command mivia is the MiviaLabs local CLI AI agent entrypoint.	Command mivia is the MiviaLabs local CLI AI agent entrypoint.
internal
agent The SDK imports are out-of-prefix; the gate filters them out of the in-prefix edge set (scripts/check_import_layers.py compute_edges), and the policy baseline is unchanged.	The SDK imports are out-of-prefix; the gate filters them out of the in-prefix edge set (scripts/check_import_layers.py compute_edges), and the policy baseline is unchanged.
agentmsg Package agentmsg is the leaf surface for typed agent-to-agent messages.	Package agentmsg is the leaf surface for typed agent-to-agent messages.
agents Package agents resolves file-backed agent definitions into immutable runtime snapshots.	Package agents resolves file-backed agent definitions into immutable runtime snapshots.
chat Package chat implements multi-turn sessions with disk persistence.	Package chat implements multi-turn sessions with disk persistence.
cli Package cli implements mivia command handlers.	Package cli implements mivia command handlers.
cliagents
clichat Typed action model: every transcript action is a tool (⚙), an agent (◆), or a skill (§).	Typed action model: every transcript action is a tool (⚙), an agent (◆), or a skill (§).
cliorchestrate
cliworkflow Package cliworkflow holds the workflow CLI domain: workflow run, resume, deliver, status, events, approve, reject, cancel, cleanup, delete, and gc commands, the session workflow tool engine, and the workflow snapshot and verifier pinning machinery.	Package cliworkflow holds the workflow CLI domain: workflow run, resume, deliver, status, events, approve, reject, cancel, cleanup, delete, and gc commands, the session workflow tool engine, and the workflow snapshot and verifier pinning machinery.
cliworktree
codeintel Package codeintel resolves symbol references by type-checking a workspace.	Package codeintel resolves symbol references by type-checking a workspace.
composition Package composition owns session wiring: registries, dispatchers, hooks, MCP merge, session construction.	Package composition owns session wiring: registries, dispatchers, hooks, MCP merge, session construction.
config Package config loads mivia TOML configuration and resolves provider settings.	Package config loads mivia TOML configuration and resolves provider settings.
contextmgr Package contextmgr owns context preparation policy and provider-message conversion.	Package contextmgr owns context preparation policy and provider-message conversion.
contextstate Package contextstate is the CLI's durable context contract layer.	Package contextstate is the CLI's durable context contract layer.
coordinator Package coordinator provides the orchestration seam between model-facing tools and the subagent execution pool.	Package coordinator provides the orchestration seam between model-facing tools and the subagent execution pool.
diff Package diff provides bounded, dependency-free line diffs for tool output.	Package diff provides bounded, dependency-free line diffs for tool output.
events
evidencecheck
faultinject Package faultinject provides a deterministic, counter-based fault and hang trigger for concurrency and failure-path tests.	Package faultinject provides a deterministic, counter-based fault and hang trigger for concurrency and failure-path tests.
gittest Package gittest holds test-process configuration for packages whose tests spawn real git processes against temporary fixture repositories.	Package gittest holds test-process configuration for packages whose tests spawn real git processes against temporary fixture repositories.
hooks Package hooks owns mivia's deterministic lifecycle-hook layer: the config shape and the isolated execution path hook commands run through.	Package hooks owns mivia's deterministic lifecycle-hook layer: the config shape and the isolated execution path hook commands run through.
hooksession Package hooksession owns the running session's resolved lifecycle-hook state: discovery, arming, and the /hooks listing text.	Package hooksession owns the running session's resolved lifecycle-hook state: discovery, arming, and the /hooks listing text.
hub Package hub lets several `mivia` processes working the same session - a terminal TUI and, e.g., mivia-agent-desktop's spawned `mivia chat --json` process - see each other's live turns.	Package hub lets several `mivia` processes working the same session - a terminal TUI and, e.g., mivia-agent-desktop's spawned `mivia chat --json` process - see each other's live turns.
jschema Package jschema is a fail-closed JSON Schema compile/validate wrapper for structured subagent outputs (plan tools/02).	Package jschema is a fail-closed JSON Schema compile/validate wrapper for structured subagent outputs (plan tools/02).
ledger Package ledger defines immutable identity types, snapshots, and the repository boundary for subagent orchestration.	Package ledger defines immutable identity types, snapshots, and the repository boundary for subagent orchestration.
ledgercore Package ledgercore provides shared primitives and infrastructure for event-sourced ledger implementations in the mivia agent.	Package ledgercore provides shared primitives and infrastructure for event-sourced ledger implementations in the mivia agent.
mcp Package mcp implements MCP client configuration and tool adapters.	Package mcp implements MCP client configuration and tool adapters.
memory Package memory implements durable agent memory: project-scoped and org-scoped entries with a strict Markdown format.	Package memory implements durable agent memory: project-scoped and org-scoped entries with a strict Markdown format.
miviaauth Package miviaauth provides primitives to interact with the openapi HTTP API.	Package miviaauth provides primitives to interact with the openapi HTTP API.
newtui
prompts Package prompts holds prompt fragments that the compiled-in system prompts share.	Package prompts holds prompt fragments that the compiled-in system prompts share.
provider Package provider implements LLM chat adapters for mivia.	Package provider implements LLM chat adapters for mivia.
providerregistry Package providerregistry owns dependency-neutral built-in provider metadata.	Package providerregistry owns dependency-neutral built-in provider metadata.
reasoning Package reasoning is the provider-neutral vocabulary for model reasoning control: how hard a model should think, and which wire dialect expresses that to its provider.	Package reasoning is the provider-neutral vocabulary for model reasoning control: how hard a model should think, and which wire dialect expresses that to its provider.
redact Package redact applies the workspace's redaction policy to operator-visible text and structured values.	Package redact applies the workspace's redaction policy to operator-visible text and structured values.
remainder Package remainder owns the truncated-result spool and its caller-scoped visibility grants.	Package remainder owns the truncated-result spool and its caller-scoped visibility grants.
runtime Package runtime contains the shared invocation boundary for model-directed work.	Package runtime contains the shared invocation boundary for model-directed work.
sdkadapter Package sdkadapter - shared approval types.	Package sdkadapter - shared approval types.
secretpath Package secretpath matches configured workspace secret paths.	Package secretpath matches configured workspace secret paths.
skills Package skills defines independently typed, policy-bearing skills.	Package skills defines independently typed, policy-bearing skills.
storage Package storage provides the validation seam for durable agent events.	Package storage provides the validation seam for durable agent events.
subagents Package subagents provides shared prompt constants for sub-agent handlers.	Package subagents provides shared prompt constants for sub-agent handlers.
testenv Package testenv isolates a test binary from the developer's own machine state.	Package testenv isolates a test binary from the developer's own machine state.
textutil Package textutil provides small, dependency-free string-safety primitives shared by packages that must not depend on each other: rune-safe byte-cap truncation (jschema, delivery) and control-byte detection (workflows/controller, workflows/compiler).	Package textutil provides small, dependency-free string-safety primitives shared by packages that must not depend on each other: rune-safe byte-cap truncation (jschema, delivery) and control-byte detection (workflows/controller, workflows/compiler).
tools Package tools implements workspace-bound agent tools.	Package tools implements workspace-bound agent tools.
ui/app Package app is the root Bubble Tea model: a Screen router (a stack, not nullable dialog pointers - build spec section 4.5) plus the global keymap.	Package app is the root Bubble Tea model: a Screen router (a stack, not nullable dialog pointers - build spec section 4.5) plus the global keymap.
ui/component/approval Package approval renders one pending tool-approval request inline and turns keypresses into a ports.Decision.	Package approval renders one pending tool-approval request inline and turns keypresses into a ports.Decision.
ui/component/blackboard Package blackboard renders the interactive run blackboard and inter-agent messaging center in the Terminal UI.	Package blackboard renders the interactive run blackboard and inter-agent messaging center in the Terminal UI.
ui/component/composer Package composer is the multi-line message input plus a slash-command completion list and an @-mention file picker.	Package composer is the multi-line message input plus a slash-command completion list and an @-mention file picker.
ui/component/field Package field is one editable settings row: a label plus either free text (KindText, wrapping bubbles/textinput) or a cycled value from a closed set (KindChoice, no textinput at all - so an invalid value is unreachable, not merely rejected).	Package field is one editable settings row: a label plus either free text (KindText, wrapping bubbles/textinput) or a cycled value from a closed set (KindChoice, no textinput at all - so an invalid value is unreachable, not merely rejected).
ui/component/history Package history renders the message history overlay above the composer and lets the user navigate and select previous prompt messages.	Package history renders the message history overlay above the composer and lets the user navigate and select previous prompt messages.
ui/component/mark
ui/component/picker Package picker is a generic, minimal list picker.	Package picker is a generic, minimal list picker.
ui/component/queue Package queue renders the queued messages overlay above the composer and lets the user inspect, navigate, and remove queued messages.	Package queue renders the queued messages overlay above the composer and lets the user inspect, navigate, and remove queued messages.
ui/component/statusline Package statusline renders the permanent status row above the composer: the brand mark in the turn's state, the activity label, and the elapsed time while a turn is in flight, and the row is reserved (and shows the keymap hint) when it is not.	Package statusline renders the permanent status row above the composer: the brand mark in the turn's state, the activity label, and the elapsed time while a turn is in flight, and the row is reserved (and shows the keymap hint) when it is not.
ui/component/topbar Package topbar is the cockpit's fixed top row: the brand mark and wordmark on the left, the session's model and context usage on the right.	Package topbar is the cockpit's fixed top row: the brand mark and wordmark on the left, the session's model and context usage on the right.
ui/component/transcript Package transcript renders the conversation for the inline-first UI.	Package transcript renders the conversation for the inline-first UI.
ui/component/welcome Package welcome renders the start screen splash banner for a clean CLI session.	Package welcome renders the start screen splash banner for a clean CLI session.
ui/jsonout Package jsonout is the --output json renderer: newline-delimited JSON, one uievent.Event per line, in the same wire form testdata/ fixtures use.	Package jsonout is the --output json renderer: newline-delimited JSON, one uievent.Event per line, in the same wire form testdata/ fixtures use.
ui/render Package render turns theme roles into concrete lipgloss styles and renders structured event bodies (diffs, markdown, dialogs, headers) into styled text.	Package render turns theme roles into concrete lipgloss styles and renders structured event bodies (diffs, markdown, dialogs, headers) into styled text.
ui/screen/conversation agent_stall.go holds the "stalled" display derivation for the files panel's subagent rows.	agent_stall.go holds the "stalled" display derivation for the files panel's subagent rows.
ui/screen/settings Package settings is the full-screen /settings modal: a left nav sidebar (General, Models, MCP, Agents, Automations) beside a detail pane, keeping the top bar and a status row.	Package settings is the full-screen /settings modal: a left nav sidebar (General, Models, MCP, Agents, Automations) beside a detail pane, keeping the top bar and a status row.
ui/screen/themepicker Package themepicker is the alt-screen modal (build spec section 3.4) that live-previews and selects an app-wide theme.	Package themepicker is the alt-screen modal (build spec section 3.4) that live-previews and selects an app-wide theme.
ui/screen/transcript Package transcript is the full-screen pager over the conversation (cockpit-research.md rule 6.2).	Package transcript is the full-screen pager over the conversation (cockpit-research.md rule 6.2).
ui/select Package sel holds the value types for component-owned mouse text selection.	Package sel holds the value types for component-owned mouse text selection.
ui/stream Package stream is the non-TTY plain renderer: readable text with no ANSI escapes, no theme dependency, safe to pipe.	Package stream is the non-TTY plain renderer: readable text with no ANSI escapes, no theme dependency, safe to pipe.
ui/theme Package theme is the single source of style for internal/ui: semantic roles, never raw colours at call sites.	Package theme is the single source of style for internal/ui: semantic roles, never raw colours at call sites.
uiadapter Package uiadapter: Phase 2 Conversation and TurnHandle over chat.Session.	Package uiadapter: Phase 2 Conversation and TurnHandle over chat.Session.
uikit/clipboardwrite Package clipboardwrite shells out to the local system's clipboard tool as a fallback delivery path alongside OSC 52.	Package clipboardwrite shells out to the local system's clipboard tool as a fallback delivery path alongside OSC 52.
uikit/config Package config holds every timing, limit, and threshold used by the new UI in one place.	Package config holds every timing, limit, and threshold used by the new UI in one place.
uikit/intent Package intent carries user intents from the UI to the harness, the input side of the uievent contract.	Package intent carries user intents from the UI to the harness, the input side of the uievent contract.
uikit/keymap Package keymap is the keymap as data, not as code.	Package keymap is the keymap as data, not as code.
uikit/ports Package ports defines the consumer-side interfaces between the UI and the harness.	Package ports defines the consumer-side interfaces between the UI and the harness.
uikit/replay Package replay implements ports.Conversation/TurnHandle/Approver over a fixed sequence of uievent.Event, replayed on every Send call.	Package replay implements ports.Conversation/TurnHandle/Approver over a fixed sequence of uievent.Event, replayed on every Send call.
uikit/termprobe Package termprobe turns terminal environment facts into cockpit decisions.	Package termprobe turns terminal environment facts into cockpit decisions.
uikit/uievent Package uievent defines the canonical UI event stream: the contract between the harness and all three renderers (TUI, plain stream, JSON).	Package uievent defines the canonical UI event stream: the contract between the harness and all three renderers (TUI, plain stream, JSON).
usage Package usage defines the usage-accounting contract shared by the agent runtime and the storage layer.	Package usage defines the usage-accounting contract shared by the agent runtime and the storage layer.
vcs
version Package version reports build identity for the mivia CLI.	Package version reports build identity for the mivia CLI.
workflows/controller Package blockedpath detects when task text or agent output instructs a write to a workspace path that the host write-path policy blocklists for workflow agents.	Package blockedpath detects when task text or agent output instructs a write to a workspace path that the host write-path policy blocklists for workflow agents.
workflows/definition Package verifier provides the execution machinery for deterministic verifier profiles behind evidence_gate steps.	Package verifier provides the execution machinery for deterministic verifier profiles behind evidence_gate steps.
workflows/delivery Package delivery runs delivery commands against pinned git contexts.	Package delivery runs delivery commands against pinned git contexts.
workflows/ledger Package agenttools exposes in-process workflow tools for the agent surface.	Package agenttools exposes in-process workflow tools for the agent surface.
workflows/localengine Package localengine provides an in-process workflow Engine for agent tools.	Package localengine provides an in-process workflow Engine for agent tools.
workspace Package workspace confines filesystem access to a root directory.	Package workspace confines filesystem access to a root directory.