Setup & Teardown Scripts

Overview

Setup scripts run automatically when creating new worktrees or containers. Use them to:

• Install dependencies (npm install, bundle install)
• Copy environment files (.env, .envrc)
• Run database migrations
• Configure project-specific settings

Worktree Setup Script

Location

Create a setup script in your repository:

.agentastic/setup.sh

Make it executable:

chmod +x .agentastic/setup.sh

Basic Example

#!/bin/bash
set -euo pipefail

echo "Setting up worktree: $AGENTASTIC_BRANCH"

# Install dependencies
npm install

# Copy environment file
if [ -f "$AGENTASTIC_MAIN_REPO_PATH/.env" ]; then
  cp "$AGENTASTIC_MAIN_REPO_PATH/.env" "$AGENTASTIC_WORKTREE_PATH/.env"
  echo "Copied .env file"
fi

echo "Setup complete!"

Environment Variables

Your script receives these variables:

Variable	Description	Example
AGENTASTIC_BRANCH	New branch name	feature-auth
AGENTASTIC_BASE_BRANCH	Base branch (if specified)	main
AGENTASTIC_WORKTREE_PATH	Path to new worktree	/Users/dev/repo-worktrees/feature-auth
AGENTASTIC_MAIN_REPO_PATH	Path to main repository	/Users/dev/repo
AGENTASTIC_COMMIT	Commit SHA	abc123def456...
AGENTASTIC_REPO_NAME	Repository folder name	my-project

Advanced Example

#!/bin/bash
set -euo pipefail

echo "=== Agentastic Worktree Setup ==="
echo "Branch: $AGENTASTIC_BRANCH"
echo "Path: $AGENTASTIC_WORKTREE_PATH"

# Function to copy env files
copy_env_files() {
  local source="$1"
  local dest="$2"

  find "$source" -name '.env*' -type f | while read -r file; do
    relative="${file#$source/}"
    target="$dest/$relative"
    mkdir -p "$(dirname "$target")"
    cp "$file" "$target"
    echo "Copied: $relative"
  done
}

# Copy all .env files from main repo
copy_env_files "$AGENTASTIC_MAIN_REPO_PATH" "$AGENTASTIC_WORKTREE_PATH"

# Detect package manager and install
if [ -f "package-lock.json" ]; then
  echo "Installing with npm..."
  npm ci
elif [ -f "yarn.lock" ]; then
  echo "Installing with yarn..."
  yarn install --frozen-lockfile
elif [ -f "pnpm-lock.yaml" ]; then
  echo "Installing with pnpm..."
  pnpm install --frozen-lockfile
fi

# Ruby/Rails
if [ -f "Gemfile" ]; then
  echo "Installing Ruby gems..."
  bundle install
fi

# Python
if [ -f "requirements.txt" ]; then
  echo "Setting up Python environment..."
  python -m venv .venv
  .venv/bin/pip install -r requirements.txt
fi

# Run database setup if Rails
if [ -f "bin/rails" ]; then
  echo "Setting up database..."
  bin/rails db:setup || bin/rails db:migrate
fi

echo "=== Setup complete ==="

Behavior

• Script runs from the new worktree directory
• Script execution is non-blocking - worktree creation succeeds even if script fails
• Output appears in the "Worktree Setup" task panel
• You can re-run the setup script from the task panel

Container Setup Script

Container setup scripts run on your host machine before the container is created. They output JSON configuration.

Location

~/.config/agentastic/container-setup.sh

How It Works

1. Agentastic runs your script with environment variables
2. Script outputs JSON to stdout
3. Agentastic parses JSON to configure the container

Output Format

{
  "mounts": [
    {"host": "/path/on/host", "container": "/path/in/container", "readonly": true}
  ],
  "env": {
    "ANTHROPIC_API_KEY": "sk-...",
    "CUSTOM_VAR": "value"
  },
  "network": "bridge",
  "workdir": "/workspace",
  "shell": "/bin/bash"
}

Default Script

Agentastic creates a default script if none exists. To customize:

open ~/.config/agentastic/container-setup.sh

Example Customization

Add a shared npm cache:

#!/bin/bash

# ... (default script content) ...

# Add custom mount for npm cache
MOUNTS+='{"host": "'"$HOME"'/.npm", "container": "/root/.npm", "readonly": false},'

# Add custom environment variable
ENV+='  "MY_CUSTOM_VAR": "my-value",'

# ... (rest of default script) ...

Environment Variables

Variable	Description
AGENTASTIC_WORKTREE_PATH	Path to the worktree
AGENTASTIC_REPO_NAME	Repository name
AGENTASTIC_BRANCH	Branch name
AGENTASTIC_MOUNT_SSH_KEYS	true or false
AGENTASTIC_MOUNT_GIT_CONFIG	true or false
AGENTASTIC_COPY_SHELL_CONFIG	true or false
AGENTASTIC_NETWORK_MODE	bridge, restricted, or none

Resetting

If your script has issues:

1. Open Settings > Agents
2. Click Reset Setup Script

Teardown Scripts

Currently, Agentastic doesn't run teardown scripts automatically. To clean up:

1. Stop any running processes in the worktree
2. Remove the worktree via Settings > Agents or git worktree remove
3. For containers, the container is stopped and removed automatically

Best Practices

Keep Scripts Idempotent

Scripts should be safe to run multiple times:

# Good: only copy if missing
[ -f .env ] || cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env

# Avoid: always overwrites
cp "$AGENTASTIC_MAIN_REPO_PATH/.env" .env

Handle Errors Gracefully

set -euo pipefail  # Exit on errors

# Or handle specific failures
npm install || echo "npm install failed, continuing..."

Log Progress

echo "Step 1: Installing dependencies..."
npm install
echo "Step 2: Copying environment files..."
# ...

Test Manually

Run your script manually to debug:

AGENTASTIC_BRANCH=test \
AGENTASTIC_WORKTREE_PATH=/tmp/test \
AGENTASTIC_MAIN_REPO_PATH=/path/to/repo \
.agentastic/setup.sh

Troubleshooting

Script Not Running

1. Check script exists at .agentastic/setup.sh
2. Verify it's executable: chmod +x .agentastic/setup.sh
3. Check for syntax errors: bash -n .agentastic/setup.sh

Script Fails Silently

Add debugging:

set -x  # Print each command
set -e  # Exit on error

Environment Variables Missing

Print them to verify:

echo "AGENTASTIC_BRANCH: $AGENTASTIC_BRANCH"
echo "AGENTASTIC_WORKTREE_PATH: $AGENTASTIC_WORKTREE_PATH"

Container Setup Invalid JSON

Test your script:

~/.config/agentastic/container-setup.sh | jq .

If jq reports an error, fix the JSON syntax in your script.