Troubleshooting

Fixes for the problems people run into most, and how to report the rest.

Agents

An agent is missing from New session

New session lists only installed agents, and Kettu looks for them on the PATH of your login shell. In Settings › Harnesses, an agent Kettu did not find is under Not installed, and Install… shows the ways its maker documents. If it is installed somewhere Kettu does not look, click Installed somewhere else? Choose the program… and pick it.

If you installed it in your own terminal while Kettu was open, click Reload environment at the bottom of Settings › Harnesses.

The agent menu marks it Sign in, and starting it opens a dialog such as Sign in to Codex. Click Sign in in terminal, sign in the agent’s own way, then click I’ve signed in, retry. For Codex you can also run codex login in a terminal. Kettu never sees your credentials.

An agent fails to install

Agents installed as ACP packages need Node.js 22 or later with npm. fast-agent and Minion Code need uv instead. After installing either, click Reload environment in Settings › Harnesses.
Behind a proxy, set it in Settings › Advanced › Proxy, which agents, npx and updates use.
Copy log copies what the install printed, and Install failed, retry tries again.

Claude Code says your claude is too old

Kettu drives your own claude through the Claude Agent SDK, which needs at least the version of Claude Code it was built for. With an older one, Claude Code reports that it needs a newer claude and names the version you have. In Settings › Harnesses › Claude Code, the Update to button with the new version updates it the way you installed it. The command is shown too, so you can run it in your own terminal instead.

An agent keeps stopping

When an agent stops several times within five minutes, Kettu does not start it again until you retry. If it keeps happening, export diagnostics as described below and report it.

Installing and opening Kettu

The macOS build is signed and notarized by Apple, so it opens like any other app once it is in Applications. If you run Kettu straight from the disk image, it cannot update there: Update moves it to Applications first, then restarts.

For Open at login, macOS may ask you to allow Kettu in System Settings › General › Login Items.

The AppImage needs FUSE 2: install libfuse2, or libfuse2t64 on Ubuntu 24.04 and later. Make the file executable before you run it:

chmod +x Kettu-x86_64.AppImage

Logs and reports

Where are the logs?

Kettu keeps its log, the agents’ messages and their error output in memory, not in files. To save them, click Export diagnostics in Settings › Advanced. Kettu asks where to save a JSON file, in Downloads by default. The file can contain code and prompts, so share it only with people you trust.

Report a problem

Open an issue at github.com/KettuAI/Kettu/issues, or click Report an issue in Settings › About. Say what you did and what happened, in any language; a screenshot and the diagnostics file help. Report security problems privately, as SECURITY.md says, never in a public issue.