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

# Setup scripts

# Setup scripts

Cyrus supports automated repository initialization through setup scripts that run when creating new Git worktrees for Linear issues. This powerful feature allows you to prepare the development environment automatically for each task.

## Overview

When Cyrus processes a Linear issue, it:

1. Creates a new Git worktree for isolation
2. Runs setup scripts to prepare the environment
3. Processes the issue in the prepared worktree
4. Cleans up the worktree after completion

Setup scripts ensure each worktree starts with the correct dependencies, configuration, and environment.

## Repository setup script

### Creating a repository script

Place a `cyrus-setup.sh` script in your repository root:

```bash theme={null}
#!/bin/bash
# cyrus-setup.sh - Repository initialization script

# Install dependencies
npm install

# Copy environment files
cp .env.example .env

# Build the project
npm run build

# Any other repository-specific setup
echo "Repository setup complete for issue: $LINEAR_ISSUE_IDENTIFIER"
```

Make the script executable:

```bash theme={null}
chmod +x cyrus-setup.sh
```

### Available environment variables

Cyrus provides these environment variables to your script:

* **`LINEAR_ISSUE_ID`**: The Linear issue ID (UUID format)
* **`LINEAR_ISSUE_IDENTIFIER`**: The issue identifier (e.g., "CEA-123")
* **`LINEAR_ISSUE_TITLE`**: The issue title

**Example Usage:**

```bash theme={null}
#!/bin/bash

echo "Setting up environment for: $LINEAR_ISSUE_IDENTIFIER"
echo "Title: $LINEAR_ISSUE_TITLE"

# Create issue-specific log directory
mkdir -p logs/$LINEAR_ISSUE_IDENTIFIER

# Install dependencies
npm install

# Setup database with issue identifier
createdb "test_db_${LINEAR_ISSUE_IDENTIFIER}"
```

### When to use repository scripts

**Common Use Cases:**

* **Dependency Installation**: `npm install`, `pip install -r requirements.txt`
* **Environment Configuration**: Copy `.env` files, set up credentials
* **Database Setup**: Create test databases, run migrations
* **Build Steps**: Compile code, generate assets
* **Service Startup**: Start local services needed for development

**Example: Node.js Project**

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

echo "Setting up Node.js project for $LINEAR_ISSUE_IDENTIFIER"

# Install dependencies
npm install

# Copy environment configuration
if [ ! -f .env ]; then
    cp .env.example .env
    echo "Created .env from .env.example"
fi

# Run database migrations
npm run db:migrate

# Build the project
npm run build

echo "Setup complete!"
```

**Example: Monorepo**

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

echo "Setting up monorepo for $LINEAR_ISSUE_IDENTIFIER"

# Install root dependencies
npm install

# Build all packages
npm run build --workspaces

# Copy shared configuration
cp config/shared/.env.example config/shared/.env

# Setup test databases
./scripts/setup-test-db.sh

echo "Monorepo setup complete!"
```

### Script best practices

#### Exit on error

Always use `set -e` to exit immediately if any command fails:

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

#### Keep scripts fast

Setup scripts delay issue processing. Keep them fast:

* Cache dependencies when possible
* Skip unnecessary steps
* Use parallel installation when available

```bash theme={null}
# Fast npm install with frozen lockfile
npm ci --prefer-offline
```

### Timeout and error handling

* **Timeout**: Scripts have a 5-minute timeout
* **Failure Behavior**: Script failures don't prevent worktree creation
* **Logs**: Script output appears in Cyrus logs for debugging

### Testing your script

Test the script locally before relying on it:

```bash theme={null}
# Set test environment variables
export LINEAR_ISSUE_ID="test-id"
export LINEAR_ISSUE_IDENTIFIER="TEST-123"
export LINEAR_ISSUE_TITLE="Test Issue"

# Run the script
./cyrus-setup.sh
```

## Advanced patterns

### Conditional setup based on issue

Run different setup based on issue labels or title:

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

echo "Setup for: $LINEAR_ISSUE_IDENTIFIER"

# Check if this is a database issue
if [[ "$LINEAR_ISSUE_TITLE" == *"database"* ]]; then
    echo "Database issue detected, setting up test DB"
    ./scripts/setup-test-database.sh
fi

# Standard setup for all issues
npm install
npm run build
```

### Caching dependencies

Speed up setup by caching dependencies:

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

CACHE_DIR="$HOME/.cyrus/cache/$(basename $(pwd))"

# Create cache directory if it doesn't exist
mkdir -p "$CACHE_DIR"

# Link node_modules from cache if available
if [ -d "$CACHE_DIR/node_modules" ]; then
    echo "Using cached node_modules"
    ln -s "$CACHE_DIR/node_modules" node_modules
else
    echo "Installing dependencies (will be cached)"
    npm install
    # Copy to cache
    cp -r node_modules "$CACHE_DIR/"
fi
```

### Parallel setup

Run independent setup tasks in parallel:

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

echo "Running parallel setup tasks..."

# Start parallel tasks
npm install &
PID1=$!

./scripts/setup-database.sh &
PID2=$!

./scripts/download-assets.sh &
PID3=$!

# Wait for all tasks to complete
wait $PID1
echo "Dependencies installed"

wait $PID2
echo "Database setup complete"

wait $PID3
echo "Assets downloaded"

echo "All setup tasks complete!"
```

### Issue-specific configuration

Create configuration specific to each issue:

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

# Create issue-specific environment
cat > .env.local << EOF
ISSUE_ID=$LINEAR_ISSUE_ID
ISSUE_IDENTIFIER=$LINEAR_ISSUE_IDENTIFIER
LOG_PREFIX=[$LINEAR_ISSUE_IDENTIFIER]
TEST_DB_NAME=cyrus_test_${LINEAR_ISSUE_IDENTIFIER}
EOF

echo "Created issue-specific configuration"
```

## Troubleshooting

### Script not running

**Check:**

1. Script exists at repository root
2. Script is named exactly `cyrus-setup.sh`
3. Script has execute permissions (`chmod +x cyrus-setup.sh`)
4. Script has correct shebang (`#!/bin/bash`)

### Script failing

**Debug Steps:**

1. Test script locally with test environment variables
2. Check Cyrus logs for script output and errors
3. Add echo statements to identify where script fails
4. Verify all dependencies and commands are available

**Common Issues:**

* Missing dependencies (e.g., `npm` not in PATH)
* Permission errors (e.g., can't write to directories)
* Timeout (script takes longer than 5 minutes)

### Script timeout

If scripts consistently timeout:

1. **Optimize dependency installation**:
   ```bash theme={null}
   # Use npm ci instead of npm install (faster)
   npm ci --prefer-offline
   ```

2. **Skip unnecessary steps**:
   ```bash theme={null}
   # Skip build if not needed for testing
   # npm run build
   ```

3. **Cache dependencies**:
   See caching pattern above

### Script works locally but fails in Cyrus

Check that:

* All paths are relative or use environment variables
* All required tools are installed in the Cyrus environment
* No interactive prompts (scripts must run non-interactively)

***

Next: [Remote Hosting](remote-hosting.md)