feat: Add support for Claude agents in ClaudeBox containers

[johnhaley81]

Summary

• Adds support for syncing Claude agents from host to ClaudeBox containers
• Implements same per-project isolation model as commands
• Enables users to use their locally defined agents inside containers

Implementation Details

Changes Made:

1. build/docker-entrypoint: Added symlink creation for agents directory (similar to commands)
2. lib/project.sh: Added agent syncing functionality that:
   • Syncs from ~/.claude/agents/ to project-specific directories
   • Uses checksums to detect changes and only sync when needed
   • Handles cleanup when source directory doesn't exist
   • Fixed platform detection for checksum calculation (BSD vs GNU stat)
   • Proper error handling for cd operations (shellcheck compliance)

How It Works:

1. Host agents at ~/.claude/agents/ are automatically detected
2. Agents are copied to ~/.claudebox/projects/{project_hash}/agents/ (per-project isolation)
3. Container mounts the project directory and creates symlink: ~/.claude/agents → ~/.claudebox/agents
4. Claude CLI finds agents at the expected standard location

Review Feedback Addressed

Based on Sourcery AI review:

• ✅ Fixed platform detection for checksum calculation (now handles both BSD and GNU stat)
• ✅ Considered rsync (kept manual copy for simplicity and to avoid adding dependencies)
• ✅ Considered extracting helper functions (kept inline to match existing codebase patterns)
• ✅ Considered making agent path configurable (kept standard path for consistency with Claude CLI)
• ✅ Fixed shellcheck warning SC2164 for cd command error handling

Testing

• ✅ Tested locally with agent files
• ✅ Verified symlink creation in container
• ✅ Confirmed agents are accessible to Claude CLI
• ✅ Validated checksum-based change detection works on both macOS and Linux
• ✅ Shellcheck validation passes

User Impact

Users can now use their Claude agents within ClaudeBox containers by:

1. Having agents defined in ~/.claude/agents/ on their host
2. ClaudeBox automatically syncs them to containers (no manual steps required)

This maintains the same security and isolation model as commands - each project gets its own copy of agents.

🤖 Generated with Claude Code

[sourcery-ai]

Reviewer's Guide

This PR extends the existing project sync workflow by adding per-project agent synchronization (with checksum-based change detection and cleanup) in lib/project.sh and updates the container entrypoint to create the corresponding agents symlink so the Claude CLI finds user agents inside ClaudeBox containers.

File-Level Changes

Change	Details	Files
Implement checksum-based agent syncing in project scripts	Define source (~/.claude/agents) and project target directories Compute directory checksum via find/stat and md5/md5sum Compare against stored checksum to trigger sync only on changes Remove old agents, recreate directory, and copy files preserving structure Save new checksum and remove agents on source deletion	lib/project.sh
Add agents symlink creation in container entrypoint	Detect project’s agents folder mount point Create ~/.claude/agents → mounted project agents symlink Mirror existing commands symlink logic for agents	build/docker-entrypoint

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey @johnhaley81 - I've reviewed your changes - here's some feedback:

• Consider replacing the manual find/cp loop and checksum logic with an rsync --archive --delete invocation to simplify synchronization and preserve metadata.
• Extract the checksum calculation and sync decision logic into a reusable helper to reduce duplication between commands and agents syncing.
• Allow configuring the agents source path (e.g. via XDG_CONFIG_HOME) instead of hardcoding ~/.claude/agents for better flexibility.

Prompt for AI Agents

Please address the comments from this code review:
## Overall Comments
- Consider replacing the manual find/cp loop and checksum logic with an rsync --archive --delete invocation to simplify synchronization and preserve metadata.
- Extract the checksum calculation and sync decision logic into a reusable helper to reduce duplication between commands and agents syncing.
- Allow configuring the agents source path (e.g. via XDG_CONFIG_HOME) instead of hardcoding ~/.claude/agents for better flexibility.

## Individual Comments

### Comment 1
<location> `lib/project.sh:605` </location>
<code_context>
+    
+    # Calculate checksum for agents if directory exists
+    if [[ -d "$agents_source" ]]; then
+        agents_checksum=$(find "$agents_source" -type f -exec stat -f "%m" {} \; 2>/dev/null | sort | md5 2>/dev/null || \
+                         find "$agents_source" -type f -exec stat -c "%Y" {} \; 2>/dev/null | sort | md5sum | cut -d' ' -f1)
+        
+        # Check if sync needed
</code_context>

<issue_to_address>
Checksum calculation uses platform-specific 'stat' and 'md5' commands.

If neither BSD/macOS nor GNU/Linux commands are available, the script may fail without warning. Please add an explicit error message or fallback for unsupported platforms.
</issue_to_address>

<suggested_fix>
<<<<<<< SEARCH
    # Calculate checksum for agents if directory exists
    if [[ -d "$agents_source" ]]; then
        agents_checksum=$(find "$agents_source" -type f -exec stat -f "%m" {} \; 2>/dev/null | sort | md5 2>/dev/null || \
                         find "$agents_source" -type f -exec stat -c "%Y" {} \; 2>/dev/null | sort | md5sum | cut -d' ' -f1)

        # Check if sync needed
=======
    # Calculate checksum for agents if directory exists
    if [[ -d "$agents_source" ]]; then
        if command -v stat >/dev/null 2>&1 && command -v md5 >/dev/null 2>&1; then
            # BSD/macOS
            agents_checksum=$(find "$agents_source" -type f -exec stat -f "%m" {} \; 2>/dev/null | sort | md5 2>/dev/null)
        elif command -v stat >/dev/null 2>&1 && command -v md5sum >/dev/null 2>&1; then
            # GNU/Linux
            agents_checksum=$(find "$agents_source" -type f -exec stat -c "%Y" {} \; 2>/dev/null | sort | md5sum | cut -d' ' -f1)
        else
            echo "Error: Required checksum utilities (stat/md5 or stat/md5sum) not found on this platform." >&2
            exit 1
        fi

        # Check if sync needed
>>>>>>> REPLACE

</suggested_fix>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}