Install

Kora is a macOS app (10.15 or later). It wraps the agent CLIs you already have, so install and sign in to Claude Code first and make sure claude is on your PATH.

Kora is in early release (v0.1) and is built from source for now. You'll need Node.js 18+, Rust 1.77+ and the Tauri 2 prerequisites (Xcode Command Line Tools).

$ git clone https://github.com/faithdevss/kora.git
$ cd kora
$ npm install
$ npm run tauri build   # → src-tauri/target/release/bundle/macos/Kora.app

To hack on Kora, run npm run tauri dev for a live-reloading window. npm run dev serves the UI alone in a browser, which is handy for layout work, but no agent runs there.

Quick start

1. Open KoraA new tab starts a Claude Code session in your workspace. The status bar shows the agent, account and model, plus live context and token meters.
2. Type a prompt and press EnterResponses stream in with markdown, syntax highlighting and diffs. Press ⌘. to stop generating.
3. Type / for commandsThe palette shows Kora's commands plus the active agent's own, such as /compact and /review.
4. Add a second account (optional)/accounts add personal, then /accounts login personal. Kora prints a sign-in command; run it in a terminal, then /accounts refresh personal. The credential stays with the CLI.

Agents

Switch with /agents. Each agent brings its own accent color, models and commands, and the whole terminal recolors so you always know which one you're talking to.

Planned agents already appear in the switcher, but they say not connected until an adapter exists. Kora drives Claude Code in structured mode (claude -p --input-format stream-json --output-format stream-json), so there is no terminal scraping. The model list comes live from the CLI, not from a hard-coded table.

Accounts & parallel sessions

A Kora account is a separate Claude Code profile directory (CLAUDE_CONFIG_DIR). The CLI runs its own auth login into that directory. Kora reads back only the email, organization and plan from claude auth status.

/accounts

List accounts for the current agent. /users is an alias.

/accounts add <name>

Create a new profile.

/accounts login <name>

Print the command that signs this profile in. Run it in a terminal, then refresh.

/accounts <name>

Switch this session to that account. switch <name> also works.

/accounts refresh <name>

Re-read the identity and plan from the CLI.

/accounts rename <name> <new>

Rename an account.

/accounts remove <name>

Forget an account.

Usage & context

The status bar tracks the context window, session tokens (↑ in, ↓ out) and weekly usage for the active session. The weekly meter shows the utilization the CLI itself reports, never a guess. Usage is stored locally in SQLite and persists across restarts.

• 70% context: Kora suggests /compact or /clear.
• 90% context: Kora urges a compact, a clear or a fresh tab. Turn on Auto-compact in Settings to have the agent compact itself at this point.
• 90% of your rate limit: Kora warns you before you run out.

Compaction is always done by the agent. Kora never rewrites or drops your conversation. /usage, /statistics and /cost open card panels. Cost is real for API-key accounts and labeled as an estimated API-equivalent for Pro and Max subscriptions.

Files, images & search

• Paste or drag images into the prompt. They reach the agent as image blocks in its own protocol.
• Attach source, markdown, JSON, YAML and logs. Large files show a truncated preview before you send.
• Code blocks can be copied, saved to a file, or opened in your editor ($VISUAL / $EDITOR).
• Markdown is rendered with syntax highlighting and a diff viewer, and is sanitized so remote images can't leak data.
• ⌘K searches this session's scrollback. ⌘⇧P opens the global palette, which also searches every saved session.

Commands

Type these in the prompt. Any other slash command the agent supports (for example /compact, /clear, /review, /init) goes straight to the agent.

/help

List every command available right now.

/agents

Switch coding agent.

/accounts, /users

List, add, sign in to or switch accounts.

/models, /model

Pick a model the current agent offers.

/usage

Context, session and weekly meters with suggestions.

/statistics, /cost

Session statistics and cost.

/session

Save, list, rename, pin, archive, export and import sessions.

/search

Search the scrollback.

/tab, /split

Open a new session, or toggle split view.

/stop

Interrupt the agent.

/respawn

Restart a crashed agent, resuming its context.

/settings, /theme

Open settings.

/version, /update

Show the build and where to get a newer release.

Keyboard shortcuts

⌘ on macOS. Every binding is defined in one table (src/state/keymap.ts).

• Search this session⌘K
• Command palette⌘⇧P
• New session⌘T
• Close session⌘W
• Next session⌘⌥→
• Previous session⌘⌥←
• Toggle split view⌘D
• Stop generating⌘.
• Clear the context⌘L
• Command history⌘R
• Copy last response⌘⇧C
• Paste into prompt⌘⇧V
• Settings⌘,
• Show help⌘/
• Previous / next prompt↑ ↓

Settings & environment

The Settings panel (⌘,) writes settings.json in Kora's data directory, ~/Library/Application Support/dev.faithdevs.kora/. Sessions and usage live alongside it in SQLite. The settings file holds preferences only and cannot hold a secret.

{
  "theme": "kora-dark",
  "fontSize": 13,            // 9–24 px
  "fontFamily": "",           // empty = bundled JetBrains Mono
  "density": "comfortable",  // or "compact"
  "glow": true,
  "statusBar": true,
  "defaultAgent": "claude",
  "defaultModel": null,
  "autoCompact": false,
  "notifications": { … }
}

KORA_CLAUDE_BIN

Path to the claude executable if it is not on PATH.

KORA_DATA_DIR

Use a different data directory.

KORA_TIMING=1

Print how long the window took to appear.

Privacy & security

• No telemetry. Kora makes no network requests of its own. /update only shows you the releases page.
• No credentials. Accounts are CLI profile directories, and tests fail if anything secret-shaped lands in Kora's account or settings files.
• Approvals. The agent runs in its default deny mode. When it is refused a tool, Kora shows an approval prompt and retries once you approve.
• Locked-down UI. The webview has no filesystem, shell, HTTP or clipboard capability, and runs under a strict Content Security Policy.
• No shell injection. Agents are spawned with an argv array, never a shell string.

Add an agent

Adding an agent takes one new Rust file, one registry line and a test file. It needs no changes to the process manager, the Tauri commands or any TypeScript. Implement AgentAdapter (spawn spec, line parser, prompt encoder, capabilities, optional multi-account hooks) and register it.

Read the adapter guide → Adapters for Codex, Gemini CLI and Aider are the most valuable contributions right now.