Merge pull request #103 from j3soon/feat/readme-for-ai-agents

AI Agents (Claude Code, Codex) Support

Author: j3soon

.gitignore

@@ -1 +1,2 @@
 _isaac_sim
+.env*

AGENTS.md

@@ -0,0 +1,38 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `*_ws/` are independent ROS2 workspaces. Each contains `docker/compose.yaml`, `docker/Dockerfile`, `.devcontainer/`, and `src/` (ROS2 packages built with colcon inside the container).
+- `docker_modules/` holds shared install scripts that are hard-linked into each workspace via `./scripts/post_install.sh`.
+- `docs/` is MkDocs content, including per-workspace docs under `docs/<workspace-name>/`.
+- `scripts/` contains setup helpers (e.g., `post_install.sh`, `create_workspace.sh`).
+- `tests/` contains lint-style checks for compose files, Dockerfiles, MkDocs, and workspace templates.
+
+## Build, Test, and Development Commands
+- `./scripts/post_install.sh` (or `-f` to force): refreshes docker module hard links; run after any repo change or branch switch.
+- `cd <workspace>/docker && docker compose build`: builds the workspace image.
+- `cd <workspace>/docker && docker compose up -d`: starts containers in the background.
+- `cd <workspace>/docker && docker compose exec <service> bash`: opens a shell in the container.
+- `./scripts/create_workspace.sh <new_workspace_name>`: scaffolds a new workspace from `template_ws`.
+- `./tests/test_all.sh`: runs linting scripts for structure and config validation.
+
+## Coding Style & Naming Conventions
+- Workspaces must follow the `*_ws` naming pattern.
+- Use `docker/compose.yaml` (not `compose.yml` or other variants).
+- Keep required default files in each workspace: `.devcontainer/devcontainer.json`, `docker/Dockerfile`, `docker/compose.yaml`, `src/`, and `README.md`.
+- Prefer USDA over USD for Omniverse/Isaac assets where possible.
+
+## Testing Guidelines
+- Primary checks are Python-based lint scripts executed via `./tests/test_all.sh`.
+- You can skip workspaces by setting `IGNORED_WORKSPACES` (e.g., `export IGNORED_WORKSPACES="tmp_ws"`).
+
+## Commit & Pull Request Guidelines
+- Open and self-assign a GitHub issue before starting.
+- Branch naming: `feat/<name>` or `fix/<name>`.
+- Commit messages must follow Conventional Commits and include rationale and sources when relevant.
+- When `template_ws` changes require syncing other workspaces, make a separate minimal "unify" commit (preferred message: `feat: Unify workspaces style`).
+- If code/content is copied, include source and commit permalink in the commit message.
+- Add `Co-authored-by` lines for contributors who helped; avoid force-pushes once review starts.
+
+## Configuration Tips
+- Set `export USER_UID=$(id -u)` on the host to match container user permissions.
+- Enable/disable modules via `build.args` in `docker/compose.yaml` (e.g., `CARTOGRAPHER=ON`).

CLAUDE.md

