Agent Task Manager VS Code Extension

The Agent Task Manager is a VS Code extension that exposes a set of tools to AI agents. These tools allow the agent to track, create, read, and update tasks within the workspace. Tasks are persistently stored in a dedicated Markdown file, making them seamlessly parseable for the extension and perfectly human-readable for the developer.

By providing a reliable shared source of truth, it is perfect for:

• Orchestrating complex multi-step workflows
• Coordinating between multiple agents
• Breaking down large feature requests into actionable steps

Prompt Instructions

The prompt includes the necessary tool references and operational guidelines for the agent to use the task manager. To use the prompt instructions, reference the /AgentTask in your chat prompt.

Automating Workflows with Chat Participant

The extension contributes a powerful, natural-language-driven chat participant, @AgentTask, which allows you to seamlessly query tasks and dispatch them to specific sub-agents.

Syntax: @AgentTask [natural language request]

Example Usage: @AgentTask find all pending tasks with the "frontend" tag and have the Explore agent review them for security vulnerabilities

Fully Automated Routing: If you invoke @AgentTask without any additional prompt, it will automatically fetch all tasks and dynamically route them to the appropriate agents based entirely on the conditions defined in your Routing Table. This enables a completely hands-off, automated pipeline.

When invoked with a prompt, the extension uses a Language Model to parse your intent into specific filters (task name, status, tags, and message query) and automatically dispatches the matched tasks concurrently to the specified target agent (or dynamically routes them based on the Routing Table). Tasks are sorted by priority to ensure higher priority tasks are processed first. It respects the concurrency and retry limits configured in your settings.

Data Model

Each task represents an actionable item or status associated with a specific task.

Task Struct:

• taskName (string): The name of the task (acts as the primary identifier).
• status (string): The current state of the task (dynamically populated from existing tasks).
• message (string): Context, error logs, or notes about the task.
• tags (string): A list of categories or labels associated with the task.
• priority (number, optional): The priority of the task. Lower numbers indicate higher priority. Defaults to the highest priority (null) if not set. A low priority task cannot be started if there is a higher priority task with the same initial status.

Storage Mechanism

Tasks and routing rules are stored in a Markdown file at the root of the workspace (default: AGENT_TASKS.md). The extension reads from and writes to this file to persist the task state and execution flow.

Markdown Format Example: The file contains two tables: a Routing Table at the top (to define which status and/or tags condition goes to which agent), and the Tasks Table below it.

# Agent Tasks

## Routing Table
| Status | Tags Condition | Agent |
|--------|----------------|-------|
| planning | | plan |
| coding | frontend or backend | coder |
| testing | | terminal |

## Tasks Table
| Task Name | Priority | Status | Tags | Message |
|-----------|----------|--------|------|---------|
| `src/main.ts` | 1 | pending | `core, startup` | Task initialized |
| `src/utils.ts` | | in-progress | `utils, refactor` | Refactoring regex |

Available Agent Tools

The extension exposes the following tools via the VS Code Language Model API (vscode.lm.registerTool).

loadFileNameAsTask

Scans the workspace for files matching a provided regular expression and initializes a new task for each matched file.

