How to Use Kero: The Beginner's Guide

CodexFuse Team · 2026-11-04T01:09:23.334Z · 14 min read min read

How to Use Kero: The Beginner's Guide

Learning how to use Kero starts with one clarification, said once: this is Kero the terminal app for coding agents (kero.sh), not the KERO kerosene-heater brand that owns the bare word "kero" in search results. Kero is, in its own words, "a terminal for macOS, Windows and Linux built for working with coding agents" — you run Claude Code, Codex, a dev server, or a test watcher in its own session, and everything keeps running when you quit the app. If you already live in a plain terminal, the Ghostty beginner guide covers the classic fast-terminal side of the family; Kero is the agent-optimized offshoot that your agents can drive from the command line.

This Kero terminal tutorial walks the whole beginner arc in order: installing Kero and its kero command, starting your first session, controlling panes from any shell, watching agents with the events stream, and handing your agents a browser pane. Every command and behavior below comes from the Kero docs and the egoist/kero GitHub repo, both fetched on 2026-11-04 — nothing here is guessed.

What Is Kero?

Kero is a cross-platform native terminal app optimized for agents. Sessions run in kerod, a small daemon Kero starts on your machine, so closing the app — or even rebooting — does not end your sessions; reopening Kero restores every session, pane, and scrollback exactly where you left them. The sidebar groups sessions by project and shows each pane's status — working, waiting, idle, error, or exited — and ⌘J jumps you straight to the session that needs you, with notifications when an agent finishes, fails, or gets blocked.

The reason agents love Kero is the kero command: from any shell, a script, or an agent itself, it can list sessions, open panes, type, read screens, and wait for work to finish. Kero's terminals render with libghostty, so Ghostty themes, fonts, and config keys work unchanged. The project is by GitHub user @egoist (egoist/kero), written in Go, MIT licensed, at v2.1.32 as of 2026-11-03 — and it is the only terminal in its lane built around this idea: an AI agent terminal app your agents operate themselves.

How Do I Install Kero and the kero CLI?

