diff --git a/.env.example b/.env.example index e1e10a4..2255671 100644 --- a/.env.example +++ b/.env.example @@ -1,6 +1,10 @@ # Copy this file to .env and fill in your credentials # The .env file will be baked into the Docker image during build +# Required: Git configuration for commits made inside the container +GIT_USER_NAME=Your Name +GIT_USER_EMAIL=your.email@example.com + # Optional: Twilio credentials for SMS notifications TWILIO_ACCOUNT_SID=your_twilio_account_sid TWILIO_AUTH_TOKEN=your_twilio_auth_token diff --git a/Dockerfile b/Dockerfile index cfd0b2d..973eb6d 100644 --- a/Dockerfile +++ b/Dockerfile @@ -82,6 +82,18 @@ RUN bash -c 'source /app/.env && \ echo "No Twilio credentials found, skipping MCP configuration"; \ fi' +# Configure git user during build +RUN bash -c 'source /app/.env && \ + if [ -n "$GIT_USER_NAME" ] && [ -n "$GIT_USER_EMAIL" ]; then \ + echo "Configuring git user: $GIT_USER_NAME <$GIT_USER_EMAIL>" && \ + git config --global user.name "$GIT_USER_NAME" && \ + git config --global user.email "$GIT_USER_EMAIL" && \ + echo "Git configuration complete"; \ + else \ + echo "Warning: GIT_USER_NAME and GIT_USER_EMAIL not set in .env"; \ + echo "Git commits will require manual configuration"; \ + fi' + # Set working directory to mounted volume WORKDIR /workspace diff --git a/README.md b/README.md index ad92ed5..1cf7497 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,13 @@ ls ~/.claude.json ~/.claude/ - **Docker Desktop**: https://docs.docker.com/get-docker/ - Ensure Docker daemon is running before proceeding -### 3. Twilio Account (Optional - for SMS notifications) +### 3. Git Configuration (Required) +For any git commits made inside the container, you'll need to provide: +- Your name and email address +- These will be configured in the `.env` file +- Used for `git config --global user.name` and `git config --global user.email` + +### 4. Twilio Account (Optional - for SMS notifications) If you want SMS notifications when tasks complete: - Create free trial account: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account - Get your Account SID and Auth Token from the Twilio Console @@ -69,6 +75,10 @@ claude-docker # Required ANTHROPIC_API_KEY=your_anthropic_key +# Required - Git configuration for commits +GIT_USER_NAME=Your Name +GIT_USER_EMAIL=your.email@example.com + # Optional - SMS notifications TWILIO_ACCOUNT_SID=your_twilio_sid TWILIO_AUTH_TOKEN=your_twilio_auth_token @@ -179,8 +189,7 @@ This workflow gives you: ### 🐳 Clean Environment - Each session runs in fresh Docker container -- Container auto-removes on exit -- No system pollution or conflicts +- Only current working directory mounted (along with conda directories specified in `.env`). ## How It Works @@ -194,7 +203,7 @@ This workflow gives you: ``` claude-docker/ -├── Dockerfile # Main container definition +├── Dockerfile # Main container definition ├── .env.example # Template for environment variables ├── scripts/ │ ├── claude-docker.sh # Wrapper script for container @@ -202,7 +211,7 @@ claude-docker/ │ └── startup.sh # Container startup script └── templates/ └── .claude/ - └── CLAUDE.md # Claude behavior instructions + └── CLAUDE.md # Claude behavior instructions ``` ## Configuration @@ -242,10 +251,10 @@ For custom conda installations (common in academic/lab environments), add these ```bash # Main conda installation -CONDA_PREFIX=/vol/biomedic3/username/miniconda3 +CONDA_PREFIX=/vol/lab/username/miniconda3 # Additional conda directories (space-separated) -CONDA_EXTRA_DIRS="/vol/biomedic3/username/.conda/envs /vol/biomedic3/username/conda_envs /vol/biomedic3/username/.conda/pkgs /vol/biomedic3/username/conda_pkgs" +CONDA_EXTRA_DIRS="/vol/lab/username/.conda/envs /vol/lab/username/conda_envs /vol/lab/username/.conda/pkgs /vol/lab/username/conda_pkgs" ``` **How it works:** @@ -270,20 +279,8 @@ SYSTEM_PACKAGES="libopenslide0" SYSTEM_PACKAGES="libopenslide0 libgdal-dev libproj-dev libopencv-dev" ``` -**Common packages:** -- `libopenslide0` - OpenSlide for whole slide imaging -- `libgdal-dev` - GDAL for geospatial data -- `libproj-dev` - PROJ for cartographic projections -- `libopencv-dev` - OpenCV for computer vision -- `libfftw3-dev` - FFTW for fast Fourier transforms - **Note:** Adding system packages requires rebuilding the Docker image (`docker rmi claude-docker:latest`). -## Requirements - -- Docker installed and running -- Anthropic API key (or Claude subscription) -- (Optional) Twilio account with API Key/Secret for SMS notifications ## Next Steps diff --git a/commit_diff_summary.txt b/commit_diff_summary.txt new file mode 100644 index 0000000..df43967 --- /dev/null +++ b/commit_diff_summary.txt @@ -0,0 +1,13 @@ +Write a commit message for the changes in the following git diff: +Follow the following instructions when writing the commit message: +Subject line: Max 50 chars, imperative mood, capitalized, no period +Skip a line between subject and body +Body text: Wrap at 72 chars per line +Explain what and why, not how +Reference issue numbers when applicable +Format: (): + +=== GIT DIFF SUMMARY FOR COMMIT === + + +=== END OF DIFF SUMMARY === diff --git a/plan.md b/plan.md new file mode 100644 index 0000000..6bfa406 --- /dev/null +++ b/plan.md @@ -0,0 +1,84 @@ +# README Update and Repository Preparation Plan + +## Objective +Update the claude-docker README to be production-ready for public release, with clear setup instructions, proper attribution, and comparison to Anthropic's devcontainer implementation. + +## Current Script Inventory (Post-Cleanup) +Based on our recent pruning, these are the active scripts: +- **claude-docker.sh**: Main wrapper script that handles Docker container lifecycle, mounts projects, copies templates +- **install.sh**: One-time installation script that builds Docker image and creates system-wide alias +- **startup.sh**: Container entrypoint that loads environment and starts Claude Code with MCP + +## Tasks + +### 1. Research Phase +- Fetch and analyze Anthropic's .devcontainer implementation files: + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/devcontainer.json + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/Dockerfile + - https://raw.githubusercontent.com/anthropics/claude-code/main/.devcontainer/init-firewall.sh +- Understand their approach to: + - Authentication handling + - Firewall/security implementation + - Environment setup + - Persistence mechanisms + +### 2. README Prerequisites Update +- Add clear warning that Claude Code must be pre-authenticated on host +- Link to official Claude Code installation docs: https://docs.anthropic.com/en/docs/claude-code +- Link to Twilio setup documentation +- Make it ultra-clear what needs to be done BEFORE using claude-docker + +### 3. Add Comparison Section +Create "How This Differs from Anthropic's DevContainer" section highlighting: +- **Authentication Persistence**: Our approach vs theirs +- **Conda Environment Management**: Full conda mounting and path preservation +- **Project Mounting**: Plug-and-play for any project directory +- **Twilio MCP Integration**: Built-in SMS notifications +- **Use Case**: Standalone tool vs VSCode-integrated development + +### 4. Simplify Setup Instructions +Transform current setup into numbered CLI commands: +```bash +1. git clone https://github.com/VishalJ99/claude-docker.git +2. cd claude-docker +3. cp .env.example .env +4. nano .env # Add your API keys +5. ./scripts/install.sh +6. claude-docker # Run from any project +``` + +### 5. Add Proper Attribution +- Link to Twilio MCP server we use: @yiyang.1i/sms-mcp-server +- Credit Anthropic's claude-code project +- Add links to all external dependencies + +### 6. Remove Legacy Content +- Remove references to setup-env.sh (already deleted) +- Update directory structure section to reflect current scripts +- Update any stale examples + + +## Key Differentiators to Emphasize + +1. **Standalone Docker** vs DevContainer (VSCode-specific) +2. **Persistent Authentication** - login once, use everywhere +3. **Conda Integration** - preserves conda environments and works with custom env and pkg dirs +4. **SMS Notifications** - autonomous execution with status updates +5. **Zero Configuration Per Project** - just run claude-docker +6. **Detach/Reattach Workflow** - long-running sessions + +## Links to Include + +- Claude Code Setup: https://docs.anthropic.com/en/docs/claude-code +- Twilio Account Setup: https://www.twilio.com/docs/usage/tutorials/how-to-use-your-free-trial-account +- Docker Installation: https://docs.docker.com/get-docker/ +- Our Repository: https://github.com/VishalJ99/claude-docker +- Anthropic's DevContainer: https://github.com/anthropics/claude-code/tree/main/.devcontainer + +## Success Criteria +- New user can go from zero to running claude-docker in < 5 minutes +- Clear understanding of what this tool provides vs alternatives +- All external dependencies properly attributed +- No legacy or confusing content remains +- Prerequisites are crystal clear +- Directory structure accurately reflects current codebase \ No newline at end of file diff --git a/scripts/startup.sh b/scripts/startup.sh index df8e253..5fdd3aa 100755 --- a/scripts/startup.sh +++ b/scripts/startup.sh @@ -34,6 +34,13 @@ else echo "No Twilio credentials found - SMS notifications disabled" fi +# Configure git for the mounted workspace +if [ -n "$GIT_USER_NAME" ] && [ -n "$GIT_USER_EMAIL" ]; then + echo "✓ Configuring git: $GIT_USER_NAME <$GIT_USER_EMAIL>" + git config --global user.name "$GIT_USER_NAME" + git config --global user.email "$GIT_USER_EMAIL" +fi + # Start Claude Code with permissions bypass echo "Starting Claude Code..." exec claude --dangerously-skip-permissions "$@" \ No newline at end of file diff --git a/task_log.md b/task_log.md new file mode 100644 index 0000000..733c68c --- /dev/null +++ b/task_log.md @@ -0,0 +1,82 @@ +# Task Execution Log + +## Task Overview +Update the claude-docker README to be production-ready for public release, with clear setup instructions, proper attribution, and comparison to Anthropic's devcontainer implementation. + +## Implementation Overview +This task involves: +1. Researching Anthropic's .devcontainer implementation +2. Updating README prerequisites with clear warnings and links +3. Adding comparison section between our approach and Anthropic's +4. Simplifying setup instructions into numbered CLI commands +5. Adding proper attribution for all dependencies +6. Removing legacy content and updating directory structure + +## Checklist +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze devcontainer.json +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze Dockerfile +- [x] Research Anthropic's .devcontainer implementation - fetch and analyze init-firewall.sh +- [x] Create task_log.md to document execution process +- [x] Update README Prerequisites section with clear warnings and links +- [x] Add 'How This Differs from Anthropic's DevContainer' comparison section +- [x] Simplify Setup Instructions into numbered CLI commands +- [x] Add Proper Attribution section with all external dependencies +- [x] Remove legacy content and update directory structure +- [x] Verify README completeness against success criteria +- [x] Test README instructions for clarity and accuracy +- [x] Commit changes with appropriate message +- [ ] Send completion notification via Twilio + +## Assumptions Made +- The README.md file exists in the project root +- The current script inventory mentioned in plan.md is accurate +- External URLs for Anthropic's devcontainer files are accessible + +## Problems Encountered +- Research phase completed successfully. Key findings: + - Anthropic's devcontainer uses a restrictive firewall approach + - They use VSCode-specific devcontainer.json configuration + - Authentication is handled differently (not persisted like ours) + - Their approach is more security-focused but less flexible + +## Verification Against Success Criteria +✅ New user can go from zero to running claude-docker in < 5 minutes + - Simplified to 4 clear command blocks + - All prerequisites clearly stated with links + +✅ Clear understanding of what this tool provides vs alternatives + - Detailed comparison table with Anthropic's DevContainer + - Clear "When to Use Each" section + +✅ All external dependencies properly attributed + - New Attribution section with all dependencies + - Links to Claude Code, Twilio MCP, Docker, and references + +✅ No legacy or confusing content remains + - Verified no references to deleted scripts + - Directory structure is accurate + +✅ Prerequisites are crystal clear + - Dedicated Prerequisites section with warnings + - Links to all setup documentation + +✅ Directory structure accurately reflects current codebase + - Shows only the 3 active scripts + - No mention of removed scripts + +## Deviations from Plan +- Found that scratchpad.md template referenced in scripts doesn't exist +- Updated README to remove scratchpad.md references and corrected directory structure +- Fixed inaccuracies discovered during testing phase + +## Final Status +SUCCESS - All tasks completed successfully + +Summary of changes: +- Enhanced README with comprehensive prerequisites section +- Added detailed comparison with Anthropic's DevContainer approach +- Simplified setup to 4 clear CLI commands +- Added proper attribution for all dependencies +- Fixed directory structure inaccuracies +- Removed references to non-existent scratchpad.md +- Committed changes with hash: 7b50165 \ No newline at end of file diff --git a/templates/.claude/CLAUDE.md b/templates/.claude/CLAUDE.md index f33ccab..dc69938 100644 --- a/templates/.claude/CLAUDE.md +++ b/templates/.claude/CLAUDE.md @@ -27,9 +27,15 @@ If ANY Twilio variables are missing, skip SMS notifications and continue task ex ## Required Workflow ### 1. Task Initialization -- **FIRST**: Check for `claude.md` in project root - if exists, read it to understand project-specific context and requirements -- Read and understand the complete specification/plan written in `plan.md`. -- **ULTRA THINK**: ultrathink about the execution approach - analyse potential pitfalls, complications, technical challenges, and validate that your planned approach will actually work and properly implement the specification. +- **FIRST**: Set up Git branch: + ```bash + git stash -u # Stash any uncommitted changes including untracked files + git checkout -b claude-docker || git checkout claude-docker # Create branch or switch to it + git stash apply # Apply stashed changes if any + ``` +- Check for `claude.md` in project root - if exists, read it to understand project-specific context and requirements +- Read and understand the complete specification/plan written in `plan.md` +- **ULTRA-THINK**: Analyze potential pitfalls, complications, technical challenges, and validate that your planned approach will actually work and properly implement the specification - Create a detailed checklist using TodoWrite breaking down all steps - Create `task_log.md` in project root to document the execution process - Begin systematic execution @@ -89,17 +95,46 @@ Upon successful task completion: 3. Complete final documentation in `task_log.md` 4. Make git commits following the commit message rules below 5. If Twilio is configured (all env vars present), send completion message to `$TWILIO_TO_NUMBER` with summary +6. Completion msg MUST include a remote url link. See below for generation instructions. + +### Constructing Remote Git URLs +When you need to create GitHub commit URLs, use these commands to extract repository information: +```bash +REMOTE_URL=$(git config --get remote.origin.url) +COMMIT_SHA=$(git rev-parse HEAD) +``` + +Parse the remote URL to construct GitHub commit links: +- For HTTPS URLs like `https://github.com/username/repo.git`: Extract username and repo from path +- For SSH URLs like `git@github.com:username/repo.git`: Extract username and repo after the colon +- Final URL format: `https://github.com/username/repo/commit/COMMIT_SHA` + +Example extraction logic: +```bash +# Remove .git suffix and extract parts +if [[ $REMOTE_URL == *"github.com:"* ]]; then + # SSH format: git@github.com:username/repo.git + REPO_PATH=${REMOTE_URL#*:} + REPO_PATH=${REPO_PATH%.git} +elif [[ $REMOTE_URL == *"github.com/"* ]]; then + # HTTPS format: https://github.com/username/repo.git + REPO_PATH=${REMOTE_URL#*github.com/} + REPO_PATH=${REPO_PATH%.git} +fi +GITHUB_URL="https://github.com/${REPO_PATH}/commit/${COMMIT_SHA}" +``` + ## Environment & Tools ### Python/Conda Environment -- ALWAYS use conda binary at `/vol/biomedic3/vj724/miniconda3/bin/conda` +- ALWAYS use conda binary at `$CONDA_PREFIX/bin/conda` - ALWAYS use this format for script execution: ```bash -/vol/biomedic3/vj724/miniconda3/bin/conda run --live-stream -n ENVIRONMENT_NAME python -u your_script.py [args] +$CONDA_PREFIX/bin/conda run --live-stream -n ENVIRONMENT_NAME python -u your_script.py [args] ``` - ALWAYS include --live-stream and -u flags for real-time output -- You will be told the conda env name to use in the `plan.md` +- You will be TOLD the conda env name to use in the `plan.md`, if not told, log this as termination reason in `task_log.md` and if twilio configured, text to the user. ### Sandbox Environment - You have full file system access within the container @@ -141,6 +176,7 @@ Upon successful task completion: ### When to Commit - Commit after completing each major step in your checklist - Use execution context, not git diff, to write messages +- Always push to origin after commits: git push -u origin claude-docker ### Commit Message Format **Subject Line:** @@ -180,7 +216,7 @@ See task_log.md for details **Successful Completion:** ``` TASK COMPLETED: [Brief summary] -Files modified: [Key files changed] +GIT_COMMIT_URL: [Remote Git URL] See task_log.md for full details ```