Docker Sandbox with Claude Code

CLAUDE_brainjuck_sandbox.md

Project Guidance

This file provides context and guidance for working with this project.

Project Overview

This is a multi-language project with the following languages detected: javascript and java.

javascript

Tools and Commands

• Use "npm install" or "yarn install" to install dependencies
• Use "npm test" or "yarn test" to run tests
• Use "npm run build" or "yarn build" to build the project
• Use "npm start" or "yarn start" to start the development server
• Check package.json for available scripts

Development Workflow

1. Make changes to .js/.ts files
2. Run "npm install" if dependencies changed
3. Run linters if configured (ESLint)
4. Run tests with "npm test"
5. Build/start the project to verify changes

Coding Style

• Follow the existing code style in the project
• Use ESLint rules if configured
• Use Prettier for formatting if configured
• Write modular, reusable code
• Use modern JavaScript/ES6+ features appropriately

Testing Approach

• Write tests using the configured framework (Jest, Mocha, etc.)
• Place tests near source files or in tests directory
• Run "npm test" to execute tests
• Check package.json for test scripts
• Aim for good test coverage

java

Tools and Commands

• Use "mvn compile" or "gradle build" to build the project
• Use "mvn test" or "gradle test" to run tests
• Use "mvn clean install" for full Maven build
• Check pom.xml or build.gradle for project configuration

Development Workflow

1. Make changes to .java files
2. Compile with Maven or Gradle
3. Run tests to verify changes
4. Check for compilation errors
5. Build the complete project

Coding Style

• Follow Java naming conventions
• Use proper access modifiers
• Write JavaDoc for public APIs
• Keep classes focused and cohesive
• Follow SOLID principles

Testing Approach

• Write JUnit tests in src/test/java
• Use @Test annotations for test methods
• Run "mvn test" or "gradle test"
• Use assertion libraries effectively
• Aim for good test coverage

Environment Persistence

This project has a persistent environment configured via CLAUDE_ENV_FILE (/etc/sandbox-persistent.sh).

According to Claude Code Documentation:

CLAUDE_ENV_FILE

If set, this file will be sourced before each Bash command execution. This allows environment variables to persist across multiple Bash tool invocations.

The sandbox environment provides persistent environment variable storage across all shell sessions.

• Environment variables stored in /etc/sandbox-persistent.sh persist across all bash invocations
• The CLAUDE_ENV_FILE environment variable points to /etc/sandbox-persistent.sh
• Use echo "export VAR_NAME=value" >> /etc/sandbox-persistent.sh to add persistent variables
• Useful for tool installations (nvm, sdkman, etc.) that modify PATH or environment variables

Critical: Shell Completions Must NOT Be in CLAUDE_ENV_FILE

NEVER add shell completion scripts to the persistent environment file.

Shell completion scripts (like bash_completion for NVM, SDKMAN, etc.) will completely break the bash tool when sourced via CLAUDE_ENV_FILE.

Why Completions Break

CLAUDE_ENV_FILE is sourced before every single bash command execution, not just during shell initialization. Completion scripts rely on special variables (COMP_WORDS, COMP_CWORD, COMPREPLY) that only exist during tab-completion contexts, not during normal command execution.

WRONG - Will Break Bash

# DO NOT ADD THESE TO /etc/sandbox-persistent.sh
[ -s "$NVM_DIR/bash_completion" ] && \. "$NVM_DIR/bash_completion"
[[ -s "$SDKMAN_DIR/etc/bash_completion.sh" ]] && source "$SDKMAN_DIR/etc/bash_completion.sh"

CORRECT - Only Load Core Functionality

# ONLY add the main initialization scripts
export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

export SDKMAN_DIR="$HOME/.sdkman"
[[ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ]] && source "$SDKMAN_DIR/bin/sdkman-init.sh"

Symptoms of Broken Shell

When completion scripts are incorrectly added to CLAUDE_ENV_FILE:

• All bash commands return no output (silent failure)
• echo, pwd, and other basic commands produce no results
• The bash tool becomes completely unusable

Solution

If you accidentally added completion scripts and broke the shell:

1. Remove the completion line(s) from /etc/sandbox-persistent.sh
2. Exit and restart the Claude Code session
3. Verify with echo "test" that bash works again

IMPORTANT: Using the Bash Tool

When using the Bash tool, in the case of not finding the tool in the PATH, try using a fresh login shell to ensure the persistent environment is properly loaded:

• Use bash -l -c "your-command" instead of running commands directly
• This ensures /etc/sandbox-persistent.sh is sourced and PATH modifications are honored
• Example: bash -l -c "java -version" instead of java -version
• This is critical when tools like sdkman, nvm, or other environment managers modify PATH

Why this is necessary:

• Shell snapshots may contain cached environment state from before tools were installed
• Login shells always source the persistent environment file fresh, ensuring latest configuration
• This guarantees that agent's extension of the environment file, such as CLAUDE_ENV_FILE for Claude, is properly honored

Example - persisting nvm installation:

# After installing nvm
echo 'export NVM_DIR="$HOME/.nvm"' >> /etc/sandbox-persistent.sh
echo '[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"' >> /etc/sandbox-persistent.sh

# Then use login shells to access it
bash -l -c "node --version"

Example - persisting sdkman installation:

# After installing sdkman and Java
echo 'export SDKMAN_DIR="$HOME/.sdkman"' >> /etc/sandbox-persistent.sh
echo '[[ -s "$SDKMAN_DIR/bin/sdkman-init.sh" ]] && source "$SDKMAN_DIR/bin/sdkman-init.sh"' >> /etc/sandbox-persistent.sh

# Then use login shells to access it
bash -l -c "java -version"
bash -l -c "sdk current"

Network access

There is a firewall in place to restrict outbound network access. If you need http/https access to an external service, request it, specifying the domain and port.

Docker network access

You have access to a Docker daemon in this environment. You can access published ports on "localhost" because it is included in the shell's "no proxy" configuration. For direct access to container ports, you must add the container's network to the "no proxy" configuration.

Additional Notes

• Always read relevant files before making changes
• Run tests after making modifications
• Follow the existing code structure and patterns
• Ask for clarification if project requirements are unclear
• You have sudo permissions, so you can install necessary packages
• npm, pip and uv are already available for package management