Install the app first, then install its command-line tool. Download the latest Kero from the releases page at github.com/egoist/kero/releases; on macOS you drag Kero.app into Applications, and on Windows you run the "Kero Setup" installer, which needs no administrator rights. On Windows, Kero uses PowerShell 7 if it is installed, otherwise Windows PowerShell (cmd or Git Bash's bash are switchable in Settings › Shell) — and note that Windows 10 1809 or later is required for the pseudo consoles Kero relies on.

Once the app is open, choose Kero › Install Command Line Tool… and Kero puts kero on your PATH — a symlink in /usr/local/bin on macOS, ~/.local/bin on Linux, or Kero's bin folder added to your user PATH on Windows. Verify with kero help; typing bare kero opens the app. One thing to know before you search elsewhere for install commands: there is no documented Homebrew cask, winget, or scoop install — the documented channels are the releases page download and that in-app menu item. And on pricing: kero.sh publishes no pricing page or paid tiers, so treat Kero as free open-source (MIT); this guide will not quote a price that does not exist.

How Do I Start My First Kero Session?

You start a session with kero new, name it, and point it at a directory — Kero prints the session's id and the session joins your sidebar. In other words, kero CLI sessions are simply terminal sessions you start, split, and inspect with the kero command instead of clicking around a UI. Here is the beginner arc, six steps, each one verifiable in your own terminal:

1. Open the Kero app and make sure kero help answers in your shell.
2. Start a named session in a project folder: kero new -n api -d ~/code/api — it prints the session id.
3. List everything: kero ls shows every session and its panes.
4. Start a session that immediately runs a command: kero new -- npm run dev.
5. Bring it into view: kero focus api, or add -f when creating to focus at once.
6. Watch the sidebar: your session is grouped under its project, with a status that follows what the pane is doing.

A few flags make kero new much more useful. -n/--name names the session, -d/--dir sets its directory (default: current directory), -p/--project assigns the project (default: derived from the directory), -w/--wait waits for the session's command to end and exits with its status, -u/--url opens a browser showing the page instead of a shell, --worktree <branch> starts the session in a git worktree of its own on a new branch, and --base <ref> sets which branch that worktree starts from. kero close backend ends a session (or, given a pane, just the pane); kero close fix-login --remove-worktree also removes that session's own worktree — handle that flag with care, since it deletes the worktree.

How Do I Control Panes from the Shell?

You drive panes with kero split and a small family of commands, and almost every command takes a target: a session or pane id, any unique prefix of it, a session's name, or a session name standing for its focused pane. Inside Kero, $KERO_SESSION and $KERO_PANE name the session and pane the command runs in, and they are the default target — so commands typed in a pane act on that pane without naming anything.

Splitting is the core move: kero split --down -- npm test opens a pane beside the current one running your tests, kero split --right --ratio 0.3 -- go test ./... puts it on the right at thirty percent width, and run anywhere else, kero split my-session --down targets a named session. The command prints the new pane's id. kero split --url localhost:3000 opens a browser pane instead of a shell, which the browser section below covers. Manage panes with kero rename api backend, kero focus backend, kero close backend, and kero restart <pane>, which starts an exited pane's shell again in the same directory.

Then the agent-flavored part: type into a pane with kero send api "npm run migrate" --enter, press keys with kero key api ctrl+c (it understands enter, tab, escape, arrows, backspace, and modifiers like ctrl+d), and read screens with kero read api -n 40 (last 40 lines) or kero read api -a (screen plus scrollback). Waiting is built in: kero wait api waits until the pane stops working, kero wait api --for waiting,error --timeout 10m waits for specific statuses with a deadline, and kero prompt review "summarize the diff" sends text, waits until the pane stops working, and prints its screen — the quickest way to ask another agent something. One documented catch: waiting for a command does not work with cmd as the shell, because cmd cannot tell when a command ends.

How Does the kero Events Stream Watch My Agents?

kero events prints what happens to sessions and panes as it happens — one line per event, until you stop it — so a script can react to agents without polling. kero events watches every session, kero events api narrows to one session or pane, kero events -p kero narrows to one project's sessions, and kero events --for waiting,error shows only panes moving into those statuses. For machines, kero events --json | jq -r .name emits one JSON object per line; add --once to exit after the first matching event.

The events themselves tell the story: pane.status reports transitions like 12:04:31 api x78n9ss working → waiting — Allow Bash: rm -rf dist?, command.exited carries the exit code, and there are events for panes and sessions being created, closed, renamed, and moved, plus notice when a program in a session raises a desktop notification. JSON events add event, time (unix milliseconds), session, project, and the session's display name. Three cautions from the docs, each said once: events report changes from now on only — use kero ls --json for the current state; a status that lasts only a moment (a blip of "working") may never show; and --once exits with status 1 if the target closes first or --timeout passes.

What Can I Do with a Kero Browser Pane?

A Kero browser pane shows a web page beside your terminals — the dev server an agent is working on, the docs it reads, the pull request it opened — and agents can drive it with kero browser the way kero send and kero read drive a terminal. Open one with kero split --url localhost:3000 (it prints the pane's id), then: kero browser open localhost:3000/todos navigates and waits for load, kero browser snapshot lists what's on the page with refs for each element, kero browser click --ref e5 clicks, kero browser type --ref e3 "Buy milk" --enter fills a field and submits, kero browser wait --text "1 item left" waits for text to appear, and kero browser screenshot -o page.png captures the page. eval runs JavaScript and returns strings as-is or anything else as JSON, and cookies save/load persists logins as Playwright storage-state JSON or Netscape cookies.txt.

Two things to respect. Clicks and types send real mouse and keyboard events, so frameworks like React see them; refs persist until page navigation, and a ref whose element is gone fails rather than guessing another — deterministic, never fuzzy. And kero browser (like kero do) requires Remote Control turned on in Settings › Agents, which it is by default, and the app to be open. The docs' security note is worth quoting once: cookie files sign you in to sites, so "share their file only with what you'd trust with your logins" — and cookies stay on the machine that saved them, so programs on a remote host cannot save or load them. On the pleasant side, browser panes block ads and trackers with filter lists (EasyList and EasyPrivacy unless you choose others).

How Do I Run Kero Sessions on a Remote Machine?

Kero shows sessions running on other machines — a Linux dev box, a cloud VM, a Mac mini under your desk, a WSL distribution — in the same window as your local ones, with the same sidebar, statuses, notifications, and kero command. Add a host with kero hosts add devbox me@devbox, then kero -H devbox new -n review -- claude starts a session there. On a machine without the app (a cloud server, a Linux box), install the server build: curl -fsSL https://github.com/egoist/kero/releases/latest/download/install-server.sh | sh, or in Windows PowerShell irm https://github.com/egoist/kero/releases/latest/download/install-server.ps1 | iex — or simply kero hosts install devbox over SSH, which needs no root. If that remote machine will be a VPS, the what is VPS hosting guide covers picking one.

The details matter for reliability. Each machine runs its own kerod, so closing your laptop or quitting Kero leaves remote agents running, exactly as locally; when a link drops, the host's sessions stay in the sidebar, faded, and Kero reconnects on its own. Over SSH, Kero needs key-based login — password logins are not supported, keys with passphrases need your SSH agent, and a host you have never connected to should get one manual ssh me@devbox first so its key is trusted. kero ls --all lists sessions here and on every host at once, with an unreachable host saying why in place of its sessions.

How Do I Teach My Coding Agent to Use Kero?

Run kero skill setup: it installs a skill file that teaches agents the CLI — Claude Code reads it from ~/.claude/skills/kero, Codex, OpenCode and others from ~/.agents/skills/kero — plus a SessionStart hook that tells the agent which Kero session and pane it is in and names an unnamed session after its task, like fix-login-redirect. Use --agent claude|codex|pi|omp|opencode to set up one agent only; kero skill status, show, and remove manage it. If you have not met Claude Code yet, the Claude Code beginner guide is the companion to read next.

Once agents are inside Kero, the loop closes with status reporting: an agent runs kero report working "Migrating the database" --progress 40, kero report blocked "Approve the production deploy?" (which flips the session to waiting and notifies you — agents should only use it when they truly cannot continue without you), or kero report done "Deployed to staging", plus kero notify "Need your input" to flag its pane. Past work is recoverable: kero history lists agents' conversations, last-run first, and kero resume fix-login -f starts a session that resumes one and shows it in the app. And kero do runs the app's own menu actions from the shell — kero do pane.split.right, kero do sidebar.toggle — listed by kero actions, enabled by the same Remote Control setting.

Kero vs Ghostty: Which Terminal Should You Pick?

Pick Ghostty for a fast daily terminal; pick Kero when your terminals run coding agents. Ghostty is the general-purpose GPU-accelerated terminal, while Kero's whole design is sessions that outlive the app and a CLI that agents operate — and since Kero renders with libghostty, your Ghostty themes, fonts, and config keys carry over, so choosing Kero costs you nothing in familiarity. If the SSH-first workflow is your angle instead, the xtty beginner guide covers that lane.

In practice the two answer different questions. A general terminal answers "give me a fast shell"; Kero answers "run my agents and keep my place," with the sidebar statuses, ⌘J triage, the events stream for scripts, and browser panes for whatever the agent opens. For a beginner who just wants to type commands, Ghostty (or any terminal) is the simpler start; the moment your workflow becomes "an agent runs tests in one pane while you review in another," Kero's sessions-and-daemon model is the thing that was missing.

Sources

• Kero docs — kero.sh/docs (fetched 2026-11-04)
• Command Line reference — kero.sh/docs/cli (fetched 2026-11-04)
• Quick start / install — kero.sh/docs/quick-start (fetched 2026-11-04)
• Panes reference — kero.sh/docs/panes (fetched 2026-11-04)
• Remote hosts — kero.sh/docs/remote (fetched 2026-11-04)
• Teaching agents to use Kero — kero.sh/docs/agents (fetched 2026-11-04)
• egoist/kero GitHub repository README — github.com/egoist/kero (fetched 2026-11-04)
• egoist/kero releases — github.com/egoist/kero/releases (v2.1.32, released 2026-11-03; fetched 2026-11-04)

Frequently Asked Questions

Is Kero free?

Kero publishes no pricing page or paid tiers — the project is MIT-licensed open source on GitHub (egoist/kero). Treat it as free; this guide quotes no price because none is documented.

Is Kero the same as Ghostty?

No, but they are related: Kero renders its terminals with libghostty, so Ghostty themes, fonts, and config keys work in Kero. Ghostty is a general fast terminal; Kero is the agent-optimized terminal — sessions in a daemon that survive quit and reboot, plus the agent-drivable kero CLI.

Does Kero work with Claude Code and Codex?

Yes — the docs name Claude Code, Codex, and more. kero skill setup installs per-agent skills and a SessionStart hook so each agent knows which session and pane it is in.

Will quitting Kero stop my agents?

No. Sessions run in kerod and keep running when you quit or reboot; reopening Kero restores them. To actually end everything, use Kero › Quit and End All Sessions… (⌘⌥Q).

Can I run Kero sessions on a remote Linux server?

Yes. Install the server build with the documented curl command (no root needed), then kero hosts add devbox me@devbox and drive it with kero -H devbox …. Password logins are not supported — use SSH keys.