{"id":51567647,"url":"https://github.com/arkan/zigzag","last_synced_at":"2026-07-10T16:01:48.906Z","repository":{"id":357932736,"uuid":"1202271332","full_name":"arkan/zigzag","owner":"arkan","description":"Zigzag: a Rust TUI/CLI project manager for Zellij sessions, git worktrees, and autopilot workflows","archived":false,"fork":false,"pushed_at":"2026-05-14T21:23:25.000Z","size":1295,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-14T23:29:27.834Z","etag":null,"topics":["automation","cli","developer-tools","git-worktree","kdl","ratatui","rust","tui","zellij"],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arkan.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-04-05T20:31:00.000Z","updated_at":"2026-05-14T21:23:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/arkan/zigzag","commit_stats":null,"previous_names":["arkan/zigzag"],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/arkan/zigzag","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkan%2Fzigzag","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkan%2Fzigzag/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkan%2Fzigzag/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkan%2Fzigzag/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arkan","download_url":"https://codeload.github.com/arkan/zigzag/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arkan%2Fzigzag/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35335898,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-10T02:00:06.465Z","response_time":60,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["automation","cli","developer-tools","git-worktree","kdl","ratatui","rust","tui","zellij"],"created_at":"2026-07-10T16:01:43.617Z","updated_at":"2026-07-10T16:01:48.901Z","avatar_url":"https://github.com/arkan.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Zigzag\n\n**Rust TUI/CLI for [Zellij](https://github.com/zellij-org/zellij)-based development** — manage projects, git worktrees, Zellij sessions, and workflow automations from one terminal dashboard.\n\n[Install](#install) · [Basic start](#basic-start) · [Shortcuts](#shortcuts) · [Configuration](#configuration) · [Autopilot](#autopilot) · [Development](#development)\n\n## Overview\n\n`zigzag` is for developers who keep many repositories, branches, and terminal sessions open at once. It gives you one workflow around Zellij and git worktrees:\n\n- **Project dashboard** — browse configured projects, worktrees, running sessions, notifications, and git/PR/CI preview data.\n- **Worktree-first sessions** — `zigzag open` restores the primary checkout or creates/restores a branch worktree through [`wt`](https://github.com/max-sixty/worktrunk).\n- **Native Zellij integration** — generated layouts load the Zigzag WASM plugin for in-session toasts and session switching, plus shortcuts for actions and logs.\n- **Action menu** — run contextual tools such as review, lazygit, PR opening, CI fixes, or custom commands.\n- **Autopilot workflows** — KDL-defined background workflows for CI fixes, review follow-up, merge/deploy flows, and custom automation.\n\n```text\n┌─ Zigzag ──────────────────────────────────────┐\n│ PROJECTS             WORKTREES                 │\n│ \u003e myapp              main                 ●    │\n│   api                feat/login           🔔   │\n│                                                │\n│ PREVIEW                                        │\n│ myapp:feat/login · dirty · PR #42 · CI passing │\n│                                                │\n│ [o]pen [n]ew [r]un [K]ill [d]el [?]help [q]uit│\n└────────────────────────────────────────────────┘\n```\n\n\u003e [!NOTE]\n\u003e Zigzag is still in early development. For deeper design context, see [`docs/PRD.md`](docs/PRD.md) and [`docs/SPECS.md`](docs/SPECS.md).\n\n## Install\n\n### Prerequisites\n\n| Tool | Minimum | Used for |\n|---|---:|---|\n| [Rust](https://www.rust-lang.org/tools/install) | stable | Build toolchain |\n| [Zellij](https://github.com/zellij-org/zellij) | `0.44.0` | Terminal sessions |\n| [`wt`](https://github.com/max-sixty/worktrunk) | `0.34.0` | Git worktrees |\n| [GitHub CLI](https://cli.github.com/) | `2.0.0` | PR, CI, issue data |\n\nZigzag checks these dependencies at startup and reports missing or outdated tools.\n\n### From a release\n\n```bash\n# Latest release\ncurl -fsSL https://raw.githubusercontent.com/arkan/zigzag/main/install.sh | bash\n\n# Specific version\ncurl -fsSL https://raw.githubusercontent.com/arkan/zigzag/main/install.sh | ZIGZAG_VERSION=v0.7.0 bash\n\n# Custom install directory, default is ~/.local/bin\ncurl -fsSL https://raw.githubusercontent.com/arkan/zigzag/main/install.sh | ZIGZAG_INSTALL_DIR=/usr/local/bin bash\n```\n\n### With Nix\n\n```bash\n# Install from the flake\nnix profile install github:arkan/zigzag\n\n# Or try it without installing\nnix run github:arkan/zigzag -- list\n```\n\nThe Nix package wraps `zigzag` with the common runtime tools it shells out to: `zellij`, `wt`, `git`, `gh`, `ssh`, and `mosh`.\n\n### Optional short alias\n\nZigzag does not install a `z` symlink automatically. If you still want the short command, add this to your shell profile:\n\n```bash\nalias z=zigzag\n```\n\n### Migration from `z`\n\nZigzag does not read old `z` paths. If you used the previous name, move local files manually:\n\n```bash\nmv \"$HOME/.config/z\" \"$HOME/.config/zigzag\"\nmv \"$HOME/.local/state/z\" \"$HOME/.local/state/zigzag\"\n```\n\n### From source\n\n```bash\n# Builds the CLI and the native Zellij WASM plugin.\n# The plugin is a prerequisite for generated Zellij layouts: Alt+k loads it\n# from Zigzag's user data directory.\nmake install\n```\n\nBy default this installs:\n\n- CLI: `~/.local/bin/zigzag`\n- Zellij WASM plugin: `~/.local/share/zigzag/zigzag_plugin.wasm`\n\nIf you build manually instead of using `make install`, install the plugin in the same canonical path:\n\n```bash\nrustup target add wasm32-wasip1\ncargo build --manifest-path zigzag/Cargo.toml -p zigzag-plugin --release --target wasm32-wasip1\nmkdir -p ~/.local/share/zigzag\ncp zigzag/target/wasm32-wasip1/release/zigzag_plugin.wasm ~/.local/share/zigzag/zigzag_plugin.wasm\ncargo install --path zigzag/crates/zigzag-cli\n```\n\n`zigzag` expects the native Zellij plugin for switcher and notifications at `~/.local/share/zigzag/zigzag_plugin.wasm`. Override it with `ZIGZAG_PLUGIN_WASM=/path/to/zigzag_plugin.wasm` when testing a local build.\n\n## Basic start\n\n### 1. Register your projects\n\nCreate `~/.config/zigzag/projects.kdl`:\n\n```kdl\nproject \"myapp\" {\n    path \"~/Code/myapp\"\n}\n\nproject \"api\" {\n    path \"~/Code/api\"\n}\n```\n\n### 2. Open the dashboard\n\n```bash\nzigzag\n```\n\nThen use:\n\n| Key | Action |\n|---|---|\n| `↑` / `↓` | Move in the current list |\n| `←` / `→` or `Tab` | Switch between Projects and Worktrees |\n| `Enter` or `o` | Open/restore the selected worktree session |\n| `s` or `Alt+k` | Open the active-session switcher; inside Zellij this is the native WASM plugin |\n| `n` | Create a new worktree + session from a branch, issue, or PR |\n| `/` | Fuzzy search |\n| `?` | Show in-app help |\n| `q` | Quit the dashboard |\n\n\u003e [!TIP]\n\u003e Arrow keys always work. `h/j/k/l` navigation is available when `keybindings \"vim\"` is enabled in your config.\n\n### 3. Open directly from the shell\n\n```bash\nzigzag open myapp              # Open/restore the primary checkout session\nzigzag open myapp feat/login   # Open/restore a branch worktree + session\nzigzag switch                  # Pick another local Zigzag-managed session\n```\n\nWhen a branch worktree does not exist yet, `zigzag open \u003cproject\u003e \u003cbranch\u003e` creates it with `wt`, generates a Zellij layout, starts the session, then attaches to it.\n\n### 4. Return to Zigzag from Zellij\n\nInside a session, press `Ctrl+O`, then `D` to detach. The Zellij session keeps running in the background, and you can return with `zigzag` or `zigzag open \u003cproject\u003e [branch]`.\n\n## Shortcuts\n\n### Dashboard shortcuts\n\n| Key | Action |\n|---|---|\n| `o` / `Enter` | Open/restore selected project or worktree |\n| `s` / `Alt+k` | Open the active-session switcher; inside Zellij this is the native WASM plugin |\n| `n` | New worktree + session |\n| `r` | Run action menu |\n| `a` | Autopilot workflows |\n| `K` | Kill active session only |\n| `d` | Delete selected worktree |\n| `D` | Run doctor diagnostics |\n| `A` / `E` / `X` | Add, edit, or delete a project |\n| `e` | Edit per-repo `.config/zigzag.kdl` |\n| `/` | Search |\n| `?` | Help |\n\n### In Zigzag-managed Zellij sessions\n\nZigzag injects these shortcuts into generated Zellij layouts:\n\n| Shortcut | Action |\n|---|---|\n| `Alt+k` | Open/focus the floating native Zigzag session switcher plugin |\n| `Alt+z` | Open the floating action menu |\n| `Alt+l` | Open the floating log viewer |\n\n### Useful Zellij defaults\n\n| Shortcut | Action |\n|---|---|\n| `Ctrl+O`, then `D` | Detach from the session |\n| `Ctrl+Q` | Quit the session |\n| `Ctrl+T`, then `N` | New tab |\n| `Ctrl+T`, then `1`-`9` | Switch to tab by number |\n\n## Useful commands\n\n| Command | Description |\n|---|---|\n| `zigzag` | Launch the dashboard |\n| `zigzag list` | List configured projects and active sessions |\n| `zigzag open \u003cproject\u003e [branch]` | Open/restore a checkout or branch session |\n| `zigzag close [session]` | Detach a session without deleting it |\n| `zigzag switch` | Pick and jump to another local Zigzag session |\n| `zigzag actions` | Open the action menu for the current session |\n| `zigzag logs [-n \u003ccount\u003e]` | Show Zigzag logs |\n| `zigzag doctor [--fix]` | Diagnose or repair safe project/session issues |\n| `zigzag session kill \u003cproject\u003e \u003cbranch\u003e` | Kill a Zellij session only |\n| `zigzag worktree delete \u003cproject\u003e \u003cbranch\u003e [--confirm \u003cbranch\u003e]` | Delete a worktree |\n| `zigzag project delete \u003cproject\u003e` | Remove a project from `projects.kdl` |\n| `zigzag notify [session] \u003cmessage\u003e` | Add a session notification |\n| `zigzag autopilot \u003csubcommand\u003e` | Manage workflow automation |\n\n### Zellij tab and pane control\n\nZigzag can create/focus named Zellij tabs and run commands in named panes for a Zigzag-managed session:\n\n```bash\nzigzag tab create --session myapp:main --name tests\nzigzag tab focus --session myapp:main --name tests\nzigzag pane run --session myapp:main --tab tests --pane unit \"cargo test\"\nzigzag pane focus --session myapp:main --tab tests --pane unit\nzigzag pane list --session myapp:main --json\n```\n\nPane aliases are Zigzag names stored in `worktree-metadata.json`; raw Zellij pane IDs are internal details. By default these commands refuse sessions that are not known as Zigzag-managed. Pass `--allow-unmanaged` only when you intentionally want best-effort control of an arbitrary Zellij session; metadata is limited or unavailable in that mode.\n\n## Configuration\n\nZigzag uses [KDL](https://kdl.dev) with three main files:\n\n| File | Purpose |\n|---|---|\n| `~/.config/zigzag/projects.kdl` | Project registry |\n| `~/.config/zigzag/config.kdl` | Global preferences, layout defaults, actions, notifications |\n| `\u003crepo\u003e/.config/zigzag.kdl` | Per-repository layout, actions, and autopilot settings |\n\nMinimal global config:\n\n```kdl\nkeybindings \"vim\" // or omit for arrow-key navigation\ntheme \"dracula\"\n\nnotifications {\n    tui true\n    zellij true\n    macos-native false\n}\n```\n\n`notifications.zellij true` sends `zigzag notify` events to the native plugin with `zellij action pipe`. The plugin is launched automatically as a floating notification pane when a toast arrives; this does not create a terminal pane and should not steal keyboard focus.\n\nMinimal per-repo layout:\n\n```kdl\nlayout {\n    tab \"code\" {\n        pane \"editor\"\n        pane \"shell\" size=30\n    }\n\n    tab \"agent\" {\n        pane command=\"claude\"\n    }\n}\n```\n\n## Actions and notifications\n\nThe action menu (`r` in the dashboard, `Alt+z` in a generated Zellij session) resolves built-in, global, and per-repo actions against the current project/session context.\n\nNotifications are stored in local worktree metadata and surfaced as dashboard/switcher badges. From inside a Zellij pane, `$ZELLIJ_SESSION_NAME` lets you notify the current session without naming it:\n\n```bash\nzigzag notify \"CI finished\" --level info\nzigzag notify myapp:feat-login \"Review comments arrived\" --level warning\n```\n\nWith `zellij true`, the same command also emits a native in-session toast via the plugin. Toasts render as a four-line card: status icon + notification type, session subtitle, spacer, then message body:\n\n```text\n❌ Error\nhub:main\n\nBuild failed\n```\n\nThe pipe payload is JSON and targets the `zigzag-notify` pipe; for manual testing:\n\n```bash\nzellij -s myapp:feat-login action pipe \\\n  --name zigzag-notify \\\n  --plugin file:$HOME/.local/share/zigzag/zigzag_plugin.wasm \\\n  --floating-plugin true \\\n  --plugin-title Zigzag \\\n  --skip-plugin-cache \\\n  -- '{\"message\":\"CI finished\",\"level\":\"info\",\"session\":\"myapp:feat-login\"}'\n```\n\n## Autopilot\n\nAutopilot workflows are KDL-defined state machines that can run commands, send notifications, ask for confirmations, and transition on success/failure.\n\n```bash\nzigzag autopilot list\nzigzag autopilot status\nzigzag autopilot run \u003cproject\u003e \u003cworkflow\u003e\n```\n\nBuilt-in workflows cover common PR and deploy loops such as CI fixing, review follow-up, merge-when-ready, Dependabot auto-merge, and deploy monitoring.\n\n## Development\n\nThis repository is a Rust workspace:\n\n```text\nzigzag/crates/\n├── zigzag-core       # Domain types, config, actions, traits\n├── zigzag-cli        # CLI entry point and process/filesystem adapters\n├── zigzag-tui        # Ratatui dashboard, switcher, logs, action picker\n├── zigzag-autopilot  # Workflow DSL and runner\n├── zigzag-plugin     # Native Zellij WASM plugin: toasts + session switcher\n└── zigzag-web        # Future web bridge\n```\n\nCommon checks:\n\n```bash\nnpm run typecheck\nnpm test\ncargo fmt --manifest-path zigzag/Cargo.toml --all --check\ncargo test --manifest-path zigzag/Cargo.toml --workspace\ncargo build --manifest-path zigzag/Cargo.toml -p zigzag-plugin --target wasm32-wasip1\n```\n\nFurther reading:\n\n- [`codemap.md`](codemap.md) — repository map and entry points\n- [`docs/PRD.md`](docs/PRD.md) — product requirements\n- [`docs/SPECS.md`](docs/SPECS.md) — technical specs\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkan%2Fzigzag","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farkan%2Fzigzag","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farkan%2Fzigzag/lists"}