@@ -0,0 +1,81 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+ROS2 Humble multi-workspace repository for Autonomous Mobile Robots (AMRs) and robotic arm manipulators. Supports Isaac Sim/Lab/ROS for simulation-to-reality deployment. Targets amd64 (simulation+real) and arm64 (real only).
+
+## Build & Run Commands
+
+```sh
+# After clone, pull, or branch switch - ALWAYS run this first:
+./scripts/post_install.sh
+
+# Force mode if files conflict:
+./scripts/post_install.sh -f
+
+# Build and run a workspace:
+cd <workspace_name>/docker
+docker compose build
+docker compose up -d
+docker compose exec <service_name> bash
+
+# Pull pre-built images (faster than building):
+cd <workspace_name>/docker
+docker compose pull
+
+# Create a new workspace:
+./scripts/create_workspace.sh <new_workspace_name>
+
+# Run linting tests:
+./tests/test_all.sh
+```
+
+## Architecture
+
+### Workspace Structure (`*_ws/`)
+Each workspace is independent and follows this pattern:
+- `docker/compose.yaml` - Primary build/run configuration with module args
+- `docker/Dockerfile` - Multi-arch image definition (references `modules/` scripts)
+- `.devcontainer/` - VS Code Dev Container configuration
+- `src/` - ROS2 packages (colcon builds these inside container)
+
+### Docker Modules (`docker_modules/`)
+Shared install scripts (e.g., `install_ros.sh`, `install_isaac_sim.sh`) that get hard-linked into workspace `docker/modules/` directories via `post_install.sh`. This enables Docker build context to access shared scripts.
+
+Modules are enabled/disabled via `build.args` in `compose.yaml`:
+```yaml
+args:
+  CARTOGRAPHER: "YES"  # or "" to disable
+  RTABMAP: "YES"
+  ISAAC_SIM_VERSION: "5.0.0"  # or "" to skip
+  ISAAC_LAB_VERSION: "2.2.1"
+```
+
+### Key Files
+- `template_ws/` - Base workspace used as reference for creating new workspaces
+- `docs/` - MkDocs documentation source (each workspace has `docs/<workspace-name>/`)
+- `scripts/setup_docker_modules_link.sh` - Creates hard links for docker modules
+- `scripts/setup_docker_volume.sh` - Sets up shared Docker volumes
+
+## Key Conventions
+
+- Run `./scripts/post_install.sh` after any repo change affecting docker_modules
+- Set `export USER_UID=$(id -u)` in host shell for container user permissions
+- Workspaces share Docker volumes: `ros2-gazebo-cache`, `ros2-isaac-sim-cache`, `ros2-isaac-ros-assets`
+- `template_ws` Docker cache is shared by other workspaces to save build time
+
+## Linting
+
+The `tests/` directory contains Python linting scripts:
+- `lint_compose.py` - Validates compose.yaml files
+- `lint_dockerfile.py` - Validates Dockerfiles
+- `lint_comp_template.py` - Checks workspace compliance with template
+- `lint_filenames.py` - Validates file naming conventions
+- `lint_gitignore.py` - Checks gitignore consistency
+- `lint_workflows.py` - Validates GitHub Actions workflows
+- `lint_mkdocs.py` - Validates documentation structure
+- `lint_readme.py` - Checks README files
+
+Set `IGNORED_WORKSPACES` env var to skip specific workspaces during linting.

CONTRIBUTING.md

