{"id":49252640,"url":"https://github.com/willywg/klaudio-panels","last_synced_at":"2026-05-03T17:02:22.116Z","repository":{"id":353452552,"uuid":"1213096571","full_name":"willywg/klaudio-panels","owner":"willywg","description":"Klaudio Panels — Tauri v2 + SolidJS desktop that embeds the Claude Code CLI in a PTY, with panels for the terminal, shell dock, git changes and a file tree.","archived":false,"fork":false,"pushed_at":"2026-04-24T23:15:01.000Z","size":3254,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-25T01:35:17.816Z","etag":null,"topics":["claude-code","desktop-app","macos","rust","solid-js","tauri"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/willywg.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-17T03:23:33.000Z","updated_at":"2026-04-24T23:15:04.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/willywg/klaudio-panels","commit_stats":null,"previous_names":["willywg/klaudio-panels"],"tags_count":32,"template":false,"template_full_name":null,"purl":"pkg:github/willywg/klaudio-panels","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willywg%2Fklaudio-panels","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willywg%2Fklaudio-panels/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willywg%2Fklaudio-panels/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willywg%2Fklaudio-panels/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/willywg","download_url":"https://codeload.github.com/willywg/klaudio-panels/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/willywg%2Fklaudio-panels/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32447325,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T22:27:22.272Z","status":"ssl_error","status_checked_at":"2026-04-29T22:10:49.234Z","response_time":110,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","desktop-app","macos","rust","solid-js","tauri"],"created_at":"2026-04-25T01:02:52.290Z","updated_at":"2026-05-03T17:02:22.109Z","avatar_url":"https://github.com/willywg.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Klaudio Panels\n\n\u003e A native desktop window that **embeds the real [Claude Code](https://claude.com/claude-code) CLI** via PTY, with a Slack-style projects sidebar, multi-tab sessions, and auto-resume.\n\nBuilt with Tauri v2 + SolidJS + xterm.js. The app is a thin shell around the `claude` CLI — it does **not** reimplement Claude Code's UI, it embeds it. You get every CLI feature for free: slash commands, permission prompts, the `-r` session picker, autocomplete, hooks, colors, mouse tracking.\n\n**Status:** `v1.1.2` — first public release. Multi-project + multi-tab + auto-resume, file tree with `notify` watcher, JSONL session watcher, `klaudio` shell command, and the Homebrew tap are all shipped. Diff viewer and code signing are the next milestones.\n\n---\n\n## Why\n\nClaude Code's terminal UI is already excellent. What's missing when you run it in Terminal.app is a **shell around it**:\n\n- Multiple projects side by side, one click away.\n- Multiple sessions per project, each in its own tab with its own PTY, independent scrollback.\n- Auto-resume the last active session when you reopen a project.\n- Real session titles (`/rename`) in the sidebar, not just session IDs.\n- A live file tree + a shell dock at the bottom of the window, so you can inspect files and run commands alongside your Claude session without leaving the app.\n- **Terminal editors embedded in a secondary PTY.** Click any file in the tree → pick your editor → it opens in-window. Today: **Neovim**, **Vim**, **Helix**, **Micro**. Plus \"Open in…\" routing for GUI editors (VS Code, Cursor, Windsurf, Zed, JetBrains family, Xcode, Sublime, etc.) via `open -a`.\n- (Coming soon) a diff viewer showing what Claude is touching, without parsing the PTY — we watch the filesystem and git instead.\n\nThink of it as a native window around the CLI, not a replacement for it.\n\n## Install (macOS)\n\nKlaudio Panels ships as a **universal .dmg** — one binary that runs natively on both Apple Silicon and Intel Macs.\n\n**Via Homebrew (recommended):**\n\n```bash\nbrew tap willywg/klaudio-panels\nbrew install --cask klaudio-panels\n```\n\n**Or download directly:** grab `Klaudio Panels_\u003cversion\u003e_universal.dmg` from the [latest release](https://github.com/willywg/klaudio-panels/releases/latest) and drag the app into `/Applications`.\n\n## First launch\n\nKlaudio Panels is **not yet signed with an Apple Developer ID** — see [Platform support](#platform-support) for why. On first launch, macOS will refuse to open the app and show one of these two warnings:\n\n**\"Klaudio Panels\" can't be opened because it is from an unidentified developer**\n\n1. Open `/Applications` in Finder.\n2. **Right-click** (or Control-click) on **Klaudio Panels** → **Open**.\n3. Click **Open** in the confirmation dialog.\n\nAfter that one-time approval, the app launches normally like any other app.\n\n**\"Klaudio Panels\" is damaged and can't be opened**\n\nRun this once in Terminal:\n\n```bash\nxattr -cr \"/Applications/Klaudio Panels.app\"\n```\n\nThen open the app normally. This clears a macOS quarantine flag that sometimes lingers on unsigned downloads.\n\nBoth warnings are Gatekeeper defaults for unsigned apps, not signs that anything is wrong with the binary — the source is public and inspectable right here.\n\n## Platform support\n\n| OS | Status | Notes |\n| --- | --- | --- |\n| **macOS 14+** (Sonoma, Sequoia) | ✅ primary target | Tested on Apple Silicon and Intel. Universal `.dmg` is what the maintainer ships. |\n| **Linux** | 🧪 untested | Should build via `bun tauri build` (Tauri is cross-platform). Help validating is very welcome — see [#1](https://github.com/willywg/klaudio-panels/issues/1). |\n| **Windows** | ❌ not supported yet | Several backend modules are stubbed on Windows. Help porting is welcome — see [#2](https://github.com/willywg/klaudio-panels/issues/2). |\n\n**About code signing.** Apple's Developer Program is US$99/year. We'll pay it once the project has real usage; until then, the first-launch workaround above is the cost of keeping the project free. Apple has been tightening the unsigned-app escape hatches with each macOS release, so this is a temporary state, not a permanent stance.\n\n## Screenshots\n\n**Sessions sidebar + inline Markdown preview with the shell dock at the bottom.**\n\n![Claude session with Markdown preview and shell dock](./docs/screenshots/sessions-and-diff-panel.png)\n\n**File tree on the left, Neovim embedded in a secondary PTY on the right, Claude session in the middle.**\n\n![File tree with Neovim editor embedded](./docs/screenshots/file-tree-and-terminal-editor.png)\n\n## Notifications\n\nKlaudio Panels surfaces three kinds of signals when a Claude session\nneeds your attention: a chime, a native macOS notification banner,\nand an amber ring on the project's avatar in the sidebar (plus a Dock\nbadge counting how many projects are waiting). All three are\nsuppressed when you're already focused on the project the event came\nfrom — they only fire for **background** activity.\n\n\u003e 🔔 **Recommended: install the warp plugin first.** Without it,\n\u003e Klaudio falls back to the noisier transcript-watcher path, which\n\u003e fires once per Claude turn (often several times a minute on long\n\u003e agentic work). With the plugin you get the cleaner\n\u003e `permission_request` channel — Claude pings you only when it's\n\u003e actually waiting for you. Five-second install, see [Permission\n\u003e requests (recommended warp plugin)](#permission-requests-recommended-warp-plugin).\n\u003e\n\u003e Want to mute or change which channels notify you? Click the bell in\n\u003e the titlebar → ⚙️ Settings — toggle Task complete, Permission\n\u003e requests, and Sounds independently.\n\n### Permission requests (recommended warp plugin)\n\nThe transcript watcher cannot see when Claude wants to run a tool\n(`Bash`, `Edit`, etc.) that requires your approval — that signal\nnever gets written to disk. To catch those, install the [warp Claude\nCode plugin](https://github.com/warpdotdev/claude-code-warp). It\nemits [OSC 777 sidechannel events](https://github.com/warpdotdev/warp/blob/main/app/src/terminal/cli_agent_sessions/event/v1.rs)\nthat Klaudio Panels parses out of the PTY stream. The same plugin\nalso works in [warp.app](https://www.warp.dev/) and any other terminal\nthat speaks the `warp://cli-agent` protocol — install once, get\nnotifications everywhere.\n\n```bash\n# Requires `jq` on PATH (brew install jq if missing)\nclaude plugin marketplace add warpdotdev/claude-code-warp\nclaude plugin install warp@claude-code-warp\n```\n\nRestart your Claude session afterwards so the plugin loads. From then\non, permission requests get a more attention-grabbing chime + a\nbanner on top of the built-in turn-completion notifications.\n\n### Built-in fallback (zero-config)\n\nOut of the box, Klaudio Panels watches the Claude transcript files\nunder `~/.claude/projects/` and notifies you whenever a session ends\nits turn. This works for every Claude session you run inside Klaudio,\nno extra setup needed — but Claude reaches \"end of turn\" after every\ntool-free reply, which means several notifications per minute on\nbusy work. The warp plugin (above) is the cleaner signal; this path\nis the safety net if you can't install it. You can also disable it\nentirely from the bell's ⚙️ Settings panel.\n\n\u003e The plugin also emits an `idle_prompt` event every 60s while the\n\u003e Claude prompt sits empty (which fires while you're *reading*\n\u003e output too). Klaudio drops it server-side because it's noise, not\n\u003e signal — `permission_request` already covers the actually-blocked\n\u003e case.\n\n\u003e Why this approach? Klaudio's [non-negotiable\n\u003e rule #2](./CLAUDE.md) is to never parse Claude's terminal\n\u003e output — it's brittle across Claude versions. OSC 777 with the\n\u003e `warp://cli-agent` sentinel is a different beast: a stable, public,\n\u003e versioned wire contract. Klaudio's sniffer in\n\u003e `src-tauri/src/cli_agent.rs` observes those frames without mutating\n\u003e the byte stream (xterm.js still renders the terminal exactly as\n\u003e Claude sent it).\n\n## Architecture at a glance\n\n```\n┌─────────────────────────────────────────────────┐\n│  Tauri v2 Window (Rust)                         │\n│                                                 │\n│  ┌───────────────────────────────────────────┐  │\n│  │  SolidJS UI (webview)                     │  │\n│  │  ┌────────┬─────────┬──────────────────┐  │  │\n│  │  │Projects│Sessions │  xterm.js        │  │  │\n│  │  │sidebar │sidebar  │  (renders PTY)   │  │  │\n│  │  └────────┴─────────┴──────────────────┘  │  │\n│  └───────────────────────────────────────────┘  │\n│                                                 │\n│  Rust backend                                   │\n│  ├─ binary.rs    : detect `claude` on PATH      │\n│  ├─ shell_env.rs : hydrate login shell env      │\n│  ├─ sessions.rs  : read ~/.claude/projects/*    │\n│  └─ pty.rs       : portable-pty spawn + stream  │\n└─────────────────────────────────────────────────┘\n```\n\nKey rules (see `CLAUDE.md` for the full set):\n\n- **Claude runs interactively in a PTY.** No `-p`, no `--output-format`. xterm.js renders bytes as-is.\n- **We never parse the PTY output.** If a feature seems to need it, we watch the filesystem + git instead.\n- **Shell env hydration is mandatory.** macOS GUI apps inherit a stripped PATH; we merge the login shell's env so `node`, `nvm`, `git`, `rg` work inside Claude's Bash tool.\n- **Sessions live in `~/.claude/projects/`.** We read JSONL files for sidebar previews; we never write there.\n- **Each tab is its own PTY.** Switching tabs toggles visibility (never re-creates xterm, to preserve scrollback + WebGL).\n- **Persistence is minimal.** `localStorage` for `lastSessionId:\u003cprojectPath\u003e`. SQLite is for later.\n\nFull design doc: [`PROJECT.md`](./PROJECT.md).\n\n## Prerequisites\n\n- [Bun](https://bun.com) 1.3+\n- [Rust](https://rustup.rs) stable toolchain\n- The [`claude` CLI](https://docs.anthropic.com/en/docs/claude-code) installed and authenticated (run `claude` once in a terminal first).\n- macOS is the primary development target. See [Platform support](#platform-support) for Linux / Windows status.\n\n## Development\n\n```bash\nbun install\nbun tauri dev\n```\n\nFirst cold Rust build: ~3–5 minutes. After that HMR is instant.\n\nOther useful commands:\n\n```bash\nbun run typecheck               # tsc --noEmit\ncd src-tauri \u0026\u0026 cargo check\ncd src-tauri \u0026\u0026 cargo clippy -- -D warnings\n```\n\n## Building a release\n\nOn macOS, build a **universal** binary (native on both Apple Silicon and Intel):\n\n```bash\nrustup target add aarch64-apple-darwin x86_64-apple-darwin   # one-time\nbun run release:mac\n```\n\nArtifacts land under `src-tauri/target/universal-apple-darwin/release/bundle/`.\n\nBuilding with a plain `bun tauri build` is fine for local smoke-testing, but **don't ship it** — it produces a host-arch-only binary, which on an x86_64 toolchain means Intel-only, and Apple Silicon users will run it under Rosetta and see macOS's \"End of support for Intel-based apps\" warning.\n\nOn Windows / Linux, `bun tauri build` is still the right command; artifacts land under `src-tauri/target/release/bundle/`.\n\n_Note: release builds are not yet signed with an Apple Developer ID. End-users hit a Gatekeeper warning on first launch — see [First launch](#first-launch) for the one-time workaround._\n\n## Release history\n\nMilestones only — intermediate tags (`v0.4.x` through `v0.9.x`) covered polish and bug fixes on the Sprint 02/03 feature set. Full detail in [`CHANGELOG.md`](./CHANGELOG.md); every tag is at [GitHub Releases](https://github.com/willywg/klaudio-panels/releases).\n\n| Tag                      | Milestone                                                        | Status      |\n| ------------------------ | ---------------------------------------------------------------- | ----------- |\n| `v0.0.1-stream-json-poc` | Sprint 00 — stream-json PoC, pivoted to PTY                      | ✅ archived |\n| `v0.1.0-pty`             | Sprint 01 — `claude` in PTY, single tab, sidebar sessions        | ✅ shipped  |\n| `v0.2.0`                 | Sprint 02 — multi-tab, multi-project, auto-resume                | ✅ shipped  |\n| `v0.3.0`                 | Sprint 03 — file tree, `notify` watcher, JSONL session watcher   | ✅ shipped  |\n| `v1.0.0`                 | Rename \"Klaudio UI\" → \"Klaudio Panels\"                           | ✅ shipped  |\n| `v1.1.0`                 | `klaudio` shell command + `klaudio://` URL scheme                | ✅ shipped  |\n| `v1.1.2`                 | **First public release** — Homebrew tap, OSS hygiene, bundle id  | ✅ shipped  |\n| next                     | Sprint 04 — diff viewer (`@pierre/diffs`)                        | 🔜 planned  |\n| later                    | Code signing + notarization (Apple Developer Program)            | 🔜 planned  |\n\nRetros live in [`docs/`](./docs/); PRPs in [`PRPs/`](./PRPs/).\n\n## Troubleshooting\n\nKlaudio Panels writes a diagnostic log on every run. If something goes\nwrong, grab it before filing an issue:\n\n**macOS** — `~/Library/Logs/Klaudio Panels/klaudio.log`\n\n```bash\ntail -n 200 \"$HOME/Library/Logs/Klaudio Panels/klaudio.log\"\nopen \"$HOME/Library/Logs/Klaudio Panels\"   # reveal in Finder\n```\n\n**Linux** — `~/.klaudio-panels/logs/klaudio.log`\n\n```bash\ntail -n 200 \"$HOME/.klaudio-panels/logs/klaudio.log\"\n```\n\nPlease redact anything you'd rather not share (project paths, usernames,\ntokens). The bug report template has a slot for the log chunk.\n\n## Contributing\n\nSee [`CONTRIBUTING.md`](./CONTRIBUTING.md). In short:\n\n- All repo artifacts (code, comments, docs, PRs, issues, commits) in **English**.\n- Open an issue before a large PR so we can agree on scope.\n- Conventional commits (`feat:`, `fix:`, `docs:`, `refactor:`, `chore:`).\n- Run `bun run typecheck` + `cargo check` + `cargo clippy -- -D warnings` before pushing.\n\n## Credits\n\n- **[Claude Code](https://claude.com/claude-code)** — the CLI we embed. Without it, there's no app.\n- **[OpenCode Desktop](https://github.com/anomalyco/opencode)** — the reference architecture for embedding a CLI in a Tauri native window. We borrowed the `probe_shell_env` / `load_shell_env` / `merge_shell_env` pattern verbatim from their `packages/desktop/src-tauri/src/cli.rs`.\n- **[Claudia](https://github.com/getAsterisk/claudia)** — used during the Sprint 00 stream-json PoC for `claude` binary detection and JSONL parsing patterns.\n\n## License\n\n[MIT](./LICENSE) © 2026 William Wong Garay\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillywg%2Fklaudio-panels","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwillywg%2Fklaudio-panels","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwillywg%2Fklaudio-panels/lists"}