### Example: Getting Q CLI Help with Tangent Mode

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md

Illustrates using Tangent Mode to ask for specific Q CLI commands related to file operations while in the middle of a deployment script generation conversation.

```bash
> Help me write a deployment script

I can help you create a deployment script...

> /tangent
Created a conversation checkpoint (↯).

↯ > What Q CLI commands are available for file operations?

Q CLI provides fs_read, fs_write, execute_bash...

↯ > /tangent
Restored conversation from checkpoint (↯).

> It's a Node.js application for AWS
```

--------------------------------

### Q CLI Usage Examples

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/introspect-tool.md

Examples demonstrating how to ask Q CLI about saving conversations, experimental features, and file operations.

```text
> How do I save conversations with Q CLI?
You can save conversations using `/save` or `/save name`.
Load them later with `/load`.
```

```text
> What experimental features does Q CLI have?
Q CLI offers Tangent Mode and Thinking Mode. 
Use `/experiment` to enable them.
```

```text
> Can Q CLI read and write files?
Yes, Q CLI has fs_read, fs_write, and execute_bash tools
for file operations.
```

--------------------------------

### Complete MCP Servers Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/draft/the-agent-format-2.md

An example demonstrating the configuration of multiple MCP servers, including local and remote definitions.

```json
{
  "mcpServers": {
    "fetch": {
      "command": "fetch",
      "args": [],
      "transport": "stdio"
    },
    "git": {
      "command": "git-mcp",
      "transport": "streamable-http",
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    },
    "github-mcp": {
      "url": "https://api.githubcopilot.com/mcp",
      "headers": {
        "Authorization": "Bearer ${GITHUB_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### Complete Agent Configuration Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

A comprehensive example demonstrating all configurable fields for an agent, including name, description, MCP servers, tools, hooks, and model settings.

```json
{
  "name": "aws-rust-agent",
  "description": "A specialized agent for AWS and Rust development tasks",
  "mcpServers": {
    "fetch": {
      "command": "fetch3.1",
      "args": []
    },
    "git": {
      "command": "git-mcp",
      "args": []
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@git",
    "@fetch/fetch_url"
  ],
  "toolAliases": {
    "@git/git_status": "status",
    "@fetch/fetch_url": "get"
  },
  "allowedTools": [
    "fs_read",
    "@git/git_status"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["src/**", "tests/**", "Cargo.toml"]
    },
    "use_aws": {
      "allowedServices": ["s3", "lambda"]
    }
  },
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [
      {
        "command": "git status"
      }
    ],
    "userPromptSubmit": [
      {
        "command": "ls -la"
      }
    ]
  },
  "useLegacyMcpJson": true,
  "model": "claude-sonnet-4"
}
```

--------------------------------

### Install Rust Toolchain and Dependencies

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/README.md

Installs the Rust toolchain, including stable and nightly versions, and the typos-cli for checking.

```shell
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
rustup default stable
rustup toolchain install nightly
cargo install typos-cli
```

--------------------------------

### Quick Start: Initialize Client and Add Context

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Initializes an async client, adds a project directory as a context with specified include/exclude patterns, and starts an indexing operation. Requires tokio runtime.

```rust
use semantic_search_client::{AsyncSemanticSearchClient, AddContextRequest, Result};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> Result<()> {
    // Create a new async client with default settings
    let client = AsyncSemanticSearchClient::new_with_default_dir().await?;
    
    // Add a context using the new structured request API
    let request = AddContextRequest {
        path: PathBuf::from("/path/to/project"),
        name: "My Project".to_string(),
        description: "Code and documentation for my project".to_string(),
        persistent: true,
        include_patterns: Some(vec!["**/*.rs".to_string(), "**/*.md".to_string()]),
        exclude_patterns: Some(vec!["target/**".to_string(), "**/.git/**".to_string()]),
    };
    
    let (operation_id, _cancel_token) = client.add_context(request).await?;
    println!("Started indexing with operation ID: {}", operation_id);
    
    // Search across all contexts
    let results = client.search_all("implement authentication", None).await?;
    
    // Print the results
    for (context_id, context_results) in results {
        println!("Results from context {}", context_id);
        for result in context_results {
            println!("Score: {}", result.distance);
            if let Some(text) = result.text() {
                println!("Text: {}", text);
            }
        }
    }
    
    Ok(())
}

```

--------------------------------

### Example Workflow for Agent Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/default-agent-behavior.md

Demonstrates a typical workflow for setting a user default agent, using the default agent, and overriding it for specific tasks.

```bash
# Set up a preferred default agent
q settings chat.defaultAgent development-helper

# Use default agent (development-helper)
q chat

# Override for specific task
q chat --agent aws-specialist

# If development-helper doesn't exist, falls back to built-in default
# with warning message

