@kvar/cli

Pair a device and serve ethical, transparent ads inside terminal AI coding tools — Claude Code, Codex, and Kimi Code.

Install

npm install -g @kvar/cli

Quick start (MCP)

The recommended way to use Kvar with modern AI coding agents is via the Model Context Protocol (MCP). kvar mcp exposes resources (current ad, transparency log) and tools (pair, status, pause/resume, refresh ad) that any MCP host can use.

# 1. Get a pairing code at https://www.kvar.ai/dashboard/devices, then:
kvar pair <code>

# 2. Install the Kvar MCP server into your host:
kvar setup kimi        # Kimi Code
kvar setup codex       # OpenAI Codex CLI
kvar setup claude-mcp  # Claude Code (MCP mode)

# 3. Restart the host. Kvar tools and resources are now available.

Each installer is idempotent, backs up any existing config, and supports --uninstall.

| Host | Config written by kvar setup … | |---|---| | kimi | ~/.kimi-code/mcp.json (MCP server only) | | codex | ~/.codex/config.toml | | claude-mcp | ~/.claude.json |

Note: Kimi Code does not currently expose a user-customizable bottom status line like Claude Code does, so kvar setup kimi installs the MCP server only. The model can read the current ad via the kvar://ad/current MCP resource. The kvar hook command is still available if you want to add a UserPromptSubmit hook manually.

For any other host, run kvar setup mcp to print the server JSON fragment and add it manually.

Status-line install (Claude Code)

Claude Code can also display Kvar ads directly in its status line. This is the best surface when you want the ad visible on every turn without invoking a tool.

kvar setup claude

kvar setup claude adds a statusLine entry to ~/.claude/settings.json (it backs up any existing file and won't overwrite a custom status line without --force). Remove it anytime with kvar setup claude --uninstall.

MCP vs. status-line

• MCP (kvar setup claude-mcp) gives Claude Code tools and resources: query status, pause/resume ads, inspect the transparency log, and fetch a fresh ad on demand.
• Status-line (kvar setup claude) renders the current ad continuously in the terminal UI. It is a display surface, not a management interface.
• The two can be used together: use MCP for management and the status line for display.

Commands

| Command | Description | |---|---| | kvar pair <code> | Pair this device with a 6-character code from the dashboard. | | kvar setup <target> | Install Kvar into a host (claude, claude-mcp, kimi, codex, mcp). | | kvar mcp | Start the Model Context Protocol server (stdio). | | kvar statusline | Render one ad line for a host status line (called by Claude Code). | | kvar hook | Kimi Code lifecycle hook entrypoint (injects the current ad into context). | | kvar serve | Fetch an ad for this device (prints JSON). | | kvar status | Show pairing status. | | kvar heartbeat | Send a heartbeat to Kvar. | | kvar logout | Remove stored device credentials. |

Configuration

Credentials are stored in ~/.kvar/config.json with 0600 permissions. The API base URL defaults to https://api.kvar.ai and can be overridden with API_BASE_URL. Set KVAR_CONFIG_DIR to use a different config directory (used in tests).

Privacy

Kvar never sends file names, paths, or source contents — only coarse category tags. Ads are clearly labelled. MIT © Kvar