Skip to content

Commit 8195486

Browse files
author
docs-generator[bot]
committed
Update docs based on PR #2533
Auto-generated by Q
1 parent 85d78fb commit 8195486

File tree

8 files changed

+1799
-1
lines changed

8 files changed

+1799
-1
lines changed

‎docs-generation/setup_amazon_q.sh

100644100755
File mode changed.

‎docs/SUMMARY.md

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,5 +4,7 @@
44

55
- [The Agent Format](./agent-format.md)
66
- [Built-in Tools](./built-in-tools.md)
7+
- [Slash Commands Reference](./slash-commands.md)
8+
- [To-Do List Management](./todo-lists.md)
79
- [Knowledge Management](./knowledge-management.md)
810
- [Profile to Agent Migration](./legacy-profile-to-agent-migration.md)

‎docs/agent-file-locations.md

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -108,3 +108,23 @@ EOF
108108
## Directory Creation
109109

110110
Q CLI will automatically create the global agents directory (`~/.aws/amazonq/cli-agents/`) if it doesn't exist. However, you need to manually create the local agents directory (`.amazonq/cli-agents/`) in your workspace if you want to use local agents.
111+
112+
## Related Local Storage
113+
114+
In addition to agent configurations, Q CLI stores other workspace-specific data in the `.amazonq/` directory:
115+
116+
### To-Do Lists
117+
To-do lists created by the `todo_list` tool are stored in:
118+
```
119+
.amazonq/cli-todo-lists/
120+
```
121+
122+
These files persist across chat sessions and allow you to resume work on incomplete tasks using the `/todos` slash commands.
123+
124+
### Legacy Configuration
125+
Legacy MCP server configurations may be stored in:
126+
```
127+
.amazonq/mcp.json
128+
```
129+
130+
This file is used when agents have `useLegacyMcpJson` set to `true`.

‎docs/built-in-tools.md