```

--------------------------------

### Complete Agent Manifest Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/draft/the-agent-format-2.md

A comprehensive example of an agent manifest, including name, version, model, MCP servers, tools, allowed tools, tool settings, resources, and input schema.

```json
{
  "name": "rust-developer-agent",
  "version": "1.2.0",
  "description": "A specialized agent for Rust development tasks",
  "model": "anthropic.claude-sonnet-4-20250514-v1:0",
  "mcpServers": {
    "fetch": { "command": "fetch", "args": [], "transport": "stdio" },
    "git": { "command": "git-mcp", "transport": "streamable-http" },
    "rust-analyzer": { "command": "rust-analyzer-mcp", "transport": "stdio" }
  },
  "tools": [
    "fs-read",
    "fs-write",
    "execute-bash",
    "@git",
    "@rust-analyzer/check-code",
    "@rust-analyzer/format-code"
  ],
  "allowedTools": ["fs-read", "@git.git-status", "@rust-analyzer/check-code"],
  "toolsSettings": {
    "fs-write": {
      "allowedPaths": ["src/**", "tests/**", "Cargo.toml"]
    }
  },
  "resources": [
    "file://rust-style-guide.md",
    "file://${workspace}/README.md",
    "file://project-context.md@workspace-mcp"
  ],
  "inputSchema": {
    "type": "object",
    "properties": {
      "task": {
        "type": "string",
        "description": "The development task to perform"
      },
      "context": {
        "type": "object",
        "description": "Additional context for the task"
      }
    },
    "required": ["task"]
  }
}
```

--------------------------------

### Install Amazon Q CLI with Homebrew

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/README.md

Use this command to install the Amazon Q CLI on macOS using Homebrew.

```shell
brew install --cask amazon-q 
```

--------------------------------

### Checkpoint Example Usage

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md

Demonstrates listing and expanding checkpoints. The first command lists all checkpoints, and the second expands checkpoint '2' to show its nested tool-level checkpoints.

```bash
/checkpoint list
[0] 2025-09-18 14:00:00 - Initial checkpoint
[1] 2025-09-18 14:05:31 - add two_sum.py (+1 file)
[2] 2025-09-18 14:07:10 - add tests (modified 1)

/checkpoint expand 2
[2] 2025-09-18 14:07:10 - add tests
 └─ [2.1] fs_write: Add minimal test cases to two_sum.py (modified 1)
```

--------------------------------

### PostToolUse Hook Event Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/hooks.md

Example of a hook event for the 'postToolUse' type, which runs after tool execution and has access to the tool's results. This example shows a file system read operation and its response.

```json
{
  "hook_event_name": "postToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "fs_read",
  "tool_input": {
    "operations": [
      {
        "mode": "Line",
        "path": "/current/working/directory/docs/hooks.md"
      }
    ]
  },
  "tool_response": {
    "success": true,
    "result": ["# Hooks\n\nHooks allow you to execute..."]
  }
}
```

--------------------------------

### Example: Clarifying Requirements with Tangent Mode

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md

Shows how Tangent Mode can be used to ask for necessary information (like query and schema details) to optimize an SQL query without losing the context of the optimization request.

```bash
> I need to optimize this SQL query

Could you share the query you'd like to optimize?

> /tangent
Created a conversation checkpoint (↯).

↯ > What information do you need to help optimize a query?

To optimize SQL queries effectively, I need:
1. The current query
2. Table schemas and indexes...

↯ > /tangent
Restored conversation from checkpoint (↯).

> Here's my query: SELECT * FROM orders...
```

--------------------------------

### Example: Exploring Alternatives with Tangent Mode

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md

Demonstrates using Tangent Mode to explore an alternative approach (using the `csv` module) to processing a large CSV file after initially discussing pandas.

```bash
> I need to process a large CSV file in Python. What's the best approach?

I recommend using pandas for CSV processing...

> /tangent
Created a conversation checkpoint (↯).

↯ > What about using the csv module instead of pandas?

The csv module is lighter weight...

↯ > /tangent
Restored conversation from checkpoint (↯).

> Thanks! I'll go with pandas. Can you show me error handling?
```

--------------------------------

### Manage Contexts and Operations

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Demonstrates how to retrieve all contexts, remove contexts by different identifiers, and cancel ongoing operations. Also shows how to get system status information.

```rust
let contexts = client.get_contexts().await;
for context in contexts {
    println!("Context: {} ({})", context.name, context.id);
    println!("  Description: {}", context.description);
    println!("  Created: {}", context.created_at);
    println!("  Items: {}", context.item_count);
    println!("  Include patterns: {:?}", context.include_patterns);
    println!("  Exclude patterns: {:?}", context.exclude_patterns);
}

// Remove contexts
client.remove_context_by_id("context-id").await?;
client.remove_context_by_name("Context Name").await?;
client.remove_context_by_path("/path/to/indexed/directory").await?;

// Cancel ongoing operations
client.cancel_operation(operation_id).await?;
client.cancel_all_operations().await?;

