Copilot CLI Tools (v0.0.377)

copilot-cli-tools.md

Copilot CLI: Custom Agent Tools

How to determine the internal tools used by custom agents of Copilot CLI (v0.0.377)?

1. Create a (temporary) custom agent .github/agents/tools.agent.md which allows all tools (see also Tools):

   ---
   name: Tools
   tools: ["*"]
   ---
   

2. Create a mitmdump script inspect.py:

   from mitmproxy import http
   
   def request(flow):
       if flow.request.path == "/chat/completions":
           with open('chat_completions.json', 'ab') as f:
               f.write(flow.request.content)
   

3. Run in a shell 1:

   mitmdump -q -s inspect.py
   

4. Run in a shell 2:

   export HTTP_PROXY="http://localhost:8080"
   export HTTPS_PROXY="https://localhost:8080"
   copilot
   

5. Select above custom agent Tools in Copilot CLI and prompt for something

   /agent
   

6. Back in shell 1, stop mitmdump and list all tool names from API call to /chat/completions endpoint:

   cat chat_completions.json | jq -rs '.[0].tools[].function.name'
   cat chat_completions.json | jq -sr '.[0].tools[].function | "### \(.name)\n\n\(.description)\n"'
   

Copilot CLI Tools

bash

Runs a Bash command in an interactive Bash session.

• The "command" parameter does NOT need to be XML-escaped.
• You don't have internet access via this tool.
• You can run Python, Node.js and Go code with python, node and go.
• Each sessionId identifies a persistent session. State is saved across calls.
• initial_wait must be 30-600 seconds. Give long-running commands time to produce output.
• If a command hasn't completed within initial_wait, it returns partial output and continues running. Use read_bash for more output or stop_bash to stop it.
• You can install Linux, Python, JavaScript and Go packages with the apt, pip, npm and go commands.

write_bash

Sends input to the specified command or Bash session.

• This tool can be used to send input to a running Bash command or an interactive console app.
• Bash commands are run in an interactive Bash session with a TTY device and Bash command processor.
• sessionId (required) must match the sessionId used to invoke the async bash command.
• You can send text, {up}, {down}, {left}, {right}, {enter}, and {backspace} as input.
• Some applications present a list of options to select from. The selection is often denoted using ❯, >, or different formatting.
• When presented with a list of items, make a selection by sending arrow keys like {up} or {down} to move the selection to your chosen item and then {enter} to select it.
• The response will contain any output read after "delay" seconds. Delay should be appropriate for the task and never less than 10 seconds.

read_bash

Reads output from a Bash command.

• Reads the output of a command running in an "async" Bash session.
• The sessionId MUST be the same one used to invoke the bash command.
• You can call this tool multiple times to read output produced since the last call.
• Each request has a cost, so provide a reasonable "delay" parameter value for the task, to minimize the need for repeated reads that return no output.
• If a read request generates no output, consider using exponential backoff in choosing the delay between reads of the same command.
• Though write_bash accepts ANSI control codes, this tool does not include them in the output.

stop_bash

Stops a running Bash command.

• Stops a running Bash command by terminating the entire Bash session and process.
• This tool can be used to stop commands that have not exited on their own.
• Any environment variables defined will have to be redefined after using this tool if the same session ID is used to run a new command.
• The sessionId must match the sessionId used to invoke the bash command.

list_bash

Lists all active Bash sessions.

• Returns information about all currently running Bash sessions.
• Useful for discovering sessionIds to use with read_bash, write_bash, or stop_bash.
• Shows sessionId, command, mode, PID, status, and whether there is unread output.

grep

Fast and precise code search using ripgrep. Search for patterns in file contents.

glob

Fast file pattern matching using glob patterns. Find files by name patterns.

view

Tool for viewing files and directories.

• If path is an image file, returns the image as base64-encoded data along with its MIME type.
• If path is any other type of file, view displays the content with line numbers prefixed to each line in the format N. where N is the line number (e.g., 1. , 2. , etc.).
• If path is a directory, view lists non-hidden files and directories up to 2 levels deep
• Path MUST be absolute

create

Tool for creating new files.

• Creates a new file with the specified content at the given path
• Cannot be used if the specified path already exists
• Parent directories must exist before creating the file
• Path MUST be absolute

edit

Tool for making string replacements in files.

• Replaces exactly one occurrence of old_str with new_str in the specified file
• When called multiple times in a single response, edits are independently made in the order calls are specified
• The old_str parameter must match EXACTLY one or more consecutive lines from the original file
• If old_str is not unique in the file, replacement will not be performed
• Make sure to include enough context in old_str to make it unique
• Path MUST be absolute

report_intent

Use this tool to update the current intent of the session. This is displayed in the user interface and is important to help the user understand what you're doing. Rules:

• Call this tool ONLY when you are also calling other tools. Do not call this tool in isolation.
• Put this tool call first in your collection of tool calls.
• Always call it at least once per user message (on your first tool-calling turn after a user message).
• Don't then re-call it if the reported intent is still applicable When to update intent (examples):
• ✅ "Exploring codebase" → "Installing dependencies" (new phase)
• ✅ "Running tests" → "Debugging test failures" (new phase)
• ✅ "Creating hook script" → "Fixing security issue" (new phase)
• ❌ "Installing Pandas 2.2.3" → "Installing Pandas with pip3" (same goal, different tactic: should just have said "Installing Pandas")
• ❌ "Running transformation script" → "Running with python3" (same goal, fallback attempt) Phrasing guidelines:
• The intent text must be succinct - 4 words max
• Keep it high-level - it should summarize a series of steps and focus on the goal
• Use gerund form
• Bad examples:
  • 'I am going to read the codebase and understand it.' (too long and no gerund)
  • 'Writing test1.js' (too low-level: describe the goal, not the specific file)
  • 'Updating logic' (too vague: at least add one word to hint at what logic)
