Amazon Q Developer CLI

Amazon Q CLI provides several built-in tools for agents to perform tasks:

• execute_bash: Execute shell commands.
• fs_read: Read files, directories, and images.
• fs_write: Create and edit files.
• introspect: Access Q CLI documentation and help content to answer questions about the CLI itself.
• report_issue: Opens a GitHub issue template in the browser.
• knowledge (experimental): Store and retrieve information in a semantic knowledge base.
• thinking (experimental): Internal reasoning mechanism for complex tasks.
• todo_list (experimental): Manage TODO lists stored in .amazonq/cli-todo-lists/.
• use_aws: Make AWS CLI API calls.

The aws-toolkit-telemetry-definitions package provides the definitions for telemetry data used across the AWS toolkits. The exact schema and format for telemetry events are defined in the external telemetryformat.md specification.

You can find the full specification here: https://github.com/aws/aws-toolkit-common/blob/main/telemetry/telemetryformat.md

The project is organized into several key areas:

• chat_cli (crates/chat-cli/): The core q CLI tool that allows users to interface with Amazon Q Developer from the command line.
• crates/: Contains all the Rust crates that make up the project logic.
• scripts/: Contains operational and build-related scripts.
• docs/: Contains technical documentation.

The introspect tool is used by the agent to answer questions about Amazon Q CLI's own capabilities, features, and commands. It automatically triggers when you ask questions like "What can you do?" or "How do I save conversations?".

It works by accessing built-in documentation, READMEs, settings information, and experiments. If configured with introspect.tangentMode = true, it can automatically enter tangent mode.

The library is built around two primary abstractions:

• Memory Contexts: A collection of related text or code (from files, directories, or raw text) that has been processed and indexed. Contexts can be Volatile (lost when the program exits) or Persistent (saved to disk for later retrieval).
• Data Points: The atomic units of search within a context. Each data point consists of an individual piece of text paired with associated metadata and vector embeddings.

An agent's configuration is defined in a JSON file called a manifest. The manifest contains the metadata and configuration required to instantiate and run an agent.

A manifest must include the following sections:

• name: Identifier for the agent.
• version: SemVer compliant version.
• description: Human and machine-readable behavior description.
• model: The LLM identifier.
• inputSchema: JSON schema for agent inputs.
• mcpServers: Access to Model Context Protocol servers.
• tools: List of available tools.
• allowedTools: Tools that run without user prompting.
• toolsSettings: Specific configurations for tools.
• resources: Declarative context/resources.

When searching for an agent, Q CLI follows a specific precedence order:

1. Local first: Checks .amazonq/cli-agents/ in the current working directory.
2. Global fallback: If no local agent is found, it checks ~/.aws/amazonq/cli-agents/ in the home directory.

Naming Conflicts

If a local agent and a global agent share the same name, the local agent takes precedence. Q CLI will ignore the global version and display the following warning:

WARNING: Agent conflict for my-agent. Using workspace version.

The prompt field provides high-level context (similar to a system prompt) for the agent. It supports two formats:

1. Inline Text: A direct string containing the prompt instructions.
2. File URI: A file:// URI referencing an external file. This is recommended for long or complex prompts to improve organization and version control.

Path Resolution for File URIs:

• Relative paths: Resolved relative to the agent configuration file's directory (e.g., file://./prompt.md).
• Absolute paths: Used as-is (e.g., file:///home/user/prompt.md).

{
  "prompt": "You are an expert AWS infrastructure specialist"
}

{
  "prompt": "file://./prompts/aws-expert.md"
}

When you run a chat session, Q CLI determines which agent to use based on a specific fallback hierarchy. If the highest priority agent is not found, it moves to the next level in the hierarchy.

Agent Selection Priority

1. Command-Line Specified Agent: The agent explicitly passed via the --agent flag.
2. User-Defined Default Agent: The agent configured in your settings via q settings chat.defaultAgent.
3. Built-in Default Agent: The fallback agent provided by the system if no other agent is found or accessible.