// Get system status
let status = client.get_status_data().await?;
println!("Total contexts: {}", status.total_contexts);
println!("Active operations: {}", status.active_count);
```

--------------------------------

### Agent Model Templating Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/draft/the-agent-format-2.md

Demonstrates how to use a templated input parameter for the 'model' field within an agent manifest. This allows dynamic model selection based on input.

```json
{
  "name": "my-agent",
  "model": ${model-to-use}
}
```

--------------------------------

### PreToolUse Hook Event Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/hooks.md

Example of a hook event for the 'preToolUse' type, which runs before tool execution. It can validate and block tool usage. This example shows a file system read operation.

```json
{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "fs_read",
  "tool_input": {
    "operations": [
      {
        "mode": "Line",
        "path": "/current/working/directory/docs/hooks.md"
      }
    ]
  }
}
```

--------------------------------

### MCP Tool Hook Event Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/hooks.md

Example of a hook event for a tool from an MCP server, using the namespaced format for the tool name. This example is for a 'postgres/query' tool.

```json
{
  "hook_event_name": "preToolUse",
  "cwd": "/current/working/directory",
  "tool_name": "@postgres/query",
  "tool_input": {
    "sql": "SELECT * FROM orders LIMIT 10;"
  }
}
```

--------------------------------

### Toggle Experimental Features with /experiment

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md

Use the `/experiment` command to manage experimental features. This command opens an interactive menu to view, toggle, and get descriptions of experiments.

```bash
/experiment
```

--------------------------------

### Start Amazon Q Chat Session

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Launches an interactive AI chat session. Options include specifying an agent, a custom prompt, resuming a previous conversation, or automatically trusting tool file edits.

```bash
q chat
```

```bash
q chat --agent my-custom-agent
```

```bash
q chat "Help me write a Python script to process CSV files"
```

```bash
q chat --resume
```

```bash
q chat --trust-tools
```

--------------------------------

### Stop Hook Event Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/hooks.md

Example of a hook event for the 'stop' type, which runs when the assistant finishes responding. This is useful for post-processing tasks.

```json
{
  "hook_event_name": "stop",
  "cwd": "/current/working/directory"
}
```

--------------------------------

### Migrate Context File Paths to File URIs

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/legacy-profile-to-agent-migration.md

Context files configured under the 'resources' field now use file URIs. This example shows the transformation from profile paths to agent file URIs.

```json
{
    "paths": [
        "~/my-files/**/*.txt"
    ]
}
```

```json
{
    "resources": [
        "file://~/my-files/**/*.txt"
    ]
}
```

--------------------------------

### UserPromptSubmit Hook Event Example

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/hooks.md

Example of a hook event for the 'userPromptSubmit' type, which runs when a user submits a prompt. The output is added to the conversation context.

```json
{
  "hook_event_name": "userPromptSubmit",
  "cwd": "/current/working/directory",
  "prompt": "user's input prompt"
}
```

--------------------------------

### Example: Keeping Useful Information with Tangent Mode Tail

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md

Demonstrates using `/tangent tail` to exit Tangent Mode after asking about common Python debugging techniques, preserving that specific question and answer for the main conversation.

```bash
> Help me debug this Python error

I can help you debug that. Could you share the error message?

> /tangent
Created a conversation checkpoint (↯).

↯ > What are the most common Python debugging techniques?

Here are the most effective Python debugging techniques:
1. Use print statements strategically
2. Leverage the Python debugger (pdb)...

↯ > /tangent tail
Restored conversation from checkpoint (↯) with last conversation entry preserved.

> Here's my error: TypeError: unsupported operand type(s)...

# The preserved entry (question + answer about debugging techniques) is now part of main conversation
```

--------------------------------

### Clone Amazon Q Developer CLI Repository

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/README.md

Clone the official Amazon Q Developer CLI repository from GitHub to start contributing.

```shell
git clone https://github.com/aws/amazon-q-developer-cli.git
```

--------------------------------

### Grant Access to Local Resources with resources

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

The `resources` field gives an agent access to local resources. Currently, only file resources are supported, and all resource paths must start with `file://`. Resources can include specific files, glob patterns, or absolute/relative paths.

```json
{
  "resources": [
    "file://AmazonQ.md",
    "file://README.md",
    "file://.amazonq/rules/**/*.md"
  ]
}
```

--------------------------------

### Create a Custom Default Agent File

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/default-agent-behavior.md

Instructions on creating a custom default agent by placing a file named `q_cli_default` in specific directories to override the built-in default configuration.

```bash
# Create a custom default agent by placing an agent file with the name `q_cli_default` in either:
# - .amazonq/cli-agents/ (local)
# - ~/.aws/amazonq/cli-agents/ (global)

```

--------------------------------

### Initialize Client with No File Limit

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Initializes the semantic search client with no file limit. Use this with caution as it can lead to resource exhaustion.

```rust
// No limit (use with caution!)
let config = SemanticSearchConfig::with_max_files(usize::MAX);
let client = SemanticSearchClient::with_config(path, config)?;
```

--------------------------------

### Initialize Client with Default File Limit

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Initializes the semantic search client with the default file limit of 5,000 files per directory.

```rust
// Default limit (5,000 files)
let client = SemanticSearchClient::new_with_default_dir()?;
```

--------------------------------

### Initialize Client with Custom File Limit

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Initializes the semantic search client with a custom maximum number of files for larger projects.

```rust
// Custom limit for larger projects
let config = SemanticSearchConfig::with_max_files(15000);
let client = SemanticSearchClient::with_config(path, config)?;
```

