Overview
Post-clone scripts run automatically after Blocks clones your repository into the sandbox, before the coding agent starts working. Use them to install dependencies, set up tooling, or run any initialization commands your project needs.
Creating a post-clone script
- Create a
.blocks directory in your repository root
- Add a file named
post-clone or post-clone.sh
- Make it executable:
chmod +x .blocks/post-clone
#!/bin/bash
set -e
# Install dependencies
npm ci
# Install Python packages
pip install -r requirements.txt
echo "Post-clone setup complete!"
apt-get.
Always start with set -e. Without it, the agent continues even if setup fails, which leads to confusing errors mid-task.
Common use cases
Install dependencies
Install a runtime
Install a custom binary
Install system packages
#!/bin/bash
set -e
npm ci
pip install -r requirements.txt
go mod download
#!/bin/bash
set -e
# Install Go
GO_VERSION=1.21.0
curl -L https://go.dev/dl/go${GO_VERSION}.linux-amd64.tar.gz | tar -xz -C /usr/local
export PATH=$PATH:/usr/local/go/bin
echo 'export PATH=$PATH:/usr/local/go/bin' >> ~/.bashrc
go mod download
#!/bin/bash
set -e
curl -L https://example.com/tool.tar.gz -o /tmp/tool.tar.gz
tar -xzf /tmp/tool.tar.gz -C /usr/local/bin
chmod +x /usr/local/bin/tool
tool --version
#!/bin/bash
set -e
apt-get update && apt-get install -y \
python3-dev \
libpq-dev \
mysql-client
pip install -r requirements.txt
Best practices
Check before installing — make scripts idempotent so they run cleanly every session:
if ! command -v mytool &> /dev/null; then
curl -L https://example.com/mytool -o /usr/local/bin/mytool
chmod +x /usr/local/bin/mytool
fi
npm ci over npm install for faster, reproducible installs.
Add PATH exports to ~/.bashrc — binaries installed to custom paths need to be on PATH for the agent to find them.
Log progress — echo statements make it easy to spot where a script stalls.
Limitations
Each Blocks session runs in a fresh sandbox. Packages installed by a post-clone script are not persisted — the script runs every time a new session starts on that repository.