• Good examples:
  • 'Exploring codebase'
  • 'Creating parser tests'
  • 'Fixing homepage CSS'

fetch_copilot_cli_documentation

Fetches documentation about you, the GitHub Copilot CLI, and your capabilities. Use this tool when the user asks how to use you, what you can do, or about specific features of the GitHub Copilot CLI.

update_todo

Use this TODO tool to manage the tasks that must be completed to solve the problem. Use this tool VERY frequently to keep track of your progress towards completing the overall goal, keeping all item statuses up to date. Call this tool to make the initial todo list for a complex problem. Then call this tool every time you finish a task and check off the corresponding item in the TODO list. If new tasks are identified, add them to the list as well. Re-planning is allowed if necessary. This tool accepts markdown input to track what has been completed, and what still needs to be done. This tool does not return meaningful data or make changes to the repository, but helps you organize your work and keeps you on-task. Call this tool at the same time as the next necessary tool calls, so that you can keep your TODO list updated while continuing to make progress on the problem.

web_fetch

Fetches a URL from the internet and returns the page as either markdown or raw HTML. Use this to safely retrieve up-to-date information from HTML web pages.

task

Custom agent: Launch specialized agents in separate context windows for specific tasks.

The Task tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.

Available agent types:

• explore: Fast agent specialized for exploring codebases and answering questions about code. Use this when you need to quickly find files by patterns (eg. "src/components/**/*.tsx"), search code for keywords (eg. "API endpoints"), or answer questions about the codebase (eg. "how do API endpoints work?", "what does this codebase do?", "where is authentication logic?"). Returns focused answers under 300 words. Safe to call in parallel. (Tools: grep/glob/view, Haiku model)

• task: Agent for executing commands with verbose output (tests, builds, lints, dependency installs). Returns brief summary on success ("All 247 tests passed", "Build succeeded"), full output on failure (stack traces, compiler errors). Keeps main context clean by minimizing successful output. Use for tasks where you only need to know success/failure status. (Tools: All CLI tools, Haiku model)

• general-purpose: Full-capability agent running in a subprocess. Use for complex multi-step tasks requiring the complete toolset and high-quality reasoning. Runs in a separate context window to keep your main conversation clean. (Tools: All CLI tools, Sonnet model)

User-provided custom agents:

These are custom agents configured specifically for your environment. They may have specialized knowledge, tools, or workflows tailored to your project needs.

• implementation-planner: Creates detailed implementation plans and technical specifications in markdown format

When NOT to use Task tool:

• Reading specific file paths you already know - use view tool instead
• Simple single grep/glob search - use grep/glob tools directly
• Commands where you need immediate full output in your context - use bash directly
• File operations on known files - use edit/create tools directly

Usage notes:

• Can launch multiple explore agents in parallel (task, general-purpose have side effects)
• Each agent is stateless - provide complete context in your prompt
• Agent results are returned in a single message
• Use explore proactively for codebase questions before making changes
• Use 'model' parameter to override the default model (13 models available)

github-mcp-server-actions_get

Get details about specific GitHub Actions resources. Use this tool to get details about individual workflows, workflow runs, jobs, and artifacts by their unique IDs.

github-mcp-server-actions_list

Tools for listing GitHub Actions resources. Use this tool to list workflows in a repository, or list workflow runs, jobs, and artifacts for a specific workflow or workflow run.

github-mcp-server-get_commit

Get details for a commit from a GitHub repository

github-mcp-server-get_copilot_space

This tool can be used to provide additional context to the chat from a specific Copilot space. If user mentioned the keyword 'Copilot space' with the name and owner of the space, execute this tool.

github-mcp-server-get_file_contents

Get the contents of a file or directory from a GitHub repository

github-mcp-server-get_job_logs

Get logs for GitHub Actions workflow jobs. Use this tool to retrieve logs for a specific job or all failed jobs in a workflow run. For single job logs, provide job_id. For all failed jobs in a run, provide run_id with failed_only=true.

github-mcp-server-issue_read

Get information about a specific issue in a GitHub repository.

github-mcp-server-list_branches

List branches in a GitHub repository

github-mcp-server-list_commits

Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).

github-mcp-server-list_issues

List issues in a GitHub repository. For pagination, use the 'endCursor' from the previous response's 'pageInfo' in the 'after' parameter.

github-mcp-server-list_pull_requests

List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.

github-mcp-server-pull_request_read

Get information on a specific pull request in GitHub repository.

github-mcp-server-search_code

Fast and precise code search across ALL GitHub repositories using GitHub's native search engine. Best for finding exact symbols, functions, classes, or specific code patterns.

github-mcp-server-search_issues

Search for issues in GitHub repositories using issues search syntax already scoped to is:issue

github-mcp-server-search_pull_requests

Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr

github-mcp-server-search_repositories

Find GitHub repositories by name, description, readme, topics, or other metadata. Perfect for discovering projects, finding examples, or locating specific repositories across GitHub.

github-mcp-server-search_users

Find GitHub users by username, real name, or other profile information. Useful for locating developers, contributors, or team members.