--------------------------------

### Update Hook Triggers for Agents

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/legacy-profile-to-agent-migration.md

Hook triggers have been updated for agents. 'conversation_start' is now 'agentSpawn', and 'per_prompt' is now 'userPromptSubmit'. This example shows the new format.

```json
{
    "hooks": {
        "sleep_conv_start": {
            "trigger": "conversation_start",
            "type": "inline",
            "disabled": false,
            "timeout_ms": 30000,
            "max_output_size": 10240,
            "cache_ttl_seconds": 0,
            "command": "echo Conversation start hook"
        },
        "hello_world": {
            "trigger": "per_prompt",
            "type": "inline",
            "disabled": false,
            "timeout_ms": 30000,
            "max_output_size": 10240,
            "cache_ttl_seconds": 0,
            "command": "echo Per prompt hook"
        }
    }
}
```

```json
{
    "hooks": {
        "userPromptSubmit": [
            {
                "command": "echo Per prompt hook",
                "timeout_ms": 30000,
                "max_output_size": 10240,
                "cache_ttl_seconds": 0
            }
        ],
        "agentSpawn": [
            {
                "command": "echo Conversation start hook",
                "timeout_ms": 30000,
                "max_output_size": 10240,
                "cache_ttl_seconds": 0
            }
        ]
    }
}
```

--------------------------------

### Include All Tools Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

A shorthand configuration to include all available tools, both built-in and from MCP servers, using a wildcard.

```json
{
  "tools": ["*"]
}
```

--------------------------------

### Basic Knowledge Management Commands

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Add a project to the knowledge base and display all knowledge entries. These commands are used after enabling the knowledge feature.

```bash
/knowledge add --name myproject --path /path/to/project
```

```bash
/knowledge show
```

--------------------------------

### Create Async Semantic Search Client

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Instantiate an asynchronous client with default settings, a custom directory, or custom configuration. Ensure the directory path is valid.

```rust
let client = AsyncSemanticSearchClient::new_with_default_dir().await?;
```

```rust
let client = AsyncSemanticSearchClient::new("/path/to/storage").await?;
```

```rust
let config = SemanticSearchConfig::default()
    .set_max_files(10000)      // Allow up to 10,000 files
    .set_chunk_size(1024);     // Custom chunk size
let client = AsyncSemanticSearchClient::with_config("/path/to/storage", config).await?;
```

--------------------------------

### Initialize Checkpointing

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md

Manually enable checkpoints for file change tracking in non-git directories.

```bash
/checkpoint init
```

--------------------------------

### Show Knowledge Base

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md

Display the current contents of the knowledge base, showing all added files, directories, and text content.

```bash
/knowledge show
```

--------------------------------

### Chainable Configuration for File Limits and Chunk Size

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Demonstrates chainable configuration for setting maximum files and chunk size.

```rust
// Chainable configuration
let config = SemanticSearchConfig::default()
    .set_max_files(10000)
    .set_chunk_size(1024);
```

--------------------------------

### Create a TODO list with read-only tasks

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/todo-lists.md

Use this prompt to ask Amazon Q to create a TODO list with a specified number of read-only tasks. Q will confirm and then use the `todo_list` tool to create it.

```bash
> Make a todo list with 3 read-only tasks.

> I'll create a todo list with 3 read-only tasks for you.

🛠️  Using tool: todo_list (trusted)
 ⋮ 
 ● TODO:
[ ] Review project documentation
[ ] Check system status
[ ] Read latest updates
 ⋮ 
 ● Completed in 0.4s
```

--------------------------------

### Add Files or Directories to Knowledge Base

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Add files or directories to your knowledge base for recursive indexing. Use `--name` and `--path` for required parameters. Optional `--include`, `--exclude` patterns, and `--index-type` can be specified.

```bash
/knowledge add --name "project-docs" --path /path/to/documentation
```

```bash
/knowledge add -n "config-files" -p /path/to/config.json
```

```bash
/knowledge add --name "fast-search" --path /path/to/logs --index-type Fast
```

```bash
/knowledge add -n "semantic-search" -p /path/to/docs --index-type Best
```

--------------------------------

### Create Local Project Agent

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-file-locations.md

Use this command to create a local agent configuration file for the current project. Ensure the .amazonq/cli-agents/ directory exists.

```bash
mkdir -p .amazonq/cli-agents
cat > .amazonq/cli-agents/project-helper.json << 'EOF'
{
  "description": "Helper agent for this specific project",
  "tools": ["fs_read", "fs_write", "execute_bash"],
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ]
}
EOF
```

--------------------------------

### File URI Prompt Configuration (Absolute Path)

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

References an external prompt file using an absolute file URI. The path is used as-is.

```json
{
  "prompt": "file:///Users/developer/shared-prompts/rust-specialist.md"
}
```

--------------------------------

### Add Knowledge Base Entry with Multiple Include Patterns

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Add a knowledge base entry for documentation and text files, excluding node modules. This command indexes markdown, text files, and excludes development dependencies.

```bash
/knowledge add "docs" /path/to/project --include "**/*.md" --include "**/*.txt" --exclude "node_modules/**"
```

