Agents
ket doesn’t ship its own agent. It runs the agent CLIs you already have installed, one per worktree or several side by side, and watches what they’re doing. For how to split work between them, see running coding agents in parallel.
How ket finds agents
Section titled “How ket finds agents”On launch, ket looks for Claude Code (claude), Codex (codex), Grok (grok) and OpenCode (opencode) on your PATH, and as aliases or functions in your login shell. Ollama models that can work as coding agents are listed too, as local agents. Any other agent works too: add it as an [[agents]] entry in config.toml with the command that starts it. ket can’t detect agents you add this way, so it treats them as installed.
Settings → Agents (⌘,) shows how many agents ket detected, with a Refresh button. Each agent has a card where you can turn it off, or override its command line, arguments and environment.
Local agents
Section titled “Local agents”A local agent is OpenCode 2 running a model that Ollama serves on your Mac. It appears as opencode:ollama/<tag>. Settings → Agents → On this Mac lists the models you’ve downloaded and offers downloads sized for your Mac’s memory. A model that can’t run as an agent shows why: it runs in Ollama’s cloud, it’s on another machine, it can’t call tools, or it’s too big for this Mac.
- Context. ket makes a copy of each model, named
<tag>-ket, pinned to the longest context that fits your memory: 64k, then 32k, then 16k. The copy shares the original’s files, so it takes no extra disk. - Only Ollama. A local agent’s OpenCode may use only the Ollama on your Mac. ket’s config denies every other provider, subagents included.
- One at a time. Prompts for a local agent wait in a queue while another local agent works, and go in order.
- Hand to the cloud. A local agent’s worktree menu has Hand to followed by a cloud agent’s name: your default agent, or the first cloud agent ket finds. It opens that agent in a new tab of the same worktree with a note typed in, telling it to read
git statusandgit diffand continue the task. ket doesn’t send the note, so nothing leaves the Mac until you press Enter. The local tab and its changes stay.
For setting up Ollama and OpenCode by hand, and the other ways to hand work to the cloud, see running local models with Ollama.
Which agent starts
Section titled “Which agent starts”When a worktree needs an agent, ket uses the first of these that’s set:
- The agent you picked for that worktree.
- The project’s preferred agent.
- The Default Agent in Settings: a specific agent, No agent (blank terminal), or Auto, which picks the first installed, enabled agent in alphabetical order.
How a session starts
Section titled “How a session starts”ket opens your login shell in the worktree and types the agent’s command at the first prompt, the same as you would. Your aliases, shell functions and version-manager shims all apply. In zsh you drop back to a prompt when the agent exits. In other shells, the tab closes.
When you return to a worktree, ket resumes the agent’s most recent session in that folder.
Terminals keep running after you quit ket; a small background process holds them. Set KET_HOST=0 to turn this off.
States in the sidebar
Section titled “States in the sidebar”| State | Meaning |
|---|---|
| running | The agent is thinking or running a tool. |
| waiting | The agent is blocked, usually on a permission prompt. It needs you. |
| failed | The session ended badly. Shown for five minutes. |
| merging | git is mid-operation in the worktree. It may also read rebasing, cherry-picking, reverting or bisecting. |
| busy | Something other than an agent is running, such as a build. |
| (no word) | Idle, or finished. |
Live states come from the hooks ket installs for Claude Code, Codex, Grok and OpenCode (see Install). Local agents run OpenCode, so they report the same states. Other agents show busy while their process runs, without the finer detail.
The header counts running and waiting agents across every project. ket doesn’t send macOS notifications; the header count, the pulsing row and the sidebar’s Waiting filter are how you find an agent that needs you.
Plan usage
Section titled “Plan usage”The header shows how much of each provider’s plan you’ve used, for example Claude · Session 15%, with a bar and the time until it resets. When there are several windows (per session and weekly), it shows the tightest. Click it for the full breakdown and a refresh button.
Reading usage costs no tokens. If ket can’t read it, the header says unavailable rather than showing 0%, and an old reading is dimmed. Usage is available for Claude, Codex and Grok, and for OpenCode once an OpenCode Go key is set. A provider that is turning requests away shows rate limited.
Permission presets
Section titled “Permission presets”Settings → Agents also has Agent Permissions: Yolo or Manual. These apply to sessions ket drives itself in the background, such as a quick prompt sent to a worktree with no terminal open. An agent running in a terminal tab follows its own settings.