Sync session progress to Kestral via the MCP sync_session_workflow operation. Use after push, phase completion, PR creation, or review conclusion. Ambient hooks call this for you when enabled.

2026-07-244

kestral-setup

Kestral-Team/kestral-plugins

Use when the user explicitly runs Kestral setup, asks to onboard, organize, or import work into Kestral, or wants to create a Kestral project with a Project Brain from connected tools, goals, repos, documents, or optional local files.

2026-07-204

kestral-end-day-review

Kestral-Team/kestral-plugins

Use when the user asks for an end-of-day review, what got done or not done today, Kestral project updates, tomorrow priorities, or invokes /kestral:end-day-review or $kestral-end-day-review.

2026-07-134

kestral-context

Kestral-Team/kestral-plugins

Use when the user explicitly asks to search Kestral workspace context, pull Kestral documents, projects, or tasks into chat, or invokes /kestral:context or $kestral-context.

2026-07-064

kestral-plan-day

Kestral-Team/kestral-plugins

Use when the user asks to plan today, start the workday, prioritize from a Kestral brief, use a morning or daily brief, or invokes /kestral:plan-day or $kestral-plan-day.

2026-07-064

kestral-upload

Kestral-Team/kestral-plugins

Use when a setup manifest is approved and the user or kestral-setup asks to apply it, attach documents, import tasks, or invokes /kestral:upload or $kestral-upload.

2026-06-234

name	kestral-tasks
description	Use when the user explicitly asks to list, inspect, update, assign, or comment on Kestral tasks, or invokes /kestral:tasks or $kestral-tasks.

Tasks

Search, view, and update tasks in your Kestral workspace without leaving the chat.

Prerequisites

The Kestral MCP server must be in this session (/mcp). Authentication is handled by the MCP connection (OAuth) — proceed directly with operations. If any call returns auth failure (401, unauthorized, or Not authenticated), ask the user to reconnect or authenticate through their app's UI (Cowork: Customize → Connectors; Codex: Settings → MCP Servers → Authenticate; Claude Code: /mcp → reconnect).

Human-readable references

Keep Kestral IDs internal unless the user asks for them. In user-facing output:

Tasks: show slug - title when a slug is available, linked with url when the host can render links.
Projects, documents, feedback, customers, tags, statuses, and other Kestral entities: show the readable name/title/label first, linked with url when the host can render links.
People and actors: show display names; if unresolved, write Unknown member (id: <rawId>).
Unknown non-member entities: write Unknown <entity type> (id: <rawId>).
Approval tables and write-back plans must put the human-readable label first. Raw URLs, machine IDs, source IDs, and bare slugs belong only in secondary metadata when useful.
Use existing display fields first; do extra lookups only for entities that matter to the answer.

Workflow

1. Parse intent

The user's prompt determines which path to follow:

User says	Intent	Path
"show my tasks", "list open tasks in auth project"	List	Step 2
"show task AUTH-12", "get details on AUTH-12"	Drill-down	Step 3
"mark AUTH-12 done", "assign AUTH-12 to Sarah", "comment on AUTH-12: shipped in PR #42"	Update	Step 4

If the intent is ambiguous, ask one clarifying question.

2. List tasks

2a. Resolve "my tasks"

If the user asks for "my" tasks, call execute_operation("list_my_active_tasks", {}). The OAuth token identifies the user automatically — no whoami call or manual member ID lookup is needed.

2b. Build filters

Pick the operation that matches the filter intent. search_tasks accepts only { query, limit? } — semantic NL search with no assignee or status params. Do not pass assigneeFilter or statusFilter to search_tasks; they are dropped at validation.

User phrase	Operation call
"my tasks" / "my active"	`list_my_active_tasks({})`
keyword on my tasks	`search_my_tasks_by_keyword({ keyword, statusFilter? })`
"unassigned"	`search_tasks({ query: "unassigned tasks" })`
"in project X"	`search_tasks({ query: "tasks in project X" })`
"tagged bug"	`list_tasks_by_tag({ tagNames: ["bug"] })` or `search_tasks({ query: "tasks tagged bug" })`
"due this week" / time-based	`search_tasks_by_time({ timeFilter: "due this week" })`
"urgent", "high priority"	`list_tasks_by_priority({ priority: "urgent" })` or `search_tasks({ query: "urgent tasks" })`
"open", "in progress", "done"	`list_tasks_by_status({ statusFilter: ["todo", "in_progress"] })` (use `list_statuses` for keys)
general topic search	`search_tasks({ query })`

Call the matching execute_operation from the table above.

2c. Resolve display values

Before rendering, prefer display fields already returned by the task search result: slug, title, url, statusName, priorityLabel, projectName, and any display-name fields.

