Tasks

Overview

Tasks let you define reusable commands for your workspace - build scripts, test runners, development servers, and more. Run them from the toolbar or with keyboard shortcuts.

Creating Tasks

From Settings

1. Open Settings (Cmd+,)
2. Navigate to your workspace settings
3. Click Add Task
4. Configure:
   • Name: Display name for the task
   • Command: Shell command to execute
   • Working Directory: Where to run (leave empty for agent root)
   • Environment Variables: Additional env vars for the task

From Agent Setup

When you create an agent with a setup script, Agentastic automatically creates an "Agent Setup" task that you can re-run anytime.

Running Tasks

From Toolbar

1. Select a task from the task dropdown in the toolbar
2. Click Run or press Cmd+R

Keyboard Shortcuts

Action	Shortcut
Run Selected Task	Cmd+R
Stop Task	Cmd+.

Task Status

Tasks show their current status with color-coded indicators:

Status	Color	Description
Not Running	Gray	Task is idle
Running	Orange	Task is executing
Finished	Green	Task completed successfully (exit code 0)
Failed	Red	Task exited with error (non-zero exit code)
Stopped	Yellow	Task was manually stopped

Task Output

Each task runs in its own terminal view:

• Output appears in real-time
• Scrollback is preserved
• Exit status is shown when complete
• Can be scrolled and copied like any terminal

Environment Variables

Add custom environment variables to your tasks:

{
  "name": "Development Server",
  "command": "npm run dev",
  "environmentVariables": {
    "NODE_ENV": "development",
    "PORT": "3000"
  }
}

Tasks also inherit environment variables from:

• Your shell profile
• The terminal environment
• Agent setup scripts

Working Directory

By default, tasks run in the current agent's root directory.

Specify a custom working directory for tasks that need to run in a subdirectory:

{
  "name": "Frontend Dev",
  "command": "npm run dev",
  "workingDirectory": "frontend"
}

Leave empty to use the agent root (recommended for most tasks).

Process Control

Control running tasks from the toolbar or with shortcuts:

Action	Description
Stop	Sends SIGTERM to gracefully stop the task
Interrupt	Sends SIGINT (like Ctrl+C)

Common Tasks

Development Server

{
  "name": "Dev Server",
  "command": "npm run dev"
}

Run Tests

{
  "name": "Test",
  "command": "npm test"
}

Build

{
  "name": "Build",
  "command": "npm run build"
}

Lint

{
  "name": "Lint",
  "command": "npm run lint"
}

Database

{
  "name": "DB Migrate",
  "command": "rails db:migrate"
}

Agent Setup Task

When you configure a setup script at .agentastic/setup.sh, Agentastic creates a special "Agent Setup" task:

• Runs automatically when creating new agents
• Available for manual re-runs (e.g., after pulling changes)
• Receives agent environment variables

See Git Worktrees for setup script details.

Storage

Tasks are stored in your workspace settings at .agentastic/settings.json:

{
  "tasks": [
    {
      "name": "Dev Server",
      "command": "npm run dev",
      "target": "My Mac",
      "workingDirectory": "",
      "environmentVariables": {}
    }
  ]
}

This file can be committed to share tasks with your team.

Tips

• Keep tasks simple - One command per task is easier to debug
• Use descriptive names - "Build Production" vs just "Build"
• Share with team - Commit .agentastic/settings.json to your repo
• Re-run setup - Use the Agent Setup task after pulling changes that affect dependencies