DocsAutomation

Tasks

Run repository commands, reusable custom Actions, and built-in agent workflows

Overview#

The Tasks picker combines three sources:

Repository shell tasks from .agentastic/settings.json, such as build scripts, test runners, and development servers.
Custom Actions created in Settings > Tasks. These are stored globally and appear in every existing or new repository and worktree.
Agentastic's interactive built-in Actions, including source-control, review, CI, and pull-request workflows.

Agent Actions render a configurable prompt and route it to an agent. Configure their prompt, model, and execution target in Settings > Tasks. Interactive built-in Actions use the Primary Agent, with Utility Chat as the fallback when no eligible live agent is available. See Actions for the complete built-in catalog and placeholder reference.

Every interactive built-in Action appears in Tasks. Worktree Display Name and Inline Commit Message do not appear because they run automatically and return structured results directly to the feature that requested them. Their Run In setting can use the selected agent's preferred interface in a hidden session that closes after a valid result (Headless), or explicitly use and retain the visible Chat interface (Utility Chat). Failed headless sessions remain available for inspection.

Creating tasks#

Repository shell task#

Open Settings (Cmd+,)
Navigate to your workspace settings
Click Add Task
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

Repository shell tasks belong to that repository and can be committed for your team.

Global custom Action#

Open Settings > Tasks
Click Add Task
Enter a name and prompt, then choose its tier, model, and Run In target
Click Add

The Action immediately appears in the Tasks picker for every repository and worktree. Use its ellipsis menu in Tasks settings to edit, duplicate, or delete it.

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#

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

Keyboard Shortcuts#

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

Agent Actions must be selected explicitly. Agentastic does not replace your selected repository shell task with an Action when you press Cmd+R.

Choosing an Action surface#

The Run In setting controls where an interactive Agent Action runs:

Run In	Result
Primary Agent	Continues the canonical live agent for the exact target worktree. A user-designated Primary Agent is tried first. If no eligible live agent in that worktree can accept the prompt, the Action starts a Utility Chat using its configured model or tier default.
Editor Terminal	Creates a separate agent in a new editor terminal.
Utility Chat	Creates a separate terminal-backed agent chat in the Utility Area. This is the default for new custom Actions.
Sidebar Chat	Creates a separate terminal-backed agent chat in the Agent sidebar.
Utility Terminal	Creates a separate agent in the Utility Area terminal. The target worktree must be active.

Primary Agent routing never sends an Action to a bare shell, a different worktree, or a different workspace. An existing Primary Agent keeps its current provider and model. New-agent destinations—and the Utility Chat fallback—use the Action's configured model or its Fast or Thorough tier default.

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 repository shell 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

Agent Actions do not create a shell-task output pane. Their feedback appears in the selected destination: the existing Primary Agent, a new editor terminal, Utility Chat, Sidebar Chat, or the Utility Terminal.

Environment Variables#

Add custom environment variables to your tasks:

json

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

json

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

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

Remote workspaces#

Interactive Agent Actions can use all five destinations for a connected remote worktree. Agentastic keeps the prompt scoped to that worktree and uses its remote terminal or agent-chat connection. The selected agent provider's command must be installed and usable on the remote host.

Activate a remote worktree before running an Action in Utility Terminal, because the Utility Area belongs to the active worktree. Primary Agent remains scoped to that exact remote worktree and falls back to its Utility Chat when no eligible live agent is available.

Repository shell tasks are currently local-workspace only. Remote workspaces do not load shell tasks from .agentastic/settings.json or run those commands through the remote server.

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#

json

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

Run Tests#

json

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

Build#

json

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

Lint#

json

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

Database#

json

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

Repository shell tasks are stored in .agentastic/settings.json:

json

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

This file can be committed to share shell tasks with your team. Custom Actions are stored in your global Agentastic settings instead, so they are available in all repositories and are not added to .agentastic/settings.json. Built-in Actions are supplied by the app and are not persisted as repository tasks.

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

Tasks

Overview#

Creating tasks#

Repository shell task#

Global custom Action#

From Agent Setup#

Running Tasks#

From Toolbar#

Keyboard Shortcuts#

Choosing an Action surface#

Task Status#

Task Output#

Environment Variables#

Working Directory#

Remote workspaces#

Process Control#

Common Tasks#

Development Server#

Run Tests#

Build#

Lint#

Database#

Agent Setup Task#

Storage#

Tips#