{"id":30697462,"url":"https://github.com/b0o/zellij-tools","last_synced_at":"2026-04-02T14:52:20.683Z","repository":{"id":302687683,"uuid":"1013305999","full_name":"b0o/zellij-tools","owner":"b0o","description":"🔧 A Zellij plugin that adds a few handy utilities.","archived":false,"fork":false,"pushed_at":"2026-03-26T08:21:03.000Z","size":409,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-03-27T02:54:07.786Z","etag":null,"topics":["zellij","zellij-plugin"],"latest_commit_sha":null,"homepage":"","language":"Rust","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/b0o.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","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},"funding":{"github":"b0o"}},"created_at":"2025-07-03T17:18:16.000Z","updated_at":"2026-03-26T08:18:18.000Z","dependencies_parsed_at":"2025-07-03T18:48:56.236Z","dependency_job_id":null,"html_url":"https://github.com/b0o/zellij-tools","commit_stats":null,"previous_names":["b0o/zellij-tools"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/b0o/zellij-tools","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b0o%2Fzellij-tools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b0o%2Fzellij-tools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b0o%2Fzellij-tools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b0o%2Fzellij-tools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/b0o","download_url":"https://codeload.github.com/b0o/zellij-tools/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/b0o%2Fzellij-tools/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31308447,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-02T12:59:32.332Z","status":"ssl_error","status_checked_at":"2026-04-02T12:54:48.875Z","response_time":89,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: 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":["zellij","zellij-plugin"],"created_at":"2025-09-02T09:09:43.573Z","updated_at":"2026-04-02T14:52:20.678Z","avatar_url":"https://github.com/b0o.png","language":"Rust","funding_links":["https://github.com/sponsors/b0o"],"categories":[],"sub_categories":[],"readme":"# zellij-tools\n\nA [Zellij](https://github.com/zellij-org/zellij) plugin and companion CLI that add scratchpads, focus helpers, event streaming, and session tree utilities.\n\n## Installation\n\n```kdl\nplugins {\n    zellij-tools location=\"https://github.com/b0o/zellij-tools/releases/latest/download/zellij-tools.wasm\"\n}\n\nload_plugins {\n    zellij-tools\n}\n```\n\n### Nix Flake\n\nThe plugin and CLI are available as flake outputs:\n\n```sh\n# Build the plugin\nnix build github:b0o/zellij-tools          # → result/share/zellij/plugins/zellij-tools.wasm\n\n# Build the CLI\nnix build github:b0o/zellij-tools#cli      # → result/bin/zellij-tools\n\n# Run the CLI without installing\nnix run github:b0o/zellij-tools#cli -- scratchpad list\n\n# Enter a dev shell with the Rust toolchain and CLI\nnix develop github:b0o/zellij-tools\n```\n\nTo use the plugin from your Nix-managed Zellij config, add the flake as an input and reference the wasm path:\n\n```nix\n# flake.nix\n{\n  inputs.zellij-tools.url = \"github:b0o/zellij-tools\";\n\n  # ...in your outputs:\n  # The plugin wasm is at:\n  #   zellij-tools.packages.${system}.default + \"/share/zellij/plugins/zellij-tools.wasm\"\n  # The CLI binary is at:\n  #   zellij-tools.packages.${system}.cli + \"/bin/zellij-tools\"\n}\n```\n\n## Scratchpads\n\nScratchpads are floating terminal panes that can be quickly toggled on and off. They follow you across tabs and persist their state.\n\n### Configuration\n\nScratchpads can be configured inline or in an external file.\n\n**Important:** Inline configuration requires restarting zellij to apply changes. For hot-reloading, use an external config file.\n\n#### Inline Configuration (no hot-reload)\n\n```kdl\nplugins {\n    zellij-tools location=\"...\" {\n        scratchpads {\n            term { command \"zsh\"; }\n            btop { command \"btop\"; }\n            notes { command \"nvim\" \"+cd ~/notes\"; }\n            popup {\n                command \"zsh\"\n                width \"80%\"\n                height \"60%\"\n                origin \"center\"\n                title \"Popup Shell\"\n                cwd \"/home/user/projects\"\n            }\n        }\n    }\n}\n```\n\n#### External Configuration File (hot-reload supported)\n\nUse an external file to edit scratchpad definitions without restarting zellij:\n\n```kdl\nplugins {\n    zellij-tools location=\"...\" {\n        include \"zellij-tools.kdl\"  // Relative to zellij config directory\n        // config_dir \"~/.config/zellij\"  // Override base directory for relative includes\n        // watch_ms \"2000\"  // Polling interval in ms, or \"false\"/\"0\" to disable\n    }\n}\n```\n\nThen create `~/.config/zellij/zellij-tools.kdl`:\n\n```kdl\nscratchpads {\n    term { command \"zsh\"; }\n    btop {\n        command \"btop\"\n        width \"120\"\n        height \"40\"\n        origin \"center\"\n    }\n}\n```\n\nThe plugin polls the external file for changes and automatically reloads scratchpad definitions.\n\n### Include Path Resolution\n\nThe `include` path is resolved as follows:\n\n- Absolute paths (starting with `/`) are used as-is\n- Paths starting with `~` are expanded to your home directory\n- Relative paths are resolved against your zellij config directory\n\nThe config directory is determined by (in order):\n\n1. `ZELLIJ_CONFIG_DIR` environment variable\n2. `$XDG_CONFIG_HOME/zellij`\n3. `$HOME/.config/zellij`\n\n### Configuration Options\n\n| Option        | Description                                            | Default       | Inline Config | External Config File |\n| ------------- | ------------------------------------------------------ | ------------- | :-----------: | :------------------: |\n| `include`     | Path to external config file                           | -             |      Yes      |          No          |\n| `config_dir`  | Override base directory for relative includes          | Auto-detected |      Yes      |          No          |\n| `watch_ms`    | Polling interval in ms. `\"false\"` or `\"0\"` to disable. | `2000`        |      Yes      |          No          |\n| `scratchpads` | Scratchpad definitions                                 | -             |      Yes      |         Yes          |\n\n### Scratchpad Options\n\nEach scratchpad supports these options:\n\n| Option    | Description                                                                     |    Required     |\n| --------- | ------------------------------------------------------------------------------- | :-------------: |\n| `command` | Command and arguments to run (e.g. `command \"zsh\"` or `command \"nvim\" \"+cd ~\"`) |       Yes       |\n| `width`   | Pane width: fixed columns (`\"80\"`) or percent (`\"50%\"`)                         |       No        |\n| `height`  | Pane height: fixed rows (`\"24\"`) or percent (`\"50%\"`)                           |       No        |\n| `x`       | Horizontal offset: fixed columns or percent                                     |       No        |\n| `y`       | Vertical offset: fixed rows or percent                                          |       No        |\n| `origin`  | Anchor point for x/y coordinates (see below)                                    |   `\"center\"`    |\n| `title`   | Pane title displayed in the Zellij UI                                           | Scratchpad name |\n| `cwd`     | Working directory for the command                                               |       No        |\n\n### Origin\n\nThe `origin` option sets the reference point for `x` and `y` coordinates. It accepts one or two arguments:\n\n- **One argument:** `\"center\"` (both axes), `\"top\"`, `\"bottom\"`, `\"left\"`, `\"right\"`\n- **Two arguments:** vertical then horizontal, e.g. `origin \"bottom\" \"center\"`, `origin \"top\" \"right\"`\n\n| Vertical | Horizontal | Description                              |\n| -------- | ---------- | ---------------------------------------- |\n| `top`    | `left`     | Offset from top-left corner              |\n| `center` | `center`   | Centered, offset shifts away from center |\n| `bottom` | `right`    | Offset inward from bottom-right corner   |\n\n### Scratchpad CLI\n\nControl scratchpads from the command line:\n\n```sh\nzellij-tools scratchpad toggle         # Toggle the last-focused scratchpad\nzellij-tools scratchpad toggle term    # Toggle a named scratchpad\nzellij-tools scratchpad show term      # Show a scratchpad\nzellij-tools scratchpad hide term      # Hide a scratchpad\nzellij-tools scratchpad close term     # Close a scratchpad (terminates the pane)\n```\n\n## Other Actions\n\n### Focus Pane\n\nFocuses a pane by ID. You can get the pane ID from the `$ZELLIJ_PANE_ID` environment variable.\n\nNote: pane IDs are only unique within their type. A `terminal` id `0` and a `plugin` id `0` can both exist at the same time.\n\nDefaults to terminal panes in the CLI. Use `--plugin` to target plugin panes.\n\n```sh\nzellij-tools focus pane 2\nzellij-tools focus pane --plugin 7\n```\n\n### Focus Tab\n\nFocuses a tab by position (1-based) by default.\n\nUse `--id` to focus by tab ID.\n\n```sh\nzellij-tools focus tab 2\nzellij-tools focus tab --id 42\n```\n\n## Events and Tree\n\nStream pane/tab events:\n\n```sh\nzellij-tools subscribe\nzellij-tools subscribe --full\nzellij-tools subscribe --event PaneFocused,TabMoved --pane-id 2 --plugin-pane-id 7 --tab-id 42\n```\n\nGet a session tree snapshot:\n\n```sh\nzellij-tools tree\n```\n\nFor full event formats and filter options, see `zellij-tools subscribe --help`.\n\n## Permissions\n\nThe plugin requires the following permissions:\n\n- `ReadApplicationState` - Track panes and tabs\n- `ChangeApplicationState` - Show/hide panes\n- `RunCommands` - Launch scratchpad commands\n- `ReadCliPipes` - Stream events and tree data to CLI pipes\n- `FullHdAccess` - Read external config files\n\n## License\n\n\u0026copy; 2025-2026 Maddison Hellstrom\n\nMIT License\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb0o%2Fzellij-tools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fb0o%2Fzellij-tools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fb0o%2Fzellij-tools/lists"}