How aws/amazon-q-developer-cli works
Project Type and Purpose
• This is an open-source, multi-crate Rust monorepo that produces the “Amazon Q” command-line tool. Its primary purpose is to deliver a terminal-based IDE-style autocomplete and chat experience by:
• Invoking AWS Q-Developer service APIs (via generated service clients under crates/amzn-*).
• Managing natural-language chat flows (chat_cli binary in crates/cli).
• Persisting conversation history and context locally (SQLite).
• Streaming events for long-polling and agentic execution.
• Exposing extension points for VSCode/JetBrains via a mini MCP (JSON-RPC over stdio or WebSocket).
Top-Level Components
• Front-end binaries
• chat_cli (in crates/cli/src/main.rs): orchestrates commands (q chat, q feed, etc.).
• Core Libraries
• api_client (under crates/cli/src/api_client): request builder, credential management, interceptors.
• AWS Q service SDK crates (crates/amzn-codewhisperer-client, -streaming-client, -consolas-client, -qdeveloper-streaming-client, -toolkit-telemetry-client).
• MCP transport (crates/cli/src/mcp_client): JSON-RPC wire protocol for IDE integrations.
• Local database module (crates/cli/src/database): SQLite migrations, state/history tables.
• External Services
• AWS Q-Developer APIs (CodeWhisperer, Streaming Assistant, Consolas customizations, Q-Developer commands).
• Telemetry endpoints.
• Extensions & IDE Integrations
• VSCode / JetBrains extensions invoking the CLI via MCP.
• Support Artifacts
• Build scripts (scripts/), documentation site (docs/), pre-commit hooks.
Interactions & Data Flow
• User types a q command in the terminal.
→ CLI parser dispatches to a subcommand (chat_cli, feed, issue, etc.).
→ For chat: Chat module collects environment context (cwd, files), loads history from SQLite, renders prompt.
→ API requests are built via api_client, sent to AWS Q APIs through the generated AWS service crates.
→ Streaming responses (events) are handled by the streaming client crates, displayed in real time.
→ Conversations and state updates are written back to the local SQLite DB.
→ If user installs VSCode extension, the CLI runs in MCP server mode, exchanging JSON-RPC over stdio/WebSocket.
Architectural Patterns & Design Principles
• Modular crate-per-service approach: each AWS service has its own generated client crate.
• Thin orchestration layer in the cli crate, separating command parsing, API calling, streaming consumption, and persistence.
• Clear separation between:
• Presentation (terminal UI / MCP protocol)
• Domain logic (chat orchestration)
• Infrastructure (AWS HTTP client, telemetry, database)
• Event-driven streaming: uses event_receiver.rs and event_stream_serde.rs in streaming crates.