gh agent-task

[pelikhan]

/scout explore the github cli extension "github/agent-task" and provide an instructions.md file to use it.

[github-actions]

Agentic Scout triggered by this issue.

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan

Executive Summary

Successfully researched the gh agent-task command set - a built-in GitHub CLI feature (v2.80.0+) for managing GitHub Copilot Coding Agent tasks from the terminal. Created comprehensive instructions.md file with setup, usage examples, and best practices.

Click to expand detailed findings

Research Findings

What is gh agent-task?

Important clarification: There is no separate GitHub CLI extension called "github/agent-task". The agent-task command set is a built-in feature of the GitHub CLI starting from version 2.80.0, released in October 2025.

This command set allows developers to:

• Create and manage GitHub Copilot Coding Agent tasks from the terminal
• Monitor agent progress in real-time
• View detailed session logs
• Integrate agent workflows with scripts and automation

Key Features

Three Core Commands:

1. gh agent-task create - Start new coding agent sessions

   • Interactive or direct prompt input
   • Specify repository and base branch
   • Real-time log following with --follow

2. gh agent-task list - View all your agent tasks

   • Shows running and completed sessions
   • Displays status, repository, and timestamps

3. gh agent-task view - Inspect specific task details

   • View session information
   • Access logs with --log
   • Stream live logs with --follow

Convenience Aliases:

• gh agent-tasks
• gh agent
• gh agents

Prerequisites

• GitHub CLI: Version 2.80.0 or later
• Copilot Subscription: Pro, Pro+, Business, or Enterprise plan
• Repository Access: Write access to target repositories

Installation

# Check version
gh --version

# Update GitHub CLI
brew upgrade gh           # macOS
winget upgrade --id GitHub.cli  # Windows
sudo apt install gh       # Linux

Example Usage

# Create a task interactively
gh agent-task create

# Create with inline prompt
gh agent-task create "Refactor authentication to use JWT tokens"

# Target specific repo and branch
gh agent-task create "Add unit tests" --repo owner/repo --base develop

# Monitor in real-time
gh agent-task create "Fix memory leak" --follow

# List all tasks
gh agent-task list

# View task details with logs
gh agent-task view 123 --log --follow

Advanced Integration Examples

From GitHub Issues:

ISSUE_TITLE=$(gh issue view 42 --json title -q .title)
gh agent-task create "$ISSUE_TITLE" --follow

Bulk Task Creation:

cat TODO.md | while IFS= read -r line; do
  gh agent-task create "$line"
done

CI/CD Integration:

# In GitHub Actions
gh agent-task create "Generate changelog" --repo ${{ github.repository }}

How It Works

1. Task Creation: Agent receives prompt and analyzes codebase
2. Autonomous Work: Agent makes changes, runs tests, validates
3. Pull Request: Creates PR with changes
4. Iterations: Pushes additional commits as needed
5. Review Request: Adds you as reviewer when complete

Best Practices

Effective Prompts:

• Be specific and detailed
• Include constraints and requirements
• Reference specific files when applicable

Example:

gh agent-task create "Refactor src/auth.js to use JWT instead of sessions, maintaining backward compatibility with existing API clients"

Monitoring:

• Use --follow for critical tasks
• Check logs regularly
• Review PRs promptly

Stopping Tasks

Navigate to PR → Find "Copilot started work..." event → Click "View session" → Click "Stop session"

Recommendations

1. ✅ Update GitHub CLI to v2.80.0+ immediately to access this feature
2. ✅ Use the instructions.md file created at /tmp/gh-aw/agent/instructions.md as a comprehensive reference
3. ✅ Start with simple tasks to understand agent behavior before complex refactorings
4. ✅ Leverage --follow for learning how the agent approaches problems
5. ✅ Integrate with existing workflows using scripting and automation
6. ✅ Add repository custom instructions in .github/copilot-instructions.md for better results

Deliverable

📄 Created comprehensive instructions.md file with:

• Complete setup and installation guide
• All command usage with options
• 15+ practical examples
• Workflow integration patterns
• Best practices and troubleshooting
• Advanced scripting examples
• Comparison with other Copilot interfaces

File location: /tmp/gh-aw/agent/instructions.md

Key Sources

• GitHub Docs - Creating a PR with Copilot
• GitHub Docs - Tracking Copilot Sessions
• GitHub CLI v2.80.0 Release Notes
• GitHub Blog - Mission Control for Copilot

Suggested Next Steps

1. Review the instructions.md file created
2. Update your GitHub CLI to v2.80.0+
3. Try creating your first task with gh agent-task create --follow
4. Experiment with scripting patterns for workflow automation
5. Consider adding the instructions to the repository documentation

---

Note: This feature is in public preview and may change. The instructions include all current capabilities as of October 2025.

AI generated by Scout for #2824

[pelikhan]

@copilot create a "gh-agent-task" instructions file.