Run the agent on your own desktop not in another browser tab
Kova is a native desktop app: a streaming conversation surface driven by an independent local agent runtime that handles model turns, tool execution, and session persistence. What it may change, and whether it has to ask first, is decided by you — not by the model.
Three different bets
Most AI assistants are either a browser tab or a chat box with everything pushed through someone else’s cloud. Kova takes another road: the app is local, the model is swappable, the agent is constrainable.
Data and credentials bypass the middleman
Sessions, memory, subagent definitions, and MCP configuration live in
~/.kova/ and your workspace’s .kova/. API keys go to
the system keychain — on macOS, service name
com.kova.assistant. You can open the directory and see exactly
what it stores.
Changing models is a dropdown
Configure several providers in the model picker. Tool execution, session persistence, context compaction, and permission checks all run in the local sidecar, independent of the model — switching models bypasses no approval.
”Stop and ask” is local logic, not model manners
Suspending, approving, denying, and rolling back happen in deterministic code. When the model says “done”, that alone does not count — exit tools carry an objective id check, and a stale completion signal is rejected.
What actually happens in a conversation
You see a streaming thread. Behind it runs a deterministic loop — and only one of its steps belongs to the model. The rest is local code.
Assemble context
Pull session history, inject long-term memory and loaded skills, attach the content of @-mentioned files and any attachments. If the context is filling up, compact first, preserving key decisions and produced files.
Call the model
Hand it to the currently selected model; receive incremental text or a set of tool calls. Switching models affects only this step.
Adjudicate each tool call
Every call passes the session mode (may this tier write?) and then the approval level (must this tier ask?). Both must allow it.
Stop and ask when required
An approval suspends the turn with state preserved; when your answer arrives it resumes from exactly that step. A denied call returns to the model as a blocked result so it can take another route instead of deadlocking.
Execute, feed back, checkpoint
The tool runs inside the sidecar, its result is appended to the context, and the loop returns to step two. Every call and file change becomes a checkpoint you can return to.
It does not quietly decide for you
In the UI these are two separate dropdowns, and the combination is the actual behaviour. Collapsing them is the most common misunderstanding about Kova.
The full toolset. The default — reads, writes, runs commands, dispatches subagents.
Structurally read-only. It can read and plan, then uses plan_exit to
get approval before handing back to agent to implement. Planning and
implementation are separated by permission, so the reading phase never holds
write rights.
A read-only subset with no bash. For “just tell me, don’t touch
anything”.
Full toolset plus cross-turn autonomy. Your first message is the objective; the model works to completion without you pressing continue. See goal mode.
Inside the workspace and the writable-root list, writes are auto-approved; bash still asks, with “remember this class of command” generating prefix rules.
Deny, just this once, allow and remember. “Remember” stores a command word prefix, never a blanket: interpreter and destructive commands get no such button, matches are checked segment by segment, and redirects or command substitution are rejected the way the shell would read them. The writable-root list keeps it from ever granting write access to a directory you did not approve.
workspace-write level does not contain bash
— a command can reach any path outside the workspace through the shell. That
is a deliberate trade-off, covered in its own section of
docs/permission-modes.md. When you need real isolation, use a sandbox
or a container.Core capabilities
Multi-threaded sessions, attachments, and the prompt queue
Session management, attachments and @-mentions, slash commands, a model picker, voice input, and AI-summarised titles. The prompt queue keeps the composer usable while the agent is still working, and its entries persist into the session transcript — refresh, restart, and thread switches lose nothing.
A separate sidecar process
Long jobs never block the interface, a frontend crash never kills work in progress, and every surface reuses the same runtime. Coding, browser, HTTP, and screenshot tools ship in the box, with context compaction and long-term memory.
Task / TaskWait / TaskList / TaskStop
Independent contexts and toolsets, three-layer discovery (built-in / user / plugin), and an activity trail written as it runs — replayable after a restart.
Multi-server connection pool
Two-layer config merging, output guards, OAuth, and calls that pass through the same approval flow with an audit trail.
From setup to stats, all on your own machine
Pick a direction, or just say what you need.
The feature tour
Ten topics, each with a full design write-up — from the conversation workspace to prompt caching. Click through.
Conversation workspace
Multi-threaded sessions, attachments and @-mentions, checkpoint rollback, slash commands and voice input.
Prompt queue v2
QueueEngine snapshot persistence, three idempotent sync rules — queue entries keep even their images.
Modes overview
Five things called “mode”, fully separated: session mode, approval level, work mode, automation tier.
Goal mode
An explicit state machine, two stop valves, the stale-turn guard, and why there is deliberately no token budget.
Subagent design
The Task quartet, three-layer discovery, persistent activity replay, and token settlement.
Prompt caching
prompt_cache_key shard routing, shaped-alike summary requests, two miss-accounting standards.
Automation
Scheduled tasks, merged catch-up runs, the unattended approval tier, and webhook notifications.
Remote & mobile
Pairing codes for tokens, three network paths, the Expo app, and the security boundary.
Workspaces you actually open
A plugin is not a paragraph of prompt text — it is an interface you operate. The key is that its output is structured data, so the agent edits the same document instead of handing you a picture.
Slides & spreadsheets
Slide decks with per-slide editing, presentation mode, and .pptx
export; a spreadsheet powered by the Univer engine with formulas, styles,
merges, and frozen panes.
Infinite canvas
Text, shapes, images, Mermaid, tables, charts, and embedded web pages placed freely, exportable as a single SVG.
A Figma-style design workspace
Pages, artboards, a layer tree, and a full property inspector. It ships its own MCP server, so the agent drives canvas nodes directly — add, edit, delete, align, distribute, stack, and group.
Four layers
Splitting the agent into its own process is deliberate: long jobs never block the interface, a frontend crash never kills work in progress, and every surface reuses the same runtime. See Architecture.
Running in five minutes
You need Bun, a Rust toolchain, and Node.js. Full details in the Quickstart.
Who it is for
Code, data, and files stay on your own machine, and you would rather not upload a workspace to somebody’s server just to use an assistant.
You already run several MCP servers and want one place that manages them and records every call.
What you need is a .pptx and .xlsx you can actually
open — not a preview image in a chat box.
A template you can build on: a clear monorepo, the cross-surface contract
concentrated in packages/pi-protocol, and rebranding in one command.
Install it, or read two lines of code
Grab a build, configure a model, and start a conversation. To change it, every directory in the monorepo maps to one clear responsibility.
Kova — released under the Apache License 2.0. If you redistribute a derivative, keep the LICENSE file and the license notices of the upstream dependencies.