# zidane-gui

<p align="center">
  <img src="resources/icon.png" alt="Zizou" width="500" />
</p>

Zidane Desktop is the Electron app of `zidane`. It is a chat shell for the zidane agent, with a session sidebar, a transcript, a composer and side panels.

## Install

```sh
npm install -g zidane-gui
```

On macOS and Linux, a global install also adds a launcher app through the
postinstall script. On macOS the launcher is `~/Applications/Zidane.app`
(Spotlight, Raycast, Launchpad). On Linux it is a `.desktop` entry. If you
installed with `--ignore-scripts` or as root, run `zidane-gui install-app` as
your regular user. Run `zidane-gui` with no argument to start the app from a
terminal.

To uninstall, remove the launcher app before you remove the package. npm 7
and later does not run `preuninstall` scripts. So if you remove the package
first, the app stays in your launcher and points at a deleted install:

```sh
zidane-gui uninstall-app
npm uninstall -g zidane-gui
```

## Dev

`gui/` is not a member of the root bun workspaces. It has its own `bun.lock`, and it compiles `@zidane/ui` from `ui/` source.

1. Run `bun install` at the monorepo root.
2. Run `bun install` in `gui/`. Its postinstall script links `gui/node_modules/zidane` to the repo root.
3. Run `bun install` in `ui/`.
4. Run `bun --cwd=gui run dev`. The script builds the root `dist/` first, then starts electron-vite.

The renderer dev server runs on `http://localhost:21200`. Electron loads it into the window.

## Scripts

Run these from `gui/`, or run `bun --cwd=gui run <script>` from the root.

- `bun run dev` builds the root `dist/`, then starts the electron-vite dev server with HMR.
- `bun run build` bundles main, preload and renderer into `out/`.
- `bun run start` previews a built bundle (`electron-vite preview`).
- `bun run typecheck` builds the root `dist/`, then runs `bun check` on the node and web projects.
- `bun run typecheck:tsc` runs `tsc --noEmit` on the node and web projects.
- `bun run format` formats the package with Prettier. `bun run format:check` only checks, as CI does.
- `bun run test` builds the root `dist/` (the `pretest` script), then runs the vitest unit suite in `src/` and `scripts/`.
- `bun run test:watch` runs vitest in watch mode.
- `bun run test:e2e` runs Playwright end-to-end tests. It runs `build` first.
- `bun run test:visual` runs the Playwright visual regression suite. It runs `build` first.
- `bun run package` builds a macOS arm64 app with electron-builder.

## Stack

- Electron 41 and electron-vite 5 (which uses Vite 7)
- React 19 renderer, UnoCSS for styling
- TipTap 3 for the chatbox editor
- Shiki 4 for syntax highlighting
- `react-markdown` 10 and `remark-gfm` for transcript rendering
- `@pierre/diffs` and `@pierre/trees` for the code view, the diffs and the file tree
- `@tahul/ghostty-web` for the terminal
- `motion` for animation
- TypeScript 6
- SQLite through Electron's built-in `node:sqlite` (no native modules). Sessions live in `<dataDir>/sessions.db` (`~/.zidane/sessions.db` outside XDG), the same file as the TUI. The app's own state (the last folder, the sidebar's views, the app icon) and pending approvals live in `app.getPath('userData')/zidane-gui.db`. Settings live in `state.json`, shared with the TUI.
- Numbered SQL migrations in `migrations/` for `zidane-gui.db`, applied when the app first opens it
- Vitest 4 for unit tests. The default environment is node. A `.test.tsx` file opts into jsdom with `// @vitest-environment jsdom`.

## Notes

- `vite` is held at v7 because `electron-vite` 5 does not support Vite 8.
- `@vitejs/plugin-react` is held at v5 for the same reason. v6 requires Vite 8.
- This package lives in the `gui/` folder of the `zidane` monorepo. `gui/node_modules/zidane` is a symlink to the repo root, so the app uses the root `dist/`. The `dev`, `typecheck` and `test` scripts rebuild it.
- There are no native modules. SQLite is Electron's built-in `node:sqlite`, so there is no ABI rebuild step. `trustedDependencies` (`electron`, `esbuild`) lets bun run their build scripts.

## Docs

The user guide is in `website/content/docs/desktop*.mdx` (the Desktop app pages of the docs site). Coding agents read `CLAUDE.md` in this folder.