Lines changed: 66 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,6 +8,7 @@ Amazon Q CLI includes several built-in tools that agents can use. This document
88
- [`report_issue`](#report_issue-tool) — Open a GitHub issue template.
99
- [`knowledge`](#knowledge-tool) — Store and retrieve information in a knowledge base.
1010
- [`thinking`](#thinking-tool) — Internal reasoning mechanism.
11+
- [`todo_list`](#todo_list-tool) — Create and manage to-do lists for multi-step tasks.
1112
- [`use_aws`](#use_aws-tool) — Make AWS CLI API calls.
1213

1314
## Execute_bash Tool
@@ -102,6 +103,71 @@ An internal reasoning mechanism that improves the quality of complex tasks by br
102103

103104
This tool has no configuration options.
104105

106+
## Todo_list Tool
107+
108+
Create and manage to-do lists for multi-step tasks. This tool helps track progress on complex tasks by breaking them down into manageable steps and marking completion as work progresses.
109+
110+
The tool automatically creates to-do lists when you give Amazon Q multi-step tasks and tracks completion status. To-do lists are stored locally in the `.amazonq/cli-todo-lists/` directory and persist across chat sessions.
111+
112+
### Commands
113+
114+
#### `create`
115+
Creates a new to-do list with specified tasks and description.
116+
117+
**Required parameters:**
118+
- `tasks`: Array of distinct task descriptions
119+
- `todo_list_description`: Brief summary of the to-do list
120+
121+
#### `complete`
122+
Marks specified tasks as completed and updates context.
123+
124+
**Required parameters:**
125+
- `completed_indices`: Array of 0-indexed task numbers to mark complete
126+
- `context_update`: Important information about completed tasks
127+
- `current_id`: ID of the currently loaded to-do list
128+
129+
**Optional parameters:**
130+
- `modified_files`: Array of file paths that were modified during the task
131+
132+
#### `load`
133+
Loads an existing to-do list by ID.
134+
135+
**Required parameters:**
136+
- `load_id`: ID of the to-do list to load
137+
138+
#### `add`
139+
Adds new tasks to the current to-do list.
140+
141+
**Required parameters:**
142+
- `new_tasks`: Array of new task descriptions
143+
- `insert_indices`: Array of 0-indexed positions where tasks should be inserted
144+
- `current_id`: ID of the currently loaded to-do list
145+
146+
**Optional parameters:**
147+
- `new_description`: Updated description if tasks significantly change the goal
148+
149+
#### `remove`
150+
Removes tasks from the current to-do list.
151+
152+
**Required parameters:**
153+
- `remove_indices`: Array of 0-indexed positions of tasks to remove
154+
- `current_id`: ID of the currently loaded to-do list
155+
156+
**Optional parameters:**
157+
- `new_description`: Updated description if removal significantly changes the goal
158+
159+
### Configuration
160+
161+
This tool has no configuration options and is trusted by default.
162+
163+
### Usage Notes
164+
165+
- To-do lists are automatically created when you give Amazon Q complex, multi-step tasks
166+
- Tasks should be marked as completed immediately after finishing each step
167+
- The tool tracks file modifications and important context for each completed task
168+
- To-do lists persist across chat sessions and can be resumed later
169+
- Use the `/todos` slash command to view, manage, and resume existing to-do lists
170+
105171
## Use_aws Tool
106172

107173
Make AWS CLI API calls with the specified service, operation, and parameters.

‎docs/default-agent-behavior.md

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -49,10 +49,11 @@ If no agent is specified or found, Q CLI uses a built-in default agent with the
4949
The built-in default agent provides:
5050

5151
### Available Tools
52-
- **All tools**: Uses `"*"` wildcard to include all built-in tools and MCP server tools
52+
- **All tools**: Uses `"*"` wildcard to include all built-in tools (including `todo_list`) and MCP server tools
5353

5454
### Trusted Tools
5555
- **fs_read only**: Only the `fs_read` tool is pre-approved and won't prompt for permission
56+
- **todo_list**: The `todo_list` tool is also trusted by default for task management
5657
- All other tools will require user confirmation before execution
5758

5859
### Default Resources

‎docs/slash-commands.md

Lines changed: 234 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,234 @@
1+
# Slash Commands Reference
2+
3+
Amazon Q CLI provides several slash commands that allow you to perform specific actions and manage various features directly within your chat session. Slash commands start with `/` and provide quick access to functionality without needing to exit the chat interface.
4+
5+
## Available Commands
6+
7+
### General Commands
8+
9+
#### `/help`
10+
Display help information about available commands and features.
11+
12+
#### `/quit` or `/exit`
13+
Exit the current chat session and return to the command line.
14+
15+
#### `/clear`
16+
Clear the current conversation history while maintaining the same agent and configuration.
17+
18+
### Agent Management
19+
20+
#### `/agent list`
21+
List all available agents in your current workspace and global directories.
22+
23+
#### `/agent create`
24+
Create a new agent configuration. Opens an interactive wizard to set up agent properties.
25+
26+
#### `/agent switch <name>`
27+
Switch to a different agent for the current session.
28+
29+
### Model Management
30+
31+
#### `/model list`
32+
List all available language models that can be used with Amazon Q.
33+
34+
#### `/model switch <model-id>`
35+
Switch to a different language model for the current session.
36+
37+
### Conversation Management
38+
39+
#### `/save <name>`
40+
Save the current conversation with a given name for later retrieval.
41+
42+
#### `/load <name>`
43+
Load a previously saved conversation by name.
44+
45+
### Subscription Management
46+
47+
#### `/subscribe`
48+
Display your current Amazon Q subscription status and usage information.
49+
50+
### To-Do List Management
51+
52+
The `/todos` command provides comprehensive to-do list management functionality:
53+
54+
#### `/todos view`
55+
View an existing to-do list. Opens an interactive selection menu to choose from available lists.
56+
57+
**Usage:**
58+
```bash
59+
/todos view
60+
```
61+
62+
**Features:**
63+
- Lists all available to-do lists with completion status
64+
- Shows progress indicators (e.g., "3/5 tasks completed")
65+
- Displays completed lists with ✓ and in-progress lists with ✗
66+
- Interactive fuzzy search for easy selection
67+
68+
#### `/todos resume`
69+
Resume working on a selected to-do list. Amazon Q will load the list and continue from where it left off.
70+
71+
**Usage:**
72+
```bash
73+
/todos resume
74+
```
75+
76+
**Features:**
77+
- Automatically loads the selected to-do list state
78+
- Restores previous context and file modifications
79+
- Continues execution from the last completed task
80+
- Provides seamless continuation of interrupted work
81+
82+
#### `/todos delete`
83+
Delete a specific to-do list or all lists.
84+
85+
**Usage:**
86+
```bash
87+
/todos delete # Delete a selected list (interactive)
88+
/todos delete --all # Delete all lists (requires confirmation)
89+
```
90+
91+
**Options:**
92+
- `--all`: Delete all to-do lists without individual selection
93+
94+
#### `/todos clear-finished`
95+
Remove all completed to-do lists to clean up your workspace.
96+
97+
**Usage:**
98+
```bash
99+
/todos clear-finished
100+
```
101+
102+
**Features:**
103+
- Only removes lists where all tasks are marked complete
104+
- Preserves in-progress lists
105+
- Provides confirmation of cleanup actions
106+
107+
### Knowledge Management
108+
109+
The `/knowledge` command provides persistent knowledge base functionality:
110+
111+
#### `/knowledge show`
112+
Display all entries in your knowledge base with detailed information.
113+
114+
#### `/knowledge add <name> <path> [options]`
115+
Add files or directories to your knowledge base.
116+
117+
**Usage:**
118+
```bash
119+
/knowledge add "project-docs" /path/to/documentation
120+
/knowledge add "rust-code" /path/to/project --include "*.rs" --exclude "target/**"
121+
```
122+
123+
**Options:**
124+
- `--include <pattern>`: Include files matching the pattern
125+
- `--exclude <pattern>`: Exclude files matching the pattern
126+
- `--index-type <Fast|Best>`: Choose indexing approach
127+
128+
#### `/knowledge remove <identifier>`
129+
Remove entries from your knowledge base by name, path, or ID.
130+
131+
#### `/knowledge update <path>`
132+
Update an existing knowledge base entry with new content.
133+
134+
#### `/knowledge clear`
135+
Remove all entries from your knowledge base (requires confirmation).
136+
137+
#### `/knowledge status`
138+
View the status of background indexing operations.
139+
140+
#### `/knowledge cancel [operation_id]`
141+
Cancel background operations by ID, or all operations if no ID provided.
142+
143+
## Command Categories
144+
145+
### Interactive Commands
146+
Commands that open selection menus or wizards:
147+
- `/todos view`
148+
- `/todos resume`
149+
- `/todos delete` (without --all)
150+
- `/agent list`
151+
- `/model list`
152+
153+
### Immediate Action Commands
154+
Commands that perform actions directly:
155+
- `/todos clear-finished`
156+
- `/todos delete --all`
157+
- `/knowledge show`
158+
- `/clear`
159+
- `/quit`
160+
161+
### Commands with Arguments
162+
Commands that require additional parameters:
163+
- `/knowledge add <name> <path>`
164+
- `/save <name>`
165+
- `/load <name>`
166+
- `/agent switch <name>`
167+
168+
## Tips and Best Practices
169+
170+
### General Usage
171+
- Use tab completion to discover available commands
172+
- Most commands provide help when used incorrectly
173+
- Commands are case-insensitive
174+
- Use quotes around names or paths with spaces
175+
176+
### To-Do List Management
177+
- Let Amazon Q create to-do lists automatically for complex tasks
178+
- Use `/todos resume` to continue interrupted work sessions
179+
- Regularly use `/todos clear-finished` to maintain a clean workspace
180+
- View lists with `/todos view` to check progress without resuming
181+
182+
### Knowledge Management
183+
- Use descriptive names when adding knowledge bases
184+
- Leverage include/exclude patterns to focus on relevant files
185+
- Monitor indexing progress with `/knowledge status`
186+
- Use `/knowledge clear` sparingly as it removes all data
187+
188+
### Workflow Integration
189+
- Save important conversations before switching agents or models
190+
- Use `/subscribe` to monitor your usage and subscription status
191+
- Combine slash commands with natural language requests for efficient workflows
192+
193+
## Error Handling
194+
195+
### Common Error Messages
196+
197+
**"No to-do lists found"**
198+
- No to-do lists exist in the current directory
199+
- Create complex tasks to generate new lists automatically
200+
201+
**"Agent not found"**
202+
- The specified agent doesn't exist in current workspace or global directories
203+
- Use `/agent list` to see available agents
204+
205+
**"Knowledge base operation failed"**
206+
- Check file permissions and disk space
207+
- Verify paths exist and are accessible
208+
- Use `/knowledge status` to check for ongoing operations
209+
210+
### Recovery Actions
211+
- Most commands can be safely retried after fixing underlying issues
212+
- Use `/clear` to reset conversation state if commands behave unexpectedly
213+
- Check the Amazon Q CLI logs for detailed error information
214+
215+
## Advanced Usage
216+
217+
### Combining Commands
218+
You can use multiple slash commands in sequence:
219+
```bash
220+
/knowledge add "current-project" .
221+
/todos resume
222+
/save "project-work-session"
223+
```
224+
225+
### Automation Integration
226+
Slash commands work well with:
227+
- Shell scripts that launch Q CLI with specific agents
228+
- Workflow automation that saves/loads conversations
229+
- CI/CD pipelines that use knowledge bases for context
230+
231+
### Customization
232+
- Configure default knowledge base patterns with `q settings`
233+
- Set default agents to avoid repeated `/agent switch` commands
234+
- Use agent configurations to pre-configure tool permissions for smoother workflows

0 commit comments

Comments
 (0)