Workspaces & Tasks

Workspaces group related work. Tasks are individual units of work within a workspace. Together they give you structured, trackable agent workflows — from a simple to-do list to a full dependency graph.

Workspaces

A workspace is a container for tasks. It defines defaults that all its tasks inherit:

• Default environment — Where tasks run unless overridden
• Default persona — Which agent configuration to use
• Repository URL — The git repo agents work on
• Worktree isolation — Whether each task gets its own git branch (enabled by default)

grackle workspace create "Auth Rewrite" \
  --env my-docker \
  --repo https://github.com/org/repo \
  --desc "Migrate from session tokens to JWT"

Tasks

A task represents a single piece of work. When you start a task, Grackle spawns an agent session with the task's title as the prompt and its description as context.

grackle task create "Implement JWT middleware" \
  --workspace auth-rewrite \
  --desc "Replace the existing session-based auth with JWT tokens. Use RS256 signing."

Task status

Tasks move through a lifecycle:

Status	Meaning
not_started	Created but not yet started
working	An agent session is actively running
paused	Work is paused (session interrupted or idle)
complete	Marked complete (ready for review or done)
failed	Agent session failed

Starting a task

grackle task start <task-id>

This spawns an agent session in the workspace's default environment (or a specified one). The agent receives:

• The task title as its prompt
• The task description as system context
• Recent findings from the workspace (so it knows what other agents discovered)

You can also specify a persona and pass notes (useful for retries):

grackle task start <task-id> --persona senior-reviewer --notes "Focus on error handling this time"

Review and approval

When a task completes, you can review the agent's work and mark it done:

grackle task complete <task-id>

If the work isn't right, set it back to failed with notes and start it again — the agent gets the feedback in its next attempt.

Task hierarchy

Tasks can have children. This lets you decompose complex work:

Implement Auth (root)
├── Design token schema
├── Implement middleware
│   ├── Write JWT validator
│   └── Add refresh token logic
└── Write integration tests

Child tasks are created with the --parent and --can-decompose flags:

grackle task create "Write JWT validator" --workspace auth-rewrite --parent <parent-task-id>

# Allow a task to create its own subtasks (e.g., for orchestrator patterns)
grackle task create "Implement auth" --workspace auth-rewrite --can-decompose

Tasks can be nested up to 8 levels deep. Use --can-decompose to allow a task to create children — this is off by default to prevent runaway nesting. The web UI and MCP tools also support setting this flag.

Task dependencies

Tasks can depend on other tasks. A blocked task cannot start until all its dependencies are complete.

grackle task create "Write integration tests" \
  --workspace auth-rewrite \
  --depends-on <middleware-task-id>

When a dependency completes, Grackle automatically unblocks any tasks that were waiting on it.

The web UI shows these dependencies as a DAG (directed acyclic graph) in the workspace's Graph tab, and as a kanban board in the Board tab.

Branch isolation

When worktrees are enabled (the default), each task gets its own git branch:

workspace-slug/task-slug          # root task
workspace-slug/task-slug/subtask  # child task

Agents work in isolated git worktrees, so multiple agents can work on the same repo simultaneously without conflicting. Each agent sees its own branch with its own working tree.

The working directory defaults to the repo root, but you can customize it per-workspace:

grackle workspace create "My Workspace" --env my-docker --working-directory /workspaces/my-repo

Importing from GitHub

You can bulk-import GitHub issues as tasks using the standalone import-github-issues script in scripts/github-import/. See that package's README for usage.