DocsAgent Workflows

Setup & Teardown Scripts

Automate worktree and container initialization

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:

code

.agentastic/setup.sh

Make it executable:

bash

chmod +x .agentastic/setup.sh

Basic Example#

bash

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

bash

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

code

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

How It Works#

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

Output Format#

json

{
  "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:

bash

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

Example Customization#

Add a shared npm cache:

bash

#!/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:

Open Settings > Agents
Click Reset Setup Script

Teardown Scripts#

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

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

Best Practices#

Keep Scripts Idempotent#

Scripts should be safe to run multiple times:

bash

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

bash

set -euo pipefail  # Exit on errors

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

Log Progress#

bash

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

Test Manually#

Run your script manually to debug:

bash

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

Troubleshooting#

Script Not Running#

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

Script Fails Silently#

Add debugging:

bash

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

Environment Variables Missing#

Print them to verify:

bash

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

Container Setup Invalid JSON#

Test your script:

bash

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

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