Skip to content

Add Claude Code remote environment setup automation #3421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
callicles wants to merge 4 commits into
base: main
Choose a base branch
from
Open

Add Claude Code remote environment setup automation #3421

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
eb47ad8
add Claude Code remote environment setup for build dependencies
claude Jan 30, 2026
3f92b0d
add version constants and Docker installation to remote setup
claude Jan 30, 2026
3167c4c
add version constants for all installed packages
claude Jan 30, 2026
f57cea2
fix Python installation to handle blocked PPAs gracefully
claude Jan 30, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
15 changes: 15 additions & 0 deletions .claude/settings.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "\"$CLAUDE_PROJECT_DIR\"/scripts/claude-remote-setup.sh"
}
]
}
]
}
}
17 changes: 16 additions & 1 deletion AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,4 +77,19 @@ Multi-language monorepo (Rust CLI + TypeScript/Python libraries) using PNPM work

## Key Technologies

Rust (CLI), TypeScript (libs/web), Python (lib), ClickHouse (OLAP), Redpanda/Kafka (streaming), Temporal (workflows), Redis (state)
Rust (CLI), TypeScript (libs/web), Python (lib), ClickHouse (OLAP), Redpanda/Kafka (streaming), Temporal (workflows), Redis (state)

## Claude Code Remote Environment

When running in Claude Code remote (web) environments, system dependencies are automatically installed via the SessionStart hook in `.claude/settings.json`. The setup script (`scripts/claude-remote-setup.sh`) installs:

- **Docker & Docker Compose**: Required for E2E tests (ClickHouse, Kafka, Temporal containers)
- **protobuf-compiler**: Required for Rust build (prost/tonic protobuf compilation)
- **librdkafka-dev**: Required for `@514labs/kafka-javascript` native module
- **libcurl4-openssl-dev, libsasl2-dev**: Additional Kafka dependencies
- **Python 3.12+**: Required for `moose-cli` pip package in Python E2E tests

**Limitations in Claude Code Remote:**
- **Docker may not be available**: Docker requires privileged container access which may not be supported in all environments
- Run unit tests (`cargo test`, `pnpm test` in ts-moose-lib) and linting in remote environments
- Run full E2E tests (`cd apps/framework-cli-e2e && pnpm test`) in environments with Docker support
Comment on lines +82 to +95
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Add agent architecture/design patterns section

This update doesn’t document agent architecture/design patterns as required; please add a short section or link to the authoritative doc.
As per coding guidelines: Document agent architecture and design patterns in AGENTS.md.

🧰 Tools
🪛 markdownlint-cli2 (0.20.0)

[warning] 95-95: Files should end with a single newline character

(MD047, single-trailing-newline)

🤖 Prompt for AI Agents 
In `@AGENTS.md` around lines 82 - 95, Add a new short section titled "Agent
architecture / design patterns" to AGENTS.md (place it after the "Claude Code
Remote Environment" section) that either summarizes the canonical agent
architecture or links to the authoritative design doc; include one-paragraph
descriptions of the recommended patterns to follow: message-passing vs
shared-memory, controller/worker separation, stateless vs stateful agents and
state persistence, retry/backoff and error-handling conventions, and
observability/metrics/logging practices, plus a link to the primary design
document or RFC for deeper details.

Copy link
Contributor

@coderabbitai coderabbitai bot Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add trailing newline at EOF

Markdownlint MD047 expects a single trailing newline after Line 95.

Proposed fix 
- - Run full E2E tests (`cd apps/framework-cli-e2e && pnpm test`) in environments with Docker support
+ - Run full E2E tests (`cd apps/framework-cli-e2e && pnpm test`) in environments with Docker support
+
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
- Run full E2E tests (`cd apps/framework-cli-e2e && pnpm test`) in environments with Docker support
- Run full E2E tests (`cd apps/framework-cli-e2e && pnpm test`) in environments with Docker support
🧰 Tools
🪛 markdownlint-cli2 (0.20.0)

[warning] 95-95: Files should end with a single newline character

(MD047, single-trailing-newline)