• Parameters:
  • regex (string): The regular expression used to match file paths within the workspace.
  • initialStatus (string, optional): The default status for newly created tasks (defaults to "pending").
  • tags (string, optional): Default tags to assign to the initialized tasks.
  • priority (number, optional): Default priority to assign. Defaults to highest priority (null).
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Scans the workspace for files matching regex.
  2. For each matched file, generates a Task struct.
  3. Parses the existing AGENT_TASKS.md (creating it if it doesn't exist).
  4. Appends the new tasks to the Markdown table, skipping duplicates.
• Returns: A summary message of how many tasks were successfully created and how many duplicates were ignored.

createTasks

Creates one or more new tasks explicitly.

• Parameters:
  • tasks (array of objects): An array of tasks to create, where each object contains:
    • taskName (string): The name of the task to create (required).
    • status (string, optional): The initial status (defaults to "pending").
    • message (string, optional): Initial message or notes.
    • tags (string, optional): Initial tags to assign.
    • priority (number, optional): Initial priority. Defaults to highest priority (null).
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Parses the existing AGENT_TASKS.md (creating it if it doesn't exist).
  2. Iterates over the provided tasks array, skipping any taskName that already exists.
  3. Generates a Task struct for each new task and appends it to the Markdown table.
• Returns: A success message summarizing the created tasks and how many duplicates were ignored.

getTasks

Retrieves a list of tasks or a single task based on specific filters like status or tags. It can optionally update the status of the retrieved tasks transactionally.

• Parameters:
  • status (string, optional): Filter tasks by their exact status (e.g., "pending").
  • tags (string, optional): Filter tasks using a boolean expression string (e.g. "bug and (frontend or not backend)").
  • taskName (string, optional): Retrieve a specific task by its exact task name.
  • newStatus (string, optional): A new status to apply transactionally to the retrieved tasks (e.g., "in-progress").
  • limit (number, optional): The maximum number of tasks to retrieve (defaults to 1).
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Reads and parses the Markdown table from AGENT_TASKS.md.
  2. Filters the parsed tasks matching the provided criteria.
  3. Sorts the matched tasks by priority (highest priority / lowest number first).
  4. Truncates the matched tasks array to the specified limit (or 1 by default).
  5. If newStatus is provided (e.g., transitioning to "in-progress"), validates that no higher priority tasks are available in the current status before updating the status of the matched tasks, then writes back to AGENT_TASKS.md in the same atomic operation.
• Returns: An array of Task structs matching the criteria.

updateTask

Updates a single existing task's status, message, and/or tags. Returns an error if the filters match more than one task.

• Parameters:
  • taskName (string): The identifier or regular expression pattern of the task to update (required).
  • status (string, optional): The new status to apply.
  • message (string, optional): The new message or note.
  • tags (string, optional): The new list of tags (overwrites existing).
  • priority (number, optional): The new priority level.
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Parses the Markdown table from AGENT_TASKS.md.
  2. Locates the row matching the taskName.
  3. If more than one task matches the criteria, returns an error.
  4. If updating status to an active state (like "in-progress"), verifies no higher priority tasks are currently pending; if there are, returns an error preventing the update.
  5. Updates the specified fields without altering the unmentioned ones.
  6. Serializes the data back into a Markdown table and writes it to AGENT_TASKS.md.
• Returns: The updated Task struct.

bulkUpdateTasks

Updates multiple existing tasks' status, message, and/or tags.

• Parameters:
  • taskName (string): The identifier or regular expression pattern of the tasks to update (required).
  • currentStatus (string, optional): Filter tasks to update by their exact current status (e.g., "pending").
  • status (string, optional): The new status to apply.
  • message (string, optional): The new message or note.
  • tags (string, optional): The new list of tags (overwrites existing).
  • priority (number, optional): The new priority level.
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Parses the Markdown table from AGENT_TASKS.md.
  2. Locates all rows matching the taskName and, if provided, the currentStatus.
  3. Updates the specified fields without altering the unmentioned ones for all matched tasks.
  4. Serializes the data back into a Markdown table and writes it to AGENT_TASKS.md.
• Returns: An array of the updated Task structs.

searchTasks

Searches for tasks matching various criteria using regular expressions and boolean expressions.

• Parameters:
  • taskName (string, optional): A regular expression to match task names.
  • status (string, optional): A regular expression to match the task status.
  • tags (string, optional): A boolean expression string to filter tags (e.g. "bug and (frontend or not backend)").
  • query (string, optional): A regular expression to match within the task's message.
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Reads and parses the Markdown table from AGENT_TASKS.md.
  2. Filters the parsed tasks. A task matches if it satisfies all provided criteria (taskName, status, tags, and query).
• Returns: An array of Task structs matching the criteria.

deleteTask

Deletes an existing task or tasks matching specific filters like taskName, status, or tags.

• Parameters:
  • taskName (string, optional): The identifier or regular expression pattern of the tasks to delete.
  • status (string, optional): Filter tasks by their exact status (e.g., "pending").
  • tags (string, optional): Filter tasks using a boolean expression string (e.g. "bug and (frontend or not backend)").
  • workspace (string, optional): Optional workspace name to map to a specific markdown file (e.g. 'frontend' maps to 'frontend.md').
• Behavior:
  1. Parses the Markdown table from AGENT_TASKS.md.
  2. Removes the rows matching the provided filters (taskName regex, status, tags).
  3. Serializes the data back into a Markdown table and writes it to AGENT_TASKS.md.
• Returns: A summary message of how many tasks were successfully deleted.

Configuration

The extension contributes the following configuration settings:

• agentTaskTools.storageFolder: Allows specifying an optional relative path within the workspace to store the task markdown files (e.g., .tasks). If left empty, the files are stored at the workspace root.
• agentTask.dispatchConcurrency: The maximum number of tasks to dispatch concurrently to sub-agents (defaults to 3). Set to -1 for infinite concurrency.
• agentTask.dispatchTaskMaxRetries: The maximum number of retry attempts for a single failed sub-agent task dispatch (defaults to 3). Set to -1 for infinite retries.
• agentTask.dispatchTotalMaxRetries: The maximum total number of retry attempts across all failed sub-agent task dispatches in a single run (defaults to 10). Set to -1 for infinite total retries.