--------------------------------

### Add Knowledge Base Entry with Include Pattern

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Add a knowledge base entry for documentation files using an include pattern. This command indexes all markdown files within the specified project path.

```bash
/knowledge add "docs-only" /path/to/project --include "**/*.md"
```

--------------------------------

### Enable Knowledge Feature

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Enable the experimental knowledge feature in Amazon Q CLI. This is a beta feature and must be explicitly enabled before use.

```bash
q settings chat.enableKnowledge true
```

--------------------------------

### Configure Default Include Patterns

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Set the default include patterns for new knowledge base entries. This specifies which files are included by default.

```bash
q settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md"]'
```

--------------------------------

### Configure Hooks System

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Set up custom commands to execute at specific agent lifecycle trigger points. Commands can include timeouts and matchers for specific tools.

```json
{
  "hooks": {
    "agentSpawn": [
      {
        "command": "echo 'Agent started at $(date)' >> /tmp/agent.log"
      },
      {
        "command": "git fetch --all --prune"
      }
    ],

    "userPromptSubmit": [
      {
        "command": "ls -la",
        "timeout_ms": 5000
      }
    ],

    "preToolUse": [
      {
        "matcher": "execute_bash",
        "command": "{ echo \"$(date) - Bash:\"; cat; } >> /tmp/bash_audit.log"
      },
      {
        "matcher": "use_aws",
        "command": "{ echo \"$(date) - AWS:\"; cat; } >> /tmp/aws_audit.log"
      },
      {
        "matcher": "@postgres/query",
        "command": "python3 validate_sql.py"
      }
    ],

    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      },
      {
        "matcher": "fs_*",
        "command": "echo 'File operation completed'"
      }
    ],

    "stop": [
      {
        "command": "cargo test --quiet 2>/dev/null || echo 'Tests may need attention'"
      }
    ]
  }
}
```

--------------------------------

### Compile and Run Amazon Q CLI

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/README.md

Commands to compile, run, test, lint, and format the Amazon Q CLI project locally.

```shell
cargo run --bin chat_cli
cargo test
cargo clippy
cargo +nightly fmt
```

```shell
cargo run --bin chat_cli -- {subcommand}
```

```shell
cargo run --bin chat_cli -- login
```

--------------------------------

### File URI Prompt Configuration (Relative Path)

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

References an external prompt file using a relative file URI. The path is resolved relative to the agent configuration file's directory.

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

--------------------------------

### Custom Index Types with Embedding Backends

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Shows how to initialize the `SemanticSearchClient` with different embedding types based on the target operating system and architecture. This allows for optimization of embedding generation performance.

```rust
// Use ONNX (fastest, used on macOS and Windows)
#[cfg(any(target_os = "macos", target_os = "windows"))]
let client = SemanticSearchClient::with_embedding_type(
    "/path/to/storage",
    EmbeddingType::Onnx,
)?;

// Use Candle (used on Linux non-ARM)
#[cfg(all(target_os = "linux", not(target_arch = "aarch64")))]
let client = SemanticSearchClient::with_embedding_type(
    "/path/to/storage",
    EmbeddingType::Candle,
)?;

// Use BM25 (used on Linux ARM64)
#[cfg(all(target_os = "linux", target_arch = "aarch64"))]
let client = SemanticSearchClient::with_embedding_type(
    "/path/to/storage",
    EmbeddingType::BM25,
)?;
```

--------------------------------

### Create Global General Agent

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-file-locations.md

This command creates a global agent configuration file in the user's home directory, making it accessible from anywhere.

```bash
mkdir -p ~/.aws/amazonq/cli-agents
cat > ~/.aws/amazonq/cli-agents/general-helper.json << 'EOF'
{
  "description": "General purpose assistant",
  "tools": ["*"],
  "allowedTools": ["fs_read"]
}
EOF
```

--------------------------------

### Tools Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

Lists all tools available to the agent, including built-in tools and tools from MCP servers. Wildcards and prefixes can be used to include multiple tools.

```json
{
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "@git",
    "@rust-analyzer/check_code"
  ]
}
```

--------------------------------

### Resume a TODO list

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/todo-lists.md

Use the `/todos resume` command to display an interactive menu of TODO lists. Selecting a list loads it back into the chat session, allowing Q to continue tasks from where it left off.

```bash
> /todos resume

⟳ Resuming: Read-only tasks for information gathering

🛠️  Using tool: todo_list (trusted)
 ⋮ 
 ● TODO:
[x] Review project documentation
[ ] Check system status
[ ] Read latest updates
 ⋮ 
 ● Completed in 0.1s
```

--------------------------------

### Index Subdirectories Separately vs. Increase Limit

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Illustrates two strategies for handling large codebases: indexing important subdirectories separately or increasing the file limit for the entire workspace.