🤖 Prompt for AI Agents 
In `@AGENTS.md` at line 95, Add a single trailing newline at end of AGENTS.md so
the file ends with one newline (fixes Markdownlint MD047); open AGENTS.md and
ensure that after the final line "Run full E2E tests (`cd apps/framework-cli-e2e
&& pnpm test`) in environments with Docker support" there is exactly one newline
character at EOF.

141 changes: 141 additions & 0 deletions scripts/claude-remote-setup.sh
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,141 @@
#!/bin/bash
# Claude Code Remote Environment Setup Script
# This script installs dependencies required for building and developing MooseStack
# in Claude Code remote (web) environments.

set -e

# =============================================================================
# VERSION CONSTANTS
# Update these versions as needed when upgrading dependencies
# =============================================================================
PYTHON_VERSION_REQUIRED="3.12"
DOCKER_VERSION="5:27.5.1-1~ubuntu.24.04~noble"
DOCKER_COMPOSE_VERSION="2.32.4-1~ubuntu.24.04~noble"

# =============================================================================
# ENVIRONMENT CHECK
# =============================================================================

# Only run in remote environments
if [ "$CLAUDE_CODE_REMOTE" != "true" ]; then
echo "Not running in Claude Code remote environment, skipping setup."
exit 0
fi

echo "=========================================="
echo "MooseStack Claude Code Environment Setup"
echo "=========================================="

# Check if we have apt-get available
if ! command -v apt-get &> /dev/null; then
echo "apt-get not found, skipping system package installation"
exit 0
fi
Comment on lines +35 to +39
Copy link
Contributor

@coderabbitai coderabbitai bot Jan 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Guard against non-root execution before apt-get

With set -e, running the hook without root will abort setup; add a privilege check (or sudo path) and skip gracefully when not root.

Proposed fix 
 if ! command -v apt-get &> /dev/null; then
     echo "apt-get not found, skipping system package installation"
     exit 0
 fi
+if [ "$(id -u)" -ne 0 ]; then
+    echo "Insufficient privileges to install packages; skipping setup."
+    exit 0
+fi
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
# Check if we have apt-get available
if ! command -v apt-get &> /dev/null; then
echo "apt-get not found, skipping system package installation"
exit 0
fi
# Check if we have apt-get available
if ! command -v apt-get &> /dev/null; then
echo "apt-get not found, skipping system package installation"
exit 0
fi
if [ "$(id -u)" -ne 0 ]; then
echo "Insufficient privileges to install packages; skipping setup."
exit 0
fi
🤖 Prompt for AI Agents 
In `@scripts/claude-remote-setup.sh` around lines 30 - 34, The apt-get guard
should also check for sufficient privileges before attempting package
installation; update the logic around the existing apt-get check in the script
(scripts/claude-remote-setup.sh) to first verify the script is running as root
(UID 0) and if not, either attempt to use sudo (if sudo is available) for
apt-get commands or skip system package installation and exit 0
gracefully—ensure this privilege check runs before the current "if ! command -v
apt-get" block and that any error paths do not trigger set -e to abort the
entire setup.


echo ""
echo "Installing system dependencies..."
echo "------------------------------------------"

# =============================================================================
# DOCKER INSTALLATION
# =============================================================================
echo "Installing Docker..."

# Install Docker prerequisites
apt-get update -qq
apt-get install -y -qq \
ca-certificates \
curl \
gnupg \
lsb-release

# Add Docker's official GPG key
install -m 0755 -d /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg -o /etc/apt/keyrings/docker.asc
chmod a+r /etc/apt/keyrings/docker.asc

# Add Docker repository
echo \
"deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu \
$(. /etc/os-release && echo "${UBUNTU_CODENAME:-$VERSION_CODENAME}") stable" | \
tee /etc/apt/sources.list.d/docker.list > /dev/null

apt-get update -qq

# Install Docker packages
apt-get install -y -qq \
docker-ce="$DOCKER_VERSION" \
docker-ce-cli="$DOCKER_VERSION" \
containerd.io \
docker-buildx-plugin \
docker-compose-plugin="$DOCKER_COMPOSE_VERSION" || {
echo "Warning: Could not install specific Docker versions, trying latest..."
apt-get install -y -qq \
docker-ce \
docker-ce-cli \
containerd.io \
docker-buildx-plugin \
docker-compose-plugin || echo "Warning: Docker installation failed (may not be supported in this environment)"
}

# Start Docker daemon if possible
service docker start 2>/dev/null || echo "Warning: Could not start Docker daemon (may require privileged container)"

# =============================================================================
# PROTOBUF COMPILER
# =============================================================================
echo "Installing protobuf-compiler..."
apt-get install -y -qq protobuf-compiler

# =============================================================================
# KAFKA/LIBRDKAFKA DEPENDENCIES
# =============================================================================
echo "Installing Kafka native library dependencies..."
apt-get install -y -qq \
librdkafka-dev \
libcurl4-openssl-dev \
libsasl2-dev

# =============================================================================
# PYTHON 3.12+
# =============================================================================
CURRENT_PYTHON_VERSION=$(python3 --version 2>/dev/null | grep -oP '\d+\.\d+' | head -1)

if [ "$(printf '%s\n' "$PYTHON_VERSION_REQUIRED" "$CURRENT_PYTHON_VERSION" | sort -V | head -n1)" != "$PYTHON_VERSION_REQUIRED" ]; then
echo "Installing Python $PYTHON_VERSION_REQUIRED..."
apt-get install -y -qq software-properties-common
add-apt-repository -y ppa:deadsnakes/ppa
apt-get update -qq
apt-get install -y -qq \
python${PYTHON_VERSION_REQUIRED} \
python${PYTHON_VERSION_REQUIRED}-venv \
python${PYTHON_VERSION_REQUIRED}-dev

# Set up alternatives to use Python 3.12 by default
update-alternatives --install /usr/bin/python3 python3 /usr/bin/python${PYTHON_VERSION_REQUIRED} 1 2>/dev/null || true
fi

# =============================================================================
# SUMMARY
# =============================================================================
echo ""
echo "=========================================="
echo "System dependencies installed successfully"
echo "=========================================="
echo ""
echo "Installed packages:"
echo " - Docker: $(docker --version 2>/dev/null || echo 'not available')"
echo " - Docker Compose: $(docker compose version 2>/dev/null || echo 'not available')"
echo " - protobuf-compiler (protoc): $(protoc --version 2>/dev/null || echo 'installed')"
echo " - librdkafka-dev"
echo " - libcurl4-openssl-dev"
echo " - libsasl2-dev"
echo " - Python: $(python3 --version 2>/dev/null || echo 'not verified')"
echo ""
echo "To install Node.js dependencies: pnpm install"
echo "To build Rust CLI: cargo build"
echo "To run E2E tests: cd apps/framework-cli-e2e && pnpm test"
echo ""

exit 0
Loading