@@ -19,9 +19,10 @@ We welcome all kinds of contributions, including but not limited to bug reports,
 2. Commit description should include as much details as possible. Try to include references you consulted and your rationale behind the changes. This will be essential for reviewers to understand the changes and for future reference. (e.g., [`058ff59`](https://github.com/j3soon/ros2-essentials/commit/058ff598ae705c95516353cd14a71945176c337e))
 3. If copied files from other sources, please include the source in the commit message. If copied from GitHub, include the permalink (link with commit ID) and the branch name. (e.g., [`6a2dac1`](https://github.com/j3soon/ros2-essentials/commit/6a2dac186e1321dc7f7ec961ad22628bffc352d3))
 4. Each commit should be atomic and self-contained.
-5. If anyone helped you during the development, please include them in the commit message using the `Co-authored-by` format (e.g., [`4f9832d`](https://github.com/j3soon/ros2-essentials/commit/4f9832d7a0c4156449d95b3503f9928d2d7de376) due to [this comment](https://github.com/j3soon/ros2-essentials/pull/85#discussion_r2204978905)). These include, but are not limited to, feedback from reviewers, in-person discussions, and pair programming sessions.
-6. Refrain from force-pushes after a reviewer has started reviewing your changes. The only exception is for new contributors when a reviewer has explicitly asked you to rebase your branch or modify commit messages.
-7. Use USDA instead of USD file format whenever possible for better readability and version control. (e.g., [PR#101](https://github.com/j3soon/ros2-essentials/pull/101))
+5. When updating `template_ws` defaults, follow up with a separate unify workspace style commit (preferred message: `feat: Unify workspaces style`) that applies the minimal template-alignment changes across all workspaces. Keep this separate from the template update commit.
+6. If anyone helped you during the development, please include them in the commit message using the `Co-authored-by` format (e.g., [`4f9832d`](https://github.com/j3soon/ros2-essentials/commit/4f9832d7a0c4156449d95b3503f9928d2d7de376) due to [this comment](https://github.com/j3soon/ros2-essentials/pull/85#discussion_r2204978905)). These include, but are not limited to, feedback from reviewers, in-person discussions, and pair programming sessions.
+7. Refrain from force-pushes after a reviewer has started reviewing your changes. The only exception is for new contributors when a reviewer has explicitly asked you to rebase your branch or modify commit messages.
+8. Use USDA instead of USD file format whenever possible for better readability and version control. (e.g., [PR#101](https://github.com/j3soon/ros2-essentials/pull/101))
 
 Use `git log` and search for related commits to understand the commit message format.
 

README.md

@@ -108,6 +108,8 @@ Edit the `build.args` section in the `*_ws/docker/compose.yml` file and rebuild
 | [Isaac Sim](https://j3soon.github.io/ros2-essentials/docker-modules/isaac-sim/) | ✔️ | ❌ | Isaac Sim 5.0.0 Binary Install | ✔️ | [Johnson Sun](https://github.com/j3soon), [@JustinShih0918](https://github.com/JustinShih0918) |
 | [Isaac Lab](https://j3soon.github.io/ros2-essentials/docker-modules/isaac-lab/) | ✔️ | ❌ | Isaac Lab 2.2.1 Git Install | ✔️ | [Johnson Sun](https://github.com/j3soon) |
 | [Isaac ROS](https://j3soon.github.io/ros2-essentials/docker-modules/isaac-ros/) | ✔️ | TODO | Isaac ROS 3.2 Apt Install (Base only) | ❌ | [Johnson Sun](https://github.com/j3soon) |
+| [Claude Code](https://j3soon.github.io/ros2-essentials/docker-modules/claude-code/) | ✔️ | ✔️ | Claude Code CLI | ❌ | [Johnson Sun](https://github.com/j3soon) |
+| [Codex](https://j3soon.github.io/ros2-essentials/docker-modules/codex/) | ✔️ | ✔️ | Codex CLI | ❌ | [Johnson Sun](https://github.com/j3soon) |
 
 ## Docker Compose Cleanup
 

aloha_ws/docker/Dockerfile

@@ -215,5 +215,19 @@ COPY udev_rules/99-interbotix-udev.rules /etc/udev/rules.d/
 COPY --chown=$USERNAME:$USERNAME \
      .bashrc /home/$USERNAME/.bashrc
 # TODO: Copy additional files here
+
+# Claude Code CLI configuration (installed last since the installation is fast)
+ARG CLAUDE_CODE=""
+COPY --chown=$USERNAME:$USERNAME \
+     modules/install_claude_code.sh /tmp/install_claude_code.sh
+RUN --mount=type=cache,target=/var/cache/apt,sharing=private \
+    /tmp/install_claude_code.sh && rm /tmp/install_claude_code.sh
+# Codex CLI configuration
+ARG CODEX=""
+COPY --chown=$USERNAME:$USERNAME \
+     modules/install_codex.sh /tmp/install_codex.sh
+RUN --mount=type=cache,target=/var/cache/apt,sharing=private \
+    /tmp/install_codex.sh && rm /tmp/install_codex.sh
+# TODO: Install more optional development tools here
 ENTRYPOINT []
 CMD ["/bin/bash"]

aloha_ws/docker/compose.yaml

@@ -18,7 +18,7 @@ services:
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/cache &&
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/cache/ov &&
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/{logs,data}
-        "
+      "
     volumes:
       - isaac-sim-cache:/isaac-sim
   aloha-ws:
@@ -46,6 +46,10 @@ services:
         # CARTOGRAPHER: ""
         # TODO: Set to "YES" if using RTAB-Map or set to "" if not using RTAB-Map
         # RTABMAP: ""
+        # TODO: Set to "YES" if using Claude Code CLI or set to "" if not using Claude Code CLI
+        # CLAUDE_CODE: ""
+        # TODO: Set to "YES" if using Codex CLI or set to "" if not using Codex CLI
+        # CODEX: ""
       cache_from:
         - j3soon/ros2-aloha-ws:buildcache-amd64
         - j3soon/ros2-aloha-ws:buildcache-arm64
@@ -179,6 +183,10 @@ services:
       # TODO: Add more volume mounts here.
       # Mount root workspace to allow easy access to all workspaces.
       - ../..:/home/ros2-essentials
+      # Mount credentials (for Claude Code CLI, Codex CLI, and etc.)
+      - ../../.env/.claude:/home/user/.claude
+      - ../../.env/.claude.json:/home/user/.claude.json
+      - ../../.env/.codex:/home/user/.codex
 volumes:
   gazebo-cache:
     name: ros2-gazebo-cache

delto_gripper_ws/docker/Dockerfile

@@ -182,5 +182,19 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=private \
 COPY --chown=$USERNAME:$USERNAME \
      .bashrc /home/$USERNAME/.bashrc
 # TODO: Copy additional files here
+
+# Claude Code CLI configuration (installed last since the installation is fast)
+ARG CLAUDE_CODE=""
+COPY --chown=$USERNAME:$USERNAME \
+     modules/install_claude_code.sh /tmp/install_claude_code.sh
+RUN --mount=type=cache,target=/var/cache/apt,sharing=private \
+    /tmp/install_claude_code.sh && rm /tmp/install_claude_code.sh
+# Codex CLI configuration
+ARG CODEX=""
+COPY --chown=$USERNAME:$USERNAME \
+     modules/install_codex.sh /tmp/install_codex.sh
+RUN --mount=type=cache,target=/var/cache/apt,sharing=private \
+    /tmp/install_codex.sh && rm /tmp/install_codex.sh
+# TODO: Install more optional development tools here
 ENTRYPOINT []
 CMD ["/bin/bash"]

delto_gripper_ws/docker/compose.yaml

@@ -18,7 +18,7 @@ services:
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/cache &&
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/cache/ov &&
         chown ${USER_UID:-1000}:${USER_UID:-1000} /isaac-sim/standalone/{logs,data}
-        "
+      "
     volumes:
       - isaac-sim-cache:/isaac-sim
   delto-gripper-ws:
@@ -46,6 +46,10 @@ services:
         # CARTOGRAPHER: ""
         # TODO: Set to "YES" if using RTAB-Map or set to "" if not using RTAB-Map
         # RTABMAP: ""
+        # TODO: Set to "YES" if using Claude Code CLI or set to "" if not using Claude Code CLI
+        # CLAUDE_CODE: ""
+        # TODO: Set to "YES" if using Codex CLI or set to "" if not using Codex CLI
+        # CODEX: ""
       cache_from:
         - j3soon/ros2-delto-gripper-ws:buildcache-amd64
         - j3soon/ros2-delto-gripper-ws:buildcache-arm64
@@ -179,6 +183,10 @@ services:
       # TODO: Add more volume mounts here.
       # Mount root workspace to allow easy access to all workspaces.
       - ../..:/home/ros2-essentials
+      # Mount credentials (for Claude Code CLI, Codex CLI, and etc.)
+      - ../../.env/.claude:/home/user/.claude
+      - ../../.env/.claude.json:/home/user/.claude.json
+      - ../../.env/.codex:/home/user/.codex
 volumes:
   gazebo-cache:
     name: ros2-gazebo-cache

docker_modules/install_claude_code.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+set -e
+
+if [ -z "$CLAUDE_CODE" ]; then
+    echo "Skipping Claude Code installation as CLAUDE_CODE is not set"
+    exit 0
+fi
+
+# Ref: https://code.claude.com/docs/en/setup
+# Install Claude Code CLI
+# This script is intended to be run inside the Dockerfile during build.
+if [ "$CLAUDE_CODE" = "YES" ]; then
+    echo "Installing Claude Code CLI"
+
+    # Install Claude Code CLI using official installer
+    curl -fsSL https://claude.ai/install.sh | bash
+
+    echo "Claude Code CLI installed successfully!"
+    echo "Version information:"
+    claude --version || true
+fi
+
+echo "Claude Code installation completed!"