Process Architecture

The "Core concepts" group explains how Klaus works internally. You do not need it for everyday use; it helps when you want to understand a limitation or troubleshoot a problem.

Klaus is split into two layers. The shell owns the window, the interface, system integration, and everything that talks to macOS; the engine is a separate child process that talks to the model, calls tools, and maintains sessions. The two communicate over JSON-RPC on standard input and output.

The whole app starts exactly one engine process, shared by every session, scheduled task, and channel message. After startup the engine has 20 seconds to complete its handshake; if it times out, it is reclaimed, the interface reports an error, and it is started again on your next action. Each session maps to one thread inside the engine, and the session id appears in the file name of that session's record on disk (see Where the data lives).

Because one process carries every session, "what happens when the engine goes down" has to have an answer. It has three layers:

• Disconnect recovery: when the connection drops, a call in flight is not left hanging forever — pending requests fail with an error, the event pump exits on its own once the event channel closes, and anything still unsent in the client queue is redelivered. What reconnects is a new generation, and events that arrive late from the previous generation are dropped by generation id, so they never bleed into the new conversation. In the interface this shows up as the red dot in the sidebar: reconnecting, and gone once it reconnects.
• Automatic resume after a restart: Klaus keeps its own ledger recording which sessions still had an unfinished turn when it last exited (an update restart, a crash, or you quitting all count). Five seconds after the next startup it reads that ledger, opens those sessions one by one, and continues the turn that never finished; the background processes and sub-agents that turn was waiting on are rebuilt by the turn itself through the normal tool flow. So after an update restart you do not have to click continue session by session. Sessions started by a channel message are out of scope here — nobody is waiting on them, and rerunning one would amount to resending a message.
• A problem in one session does not spill over: an error or a hang in one session affects only that session; the rest carry on as usual.