> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blocks.team/llms.txt
> Use this file to discover all available pages before exploring further.

# Post-Clone Scripts

> Run setup scripts automatically after Blocks clones your repository

## 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

1. Create a `.blocks` directory in your repository root
2. Add a file named `post-clone` or `post-clone.sh`
3. Make it executable: `chmod +x .blocks/post-clone`

```bash theme={null}
#!/bin/bash
set -e

# Install dependencies
npm ci

# Install Python packages
pip install -r requirements.txt

echo "Post-clone setup complete!"
```

The script runs with root privileges, so you can install system packages via `apt-get`.

<Note>
  Always start with `set -e`. Without it, the agent continues even if setup fails, which leads to confusing errors mid-task.
</Note>

## Common use cases

<Tabs>
  <Tab title="Install dependencies">
    ```bash theme={null}
    #!/bin/bash
    set -e

    npm ci
    pip install -r requirements.txt
    go mod download
    ```
  </Tab>

  <Tab title="Install a runtime">
    ```bash theme={null}
    #!/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
    ```
  </Tab>

  <Tab title="Install a custom binary">
    ```bash theme={null}
    #!/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
    ```
  </Tab>

  <Tab title="Install system packages">
    ```bash theme={null}
    #!/bin/bash
    set -e

    apt-get update && apt-get install -y \
      python3-dev \
      libpq-dev \
      mysql-client

    pip install -r requirements.txt
    ```
  </Tab>
</Tabs>

## Best practices

**Check before installing** — make scripts idempotent so they run cleanly every session:

```bash theme={null}
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
```

**Use lock files** — prefer `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

<Warning>
  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.
</Warning>

For a full list of tools pre-installed in the sandbox, see [Environment](/using-blocks/sandbox/environment).