Desktop app

zidane-gui is the Electron desktop app. It runs the same chat engine as the TUI, so sessions, settings and sign-ins carry over (what each app has).

api/Rate limit the chat endpoint

api-errors.md

Rate limit the chat endpoint: 20 requests a minute per IP, and tell clients how long to wait when it trips. The chart shows who hit it last night.

Used find the chat route and any limiter, edited a file, used run the server tests3

2 earlier messages

• The chat route now takes a token from a per-IP bucket: 20 a minute, with bursts of 5. Over the limit it answers 429 with a Retry-After header, so clients know how long to wait.

  All 44 server tests pass.

  Opus 5.538s4$0.0717k1.1k

Document it in docs/server.mdx, then commit.

Used document the limit in a subagent, then commit, 1 worker1

• Documented under Limits in docs/server.mdx and committed as 83dfea7.

  Opus 5.552s3$0.0912k980

BuildOpus 5.5+1medium

main+24−32 files

Install#

The app is for macOS and Linux, on arm64 and x64.

brew install --cask tahul/tap/zidane

npm install -g zidane-gui

The rest of this section is about the npm install. A global install adds a launcher:

After --ignore-scripts or a root install, run zidane-gui install-app as your regular user.

To uninstall, remove the launcher first. npm 7 and later do not run preuninstall scripts. If you remove the package first, the launcher stays and points at a deleted install.

zidane-gui uninstall-app
npm uninstall -g zidane-gui

Launch#

First launch#

A fresh install opens the setup wizard. It connects a provider and brings over your Claude Code setup when it finds one. It adds connectors and extensions. It also sets the look, the conversation display, the approval mode and the optional features. Quick start on the first step keeps the defaults for the rest.

The wizard does not open on its own when this computer already has zidane settings, credentials or sessions. If you ran the wizard in the TUI, the first launch of the desktop app opens only the steps of the desktop app. If a first run does not finish, the wizard opens again at the next launch. ZIDANE_NO_ONBOARDING=1 turns the wizard off.

Connect has a Skip button, and a Not now button when Connect opens alone. Without a provider, the footer shows a red sign in button. That button opens Connect (providers).

If you send a message without a provider, the app creates no chat and keeps your text in the composer. A Connect a provider card shows above the composer, and its Connect button opens Connect. The card goes away when a provider is ready.

To open the wizard again, use Run setup again at the bottom of the Settings sidebar. Run setup in the command palette (Command KK) opens it too. The wizard then starts on Connect, with your current values.

A new chat opens on the welcome screen. You can send a message at once, because a chat needs no folder. For the agent to work on a project, pick a folder in the composer first (start a new chat).

The welcome screen shows your usage across every session on this computer, for All, 30d or 7d:

The first message replaces it with the transcript.

The window#

The command palette (Command KK) lists every action. The keyboard map lists every shortcut. Sessions, credentials and settings live in files the TUI reads too (files and folders, what the desktop app adds).

The app has no menu of its own, no tray icon and no deep links. A session that needs you shows a status dot in the sidebar and a count on its Inbox tab. Settings › General › Notifications is off by default. When it is on, the app sends a notification for a finished or failed run and for a waiting approval or question, while no Zidane window has the focus. The dock badge counts what waits.

More than one window#

Right-click a session row in the sidebar, or use the palette's Windows group:

A session lives in one extra window at most. If you open it again, the app focuses that window. Closing a chat-only window (Command WW) moves the session back into the main window. File chips and the git bar act on the window showing the session's panels.

All windows share one engine and show the same runs. The daemon shares live runs with the TUI and keeps them going after you quit.

Updates#

Where the app looks for a new version depends on how you installed it. Settings › General › Updates says which applies:

The app checks for a new version 3 seconds after start, then every 6 hours, and shows a footer button:

For an npm install, installing updates both zidane-gui and zidane-tui with the package manager you used. A zidane upgrade in a terminal also turns the button into the relaunch button.

To install new releases in the background, turn on Settings › General › Updates › Install updates automatically. The app never restarts on its own. The relaunch button appears when the new version is on disk. Quitting the app does not stop an install: it runs in a background process and finishes. If an install fails, the button shows the error once. When the failure may pass (no network, the release not downloadable yet), the app tries again later. Otherwise it waits for a newer release, or for you to click the button.

Settings › General › Updates › Check for updates off stops the checks. A pending relaunch still shows. ZIDANE_GUI_NO_UPDATE=1 turns the checks off, and so does a dev run.

If the window crashes#

Uncaught errors go to Settings › Advanced › Logs.

Reference#

• zidane/chat: the engine the app runs.
• zidane/ipc: the protocol between the window and its host.
• zidane-ui: the components the window is built from. See the UI kit guide.