If a rendered row has assigneeId or createdById but no readable name, call list_members once, build an ID-to-name map, and use it for all rows. If a member ID still cannot be resolved, render Unknown member (id: <rawId>).

3d. Render results

Show a compact table. Use task slug + title as the user-facing handle. Link the handle when url is available.

Tasks (12 results):

| Task                                                                                               | Status      | Priority | Assignee   |
| -------------------------------------------------------------------------------------------------- | ----------- | -------- | ---------- |
| [AUTH-12 - Migrate OAuth tokens to new format](https://app.kestral.ai/workspace/abc/task/example1) | In Progress | High     | Alice Chen |
| AUTH-13 - Update redirect handler                                                                  | To Do       | Medium   | Unassigned |

Say a task slug or title to see details, or describe an update ("mark AUTH-12 done").

If zero results: "No tasks matched those filters. Try broadening the search."

3. Drill-down

If the user gives a slug or title from the displayed list, map it back to that row's task ID before lookup; if it is ambiguous or not in the list, search or ask one clarifying question.

Call entity_lookup({ id: taskId, type: "task" }).

Render:

Task [AUTH-12 - Migrate OAuth tokens to new format](https://app.kestral.ai/workspace/abc/task/example1)

Status: In Progress Priority: High Assignee: Alice Chen Created by: Bob Park Project: Auth Overhaul Due: 2026-07-01
Tags: auth, migration

Description: Migrate existing OAuth 1.0 tokens to the new OIDC format...

Subtasks: -

Recent comments: Bob Park (2026-06-09): "Started token audit — 3 of 5 providers migrated."

After rendering, prompt: "What would you like to do? (update status, comment, assign, go back to list)"

4. Update

All updates require confirmation before calling the write tool.

5a. Resolve references

Before writing, resolve any human-readable references to IDs:

Status: call list_statuses to map "done" → the workspace's status ID/key.
Assignee: call list_members to map "Sarah" → member ID.
Tag: call list_tags({ search: "<name>" }) to verify the tag exists (or note it will be auto-created).
Project: call execute_operation("search_projects", { query: "<name>" }) to resolve project ID.

5b. Confirm

Show exactly what will change:

I'll update AUTH-12 - Migrate OAuth tokens to new format:
  • Status: In Progress → Done
  • Comment: "Shipped in PR #312"

Confirm? (yes / no)

Wait for explicit confirmation. On "no", cancel and return to the drill-down or list.

5c. Execute

Depending on the update type, call one or more tools:

Action	Operation	Key params
Change status	`execute_operation("update_task", ...)`	`taskId`, `statusKey`
Change priority	`execute_operation("update_task", ...)`	`taskId`, `priority`
Change assignee	`execute_operation("update_task", ...)`	`taskId`, `assigneeId`
Unassign	`execute_operation("update_task", ...)`	`taskId`, `unassign: true`
Change title	`execute_operation("update_task", ...)`	`taskId`, `title`
Change description	`execute_operation("update_task", ...)`	`taskId`, `description`
Set due date	`execute_operation("update_task", ...)`	`taskId`, `dueDate` (YYYY-MM-DD)
Clear due date	`execute_operation("update_task", ...)`	`taskId`, `dueDate: null`
Move to project	`execute_operation("update_task", ...)`	`taskId`, `projectId`
Remove from project	`execute_operation("update_task", ...)`	`taskId`, `projectId: null`
Archive	`execute_operation("update_task", ...)`	`taskId`, `archive: true`
Add comment	`execute_operation("add_task_comment", ...)`	`taskId`, `content` (markdown)
Add tag	`execute_operation("manage_project", { request: "Assign tag..." })`	natural-language request
Remove tag	`execute_operation("manage_project", { request: "Remove tag..." })`	natural-language request

Status and assignee changes use dedicated operations. Other field updates use the generic update_task operation. Comments are separate calls. Tag operations use the manage_project agent.

5d. Report

After each write, confirm what changed:

Updated AUTH-12 - Migrate OAuth tokens to new format: status → Done. Added comment: "Shipped in PR #312".

If the write fails, show the error and suggest retrying or reconnecting the MCP server if it's an auth issue.

Error handling

Failure	Message
Auth failure (401, unauthorized, or `Not authenticated`)	Guide the user to authenticate through their app's UI (see Prerequisites). The agent cannot handle OAuth directly.
Task not found	"Task `<reference>` not found in your workspace. Double-check the reference."
Project not found for filter	"I couldn't find a project matching `<query>`. Try a different name."
Write failed	"Update failed: `<error>`. Try again, or reconnect the MCP server if it's an auth issue."