The terminal agent

kovan is Kovan's coding agent in the terminal: the same agent loop as the desktop app, with a prompt in front of it. It runs on macOS, Linux and Windows and needs Node.js 22 or newer.

Install

On macOS and Linux:

curl -fsSL https://kovan.alperkayan.dev/install.sh | sh

On Windows, in PowerShell:

irm https://kovan.alperkayan.dev/install.ps1 | iex

Both install for you alone, without admin rights. The program goes to ~/.kovan/cli/ and a kovan command next to it: to ~/.local/bin on macOS and Linux (if that folder isn't on your PATH yet, the script prints the line to add to ~/.zshrc or ~/.bashrc), and to %USERPROFILE%\.kovan\bin on Windows, which is added to your user PATH.

Before anything is installed, the script checks that the release is signed with Kovan's release key and that the file matches the release's hash. A download that fails either check is not installed.

Use it

kovan                      # a conversation with the agent, in this folder
kovan "fix the failing test"  # one message: it does the work and exits
kovan -c                   # continue the last conversation in this folder
kovan -r "Auth work"       # continue a conversation by its name (or id), from any folder
kovan sessions             # conversations kept on this machine
kovan setup                # choose the model: an OpenRouter key, your Kovan account, or your own gateway
kovan config               # which server and model it talks to

In a conversation, type / for the commands, skills and custom commands, and /help for the keys. Tab changes the permission mode between allow, plan and request (full is turned on only with /mode full), Esc stops a running turn.

Conversations are kept the same way the desktop app keeps its own, so a conversation you start in the terminal shows in the app's chat list for that folder.

Name a conversation and come back to it

  • /rename <name> names the conversation you are in. The name is kept, and the desktop app's chat list shows it too. Until you name it, a conversation is called after its first message.
  • /resume lists every conversation on this machine: this folder's first, then the others with the folder they were held in. Type to filter the list by name. A conversation from this folder opens right there; one from another folder tells you the command to continue it there.
  • kovan -r <name or id> continues a conversation from anywhere, in the folder it was held in. A word of the name is enough when only one conversation fits; when several do, kovan lists them instead of guessing.
  • kovan sessions lists them all with their ids, folders and dates.

Coming back to a conversation brings back how you left it: the model (or the Claude Code or Codex account, with that CLI's own session, so it remembers what was said to it), the effort and the permission mode. A model you name now (-m, --effort, --mode) wins over what was saved. If what the conversation last used isn't available any more (an account you removed, say), kovan says so and carries on with the model at hand.

Which model it uses

The first time you run kovan with nothing set up, it asks how you want to run models: paste an OpenRouter key (kept in ~/.config/kovan/agent.json, readable only by you), sign in to your Kovan account and pay for models through Kovan, or use a gateway of your own. Nothing opens and nothing is saved until you choose. Run kovan setup to change it later.

Your own key or gateway always comes first:

  • OPENROUTER_API_KEY for any model through OpenRouter, or
  • KOVAN_BASE_URL and KOVAN_MODEL (plus KOVAN_API_KEY if it needs one) for an OpenAI-compatible gateway of your own.

With nothing of your own set up, sign in with kovan login and kovan uses your Kovan account's Kovan billing, if the server offers it. KOVAN_PROVIDER=managed asks for the account even when you have a key; KOVAN_PROVIDER=own never uses it.

The Claude Code and Codex accounts you added in the desktop app (Settings → Agents → Accounts) can also run a conversation: pick them with /models.

Asking before it acts

ModeWhat it does on its own
planPlan only: reads; changes nothing.
requestAsk first: asks before every edit and command.
allowEdit freely: edits files, asks before commands (default).
fullFull access: asks nothing.

The terminal starts at allow, one step looser than the app's Ask first: you're watching the same terminal it works in, and every edit is shown as it happens.

When it asks, answer y (yes), n (no) or a (always, for the rest of the session). For a command, a covers that command with other arguments (npm test also allows npm test -- --watch, not npm publish); a chained, piped or redirected command is allowed again only word for word. For an edit, it covers that tool. Start it with --mode <mode>, or change it with Tab or /mode.

What it reads

What you already wrote for Claude Code works here, in the same formats:

  • Skills: SKILL.md folders in the repository's .kovan/skills and .claude/skills, and in ~/.claude/skills. Type /skill-name to use one.
  • Notes: the repository's KOVAN.md, AGENTS.md and CLAUDE.md, plus your own ~/.kovan/KOVAN.md and ~/.claude/CLAUDE.md.
  • Custom commands: .kovan/commands/<name>.md and .claude/commands/<name>.md; $ARGUMENTS is what you typed after the name.

KOVAN_NO_CLAUDE=1 leaves everything of Claude Code's alone.

Updates

kovan looks for a new version in the background every twelve hours and installs it only when it is signed with Kovan's release key. When one has been installed, the status row says Update installed · Restart to update. Run kovan update to look right away, or set KOVAN_NO_UPDATE=1 to turn updates off.

Remove it

On macOS and Linux:

rm -rf ~/.kovan/cli ~/.local/bin/kovan

On Windows, delete %USERPROFILE%\.kovan\cli and %USERPROFILE%\.kovan\bin, and take %USERPROFILE%\.kovan\bin out of your user PATH (Settings → System → About → Advanced system settings → Environment Variables).

Your conversations stay in the desktop app's data folder, and your sign-in in ~/.kovan/auth.json (remove it with kovan logout first if you want it gone too).

Windows notes

  • Claude Code and Codex are found as claude.exe (the native build) or as npm's claude.cmd / codex.cmd; an npm command is started through its script with Node, never through cmd.exe, so nothing in your prompt is read as a shell command.
  • Commands the agent runs go through PowerShell.
  • Providers you added in the desktop app work here too: their keys are unlocked by Windows for your user account (DPAPI), the same way the desktop app reads them.