Mivia is built for software work that takes longer than a chat window.

Running long coding tasks in interactive chat sessions causes predictable problems:
- Closing your terminal or putting your laptop to sleep terminates the agent process mid-turn.
- When models guess on ambiguous architectural choices, they leave dirty diffs and broken syntax in your active working tree.
- Terminal scrollback discards tool exit codes and test failure traces before pull request review.

A Mivia **run** persists independently of your terminal, halts at configured approval gates, and writes an append-only event ledger to the pull request.

## Local agent and cloud workspace

Mivia operates in two places:

- **The Mivia Agent ([`mivia-agent`](https://github.com/MiviaLabs/mivia-agent))**: An open-source Go CLI that executes tools locally on your system and isolates edits in temporary git worktrees (`mivia/wt-*`).
- **The Mivia Workspace**: Cloud control plane for teams. It boots tasks in isolated micro VMs from GitHub webhooks and coordinates review queues.

Both environments share the same Go agent runtime, MCP tool schemas, and audit ledger format.

## How runs work

### Work continues in the background
Local runs execute in `.git/worktrees/mivia/wt-*`. Cloud runs execute in isolated micro VMs. Detaching your terminal or sleeping your laptop leaves the underlying execution process running.

### Halts for human decisions
Agents should not guess on irreversible operations or architectural boundaries. Mivia pauses execution at specific points:
- **Plan approval**: The agent drafts a markdown implementation plan and pauses before touching code.
- **Test verification**: Verification steps evaluate process exit codes (e.g. `pnpm gate:fast` or test suites) rather than model self-reports.
- **Delivery**: When all verification steps pass, the run pauses in `delivery_pending`. It will not push branches or open a pull request until you run `--allow-publish` or approve it from the web UI.

### Live terminal streaming and web control
When you authenticate the CLI (`mivia login`), local sessions stream output to your workspace over an authenticated connection. If you start a long refactoring task at your desk, you can check session progress from your phone or laptop browser.

The browser renders the raw token stream, tool stdin/stdout, and file diffs in real time. If the agent asks a question or pauses for plan approval, you can answer from the web UI. Your response unblocks the local agent running on your machine.

If you run the CLI unauthenticated or offline, it runs entirely local. No network events are sent.

### Audit ledger
An append-only database table records tool arguments, terminal stdout/stderr, test exit codes, and human approval timestamps. On completion, the runner attaches this ledger to the pull request so reviewers have empirical evidence of how the change was validated.

```mermaid
flowchart TD
    A[Task started via CLI, Issue, or Prompt] --> B[Create isolated worktree or VM]
    B --> C[Agent researches code and drafts plan]
    C --> D{Plan gate: human approval}
    D -- Request revisions --> C
    D -- Approved --> E[Implementation and test execution]
    E --> F[Run verification checks]
    F -- Check fails --> E
    F -- Checks pass --> G[Adversarial and boundary tests]
    G -- Defect found --> E
    G -- Passed --> H{Delivery gate: human approval}
    H -- Reject --> E
    H -- Approved --> I[Open pull request with audit ledger]
```

## Next steps

- [The Mivia Agent](/docs/mivia-agent) - Terminal architecture, git worktrees, and web control.
- [Getting started](/docs/getting-started) - Organization onboarding and provider API keys.
- [BYOK credentials](/docs/byok) - Encrypted key management for model providers.
- [Knowledge base](/docs/knowledge-base) - Storing repository conventions and architecture context.