```rust
// Instead of indexing the entire workspace
// let context = client.add_context_from_directory("/workspace", ...); // Might fail!

// Index important subdirectories separately
let src_context = client.add_context_from_directory("/workspace/src", "Source Code", "Main source code", true, None)?;
let docs_context = client.add_context_from_directory("/workspace/docs", "Documentation", "Project docs", true, None)?;
let tests_context = client.add_context_from_directory("/workspace/tests", "Tests", "Test files", true, None)?;

// Or increase the limit for the entire workspace
let config = SemanticSearchConfig::with_max_files(25000);
let client = SemanticSearchClient::with_config(path, config)?;
let workspace_context = client.add_context_from_directory("/workspace", "Full Workspace", "Complete codebase", true, None)?;
```

--------------------------------

### Configure Tool Permissions

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Define allowed and denied commands and paths for built-in tools like bash, file system access, and AWS service interactions. Set autoAllowReadonly and denyByDefault flags as needed.

```json
{
  "toolsSettings": {
    "execute_bash": {
      "allowedCommands": [
        "git status",
        "git fetch",
        "git log.*",
        "cargo build.*",
        "cargo test.*",
        "npm (run|install|test).*"
      ],
      "deniedCommands": [
        "git push.*",
        "git commit.*",
        "rm -rf.*",
        "sudo.*"
      ],
      "autoAllowReadonly": true,
      "denyByDefault": false
    },

    "fs_read": {
      "allowedPaths": [
        "~/projects",
        "./src/**",
        "./tests/**"
      ],
      "deniedPaths": [
        "~/.ssh/**",
        "~/.aws/credentials",
        "/etc/passwd"
      ]
    },

    "fs_write": {
      "allowedPaths": [
        "./src/**",
        "./tests/**",
        "./docs/**"
      ],
      "deniedPaths": [
        "./.git/**",
        "./node_modules/**"
      ]
    },

    "use_aws": {
      "allowedServices": ["s3", "lambda", "dynamodb", "cloudwatch"],
      "deniedServices": ["iam", "organizations"],
      "autoAllowReadonly": true
    }
  }
}
```

--------------------------------

### Delegate Tasks with Amazon Q

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/experiments.md

Use natural language to delegate tasks to background agents. Tasks can be launched, their status checked, and available agents listed.

```text
"Delegate a task to create a snake game in the test folder"
"Check the status of the rust-agent task"
"What agents are available for delegation?"
```

--------------------------------

### Specify Agent via Command Line

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/default-agent-behavior.md

Use the `--agent` flag to explicitly select an agent for a Q CLI session. This takes precedence over any default agent settings.

```bash
q chat --agent my-custom-agent
```

--------------------------------

### Combined Include and Exclude Patterns for File Indexing

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Demonstrates how to use both `include_patterns` and `exclude_patterns` in `AddContextRequest` for fine-grained control over file indexing. This allows for precise inclusion of certain file types while excluding specific subdirectories or test files.

```rust
let request = AddContextRequest {
    // ... other fields
    include_patterns: Some(vec![
        "**/*.rs".to_string(),
        "**/*.toml".to_string(),
        "**/*.md".to_string(),
    ]),
    exclude_patterns: Some(vec![
        "target/**".to_string(),
        "**/tests/**".to_string(),  // Skip test files
        "**/*_test.rs".to_string(), // Skip test files
    ]),
};
```

--------------------------------

### Inline Prompt Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/agent-format.md

Sets a high-level context for the agent using inline text, similar to a system prompt.

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

--------------------------------

### Configure Default Include/Exclude Patterns

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Set default patterns for including and excluding files when adding to the knowledge base. These defaults are used if explicit patterns are not provided in the 'add' command.

```bash
q settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.py"]'
```

```bash
q settings knowledge.defaultExcludePatterns '["target/**", "__pycache__/**"]'
```

```bash
# This will use the default patterns
/knowledge add "my-project" /path/to/project
```

--------------------------------

### Configure MCP Servers for Amazon Q

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Extends agent capabilities by adding, listing, checking status, removing, or importing Model Context Protocol (MCP) servers. Servers can be global, agent-specific, or configured with environment variables.

```bash
q mcp add --name fetch --command "npx" --args "@anthropic/mcp-fetch"
```

```bash
q mcp add --name git --command "git-mcp" --agent my-agent --timeout 120000
```

```bash
q mcp add --name db --command "postgres-mcp" --env "DATABASE_URL=postgres://localhost/mydb"
```

```bash
q mcp list
```

```bash
q mcp list workspace
```

```bash
q mcp list global
```

```bash
q mcp status --name fetch
```

```bash
q mcp remove --name fetch
```

```bash
q mcp import --file ./servers.json --force
```

--------------------------------

### Tool Settings Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/draft/the-agent-format-2.md

Provides specific configurations for tools. Settings are tool-specific and may require consulting tool documentation.

```json
{
  "toolsSettings": {
    "fs-write": {
      "allowedPaths": [".", "/var/www/**"]
    },
    "@my-enterprise-mcp.my-tool": {
      "some-configuration-value": true
    }
  }
}
```

--------------------------------

### Configure Semantic Search Client

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/crates/semantic-search-client/README.md

Customize search behavior using `SemanticSearchConfig`. Options include chunk size, overlap, default results, model name, timeout, base directory, and max files. Builder methods and a specific `with_max_files` constructor are available.

