ROS 2 Workspace Plugin
Claude Code plugin for ROS 2 workspace management with colcon build and test automation.
Features
- Automatic workspace detection: Finds ROS 2 workspace root by traversing up directories
- Workspace tracking: Creates
.ros_workspace.txt with workspace root path
- Git integration: Automatically adds generated files to
.gitignore
- Colcon build: Executes
colcon build with ccache support via build.sh and returns to original directory
- Colcon test: Executes
colcon test with automatic result display via test.sh and returns to original directory
- Test results: Display detailed test results with
colcon test-result --verbose and returns to original directory
- Smart package selection: Automatically builds/tests only packages in current directory
- Directory preservation: All commands preserve your working directory - no manual
cd needed
Installation
From Marketplace (Recommended)
Install directly from the Claude Code plugin marketplace:
# Search for the plugin
cc plugin search ros2
# Install the plugin
cc plugin install ros2-workspace
# The plugin will be automatically available in all your projects
Manual Installation
Option 1: Clone from GitHub
# Clone to Claude Code plugins directory
mkdir -p ~/.claude/plugins
git clone https://github.com/hakuturu583/ros2-claude-code-plugin.git ~/.claude/plugins/ros2-workspace
Option 2: Local Development
# Use plugin from local directory
cc --plugin-dir /path/to/ros2-claude-code-plugin
Usage
/colcon-build command
Execute colcon build with automatic workspace detection:
/colcon-build
With options:
/colcon-build --symlink-install
/colcon-build --packages-select my_package
/colcon-build --symlink-install --packages-select my_package
/colcon-test command
Execute colcon test with automatic workspace detection and result display:
/colcon-test
With options:
/colcon-test --packages-select my_package
/colcon-test --packages-up-to my_package
/colcon-test --retest-until-pass 3
/colcon-test-result command
Display detailed test results from the workspace:
/colcon-test-result
With options:
/colcon-test-result --all
/colcon-test-result --test-result-base custom_results
Note: This command automatically navigates to the workspace root, displays test results, and returns to your original directory.
Smart Package Selection
The plugin automatically determines which packages to build/test based on your current directory:
Scenario 1: Working on specific package
# Navigate to package directory
cd ~/ros2_ws/src/my_robot_package
# Start Claude Code
cc
# Build only this package and dependencies
/colcon-build
# Result: colcon build --packages-up-to my_robot_package
# Test only this package and dependencies
/colcon-test
# Result: colcon test --packages-up-to my_robot_package
# Note: Automatically returns to ~/ros2_ws/src/my_robot_package after build/test
Scenario 2: Working in workspace root
# Navigate to workspace root
cd ~/ros2_ws
# Start Claude Code
cc
# Build entire workspace
/colcon-build
# Result: colcon build
# Test entire workspace
/colcon-test
# Result: colcon test
Scenario 3: Override with explicit package selection
# From any directory, you can override
/colcon-build --packages-select specific_package
# Result: Builds only specific_package (not its dependencies)
/colcon-test --packages-select specific_package
# Result: Tests only specific_package (not its dependencies)
What it does: