MIVIA

Agents

The Mivia Agent

Go CLI architecture, git worktree isolation, real-time streaming, and web control.

The Mivia Agent (mivia-agent) is an open-source coding agent written in Go. It runs from your terminal, executes tools locally, and isolates changes in temporary git worktrees.

Built on mivia-ai-sdk, the binary handles interactive chat, headless script execution, and live session mirroring to the Mivia web interface.

Data boundary and API keys

Source code stays local

Your repository files stay on your machine. Mivia sends prompt context and tool results to the LLM provider you select. Code is not mirrored to third-party servers unless you configure web search tools or connect to a hosted workspace.

Supported model backends

  • OpenRouter (default)
  • Anthropic (Claude 3.7 / Claude 3.5 Sonnet)
  • DeepSeek
  • ZAI (GLM)
  • Ollama (local offline models)
  • LLM Gateway
  • LLM Proxy CLI
  • MiniMax

Keys are stored in your user directory (~/.mivia/.env, mode 0600). They are never written to project repositories and are stripped from diagnostic commands like mivia doctor.

Running the CLI

The agent works interactively or as a single-command script:

# Start an interactive session mivia chat # Run a single prompt directly from the command line mivia chat -p "Run the fast test tier and fix any failing assertions" # Point to a specific repository path mivia chat --workspace /path/to/project # Run with a specialist agent persona mivia chat --agent reviewer -p "Audit the last commit for security invariants"

Terminal behavior

  • Token streaming: Model output and reasoning tokens print to stdout as they arrive.
  • Mouse selection and clipboard: Supports terminal mouse selection and OSC 52 clipboard copy. You can select code blocks or command output directly in the terminal buffer.
  • Message queueing: Type instructions while an agent is running tools. Use force-send to redirect an agent immediately without terminating the process.

Controlling local agents from the web

You can monitor and steer your terminal agent from a browser or phone.

When you run mivia login, the CLI authenticates with your Mivia workspace. Future CLI sessions stream their execution events to the web backend over an authenticated connection.

Web steering and approvals

  • Remote steering: Start a long build or refactor at your desk, close your laptop or walk away, and check session progress from your browser. You can inspect tool stdin/stdout, review test outputs, or submit redirect prompts from any device.
  • In-browser plan approvals: When a local agent reaches a decision gate (such as drafting an implementation plan before touching code), the plan appears in the web UI. You can review the diff and approve it from the browser. Your approval unblocks the local CLI on your desk.
  • Privacy rules: The CLI redacts sensitive environment variables before sending events over the wire. If you run the CLI unauthenticated or offline, it runs entirely on your local machine and sends no network events.

Git worktree isolation

Running agents directly in your working tree pollutes uncommitted git state and breaks editor diagnostics with intermediate syntax errors.

Mivia handles this by running tasks in separate git worktrees:

  • When you start a task, Mivia creates a temporary worktree (mivia/wt-<timestamp>-<id>) branched from your target commit.
  • Edits, test runs, and commits stay inside .git/worktrees/mivia/wt-*, leaving the main working tree on your branch unmodified.
  • When the task finishes and passes review, the branch merges back and Mivia cleans up the temporary worktree.

Workflows and delivery gates

Workflows define multi-step loops in TOML. Each step has concrete exit criteria:

Deterministic exit checks

Steps do not rely on model self-evaluations. A step completes when its verification command (such as pnpm gate:fast) exits 0.

The delivery gate

When all steps pass verification, the workflow enters delivery_pending. The agent pauses. It will not push branches or open a pull request until you run --allow-publish or approve it from the web UI.

Subagents and declarative skills

Agent roles

Specialist personas are written as markdown files in .agents/agents/<name>.md. Each file defines:

  • High-level role (e.g., planner, builder, reviewer)
  • Tool permissions (such as read-only file tools for reviewers)
  • Provider and model configuration
  • System instructions

Skills

Skills are procedural guides stored in SKILL.md files (.agents/skills/<skill-name>/SKILL.md). When an agent handles a specialized task-like a database migration or security audit-it reads the corresponding skill file for instructions.

Lifecycle hooks

You can attach deterministic shell commands to agent tool events:

  • PreToolUse: Runs before a tool executes. It can inspect arguments and block execution (for example, stopping commands that touch production databases).
  • PostToolUse: Runs after a tool executes. Useful for formatting code or verifying module boundaries.
  • PostToolFailure: Runs when a tool fails to collect diagnostic data.
  • Stop: Runs when an agent turn completes.

Hooks are defined in ~/.mivia/mivia.toml (user-wide) and .mivia/mivia.toml (per-repo). Both apply without overriding each other.

Markdown memories

Agent learnings and project rules are stored as plain Markdown files rather than an opaque binary database:

  • Project scope: Stored in .agents/memories/*.md inside the workspace. Because these are plain Markdown files in your repository, you commit and review them in git. Every teammate and future agent session shares the same operational context.
  • Org scope: Stored in ~/.mivia/memories/*.md on your machine when org_id is set in ~/.mivia/mivia.toml. This lets agents recall solutions across multiple local repositories.
  • Derived search index: The agent indexes memory files into a local SQLite database at ~/.mivia/context.db. This database acts as a query cache. A background watcher updates it as files change, and you can rebuild it from the Markdown files at any time.

Agents inspect and update memories using memory_search, memory_save, and memory_delete. You can also query the index directly from your terminal:

mivia memory search "jwt token refresh" mivia memory search "postgres schema" --scope project --json

Model Context Protocol (MCP)

Mivia connects to external tools using the Model Context Protocol:

  • Connects to local MCP servers through stdio.
  • Connects to remote or containerized servers over Streamable HTTP.
  • Discovered MCP tools are scoped to authorized agents according to role configuration.