```rust
let config = SemanticSearchConfig {
    chunk_size: 512,           // Size of text chunks for processing
    chunk_overlap: 128,        // Overlap between chunks
    default_results: 5,        // Default number of search results
    model_name: "all-MiniLM-L6-v2".to_string(),
    timeout: 30000,            // 30 seconds
    base_dir: PathBuf::from("/path/to/storage"),
    max_files: 5000,          // Maximum files allowed in a directory
};
```

```rust
// Or use builder methods
let config = SemanticSearchConfig::default()
    .set_max_files(10000)     // Custom file limit
    .set_chunk_size(1024)     // Custom chunk size
    .set_chunk_overlap(256);  // Custom overlap
```

```rust
// Just set file limit
let config = SemanticSearchConfig::with_max_files(15000);
```

--------------------------------

### Add Knowledge Base Entry with Include and Exclude Patterns

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Add a knowledge base entry for Rust code, excluding files in the target directory. This command indexes all Rust files while ignoring build artifacts.

```bash
/knowledge add "rust-code" /path/to/project --include "*.rs" --exclude "target/**"
```

--------------------------------

### Configure Use_aws Tool Settings

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/built-in-tools.md

Specify allowed and denied AWS services, and whether to auto-allow read-only operations for the use_aws tool.

```json
{
  "toolsSettings": {
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2"],
      "deniedServices": ["eks", "rds"],
      "autoAllowReadonly": true
    }
  }
}
```

--------------------------------

### Troubleshoot Tangent Mode Not Working

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/tangent-mode.md

If Tangent Mode is not functioning, ensure it is enabled either via the `/experiment` command or by setting `chat.enableTangentMode` to true in the Q CLI settings.

```bash
# Enable via experiment (select from list)
/experiment

# Or enable via settings
q settings chat.enableTangentMode true
```

--------------------------------

### Configure Maximum Files per Knowledge Base

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/knowledge-management.md

Set the maximum number of files that can be indexed per knowledge base. This helps manage resource usage.

```bash
q settings knowledge.maxFiles 10000
```

--------------------------------

### Manage Amazon Q Settings

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Configures CLI behavior, tools, features, and UI preferences. Settings are persistent and can be viewed, modified, deleted, or opened in an editor.

```bash
q settings list
```

```bash
q settings list --all
```

```bash
q settings chat.defaultAgent
```

```bash
q settings chat.defaultAgent "my-custom-agent"
```

```bash
q settings chat.enableKnowledge true
```

```bash
q settings chat.enableTangentMode true
```

```bash
q settings --delete chat.defaultAgent
```

```bash
q settings open
```

--------------------------------

### Manage Knowledge Bases

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Commands for managing persistent knowledge bases for semantic search. Includes adding, showing, updating, removing, and cancelling indexing for knowledge bases.

```bash
# Enable knowledge feature
q settings chat.enableKnowledge true

# Add project to knowledge base with semantic search
/knowledge add --name "project-docs" --path /path/to/documentation --index-type Best

# Add with fast lexical search (BM25)
/knowledge add --name "logs" --path /var/log/app --index-type Fast

# Add with file filtering
/knowledge add --name "rust-code" --path /path/to/project --include "*.rs" --exclude "target/**"

# View all knowledge bases and indexing status
/knowledge show

# Update existing knowledge base
/knowledge update /path/to/updated/project

# Remove knowledge base
/knowledge remove "project-docs"

# Cancel background indexing
/knowledge cancel all

# Clear all knowledge bases
/knowledge clear
```

```bash
# Configure knowledge base defaults
q settings knowledge.maxFiles 10000
q settings knowledge.chunkSize 1024
q settings knowledge.indexType Best
q settings knowledge.defaultIncludePatterns '["**/*.rs", "**/*.md", "**/*.py"]'
q settings knowledge.defaultExcludePatterns '["target/**", "node_modules/**", ".git/**"]'
```

--------------------------------

### Local MCP Server Configuration

Source: https://github.com/aws/amazon-q-developer-cli/blob/main/docs/draft/the-agent-format-2.md

Defines a local MCP server with command, arguments, transport, and environment variables. Requires 'command' and 'transport'.

```json
{
  "type": "object",
  "properties": {
    "command": {
      "type": "string",
      "description": "The command to execute to start the MCP server"
    },
    "args": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Arguments to pass to the command"
    },
    "transport": {
      "type": "string",
      "enum": ["stdio", "streamable-http"],
      "description": "The transport protocol to use"
    },
    "env": {
      "type": "object",
      "description": "Environment variables to set for the server"
    }
  },
  "required": ["command", "transport"]
}
```

--------------------------------

### Agent Configuration File Format

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Define custom agents with specific tools, permissions, MCP servers, and prompts. This JSON structure outlines the agent's behavior and capabilities.

