ros2-workspace

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: