`gh agent-task` commandset #11797

BagToad · 2025-09-23T15:05:16Z

This introduces the foundational implementation for the new agent-task command group in the GitHub CLI, enabling users to interact with coding agent tasks.

The changes include the creation of the core command, authentication checks, unit tests, and the initial implementation of a Copilot API client for agent tasks. Additionally, there are minor enhancements to internal API types and updates to dependencies.

gh agent-task is in preview and is subject to change without notice.

The agent-task commandset also ships with the following aliases for convenience:

gh agent-tasks
gh agent
gh agents

Introduces a new `agent-task` command under pkg/cmd/agent with strict OAuth (device flow) token validation. Includes comprehensive tests for token source and host validation, and registers the command in the root command set.

Changed the RunE function of the agent-task command to display help output instead of returning nil, improving user guidance when the command is run without arguments.

Replaces require.Equal with require.Empty in TestOAuthTokenAccepted for improved clarity when checking for empty output.

Consolidates multiple individual test functions into a single table-driven test, improving maintainability and readability. This change makes it easier to add new test cases and ensures consistent test structure for agent task command authentication scenarios.

…exits-if-user-not-authenticated-with-oauth Introduce `gh agent-task`

Introduces a new 'list' subcommand under agent-task for listing agent tasks. Implements a Copilot API client for fetching agent sessions and hydrating them with pull request data. Updates PullRequest and PRRepository types to support new fields. Adds dependencies for msgpack and tagparser. Co-Authored-By: Babak K. Shandiz <babakks@github.com>

Renames the import of the shared package to 'prShared' and updates its usage in list.go to avoid naming conflicts and improve code clarity.

Simplifies logic for filtering sessions to only include those with valid pull request and repository data. This reduces nested conditionals and improves code readability.

Moves CAPI client initialization to a deferred function in ListOptions, simplifying command setup and improving testability. Updates tests to use the new client initialization pattern and adds more comprehensive test cases for session listing.

Cleaned up the sessionPullRequest struct by deleting unused commented-out fields related to Author and MergedBy.

Renamed 'Sessions' to 'result' for clarity and consistency in the ListSessionsForViewer method when hydrating session pull requests.

Changed the API query from 'FetchPRs' to 'FetchPRsForAgentTaskSessions' in hydrateSessionPullRequests to match updated backend endpoint.

Simplified error handling by inlining the encoder.Encode call and removing redundant comments for improved code clarity.

Replaces linear search with a map for associating sessions with pull requests, improving performance and simplifying code in hydrateSessionPullRequests.

Moved the session state color selection logic from list.go to a new shared/display.go file as ColorFuncForSessionState. This improves code reuse and maintainability by centralizing the color mapping for session states.

…s-with-table-of-the-users-agent-sessions Introduce `gh agent-task list`

Introduces ListSessionsForRepo to CapiClient and CAPIClient, enabling listing agent sessions for a specific repository. Updates the list command and tests to support repo override and repo-scoped session queries, including error handling and test coverage for repo resolution.

Introduces a --limit flag to control the maximum number of agent tasks fetched. Validates that the limit is greater than zero and updates tests to cover custom and invalid limit scenarios.

Updates the help text for the --limit flag in the agent-task list command to display the default value, improving clarity for users.

Introduces a --web flag to the agent-task list command, allowing users to open the agent tasks page in their browser. Updates tests to cover the new flag and browser interaction.

Updated listRun to ignore errors from BaseRepo resolution and proceed when possible. Adjusted tests to reflect that repo resolution errors no longer surface, improving robustness when repo information is ambiguous.

…-flag' into kw/1003-gh-agent-task-list-respects--l--limit

…1004-gh-agent-task-list-respects--w--web

Removes unnecessary nil check for Factory before assigning BaseRepo in the agent-task list command. This streamlines the code since Factory is always expected to be non-nil.

Replaces explicit duration parsing with direct multiplication for calculating a timestamp 6 hours ago in Test_listRun, improving code clarity.

Added a comment to clarify why the error from opts.BaseRepo() is ignored in listRun. This provides context for handling cases when the current working directory is not a repo and --repo is not set.

Replaces plain output with a NoResultsError in listRun when no agent tasks are found. Updates related tests to expect the error instead of output, improving error handling consistency.

Introduces a test to verify that passing a negative value to the --limit flag in the agent-task list command returns the expected error message.

Added a comment explaining that the web GUI does not currently support filtering by repo, so the agents dashboard is opened without arguments. Notes future improvement if repo filtering becomes available.

Added a test case to ensure that web mode in listRun uses the global URL even when the --repo flag is set. This improves coverage for scenarios where both web mode and repo are specified.

Signed-off-by: Babak K. Shandiz <babakks@github.com>

…dAt` Signed-off-by: Babak K. Shandiz <babakks@github.com>

Signed-off-by: Babak K. Shandiz <babakks@github.com>

update agents resource route

Signed-off-by: Babak K. Shandiz <babakks@github.com>

`gh agent-task view`: display session error if any

…JSON Signed-off-by: Babak K. Shandiz <babakks@github.com>

…ent-task-create `gh agent-task create`: return proper error message when resp is not a JSON

Copilot

Pull Request Overview

This PR implements a comprehensive gh agent-task command set, adding functionality to create, list, and view GitHub Copilot agent tasks through the CLI. The main purpose is to provide users with command-line access to manage agent tasks that were previously only available through the web interface.

Key changes include:

Complete agent-task command infrastructure with create, list, and view subcommands
CAPI client for communicating with GitHub's Copilot Agent API
Log rendering system for displaying agent session logs with proper formatting
Comprehensive test coverage and mock implementations

Reviewed Changes

Copilot reviewed 34 out of 35 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
pkg/cmd/root/root.go	Registers the new agent-task command in the CLI root
pkg/cmd/pr/shared/finder.go	Enhances PR URL parsing to support additional path components and adds full reference parsing
pkg/cmd/pr/shared/finder_test.go	Adds comprehensive tests for new PR parsing functionality
pkg/cmd/pr/edit/edit.go	Updates PR URL parsing call signature
pkg/cmd/agent-task/	Complete agent-task command implementation with subcommands, CAPI client, and supporting utilities

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.}

pkg/cmd/pr/shared/finder.go

pkg/cmd/agent-task/capi/sessions.go

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Imported the math package in sessions.go

babakks

LGTM! 🚀

This MR contains the following updates: | Package | Update | Change | |---|---|---| | [cli/cli](https://github.com/cli/cli) | minor | `v2.79.0` -> `v2.80.0` | MR created with the help of [el-capitano/tools/renovate-bot](https://gitlab.com/el-capitano/tools/renovate-bot). **Proposed changes to behavior should be submitted there as MRs.** --- ### Release Notes <details> <summary>cli/cli (cli/cli)</summary> ### [`v2.80.0`](https://github.com/cli/cli/releases/tag/v2.80.0): GitHub CLI 2.80.0 [Compare Source](cli/cli@v2.79.0...v2.80.0) ####

Manage GitHub Copilot Coding Agent From the GitHub CLI This GitHub CLI release introduces the `agent-task` commandset for managing [coding agent tasks](https://docs.github.com/en/copilot/concepts/agents/coding-agent/about-coding-agent) in `gh`: - Create tasks: `gh agent-task create "refactor the codebase"` - List all your tasks: `gh agent-task list` - View task details: `gh agent-task view 1234` - View the task log in real-time: `gh agent-task view 1234 --log --follow` For more information about command line flags and arguments, run `gh agent-task <command> --help`. The `agent-task` commandset also ships with the following aliases for convenience: - `gh agent-tasks` - `gh agent` - `gh agents` ℹ️ *The `agent-task` commandset is in preview and is subject to change without notice*. Got feedback? Let us know what you like or don't like [in an issue](https://github.com/cli/cli/issues/new?template=feedback.md) ❤️ #### What's Changed ##### ✨ Features - `gh agent-task` commandset by [@BagToad](https://github.com/BagToad) and [@babakks](https://github.com/babakks) in [#11797](cli/cli#11797) ##### 🐛 Fixes - Pin release runner image to Windows 2022 by [@babakks](https://github.com/babakks) in [#11799](cli/cli#11799) **Full Changelog**: <cli/cli@v2.79.0...v2.80.0> </details> --- ### Configuration 📅 **Schedule**: Branch creation - At any time (no schedule defined), Automerge - At any time (no schedule defined). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻ **Rebasing**: Whenever MR becomes conflicted, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this MR and you won't be reminded about this update again. --- - [ ] If you want to rebase/retry this MR, check this box --- This MR has been generated by [Renovate Bot](https://github.com/renovatebot/renovate).

liskin · 2025-10-02T17:43:11Z

Do I need any additional OAuth scopes to use this?

$ gh agent-task list
failed to list sessions: 403 Forbidden

babakks · 2025-10-03T11:21:38Z

@liskin Can you please create a separate issue for your problem?

Also please make sure to include the scopes of your token (you can use gh auth status to see your scopes).

BagToad and others added 30 commits August 27, 2025 12:23

Add agent-task command with OAuth token validation

3573f61

Introduces a new `agent-task` command under pkg/cmd/agent with strict OAuth (device flow) token validation. Includes comprehensive tests for token source and host validation, and registers the command in the root command set.

Show help on agent-task command execution

2128a29

Changed the RunE function of the agent-task command to display help output instead of returning nil, improving user guidance when the command is run without arguments.

Refactor test to use require.Empty assertion

1bc2710

Replaces require.Equal with require.Empty in TestOAuthTokenAccepted for improved clarity when checking for empty output.

Merge pull request #11600 from cli/kw/997-gh-agent-task-responds-and-…

09be17e

…exits-if-user-not-authenticated-with-oauth Introduce `gh agent-task`

Fix import alias for shared package in agent-task list

0de5cf2

Renames the import of the shared package to 'prShared' and updates its usage in list.go to avoid naming conflicts and improve code clarity.

Refactor session filtering in listRun function

0a5b78a

Simplifies logic for filtering sessions to only include those with valid pull request and repository data. This reduces nested conditionals and improves code readability.

Remove commented-out fields from sessionPullRequest

4801206

Cleaned up the sessionPullRequest struct by deleting unused commented-out fields related to Author and MergedBy.

Refactor variable names in ListSessionsForViewer

13c293f

Renamed 'Sessions' to 'result' for clarity and consistency in the ListSessionsForViewer method when hydrating session pull requests.

Update API query name for session PR fetch

bc1d306

Changed the API query from 'FetchPRs' to 'FetchPRsForAgentTaskSessions' in hydrateSessionPullRequests to match updated backend endpoint.

Refactor error handling in generatePullRequestNodeID

5281be4

Simplified error handling by inlining the encoder.Encode call and removing redundant comments for improved code clarity.

Optimize session pull request hydration logic

ea9dfae

Replaces linear search with a map for associating sessions with pull requests, improving performance and simplifying code in hydrateSessionPullRequests.

Refactor session state color logic to shared package

4fd6ae6

Moved the session state color selection logic from list.go to a new shared/display.go file as ColorFuncForSessionState. This improves code reuse and maintainability by centralizing the color mapping for session states.

Merge pull request #11606 from cli/kw/1001-gh-agent-task-list-respond…

c10ac8a

…s-with-table-of-the-users-agent-sessions Introduce `gh agent-task list`

Add limit flag to agent-task list command

a49994d

Introduces a --limit flag to control the maximum number of agent tasks fetched. Validates that the limit is greater than zero and updates tests to cover custom and invalid limit scenarios.

Show default limit in agent-task list flag help

83c597f

Updates the help text for the --limit flag in the agent-task list command to display the default value, improving clarity for users.

Add --web flag to agent-task list command

a2d75d1

Introduces a --web flag to the agent-task list command, allowing users to open the agent tasks page in their browser. Updates tests to cover the new flag and browser interaction.

Handle repo resolution errors gracefully in agent-task list

3197193

Updated listRun to ignore errors from BaseRepo resolution and proceed when possible. Adjusted tests to reflect that repo resolution errors no longer surface, improving robustness when repo information is ambiguous.

Merge branch 'kw/1002-gh-agent-task-list-respects-cwd-repo-and---repo…

ffc8792

…-flag' into kw/1003-gh-agent-task-list-respects--l--limit

Merge branch 'kw/1003-gh-agent-task-list-respects--l--limit' into kw/…

61c8b5e

…1004-gh-agent-task-list-respects--w--web

Simplify BaseRepo assignment in list command

97da7fc

Removes unnecessary nil check for Factory before assigning BaseRepo in the agent-task list command. This streamlines the code since Factory is always expected to be non-nil.

Simplify time calculation in listRun test

4a07cdf

Replaces explicit duration parsing with direct multiplication for calculating a timestamp 6 hours ago in Test_listRun, improving code clarity.

Add comment explaining error handling in listRun

227f0bd

Added a comment to clarify why the error from opts.BaseRepo() is ignored in listRun. This provides context for handling cases when the current working directory is not a repo and --repo is not set.

Return NoResultsError when no agent tasks found

163eb7e

Replaces plain output with a NoResultsError in listRun when no agent tasks are found. Updates related tests to expect the error instead of output, improving error handling consistency.

Add test case for negative limit in list command

51aa033

Introduces a test to verify that passing a negative value to the --limit flag in the agent-task list command returns the expected error message.

Add comment on web dashboard filtering limitation

93f7e98

Added a comment explaining that the web GUI does not currently support filtering by repo, so the agents dashboard is opened without arguments. Notes future improvement if repo filtering becomes available.

Add test for web mode with repo flag in listRun

c4c0ddc

Added a test case to ensure that web mode in listRun uses the global URL even when the --repo flag is set. This improves coverage for scenarios where both web mode and repo are specified.

babakks added 14 commits September 19, 2025 14:27

refactor(agent-task/capi): keep resource private

546ab1c

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(agent-task/capi): handle unpopulated resource session `LastUpdate…

9148f41

…dAt` Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(agent-task/capi): fetch viewer when resource session user id is zero

a108b4e

Signed-off-by: Babak K. Shandiz <babakks@github.com>

docs(agent-task/capi): add TODO note for dropping local ID generation

2fe60d9

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(agent-tassk/capi): update ListSessionsByResourceID tests

eba3134

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(agent-task/capi): remove fallback to viewer when user id is zero

597cdaf

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Merge pull request #11770 from cli/mntlty/update-session

bba12f8

update agents resource route

fix(agent-task view): re-fetch session to get all pieces of data

3091c21

Signed-off-by: Babak K. Shandiz <babakks@github.com>

refactor(agent-task view): merge empty println calls with next

3e43a98

Signed-off-by: Babak K. Shandiz <babakks@github.com>

fix(agent-task view): improve session overview

ecfbb67

Signed-off-by: Babak K. Shandiz <babakks@github.com>

test(agent-task view): populate Session.Name in all test cases

eb3c842

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Merge pull request #11763 from cli/babakks/display-session-error

002ba54

`gh agent-task view`: display session error if any

fix(agent-task/capi): return proper error message when resp is not a …

6fc5742

…JSON Signed-off-by: Babak K. Shandiz <babakks@github.com>

Merge pull request #11783 from cli/babakks/display-proper-error-in-ag…

ecb236b

…ent-task-create `gh agent-task create`: return proper error message when resp is not a JSON

Copilot AI review requested due to automatic review settings September 23, 2025 15:05

BagToad requested a review from a team as a code owner September 23, 2025 15:05

BagToad requested a review from babakks September 23, 2025 15:05

BagToad temporarily deployed to cli-automation September 23, 2025 15:05 — with GitHub Actions Inactive

cliAutomation assigned BagToad Sep 23, 2025

Copilot AI reviewed Sep 23, 2025

View reviewed changes

pkg/cmd/pr/shared/finder.go Show resolved Hide resolved

pkg/cmd/pr/shared/finder.go Show resolved Hide resolved

github-advanced-security bot found potential problems Sep 23, 2025

View reviewed changes

pkg/cmd/agent-task/capi/sessions.go Fixed Show fixed Hide fixed

babakks and others added 3 commits September 23, 2025 16:15

chore: update third-party licenses

8818c0d

Signed-off-by: Babak K. Shandiz <babakks@github.com>

Add TODO for better integer handling in GetPullRequestDatabaseID

e673dfe

Add math package import to sessions.go

8c75079

Imported the math package in sessions.go

babakks approved these changes Sep 23, 2025

View reviewed changes

BagToad merged commit 7ff84cf into trunk Sep 23, 2025
11 checks passed

BagToad deleted the github-cli-epic-990 branch September 23, 2025 15:46

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

`gh agent-task` commandset #11797

`gh agent-task` commandset #11797

Uh oh!

BagToad commented Sep 23, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

babakks left a comment

Uh oh!

Uh oh!

liskin commented Oct 2, 2025

Uh oh!

babakks commented Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

gh agent-task commandset #11797

gh agent-task commandset #11797

Uh oh!

Conversation

BagToad commented Sep 23, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

babakks left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

liskin commented Oct 2, 2025

Uh oh!

babakks commented Oct 3, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

`gh agent-task` commandset #11797

`gh agent-task` commandset #11797

BagToad commented Sep 23, 2025 •

edited

Loading