```json
{
  "name": "aws-infrastructure-agent",
  "description": "Specialized agent for AWS infrastructure management",
  "prompt": "You are an expert AWS infrastructure specialist. Focus on best practices for security, cost optimization, and reliability.",

  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["@anthropic/mcp-fetch"],
      "timeout": 60000
    },
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    }
  },

  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@git",
    "@fetch/fetch_url"
  ],

  "allowedTools": [
    "fs_read",
    "fs_*",
    "@git/git_status",
    "@fetch"
  ],

  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["~/projects/**", "./src/**"],
      "deniedPaths": ["/etc/**", "~/.ssh/**"]
    },
    "execute_bash": {
      "allowedCommands": ["git status", "git diff.*", "cargo.*", "npm.*"],
      "deniedCommands": ["rm -rf.*", "sudo.*"],
      "autoAllowReadonly": true
    },
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2", "dynamodb"],
      "deniedServices": ["iam"],
      "autoAllowReadonly": true
    }
  },

  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],

  "hooks": {
    "agentSpawn": [
      { "command": "git status --short" }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ]
  },

  "model": "claude-sonnet-4",
  "useLegacyMcpJson": true
}
```

--------------------------------

### Agent Configuration File Format

Source: https://context7.com/aws/amazon-q-developer-cli/llms.txt

Defines the structure for creating custom agents with specific tools, permissions, MCP servers, and prompts.

```APIDOC
## Agent Configuration

### Description
This section describes the format of the agent configuration file, which allows for the creation of custom agents with specific tools, permissions, MCP servers, and prompts.

### Configuration Fields
- **name** (string) - The name of the agent.
- **description** (string) - A description of the agent's purpose.
- **prompt** (string) - The system prompt for the agent.
- **mcpServers** (object) - Configuration for Message Communication Protocol (MCP) servers.
  - **fetch** (object) - Configuration for the fetch MCP server.
    - **command** (string) - The command to run the MCP server.
    - **args** (array) - Arguments for the command.
    - **timeout** (integer) - Timeout in milliseconds.
  - **git** (object) - Configuration for the git MCP server.
    - **command** (string) - The command to run the MCP server.
    - **args** (array) - Arguments for the command.
    - **env** (object) - Environment variables for the MCP server.
- **tools** (array) - A list of available tools for the agent.
- **allowedTools** (array) - A list of tools explicitly allowed for the agent.
- **toolsSettings** (object) - Settings for specific tools.
  - **fs_write** (object) - Settings for the fs_write tool.
    - **allowedPaths** (array) - Paths allowed for file writing.
    - **deniedPaths** (array) - Paths denied for file writing.
  - **execute_bash** (object) - Settings for the execute_bash tool.
    - **allowedCommands** (array) - Bash commands allowed.
    - **deniedCommands** (array) - Bash commands denied.
    - **autoAllowReadonly** (boolean) - Whether to automatically allow readonly commands.
  - **use_aws** (object) - Settings for the use_aws tool.
    - **allowedServices** (array) - AWS services allowed.
    - **deniedServices** (array) - AWS services denied.
    - **autoAllowReadonly** (boolean) - Whether to automatically allow readonly AWS operations.
- **resources** (array) - A list of resources the agent can access.
- **hooks** (object) - Hooks for agent lifecycle events.
  - **agentSpawn** (array) - Commands to run when the agent spawns.
  - **postToolUse** (array) - Commands to run after a tool is used.
- **model** (string) - The language model to use.
- **useLegacyMcpJson** (boolean) - Whether to use legacy MCP JSON format.

### Example Configuration
```json
{
  "name": "aws-infrastructure-agent",
  "description": "Specialized agent for AWS infrastructure management",
  "prompt": "You are an expert AWS infrastructure specialist. Focus on best practices for security, cost optimization, and reliability.",
  "mcpServers": {
    "fetch": {
      "command": "npx",
      "args": ["@anthropic/mcp-fetch"],
      "timeout": 60000
    },
    "git": {
      "command": "git-mcp",
      "args": [],
      "env": {
        "GIT_CONFIG_GLOBAL": "/dev/null"
      }
    }
  },
  "tools": [
    "fs_read",
    "fs_write",
    "execute_bash",
    "use_aws",
    "@git",
    "@fetch/fetch_url"
  ],
  "allowedTools": [
    "fs_read",
    "fs_*",
    "@git/git_status",
    "@fetch"
  ],
  "toolsSettings": {
    "fs_write": {
      "allowedPaths": ["~/projects/**", "./src/**"],
      "deniedPaths": ["/etc/**", "~/.ssh/**"]
    },
    "execute_bash": {
      "allowedCommands": ["git status", "git diff.*", "cargo.*", "npm.*"],
      "deniedCommands": ["rm -rf.*", "sudo.*"],
      "autoAllowReadonly": true
    },
    "use_aws": {
      "allowedServices": ["s3", "lambda", "ec2", "dynamodb"],
      "deniedServices": ["iam"],
      "autoAllowReadonly": true
    }
  },
  "resources": [
    "file://README.md",
    "file://docs/**/*.md"
  ],
  "hooks": {
    "agentSpawn": [
      { "command": "git status --short" }
    ],
    "postToolUse": [
      {
        "matcher": "fs_write",
        "command": "cargo fmt --all"
      }
    ]
  },
  "model": "claude-sonnet-4",
  "useLegacyMcpJson": true
}
```
```