# ros2-supercharged

> The fzf-powered ROS 2 productivity plugin for zsh.

`ros2-supercharged` is a curated combination of the best ideas from three
excellent ROS 2 shell projects, rebuilt as one cohesive, modern zsh plugin:

| Project | What we took |
| --- | --- |
| [danlil240/ROS-Hacks](https://github.com/danlil240/ROS-Hacks) | fzf workspace selector, launch-file picker, colcon error browser, domain management, prompt segment |
| [farzadsw/oh-my-zsh-ros2-plugin](https://github.com/farzadsw/oh-my-zsh-ros2-plugin) | the elegant `fzf` + live-preview pattern for topics/nodes, "run + push to history" UX |
| [Butakus/ros2-env](https://github.com/Butakus/ros2-env) | the robust named-workspace registry (`rosws`), per-workspace distro + overlay chaining, build-from-anywhere `cb` with real colcon argcomplete completion |

Everything is interactive, everything has a live preview, and everything you
pick is pushed to your shell history (or prefilled on the command line) so it
stays reusable.

---

## Requirements

- **zsh** (this is a zsh plugin)
- **[fzf](https://github.com/junegunn/fzf)** — for every interactive picker
- **ROS 2** (any distro) + **colcon** — sourced or auto-detected under `/opt/ros`
- Optional: `fd`, `bat` (nicer previews), Powerlevel10k (prompt segment)

---

## Install

### Oh-My-Zsh

```sh
git clone https://github.com/danlil240/ros2-supercharged \
  "${ZSH_CUSTOM:-$HOME/.oh-my-zsh/custom}/plugins/ros2-supercharged"
```

Then add it to your plugins list in `~/.zshrc`:

```zsh
plugins=( ... ros2-supercharged )
```

### Plain zsh (no framework)

```zsh
git clone https://github.com/danlil240/ros2-supercharged ~/.zsh/ros2-supercharged
echo 'source ~/.zsh/ros2-supercharged/ros2-supercharged.plugin.zsh' >> ~/.zshrc
```

### Installer script (does either of the above for you)

```sh
./install.sh
```

Restart your shell afterwards.

On every new shell, the plugin **auto-sources** your environment:

1. If `rosws default set <ws>` is configured → that workspace (distro + overlays + install)
2. Otherwise → `/opt/ros/<ROS2SC_DEFAULT_DISTRO>` (auto-detected, e.g. jazzy)

Disable with `export ROS2SC_AUTO_SOURCE=0` before loading the plugin.

---

## Workspace management — `rosws`

A named registry of your ROS 2 workspaces. Each workspace stores its **distro**
and an optional chain of **overlay (underlay) workspaces** that get sourced
before it.

```zsh
rosws                       # open the fzf workspace selector (with live preview)
rosws add                   # register $PWD (name = dir name, distro = $ROS_DISTRO)
rosws add my_ws humble      # register $PWD as 'my_ws' on humble
rosws add app jazzy ~/base_ws ~/sim_ws   # 'app' overlays base_ws then sim_ws
rosws my_ws                 # activate a workspace by name
rosws list                  # list everything
rosws show my_ws            # details (path, distro, overlays)
rosws cd my_ws src          # cd into a workspace (or a subdir)
rosws scan ~/dev            # fzf-discover workspaces under a directory and register one
rosws clean                 # forget workspaces whose directory is gone
rosws default set my_ws     # auto-activate my_ws in every new shell
rosws default unset
rosws distro rolling        # just source /opt/ros/rolling
rosws domain 42             # set + persist ROS_DOMAIN_ID
rosws rmw                   # fzf-pick the RMW implementation
```

The active workspace is exported as `$ROS2SC_ACTIVE_WS` (and `$ROSWS_ACTIVE_WS`
for compatibility), so you can use it in custom prompts.

> Switching workspaces in the same shell re-sources the base distro first, then
> the overlays, then the workspace. For perfectly isolated environments, open a
> fresh terminal.

---

## Building — `cb`

Build the active workspace from **anywhere**. Tab-completion forwards to
colcon's native argcomplete.

```zsh
cb                          # build the active workspace
cb my_ws                    # build (and activate) a named workspace
cb --packages-select foo    # any colcon args are forwarded
cbd                         # build in Debug
cbr                         # build in Release
cbp                         # fzf-pick packages, then --packages-select
cbut                        # fzf-pick a package, then --packages-up-to
colcon_clean [ws]           # remove build/ install/ log/ of the active/named ws
cbe                         # fzf browser of colcon errors & warnings (live preview)
```

Extra args always passed to colcon live in `$CB_EXTRA_ARGS` (default
`--symlink-install`).

---

## Introspection (the fun part)

Every command opens an fzf picker with a **live preview** of the thing under the
cursor. Selecting either runs the command (and saves it to history) or prefills
an editable command on your prompt.

### Topics
| Command | Action |
| --- | --- |
| `rtecho` | echo a topic (preview: `topic info -v`) |
| `rthz` | measure publish rate |
| `rtbw` | measure bandwidth |
| `rtdelay` | measure delay |
| `rtinfo` | verbose topic info |
| `rttype` | print message type |
| `rtmsg` | show the message definition behind a topic |
| `rtpub` | prefill an editable `ros2 topic pub` (type pre-filled) |

### Nodes / Services / Params / Actions
| Command | Action |
| --- | --- |
| `rninfo` | node info (preview: `node info`) |
| `rsinfo` | service type |
| `rscall` | prefill `ros2 service call` (type pre-filled) |
| `rpget` | pick node → pick param → get value |
| `rpset` | pick node → pick param → prefill `ros2 param set` |
| `rplist` | list a node's params |
| `rainfo` | action info |
| `rasend` | prefill `ros2 action send_goal` (type pre-filled) |

### Interfaces / Run / Lifecycle / Bags / Launch
| Command | Action |
| --- | --- |
| `rifshow` | browse all interfaces, preview `interface show` |
| `rrun` | pick `pkg executable`, prefill `ros2 run` |
| `roslifecycle` | pick node → pick transition → set lifecycle state |
| `rosbag_play` / `rbag` | discover bags (metadata.yaml), prefill `ros2 bag play` |
| `rosbag_info` / `rbaginfo` | bag info |
| `roslaunch_select` / `rls` | find launch files, prefill `ros2 launch pkg file` |

---

## Environment helpers

```zsh
rosenv        # pretty-print the relevant ROS 2 environment (alias: pR)
rosdomain 7   # set + persist ROS_DOMAIN_ID (rosdomain unset to clear)
rosrmw        # fzf-pick + persist RMW_IMPLEMENTATION
roslocal      # toggle ROS_LOCALHOST_ONLY
roskill       # kill stray ros2 / gazebo / rviz processes
sr            # source the detected distro into the current shell
```

---

## Prompt integration

**Powerlevel10k** — add the segment to your prompt elements:

```zsh
POWERLEVEL9K_LEFT_PROMPT_ELEMENTS=( ... ros2_workspace ... )
# optional: POWERLEVEL9K_ROS2_WORKSPACE_FOREGROUND=green
```

**Any prompt** — drop the helper into your `PROMPT`/`RPROMPT`:

```zsh
setopt prompt_subst
RPROMPT='$(ros2sc_prompt_info)'
```

---

## Keybindings (opt-in)

Off by default so they never clobber your bindings. Enable before loading:

```zsh
export ROS2SC_ENABLE_KEYBINDINGS=1
```

| Key | Action |
| --- | --- |
| `Alt-w` | workspace selector |
| `Alt-l` | launch picker |
| `Alt-e` | topic echo picker |
| `Alt-i` | node info picker |
| `Alt-b` | build active workspace |

---

## Configuration

Export any of these in `~/.zshrc` **before** the plugin loads:

| Variable | Default | Purpose |
| --- | --- | --- |
| `ROS2SC_CONFIG` | `~/.config/ros2-supercharged` | config/state directory |
| `ROS2SC_DEFAULT_DISTRO` | auto-detected | fallback distro for `rosws add` |
| `CB_EXTRA_ARGS` | `--symlink-install` | args always passed to `colcon build` |
| `ROS2SC_FZF_HEIGHT` | `60%` | fzf window height |
| `ROS2SC_FZF_PREVIEW_WINDOW` | `right:55%:wrap` | fzf preview window |
| `ROS2SC_ENABLE_ALIASES` | `1` | install the short aliases (`rt`, `cw`, ...) |
| `ROS2SC_ENABLE_KEYBINDINGS` | `0` | install the Alt-key bindings |
| `ROS2SC_ENABLE_ARGCOMPLETE` | `1` | register native ros2/colcon completion |
| `ROS2SC_AUTO_SOURCE` | `1` | on startup: default workspace, else `/opt/ros/<distro>` |

---

## Aliases

`rt rtl rn rnl rs rsl rp rpl ra ral rb rl rr rif` map to the matching
`ros2 <verb>` commands; `cw`/`cs` cd into the active workspace / its `src`;
`cg`/`rcg` add/remove a `COLCON_IGNORE`; `pR` → `rosenv`; `rosclean` prunes old
`~/.ros/log` entries. Disable them all with `ROS2SC_ENABLE_ALIASES=0`.

---

## License

MIT — see [LICENSE](LICENSE).

Built by combining and modernizing
[ROS-Hacks](https://github.com/danlil240/ROS-Hacks),
[oh-my-zsh-ros2-plugin](https://github.com/farzadsw/oh-my-zsh-ros2-plugin) and
[ros2-env](https://github.com/Butakus/ros2-env). Thanks to their authors.