ros2-supercharged

June 12, 2026 · View on GitHub

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	fzf workspace selector, launch-file picker, colcon error browser, domain management, prompt segment
farzadsw/oh-my-zsh-ros2-plugin	the elegant `fzf` + live-preview pattern for topics/nodes, "run + push to history" UX
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 — 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

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:

plugins=( ... ros2-supercharged )

Plain zsh (no framework)

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)

./install.sh

Restart your shell afterwards.

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

If rosws default set <ws> is configured → that workspace (distro + overlays + install)
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.

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.

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

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:

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

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

setopt prompt_subst
RPROMPT='$(ros2sc_prompt_info)'

Keybindings (opt-in)

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

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>`

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.

Built by combining and modernizing ROS-Hacks, oh-my-zsh-ros2-plugin and ros2-env. Thanks to their authors.