# Table of Contents - [Get started - Docs - Kiro](#get-started-docs-kiro) - [Kiro Interface - Docs - Kiro](#kiro-interface-docs-kiro) - [Your First Project - Docs - Kiro](#your-first-project-docs-kiro) - [Installation - Docs - Kiro](#installation-docs-kiro) - [Keyboard Shortcuts - Docs - Kiro](#keyboard-shortcuts-docs-kiro) - [Codebase Indexing - Docs - Kiro](#codebase-indexing-docs-kiro) - [Specs - Docs - Kiro](#specs-docs-kiro) - [Best practices - Docs - Kiro](#best-practices-docs-kiro) - [Terminal Integration - Docs - Kiro](#terminal-integration-docs-kiro) - [Concepts - Docs - Kiro](#concepts-docs-kiro) - [Autopilot - Docs - Kiro](#autopilot-docs-kiro) - [Chat - Docs - Kiro](#chat-docs-kiro) - [Vibe vs Spec sessions - Docs - Kiro](#vibe-vs-spec-sessions-docs-kiro) - [Steering - Docs - Kiro](#steering-docs-kiro) - [Model Context Protocol (MCP) - Docs - Kiro](#model-context-protocol-mcp-docs-kiro) - [Hook Types - Docs - Kiro](#hook-types-docs-kiro) - [Best Practices - Docs - Kiro](#best-practices-docs-kiro) - [Hook Management - Docs - Kiro](#hook-management-docs-kiro) - [Troubleshooting Hooks - Docs - Kiro](#troubleshooting-hooks-docs-kiro) - [Hook Examples - Docs - Kiro](#hook-examples-docs-kiro) - [Configuration - Docs - Kiro](#configuration-docs-kiro) - [Guides - Docs - Kiro](#guides-docs-kiro) - [Hooks - Docs - Kiro](#hooks-docs-kiro) - [Language Support - Docs - Kiro](#language-support-docs-kiro) - [Best Practices - Docs - Kiro](#best-practices-docs-kiro) - [Servers - Docs - Kiro](#servers-docs-kiro) - [Migrating from VSCode - Docs - Kiro](#migrating-from-vscode-docs-kiro) - [Tools - Docs - Kiro](#tools-docs-kiro) - [Privacy & Security - Docs - Kiro](#privacy-security-docs-kiro) - [Authentication Methods - Docs - Kiro](#authentication-methods-docs-kiro) - [TypeScript and JavaScript - Docs - Kiro](#typescript-and-javascript-docs-kiro) - [Python - Docs - Kiro](#python-docs-kiro) - [Java - Docs - Kiro](#java-docs-kiro) - [Troubleshooting - Docs - Kiro](#troubleshooting-docs-kiro) - [Steering Kiro, and improving the game homepage - Docs - Kiro](#steering-kiro-and-improving-the-game-homepage-docs-kiro) - [Setting up for development on Spirit of Kiro - Docs - Kiro](#setting-up-for-development-on-spirit-of-kiro-docs-kiro) - [Conclusion - Docs - Kiro](#conclusion-docs-kiro) - [Investigating and fixing a subtle bug with physics - Docs - Kiro](#investigating-and-fixing-a-subtle-bug-with-physics-docs-kiro) - [Fixing a complex issue across multiple files - Docs - Kiro](#fixing-a-complex-issue-across-multiple-files-docs-kiro) - [Vibe refactoring is 50% of vibe coding - Docs - Kiro](#vibe-refactoring-is-50-of-vibe-coding-docs-kiro) - [Using specificiations for complex work - Docs - Kiro](#using-specificiations-for-complex-work-docs-kiro) - [Extending Kiro with MCP - Docs - Kiro](#extending-kiro-with-mcp-docs-kiro) - [Managing assets with hooks - Docs - Kiro](#managing-assets-with-hooks-docs-kiro) - [Learn by Playing - Docs - Kiro](#learn-by-playing-docs-kiro) --- # Get started - Docs - Kiro Documentation Get started =========== Public Preview Kiro is currently in public preview. Features and documentation may change as we improve the product. Kiro is an agentic IDE that helps you do your best work with features such as specs, steering, and hooks. [Copied!](https://kiro.dev/docs/getting-started/#get-started) Get started ------------------------------------------------------------------------- Everything you need to begin your journey with Kiro in under 5 minutes. [### Download & Install\ \ Get Kiro running on your machine\ \ Learn more](https://kiro.dev/docs/getting-started/installation/) [### First Project\ \ Learn about Kiro's features through a hands-on project\ \ Learn more](https://kiro.dev/docs/getting-started/first-project/) [Copied!](https://kiro.dev/docs/getting-started/#core-capabilities) Core capabilities ------------------------------------------------------------------------------------- Learn about Kiro's core feature set. [### Specs\ \ Plan and build features using structured specifications.\ \ Learn more](https://kiro.dev/docs/specs/) [### Hooks\ \ Automate repetitive tasks with intelligent triggers.\ \ Learn more](https://kiro.dev/docs/hooks/) [### Agentic chat\ \ Build features through natural conversation with AI.\ \ Learn more](https://kiro.dev/docs/chat/) [### Steering\ \ Guide AI with custom rules and context.\ \ Learn more](https://kiro.dev/docs/steering/) [### MCP Servers\ \ Connect external tools and data sources.\ \ Learn more](https://kiro.dev/docs/mcp/) [### Privacy First\ \ Keep code secure with privacy controls.\ \ Learn more](https://kiro.dev/docs/reference/privacy-and-security/) [Copied!](https://kiro.dev/docs/getting-started/#learning-resources) Learning resources --------------------------------------------------------------------------------------- Master Kiro through hands-on tutorials and comprehensive documentation. [### Your first project\ \ A quick overview of how to use Kiro's feature set.\ \ Learn more](https://kiro.dev/docs/getting-started/first-project/) [### Interactive Tutorial\ \ Build a real project while learning Kiro's features through our game-based tutorial\ \ Learn more](https://kiro.dev/docs/guides/learn-by-playing/) Page updated: July 14, 2025 [Installation](https://kiro.dev/docs/getting-started/installation/) * * * --- # Kiro Interface - Docs - Kiro Documentation Kiro Interface ============== Kiro's interface is designed to provide a seamless coding experience with AI assistance integrated throughout. [Copied!](https://kiro.dev/docs/editor/interface/#main-interface-components) Main Interface Components ------------------------------------------------------------------------------------------------------ Kiro's interface is divided into the following main components: 1. **Editor** - The central workspace where you write and edit code. 2. **Chat Panel** - A dedicated panel for interacting with AI, including asking questions, requesting code modifications, and receiving AI responses. 3. **Views** - The sidebar contains specialized views for managing project files, searching, and source control. 4. **Status Bar** - Provides information about the current file, Git status, and error/warning counts. 5. **Command Palette** - A quick access tool for executing common actions and accessing AI tools. ![The Kiro interface labeled with numbers according to the above list of Kiro interface components.](https://kiro.dev/images/kiro-interface.png) ### [Copied!](https://kiro.dev/docs/editor/interface/#editor) Editor The central workspace where you write and edit code. Features include: * Syntax highlighting for multiple languages * Line numbers and error indicators * Code folding for better organization * Multiple tabs for working across files * Split view support for side-by-side editing ### [Copied!](https://kiro.dev/docs/editor/interface/#chat-panel) Chat Panel You can use the chat panel to: * Ask questions about your code * Request code generation or modifications * Get help with debugging and troubleshooting * Ask for code reviews and optimization suggestions * Include context with # commands (e.g., #File, #Folder) * Generate boilerplate code and templates **To move the chat panel to the opposite side of the IDE** In the top menu bar, choose **View** > **Appearance** > **Move Primary Side Bar Right**. ### [Copied!](https://kiro.dev/docs/editor/interface/#views) Views The sidebar contains several specialized views: * **Explorer** - Navigate your project file structure, see Git status indicators, and access special sections for Specs and MCP servers. * **Search** - Perform global search and replace operations across your entire project. * **Source Control** - Manage Git operations, view changes, and handle commits. * **Run and Debug** - View variables, call stacks, and manage breakpoints during debugging sessions. * **Extensions** - Install and manage IDE extensions. * **Kiro** - A dedicated view for AI-specific features: * Specs overview and management * Agent Hooks management * Agent Steering configuration * MCP (Model Context Protocol) servers ### [Copied!](https://kiro.dev/docs/editor/interface/#status-bar) Status Bar Located at the bottom of the interface, the status bar provides: * Current file information * Git branch and sync status * Error and warning counts * Agent status indicators ### [Copied!](https://kiro.dev/docs/editor/interface/#command-palette) Command Palette Access Kiro's commands quickly by pressing `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) to: * Execute common actions * Access MCP tools * Configure settings * Run agent hooks [Copied!](https://kiro.dev/docs/editor/interface/#navigation-tips) Navigation Tips ---------------------------------------------------------------------------------- * Use [keyboard shortcuts](https://kiro.dev/docs/editor/interface/#keyboard-shortcuts) for faster navigation * Leverage the command palette for quick access to features * Pin frequently used files for easy access * Use split views for comparing or referencing code * Configure workspace settings for personalized experience Page updated: July 14, 2025 [Your first project](https://kiro.dev/docs/getting-started/first-project/) [Keyboard shortcuts](https://kiro.dev/docs/editor/keyboard-shortcuts/) * * * --- # Your First Project - Docs - Kiro Documentation Your First Project ================== This guide walks you through Kiro's essential features by working with a real project. You'll learn how to use steering files, specs, hooks, and MCP servers to enhance your development workflow. [Copied!](https://kiro.dev/docs/getting-started/first-project/#prerequisites) Prerequisites ------------------------------------------------------------------------------------------- Before starting, ensure you have: * [Installed Kiro](https://kiro.dev/docs/getting-started/installation) . * A project to work with (either an existing project or a new one) * Basic familiarity with your project's structure and technology stack [Copied!](https://kiro.dev/docs/getting-started/first-project/#open-your-project) Open Your Project --------------------------------------------------------------------------------------------------- 1. **Launch Kiro** and open your project: * Use `File > Open Folder` to select your project directory * Or drag and drop your project folder into Kiro * Or go to the command line and run `kiro .` from your project directory 2. **Access the Kiro Panel**: * Click the Kiro Ghost icon in the activity bar (left sidebar) * This panel provides access to all of Kiro's AI-powered features 3. **Start a Chat Session**: * The chat pane should be open by default * This opens Kiro's conversational interface where you can interact with the AI [Copied!](https://kiro.dev/docs/getting-started/first-project/#set-up-steering-files) Set Up Steering Files ----------------------------------------------------------------------------------------------------------- Steering files provide context about your project, helping Kiro understand your codebase, conventions, and requirements. To get started choose `Generate Steering Docs` from the Kiro pane. Kiro generates project steering documents for you stored in `.kiro/steering/` that guide Kiro's behavior. They contain information about: * Your product and its purpose * Technical stack and frameworks * Project structure and conventions You can also create custom steering files by clicking the `+` button in the steering section and add things like coding standards, and workflows, and team best practices. Learn about steering [here](https://kiro.dev/docs/steering/) . [Copied!](https://kiro.dev/docs/getting-started/first-project/#build-features-with-specs) Build Features with Specs ------------------------------------------------------------------------------------------------------------------- Specs transform high-level feature ideas into detailed implementation plans through three phases: 1. **Requirements** - User stories with acceptance criteria in EARS notation 2. **Design** - Technical architecture and implementation approach 3. **Tasks** - Discrete, trackable implementation steps ### [Copied!](https://kiro.dev/docs/getting-started/first-project/#create-your-first-spec) Create Your First Spec 1. **Start a New Spec**: * In your chat session, click the **Spec** button * Choose the `+` button in the Kiro panel's Specs section 2. **Enter a feature description**: * Describe your feature in natural language * Example: "Add a user authentication system with login, logout, and password reset functionality" 3. **Follow the Guided Workflow**: * **Requirements Phase**: Kiro will help structure your requirements using EARS notation * **Design Phase**: Technical architecture and component design will be documented * **Implementation Phase**: Discrete tasks will be generated for execution ### [Copied!](https://kiro.dev/docs/getting-started/first-project/#execute-spec-tasks) Execute Spec Tasks Once your spec is complete: 1. **Review Generated Tasks** in the `tasks.md` file 2. **Execute Tasks** by clicking on individual task items 3. **Track Progress** as tasks automatically update to "In Progress" and "Done" Loading image... ![hooks](https://kiro.dev/videos/spec-task.gif) [Copied!](https://kiro.dev/docs/getting-started/first-project/#automate-workflows-with-hooks) Automate Workflows with Hooks --------------------------------------------------------------------------------------------------------------------------- Agent Hooks eliminate manual work by automatically executing predefined actions when: * Files are created, saved, or deleted * Manual triggers are activated * Specific file patterns are modified To get started: 1. **Access Hook Creation**: * Navigate to the **Agent Hooks** section in the Kiro panel * Click the `+` button to create a new hook 2. **Define Hook Behavior**: * Describe what you want automated in natural language * Example: "When I save a React component file, automatically create or update its corresponding test file" 3. **Configure Hook Settings**: * **Event Type**: Choose from File Created, File Saved, File Deleted, or Manual Trigger * **File Pattern**: Specify which files should trigger the hook (e.g., `src/**/*.tsx`) * **Instructions**: Define the specific actions to perform Loading image... ![hooks](https://kiro.dev/videos/hooks.gif) [Copied!](https://kiro.dev/docs/getting-started/first-project/#extend-capabilities-with-mcp) Extend Capabilities with MCP ------------------------------------------------------------------------------------------------------------------------- Model Context Protocol (MCP) allows Kiro to: * Access specialized knowledge bases and documentation * Integrate with external APIs and services * Use domain-specific tools and utilities * Connect to databases and cloud services ### [Copied!](https://kiro.dev/docs/getting-started/first-project/#set-up-mcp) Set Up MCP 1. Open the Kiro panel by clicking the Kiro Ghost icon in the activity bar. First enable MCPs, and then click the edit button (pencil icon) next to MCP in the panel 2. By default, Kiro ships with the [fetch MCP server](https://github.com/modelcontextprotocol/servers/tree/main/src/fetch) in the JSON file. Flip it to `disabled=false` to connect to it. 3. You can aslo **Add any MCP Server** by asking Kiro to add a new server or editing the JSON file directly: json `{ "mcpServers": { "web-search": { "command": "uvx", "args": ["mcp-server-brave-search"], "env": { "BRAVE_API_KEY": "your-api-key-here" }, "disabled": false, "autoApprove": ["search"] } } }` ### [Copied!](https://kiro.dev/docs/getting-started/first-project/#use-mcp-tools) Use MCP Tools Once configured, you can use MCP tools in several ways: * **Direct Questions** * Ask questions that leverage the MCP server's capabilities: * Example: `Search for the latest React 18 best practices` * **Explicit Tool Usage** * Reference specific MCP tools with the #MCP context provider * Example: `#[fetch] fetch` Use the web search to find examples of TypeScript generic constraints\` * **Integration with Other Features** * Combine MCP with hooks and specs: * Example: `Create a hook that uses the web search MCP to find relevant documentation when I create new component files` [Copied!](https://kiro.dev/docs/getting-started/first-project/#next-steps) Next Steps ------------------------------------------------------------------------------------- Now that you've experienced Kiro's core features: * **Try the Interactive Tutorial**: Work through our [hands-on game development tutorial](https://kiro.dev/docs/guides/learn-by-playing) * **Learn more about specs**: Check out the [specs documentation](https://kiro.dev/docs/specs) to learn more about the concepts and how they work * **Join the Community**: Connect with other Kiro users and share your experiences on our [Discord server](https://discord.gg/kirodotdev) Page updated: July 14, 2025 [Installation](https://kiro.dev/docs/getting-started/installation/) [Interface](https://kiro.dev/docs/editor/interface/) * * * --- # Installation - Docs - Kiro Documentation Installation ============ [Copied!](https://kiro.dev/docs/getting-started/installation/#download-kiro) Download Kiro ------------------------------------------------------------------------------------------ Getting started is simple: 1. Go to [kiro.dev](https://kiro.dev/) and download the installer 2. Open the downloaded file and follow the installation instructions for your operating system (Windows, macOS, or Linux). 3. Open Kiro IDE and start coding! [Copied!](https://kiro.dev/docs/getting-started/installation/#first-run) First run ---------------------------------------------------------------------------------- 1. When you open Kiro for the first time you will be asked to login with a provider of your choice that include social and AWS login options. Learn more about the [auth methods](https://kiro.dev/docs/reference/auth-methods) . 2. Once logged in, you can choose to [import your VS Code](https://kiro.dev/docs/guides/migrating-from-vscode) settings and extensions. If you're using another editor, you can skip this step. Select your preferred theme from the available options, then allow Kiro to set up shell integration, enabling the agent to execute commands on your behalf. 3. Finally, you'll arrive at the welcome page. Open a project to get started and proceed with [your first project](https://kiro.dev/docs/getting-started/first-project) . [Copied!](https://kiro.dev/docs/getting-started/installation/#language-support) Language support ------------------------------------------------------------------------------------------------ Kiro supports most popular programming languages. We have guides that help set up your environment and best practices for the following languages: * [TypeScript and JavaScript](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide) * [Java](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide) * [Python](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide) Page updated: July 14, 2025 [Get started](https://kiro.dev/docs/getting-started/) [Your first project](https://kiro.dev/docs/getting-started/first-project/) * * * --- # Keyboard Shortcuts - Docs - Kiro Documentation Keyboard Shortcuts ================== Kiro IDE provides a wide range of keyboard shortcuts to help you work efficiently. This guide covers the most important shortcuts organized by category. [Copied!](https://kiro.dev/docs/editor/keyboard-shortcuts/#general) General --------------------------------------------------------------------------- | Shortcut (Mac) | Shortcut (Windows/Linux) | Description | | --- | --- | --- | | `Cmd+Shift+P` | `Ctrl+Shift+P` | Open Command Palette | | `Cmd+K Cmd+S` | `Ctrl+K Ctrl+S` | Open Keyboard Shortcuts | | `` Ctrl+` `` | `` Ctrl+` `` | Toggle Terminal | | `Cmd+N` | `Ctrl+N` | New File | | `Cmd+W` | `Ctrl+W` | Close Tab | | `Cmd+S` | `Ctrl+S` | Save | | `Cmd+Shift+S` | `Ctrl+Shift+S` | Save As | | `Cmd+Z` | `Ctrl+Z` | Undo | | `Cmd+Shift+Z` | `Ctrl+Shift+Z` | Redo | [Copied!](https://kiro.dev/docs/editor/keyboard-shortcuts/#navigation) Navigation --------------------------------------------------------------------------------- | Shortcut (Mac) | Shortcut (Windows/Linux) | Description | | --- | --- | --- | | `Cmd+P` | `Ctrl+P` | Quick Open File | | `Cmd+O` | `Ctrl+O` | Open File | | `Cmd+K Cmd+O` | `Ctrl+K Ctrl+O` | Open Folder | | `Cmd+Shift+O` | `Ctrl+Shift+O` | Go to Symbol | | `Ctrl+G` | `Ctrl+G` | Go to Line | | `Cmd+F` | `Ctrl+F` | Find | | `Cmd+Shift+F` | `Ctrl+Shift+F` | Find in Files | | `Cmd+B` | `Ctrl+B` | Toggle Sidebar | | `Cmd+\` | `Ctrl+\` | Split Editor | | `Cmd+1/2/3` | `Ctrl+1/2/3` | Focus Editor Group | | `Ctrl+Shift+G` | `Ctrl+Shift+G` | Open Source Control | [Copied!](https://kiro.dev/docs/editor/keyboard-shortcuts/#editing) Editing --------------------------------------------------------------------------- | Shortcut (Mac) | Shortcut (Windows/Linux) | Description | | --- | --- | --- | | `Cmd+X` | `Ctrl+X` | Cut | | `Cmd+C` | `Ctrl+C` | Copy | | `Cmd+V` | `Ctrl+V` | Paste | | `Cmd+/` | `Ctrl+/` | Toggle Comment | | `Option+Up/Down` | `Alt+Up/Down` | Move Line Up/Down | | `Cmd+Shift+K` | `Ctrl+Shift+K` | Delete Line | [Copied!](https://kiro.dev/docs/editor/keyboard-shortcuts/#ai-features) AI Features ----------------------------------------------------------------------------------- | Shortcut (Mac) | Shortcut (Windows/Linux) | Description | | --- | --- | --- | | `Cmd+L` | `Ctrl+L` | Open Chat Session | | `Cmd+I` | `Ctrl+I` | Inline Chat | | `F5` | `F5` | Start Debugging | [Copied!](https://kiro.dev/docs/editor/keyboard-shortcuts/#custom-shortcuts) Custom Shortcuts --------------------------------------------------------------------------------------------- You can customize keyboard shortcuts in Kiro by using the following instructions: 1. Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`). 2. Search for **Keyboard Shortcuts**. 3. Select **Preferences: Open Keyboard Shortcuts**. 4. Select the command that you want to modify. 5. Choose the pencil icon and enter your preferred shortcut. This allows you to create a personalized workflow that matches your preferences and habits from other editors. Page updated: July 14, 2025 [Interface](https://kiro.dev/docs/editor/interface/) [Codebase Indexing](https://kiro.dev/docs/editor/codebase-indexing/) * * * --- # Codebase Indexing - Docs - Kiro Documentation Codebase Indexing ================= Kiro automatically indexes your codebase and documentation to provide intelligent code suggestions, navigation, and context-aware assistance. This guide explains how indexing works and how to manage it. [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#when-indexing-occurs) When Indexing Occurs ---------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#automatic-indexing) Automatic Indexing Kiro performs indexing automatically in these scenarios: 1. **Project Import**: When you first open a project in Kiro, it automatically begins indexing all files in your workspace 2. **File Changes**: When new files are created or added to your project, they are automatically indexed 3. **External Changes**: When files are modified outside of Kiro (e.g., through git operations), they are re-indexed ### [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#manual-indexing) Manual Indexing You can trigger indexing manually when needed using the Command Palette (`Cmd+Shift+P` on macOS or `Ctrl+Shift+P` on Windows/Linux). [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#available-indexing-commands) Available Indexing Commands ------------------------------------------------------------------------------------------------------------------ Kiro provides several commands to manage indexing through the Command Palette: ![Kiro indexing commands in Command Palette](https://kiro.dev/images/kiro-indexing.png) ### [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#codebase-indexing) Codebase Indexing * **`Kiro: Codebase Force Re-Index`**: Forces a complete re-indexing of your entire codebase. Use this when: * You suspect the index is corrupted or incomplete * Major structural changes have been made to your project * Kiro's code suggestions seem outdated * **`Kiro: Rebuild codebase index`**: Completely rebuilds the codebase index from scratch. This is more thorough than force re-indexing and should be used when: * The index appears severely corrupted * You're experiencing persistent issues with code navigation or suggestions ### [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#documentation-indexing) Documentation Indexing * **`Kiro: Docs Index`**: Initiates indexing of documentation files in your project * **`Kiro: Docs Force Re-Index`**: Forces a complete re-indexing of all documentation files [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#monitoring-indexing-progress) Monitoring Indexing Progress -------------------------------------------------------------------------------------------------------------------- You can monitor the indexing process through the Kiro Logs panel: 1. Access the Output panel in Kiro 2. Select "Kiro Logs" from the dropdown menu 3. View real-time indexing progress and status updates ![Kiro Logs showing indexing progress](https://kiro.dev/images/kiro-indexing-logs.png) The logs show: * When indexing starts and completes * Number of files found and processed * Progress percentage for large codebases * Completion time for indexing operations [Copied!](https://kiro.dev/docs/editor/codebase-indexing/#indexed-content) Indexed Content ------------------------------------------------------------------------------------------ Kiro indexes various types of content to provide intelligent assistance: * **Source Code**: All programming language files in your workspace * **Documentation**: Markdown, MDX, and other documentation formats * **Configuration**: Project configuration files and manifests * **Dependencies**: Package definitions and dependency information The indexed data enables features like: * Intelligent code completion * Cross-file navigation * Context-aware suggestions * Documentation lookup * Code refactoring assistance Page updated: July 11, 2025 [Keyboard shortcuts](https://kiro.dev/docs/editor/keyboard-shortcuts/) [Specs](https://kiro.dev/docs/specs/) * * * --- # Specs - Docs - Kiro Documentation Specs ===== [Copied!](https://kiro.dev/docs/specs/#what-are-specs) What are specs? ---------------------------------------------------------------------- Specs or specifications are structured artifacts that formalize the development process for complex features in your application. They provide a systematic approach to transform high-level ideas into detailed implementation plans with clear tracking and accountability. With Kiro's specs, you can: * **Break down requirements** into user stories with acceptance criteria * **Build design docs** with sequence diagrams and architecture plans * **Track implementation progress** across discrete tasks * **Collaborate effectively** between product and engineering teams [Copied!](https://kiro.dev/docs/specs/#quickstart) Quickstart ------------------------------------------------------------- Ready to create your first specification? Here's how to get started: 1. From the Kiro pane, click the `+` button under **Specs**. Alternatively, choose **Spec** from the chat pane. 2. Describe your project idea. 3. Follow the three phase workflow through Requirements → Design → Implementation. ![Creating a specification in Kiro](https://kiro.dev/videos/specs-start.gif) [Copied!](https://kiro.dev/docs/specs/#learn-more) Learn more ------------------------------------------------------------- Dive deeper into Kiro's specification system with these guides: [### Concepts\ \ Learn about the three-phase workflow.\ \ Learn more](https://kiro.dev/docs/specs/concepts/) [### Best Practices\ \ FAQs on best practices when working with specs.\ \ Learn more](https://kiro.dev/docs/specs/best-practices/) Page updated: July 14, 2025 [Codebase Indexing](https://kiro.dev/docs/editor/codebase-indexing/) [Concepts](https://kiro.dev/docs/specs/concepts/) * * * --- # Best practices - Docs - Kiro Documentation Best practices ============== [Copied!](https://kiro.dev/docs/specs/best-practices/#how-do-i-import-existing-requirements) How do I import existing requirements? ----------------------------------------------------------------------------------------------------------------------------------- If your requirements or designs already exist in another system (such as JIRA, Confluence, or Word documents), you have two options: 1. **Using MCP integration**: If your requirements tool has an MCP server that supports STDIO, you can connect directly to import requirements into your spec session. 2. **Manual import**: Simply copy your existing requirements (e.g. `foo-prfaq.md`) into a new file in your repo and open a spec chat session and say `#foo-prfaq.md Generate a spec from it`. Kiro will read your requirements, and generate requirement and design specs. [Copied!](https://kiro.dev/docs/specs/best-practices/#how-do-i-iterate-on-my-specs) How do I iterate on my specs? ----------------------------------------------------------------------------------------------------------------- Kiro's specifications are designed for continuous refinement, allowing you to update and enhance them as your project evolves. This iterative approach ensures that specifications remain synchronized with changing requirements and technical designs, providing a reliable foundation for development. 1. **Update Requirements**: Either modify the `requirements.md` file directly or initiate a spec session and instruct Kiro to add new requirements or design elements. 2. **Update Design**: Navigate to the `design.md` file for your spec and select **Refine**. This action will update both the design documentation and the associated task list to reflect your modified requirements. 3. **Update tasks**: Navigate to the `tasks.md` file and choose **Update tasks**. This will create new tasks that map to the new requirements. [Copied!](https://kiro.dev/docs/specs/best-practices/#how-do-i-share-specs-with-my-team) How do I share specs with my team? --------------------------------------------------------------------------------------------------------------------------- Specs are designed to be version-controlled, making them easily shareable across your team. Store specs directly in your project repository alongside the code they describe. This keeps all project artifacts together and maintains the connection between requirements and implementation. [Copied!](https://kiro.dev/docs/specs/best-practices/#can-i-share-specs-across-multiple-teams) Can I share specs across multiple teams? --------------------------------------------------------------------------------------------------------------------------------------- Yes, you can share specs across multiple teams by leveraging Git submodules or package references. Here are some best practices for managing shared specs across teams: 1. **Create a central specs repository** - Establish a dedicated repository for shared specifications that multiple projects can reference. 2. **Use Git submodules or package references** - Link your central specs to individual projects using Git submodules, package references, or symbolic links depending on your development environment. 3. **Implement cross-repository workflows** - Develop processes for proposing, reviewing, and updating shared specs that affect multiple projects. If you have specific needs for cross-project spec management, please share your requirements on our [GitHub issue tracker](https://github.com/kirodotdev) so we can prioritize features that support your workflow. [Copied!](https://kiro.dev/docs/specs/best-practices/#can-i-start-a-spec-session-from-a-vibe-session) Can I start a spec session from a vibe session? ----------------------------------------------------------------------------------------------------------------------------------------------------- Yes. You can have a vibe conversation and then say `Generate spec`. Kiro will then ask you if you want to start a spec session. If you say yes, it will proceed with generating requirements based on the context of your vibe session. [Copied!](https://kiro.dev/docs/specs/best-practices/#can-i-execute-all-the-tasks-in-my-spec-in-a-single-shot) Can I execute all the tasks in my spec in a single shot? ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- Yes, you can execute all the tasks in your `tasks.md` file by asking the Kiro agent to `Execute all tasks in the spec`. Kiro will start executing all your tasks. Note: we do not recommend doing this as we recommend a task-wise execution to get better results. [Copied!](https://kiro.dev/docs/specs/best-practices/#what-if-some-tasks-are-already-implemented) What if some tasks are already implemented? --------------------------------------------------------------------------------------------------------------------------------------------- When working on an existing codebase, you might find that some tasks in your spec are already complete because a coworker or you ended up doing it in another session. Here are two ways to handle this: **Option 1: Click on Update tasks in your tasks.md** * Open your `tasks.md` file * Click **Update tasks** * Kiro will automatically mark completed tasks. **Option 2: Let Kiro scan for you in a spec chat session** * In a spec session, ask Kiro: "Check which tasks are already complete" * Kiro will analyze your codebase and identify implemented functionality * Kiro will automatically mark completed tasks This keeps your task spec accurate. [Copied!](https://kiro.dev/docs/specs/best-practices/#how-many-specs-can-i-have-in-a-single-repo) How many specs can I have in a single repo? --------------------------------------------------------------------------------------------------------------------------------------------- You can have as many specs as you want in a single repo. We recommend creating multiple specs for different features for your project rather than attempting to just have a single one for your entire codebase. For example, in an e-commerce application, you might organize your specs like this: `.kiro/specs/ ├── user-authentication/ # Login, signup, password reset ├── product-catalog/ # Product listing, search, filtering ├── shopping-cart/ # Add to cart, quantity updates, checkout ├── payment-processing/ # Payment gateway integration, order confirmation └── admin-dashboard/ # Product management, user analytics` This approach allows you to: * Work on features independently without conflicts * Maintain focused, manageable spec documents * Iterate on specific functionality without affecting other areas * Collaborate with team members on different features simultaneously Page updated: July 14, 2025 [Concepts](https://kiro.dev/docs/specs/concepts/) [Chat](https://kiro.dev/docs/chat/) * * * --- # Terminal Integration - Docs - Kiro Documentation Terminal Integration ==================== [Copied!](https://kiro.dev/docs/chat/terminal/#overview) Overview ----------------------------------------------------------------- Transform your development workflow with Kiro's terminal integration. Instead of memorizing command syntax or switching between windows, describe what you want to accomplish and Kiro translates your requests into executable commands, maintains context across operations, and provides a secure approval system that keeps you in control while managing dependencies, navigating git workflows, or exploring your codebase. [Copied!](https://kiro.dev/docs/chat/terminal/#getting-started) Getting Started ------------------------------------------------------------------------------- Simply describe what you want to do in natural language. For example: * "Install the project dependencies" * "Check the git status" * "Find all TypeScript files in the src folder" * "Run the development server" Kiro translates your request into the appropriate terminal command and asks for your approval before executing. You'll review the suggested command and choose to Modify, Reject, Run, or Run and Trust, then see the output directly in chat. Loading image... ![Kiro Terminal Request](https://kiro.dev/images/kiro-terminal-request.png) [Copied!](https://kiro.dev/docs/chat/terminal/#how-it-works) How It Works ------------------------------------------------------------------------- When Kiro suggests a command, you have four options: * **Modify** - Edit the command before running * **Reject** - Cancel execution * **Run** - Execute once * **Run and Trust** - Execute and trust similar commands in the future Loading image... ![Kiro Terminal Approval Workflow](https://kiro.dev/images/kiro-terminal.gif) [Copied!](https://kiro.dev/docs/chat/terminal/#trust-commands) Trust Commands ----------------------------------------------------------------------------- For security, Kiro asks for approval before running any command. You can streamline this process by configuring which commands to trust automatically. ### [Copied!](https://kiro.dev/docs/chat/terminal/#trust-read-only-commands) Trust Read-Only Commands Automatically run safe commands like `ls`, `cat`, `pwd`, `find`, and `grep` without prompts. Loading image... ![Kiro Trust Read Only Command Setting](https://kiro.dev/images/kiro-trust-read-commands.png) ### [Copied!](https://kiro.dev/docs/chat/terminal/#trusted-commands) Trusted Commands Create a custom list of trusted commands using wildcard patterns: * `npm *` - Trust all npm commands * `git status` - Trust only git status * `npm run *` - Trust npm run with any script name You can add commands to this list by choosing `Run and Trust` when prompted, or by manually configuring them in `Settings → Trusted Commands`. These settings can be configured at both the user level (global across all workspaces) and workspace level (specific to your current project). Loading image... ![Kiro Trusted Commands Setting](https://kiro.dev/images/kiro-trust-commands.png) [Copied!](https://kiro.dev/docs/chat/terminal/#advanced-usage) Advanced Usage ----------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/chat/terminal/#using-terminal-context) Using Terminal Context Reference recent terminal output in your conversations with `#Terminal`: `#Terminal analyze the error from the last npm run build` Kiro maintains awareness of command history and outputs, enabling: * **Error Analysis** - Understanding why commands failed * **Output Interpretation** - Explaining complex command results * **Follow-up Actions** - Suggesting next steps based on results [Copied!](https://kiro.dev/docs/chat/terminal/#troubleshooting) Troubleshooting ------------------------------------------------------------------------------- For issues with terminal integration and manual setup instructions, see the [Shell Integration troubleshooting guide](https://kiro.dev/docs/reference/troubleshooting#shell-integration-issues) . Page updated: July 14, 2025 [Vibe vs. Spec](https://kiro.dev/docs/chat/vibe/) [Hooks](https://kiro.dev/docs/hooks/) * * * --- # Concepts - Docs - Kiro Documentation Concepts ======== Specs bridge the gap between conceptual product requirements and technical implementation details, ensuring alignment and reducing development iterations. Kiro generates three key files that form the foundation of each specification: * **requirements.md** - Captures user stories and acceptance criteria in structured EARS notation * **design.md** - Documents technical architecture, sequence diagrams, and implementation considerations * **tasks.md** - Provides a detailed implementation plan with discrete, trackable tasks Loading diagram... [Copied!](https://kiro.dev/docs/specs/concepts/#workflow) Workflow ------------------------------------------------------------------ The workflow follows a logical progression with decision points between phases, ensuring each step is properly completed before moving to the next. * **Requirements Phase** (leftmost section): Define user stories and acceptance criteria in structured EARS notation * **Design Phase** (second section): Document the technical architecture, sequence diagrams, and implementation considerations * **Implementation Planning** (third section): Break down the work into discrete, trackable tasks with clear descriptions and outcomes * **Execution Phase** (rightmost section): Track progress as tasks are completed, with the ability to update and refine the spec as needed Loading diagram... [Copied!](https://kiro.dev/docs/specs/concepts/#requirements) Requirements -------------------------------------------------------------------------- The `requirements.md` file is written in the form of user stories with acceptance criteria in EARS notation. The way you wish your PM would give you requirements! EARS (Easy Approach to Requirements Syntax) notation provides a structured format for writing clear, testable requirements. In a spec's requirements.md file, each requirement follows this pattern: `WHEN [condition/event] THE SYSTEM SHALL [expected behavior]` For example: `WHEN a user submits a form with invalid data THE SYSTEM SHALL display validation errors next to the relevant fields` This structured approach offers several benefits: * **Clarity**: Requirements are unambiguous and easy to understand * **Testability**: Each requirement can be directly translated into test cases * **Traceability**: Individual requirements can be tracked through implementation * **Completeness**: The format encourages thinking through all conditions and behaviors Kiro helps you transform vague feature requests into these well-structured requirements, making the development process more efficient and reducing misunderstandings between product and engineering teams. [Copied!](https://kiro.dev/docs/specs/concepts/#design) Design -------------------------------------------------------------- ![Design documentation in Kiro specs](https://kiro.dev/videos/specs-design.gif) The `design.md` file is where you document technical architecture, sequence diagrams, and implementation considerations. It's a great place to capture the big picture of how the system will work, including the components and their interactions. Kiro's specs offer a structured approach to design documentation, making it easier to understand and collaborate on complex systems. The design.md file is a great place to capture the big picture of how the system will work, including the components and their interactions. Loading diagram... [Copied!](https://kiro.dev/docs/specs/concepts/#implementation-plan) Implementation plan ---------------------------------------------------------------------------------------- The `tasks.md` file is where you provide a detailed implementation plan with discrete, trackable tasks and sub-tasks. Each task is clearly defined, with a clear description, expected outcome, and any necessary resources or dependencies. Kiro's specs offer a structured approach to implementation plans, making it easier to understand and collaborate on complex systems. Kiro provides a task execution interface for `tasks.md` files that displays real-time status updates. Tasks are updated as in-progress or completed, allowing you to efficiently track implementation progress and maintain an up-to-date view of your development status. ![Design documentation in Kiro specs](https://kiro.dev/videos/spec-task.gif) Page updated: July 14, 2025 [Specs](https://kiro.dev/docs/specs/) [Best Practices](https://kiro.dev/docs/specs/best-practices/) * * * --- # Autopilot - Docs - Kiro Documentation Autopilot ========= [Copied!](https://kiro.dev/docs/chat/autopilot/#what-is-autopilot-mode) What is Autopilot Mode? ----------------------------------------------------------------------------------------------- Autopilot mode is Kiro's autonomous execution mode that allows the agent to make code changes across your codebase and complete complex tasks with minimal intervention. It's a key feature that enables Kiro to work more independently on your behalf. [Copied!](https://kiro.dev/docs/chat/autopilot/#how-it-works) How It Works -------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/chat/autopilot/#autopilot-mode-default) Autopilot Mode (Default) Kiro works autonomously to complete tasks end-to-end. It can create files, modify code across multiple locations, run commands, and make architectural decisions without asking for approval at each step. You maintain control through the ability to view all changes, revert everything, or interrupt execution at any time. ### [Copied!](https://kiro.dev/docs/chat/autopilot/#supervised-mode) Supervised Mode Kiro presents each proposed action and waits for your approval before proceeding. You'll see exactly what changes Kiro wants to make and can accept, reject, or modify them. This mode breaks complex tasks into manageable steps with clear checkpoints for feedback. [Copied!](https://kiro.dev/docs/chat/autopilot/#switching-between-modes) Switching Between Modes ------------------------------------------------------------------------------------------------ You can toggle between Autopilot and Supervised modes at any time using the autopilot switch in the chat interface. This flexibility allows you to use the appropriate level of control for different tasks. Loading image... ![Kiro Autopilot Toggle](https://kiro.dev/images/kiro-autopilot-toggle.png) [Copied!](https://kiro.dev/docs/chat/autopilot/#when-to-use-each-mode) When to Use Each Mode -------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/chat/autopilot/#autopilot-mode-is-best-for) Autopilot Mode is best for: * Experienced users familiar with Kiro's capabilities * Repetitive or well-defined tasks * Projects where you want to move quickly * Tasks spanning multiple files or requiring several steps ### [Copied!](https://kiro.dev/docs/chat/autopilot/#supervised-mode-is-best-for) Supervised Mode is best for: * New users getting familiar with Kiro * Critical or sensitive codebases * Learning how Kiro approaches problems * When you want to carefully review each change * Working with unfamiliar code or complex systems You can toggle between these modes at any time based on your current needs and comfort level with the task at hand. [Copied!](https://kiro.dev/docs/chat/autopilot/#kiros-change-management-features) Kiro's Change Management Features ------------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/chat/autopilot/#in-autopilot-mode) In Autopilot Mode In Autopilot mode, Kiro works autonomously and can make multiple changes to your codebase without requiring approval for each individual action. However, you still maintain control over these changes through several key features: 1. **View All Changes** * You can see a comprehensive list of all modifications made by selecting the "View all changes" option in the Chat module * This gives you visibility into everything Kiro has done across your codebase * Changes are presented in a diff view that clearly shows what was added, modified, or removed 2. **Revert All Changes** * If you're not satisfied with the changes Kiro has made, you can select "Revert" * This will restore your files to their previous state in the filesystem locally * This is essentially an "undo" function for all of Kiro's modifications 3. **Interrupt Execution** * You can interrupt Autopilot mid-execution to regain manual control * This stops Kiro from making further changes if you notice something going wrong ### [Copied!](https://kiro.dev/docs/chat/autopilot/#in-supervised-mode) In Supervised Mode In Supervised mode, Kiro works interactively with you and requires your approval before making changes: 1. **Review Changes** * Kiro shows you a diff of all proposed changes before implementing them * You can review these changes in detail to ensure they meet your requirements 2. **Accept All** * The "Accept All" functionality would allow you to approve all proposed changes at once * This is useful when Kiro suggests multiple related changes that you want to implement together 3. **Reject All** * Similarly, "Reject All" would allow you to decline all proposed changes * This is helpful when Kiro's suggestions don't align with your intentions Page updated: July 14, 2025 [Chat](https://kiro.dev/docs/chat/) [Vibe vs. Spec](https://kiro.dev/docs/chat/vibe/) * * * --- # Chat - Docs - Kiro Documentation Chat ==== Kiro offers a chat panel where you can interact with your code through natural language conversations. Just tell Kiro what you need. Ask questions about your codebase, request explanations for complex logic, generate new features, debug tricky issues, and automate repetitive tasks—all while Kiro maintains complete context of your project. Loading image... ![Code review illustration](https://kiro.dev/videos/kiro-agent.gif) [Copied!](https://kiro.dev/docs/chat/#key-features) Key Features ---------------------------------------------------------------- [### Contextual Understanding\ \ Ask questions about your entire codebase, get explanations, or request edits with full awareness of your project structure\ \ Learn more](https://kiro.dev/docs/chat/vibe/) [### Smart Intent Detection\ \ Kiro intelligently determines whether you want information or action, adapting its responses to match your workflow needs\ \ Learn more](https://kiro.dev/docs/chat/autopilot/) [### Vibe vs Spec sessions\ \ Chat sessions can be either vibe or spec sessions. Learn more about the differences between these two.\ \ Learn more](https://kiro.dev/docs/chat/vibe/) [Copied!](https://kiro.dev/docs/chat/#getting-started) Getting Started ---------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/chat/#accessing-chat) Accessing Chat There are multiple ways to access the chat in your development environment: 1. **Keyboard Shortcut**: Press `Cmd+L` (Mac) or `Ctrl+L` (Windows/Linux) to open the chat panel 2. **Command Palette**: Press `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Windows/Linux) and search for `"Kiro: Open Chat"` 3. **Secondary Side Bar**: Click the Kiro chat icon toggle using `Cmd+Opt+B` (Mac) or `Ctrl+Alt+B` in the top bar on the right to open the chat panel ### [Copied!](https://kiro.dev/docs/chat/#your-first-conversation) Your First Conversation Once the chat panel is open: 1. Type your question or request in natural language in the chat input 2. Press Enter to send your message 3. Kiro will analyze your request and respond appropriately Example requests to get started: **Ask about your code** `"Explain how authentication works in this project"` **Generate new code** `"Create a React component for a user profile page"` **Fix issues** `"Help me fix the error in this function"` ### [Copied!](https://kiro.dev/docs/chat/#smart-intent-detection) Smart Intent Detection Kiro intelligently analyzes your messages to understand whether you want information or action. When you ask questions like "How does this work?" or "What's the purpose of this code?", Kiro recognizes this as an information request and responds with explanations and documentation without modifying your code. When you use directives like "Create a component" or "Fix this bug", Kiro identifies this as an action request and will propose or implement the necessary code changes, execute commands, or manage files accordingly. This seamless intent recognition allows for natural conversation without requiring explicit commands to switch between information and action modes. [Copied!](https://kiro.dev/docs/chat/#context-management) Context Management ---------------------------------------------------------------------------- Kiro's power comes from its deep understanding of your codebase context. It automatically analyzes open files in the editor, including their dependencies and structure, but you can also explicitly provide additional context. ### [Copied!](https://kiro.dev/docs/chat/#context-providers) Context Providers Use the `#` symbol in the chat input to access context providers: | Provider | Description | Example | | --- | --- | --- | | `#codebase` | Allow Kiro to automatically find relevant files across your project | `#codebase explain the authentication flow` | | `#file` | Reference specific files in your codebase | `#auth.ts explain this implementation` | | `#folder` | Reference a specific folder and its contents | `#components/ what components do we have?` | | `#git diff` | Reference the current Git changes | `#git diff explain what changed in this PR` | | `#terminal` | Include terminal output in the context | `#terminal help me fix this build error` | | `#problems` | Include all problems in the current file | `#problems help me resolve these issues` | | `#url` | Include web documentation | `#url:https://docs.example.com/api explain this API` | | `#code` | Include specific code snippets in the context | `#code:const sum = (a, b) => a + b; explain this function` | | `#repository` | Include a map of your repository structure | `#repository how is this project organized?` | | `#current` | Reference the currently active file in the editor | `#current explain this component` | | `#steering` | Include specific steering files for guidance | `#steering:coding-standards.md review my code` | | `#docs` | Reference documentation files and content | `#docs:api-reference.md explain this API endpoint` | | `#mcp` | Access Model Context Protocol tools and services | `#mcp:aws-docs how do I configure S3 buckets?` | You can combine multiple context providers in a single request: `#codebase #auth.ts explain how authentication works with our database` [Copied!](https://kiro.dev/docs/chat/#sessions-and-history) Sessions and History -------------------------------------------------------------------------------- Kiro maintains conversation history within sessions, allowing for continuous context-aware interactions. ### [Copied!](https://kiro.dev/docs/chat/#managing-sessions) Managing Sessions * **Create New Sessions**: Start fresh conversations for different topics or projects. Click on `+` icon in the chat panel to start a new session * **Switch between Sessions**: Easily navigate between ongoing conversations through the tab switcher * **View History**: Access previous interactions and their outcomes through the `History` button * **Task Tracking**: Monitor the progress of ongoing and completed tasks through the `Task list` button ### [Copied!](https://kiro.dev/docs/chat/#execution-history) Execution History Kiro maintains a detailed history of sessions that includes actions taken such as code changes, commands executed, search results, file operations, and more. You can search, restore, or delete a specific session. Loading image... ![Kiro Execution History](https://kiro.dev/images/kirohistory.png) Page updated: July 14, 2025 [Best Practices](https://kiro.dev/docs/specs/best-practices/) [Autopilot](https://kiro.dev/docs/chat/autopilot/) * * * --- # Vibe vs Spec sessions - Docs - Kiro Documentation Vibe vs Spec sessions ===================== [Copied!](https://kiro.dev/docs/chat/vibe/#what-is-a-vibe-session) What is a Vibe session? ------------------------------------------------------------------------------------------ Vibe sessions are interactive Q&A-focused sessions in Kiro that are designed for quick questions, explanations, and building projects through a more conversational approach. ### [Copied!](https://kiro.dev/docs/chat/vibe/#how-to-access) How to access You can switch between Vibe sessions and Spec sessions using the session picker when you launch a new session. This allows you to choose the interaction style that best suits your current task. Loading image... ![Kiro Vibe session Picker](https://kiro.dev/images/kiro-vibe-mode.png) ### [Copied!](https://kiro.dev/docs/chat/vibe/#when-to-vibe) When to Vibe 1. **Interactive Q&A Format**: Vibe sessions are optimized for back-and-forth conversations about code, allowing you to ask questions and get immediate responses. 2. **Quick Assistance**: They're ideal for getting quick answers to coding questions, explanations of code behavior, or understanding concepts without going through a formal specification process. 3. **Contextual Understanding**: Like other Kiro sessions, Vibe sessions leverage context providers to understand your codebase, but with a focus on explanation rather than extensive code generation. 4. **Flexible Approach**: Vibe sessions offer a more fluid, less structured approach compared to Spec sessions, making them suitable for exploratory coding and learning. [Copied!](https://kiro.dev/docs/chat/vibe/#what-is-a-spec-session) What is a Spec session? ------------------------------------------------------------------------------------------ A Spec session guides you through a structured approach to complex development tasks in Kiro that formalizes the software development process. It transforms high-level ideas into detailed implementation plans with systematic execution and clear tracking. ### [Copied!](https://kiro.dev/docs/chat/vibe/#how-to-access-1) How to access You can switch between Spec sessions and Vibe sessions using the session picker when you launch a new session. For complex development tasks, Spec sessions provide the structure needed to ensure thorough implementation. Loading image... ![Kiro Spec Mode Picker](https://kiro.dev/images/kiro-spec-mode.png) ### [Copied!](https://kiro.dev/docs/chat/vibe/#when-to-spec) When to Spec 1. **Complex Development Tasks**: Use Spec sessions for building complex features, entire applications, or significant refactoring that requires careful planning and execution. 2. **Structured Approach**: When you need a methodical, step-by-step approach to development with clear documentation of requirements and implementation details. 3. **Team Collaboration**: For projects where multiple team members need to understand the implementation plan and track progress against specifications. 4. **Documentation Needs**: When you want to generate detailed documentation alongside your code implementation for future reference or knowledge sharing. Page updated: July 14, 2025 [Autopilot](https://kiro.dev/docs/chat/autopilot/) [Terminal](https://kiro.dev/docs/chat/terminal/) * * * --- # Steering - Docs - Kiro Documentation Steering ======== [Copied!](https://kiro.dev/docs/steering/#what-is-steering) What is Steering? ----------------------------------------------------------------------------- Steering gives Kiro persistent knowledge about your project through markdown files in `.kiro/steering/`. Instead of explaining your conventions in every chat, steering files ensure Kiro consistently follows your established patterns, libraries, and standards. [Copied!](https://kiro.dev/docs/steering/#key-benefits) Key Benefits -------------------------------------------------------------------- **Consistent Code Generation** - Every component, API endpoint, or test follows your team's established patterns and conventions. **Reduced Repetition** - No need to explain project standards in each conversation. Kiro remembers your preferences. **Team Alignment** - All developers work with the same standards, whether they're new to the project or seasoned contributors. **Scalable Project Knowledge** - Documentation that grows with your codebase, capturing decisions and patterns as your project evolves. [Copied!](https://kiro.dev/docs/steering/#default-steering-files) Default Steering Files ---------------------------------------------------------------------------------------- Kiro automatically creates three foundational files that establish core project context: **Product Overview** (`product.md`) - Defines your product's purpose, target users, key features, and business objectives. This helps Kiro understand the "why" behind technical decisions and suggest solutions aligned with your product goals. **Technology Stack** (`tech.md`) - Documents your chosen frameworks, libraries, development tools, and technical constraints. When Kiro suggests implementations, it will prefer your established stack over alternatives. **Project Structure** (`structure.md`) - Outlines file organization, naming conventions, import patterns, and architectural decisions. This ensures generated code fits seamlessly into your existing codebase. These foundation files are included in every interaction by default, forming the baseline of Kiro's project understanding. [Copied!](https://kiro.dev/docs/steering/#creating-custom-steering-files) Creating Custom Steering Files -------------------------------------------------------------------------------------------------------- Extend Kiro's understanding with specialized guidance tailored to your project's unique needs: 1. Navigate to the **Steering** section in the Kiro panel 2. Click the **+** button to create a new `.md` file 3. Choose a descriptive filename (e.g., `api-standards.md`) 4. Write your guidance using standard markdown syntax 5. Use natural language to describe your requirements, then select the **Refine** button and Kiro will format it [Copied!](https://kiro.dev/docs/steering/#inclusion-modes) Inclusion Modes -------------------------------------------------------------------------- Steering files can be configured to load at different times based on your needs. This flexibility helps optimize performance and ensures relevant context is available when needed. Configure inclusion modes by adding front matter to the top of your steering files. The front matter uses YAML syntax and must be placed at the very beginning of the file, enclosed by triple dashes (`---`). ### [Copied!](https://kiro.dev/docs/steering/#always-included-default) Always Included (Default) yaml `--- inclusion: always ---` These files are loaded into every Kiro interaction automatically. Use this mode for core standards that should influence all code generation and suggestions. Examples include your technology stack, coding conventions, and fundamental architectural principles. **Best for**: Project-wide standards, technology preferences, security policies, and coding conventions that apply universally. ### [Copied!](https://kiro.dev/docs/steering/#conditional-inclusion) Conditional Inclusion yaml `--- inclusion: fileMatch fileMatchPattern: "components/**/*.tsx" ---` Files are automatically included only when working with files that match the specified pattern. This keeps context relevant and reduces noise by loading specialized guidance only when needed. **Common patterns**: * `"*.tsx"` - React components and JSX files * `"app/api/**/*"` - API routes and backend logic * `"**/*.test.*"` - Test files and testing utilities * `"src/components/**/*"` - Component-specific guidelines * `"*.md"` - Documentation files **Best for**: Domain-specific standards like component patterns, API design rules, testing approaches, or deployment procedures that only apply to certain file types. ### [Copied!](https://kiro.dev/docs/steering/#manual-inclusion) Manual Inclusion yaml `--- inclusion: manual ---` Files are available on-demand by referencing them with `#steering-file-name` in your chat messages. This gives you precise control over when specialized context is needed without cluttering every interaction. **Usage**: Type `#troubleshooting-guide` or `#performance-optimization` in chat to include that steering file for the current conversation. **Best for**: Specialized workflows, troubleshooting guides, migration procedures, or context-heavy documentation that's only needed occasionally. [Copied!](https://kiro.dev/docs/steering/#file-references) File References -------------------------------------------------------------------------- Link to live project files to keep steering current: markdown `#[[file:]]` Examples: * API specs: `#[[file:api/openapi.yaml]]` * Component patterns: `#[[file:components/ui/button.tsx]]` * Config templates: `#[[file:.env.example]]` [Copied!](https://kiro.dev/docs/steering/#best-practices) Best Practices ------------------------------------------------------------------------ **Keep Files Focused** One domain per file - API design, testing, or deployment procedures. **Use Clear Names** * `api-rest-conventions.md` - REST API standards * `testing-unit-patterns.md` - Unit testing approaches * `components-form-validation.md` - Form component standards **Include Context** Explain why decisions were made, not just what the standards are. **Provide Examples** Use code snippets and before/after comparisons to demonstrate standards. **Security First** Never include API keys, passwords, or sensitive data. Steering files are part of your codebase. **Maintain Regularly** * Review during sprint planning and architecture changes * Test file references after restructuring * Treat steering changes like code changes - require reviews [Copied!](https://kiro.dev/docs/steering/#common-steering-file-strategies) Common Steering File Strategies ---------------------------------------------------------------------------------------------------------- **API Standards** (`api-standards.md`) - Define REST conventions, error response formats, authentication flows, and versioning strategies. Include endpoint naming patterns, HTTP status code usage, and request/response examples. **Testing Approach** (`testing-standards.md`) - Establish unit test patterns, integration test strategies, mocking approaches, and coverage expectations. Document preferred testing libraries, assertion styles, and test file organization. **Code Style** (`code-conventions.md`) - Specify naming patterns, file organization, import ordering, and architectural decisions. Include examples of preferred code structures, component patterns, and anti-patterns to avoid. **Security Guidelines** (`security-policies.md`) - Document authentication requirements, data validation rules, input sanitization standards, and vulnerability prevention measures. Include secure coding practices specific to your application. **Deployment Process** (`deployment-workflow.md`) - Outline build procedures, environment configurations, deployment steps, and rollback strategies. Include CI/CD pipeline details and environment-specific requirements. Custom steering files are stored in `.kiro/steering/` and become immediately available across all Kiro interactions. Page updated: July 14, 2025 [Troubleshooting](https://kiro.dev/docs/hooks/troubleshooting/) [MCP](https://kiro.dev/docs/mcp/) * * * --- # Model Context Protocol (MCP) - Docs - Kiro Documentation Model Context Protocol (MCP) ============================ Model Context Protocol (MCP) extends Kiro's capabilities by connecting to specialized servers that provide additional tools and context. This guide helps you set up, configure, and use MCP servers with Kiro. [Copied!](https://kiro.dev/docs/mcp/#what-is-mcp) What is MCP? -------------------------------------------------------------- MCP is a protocol that allows Kiro to communicate with external servers to access specialized tools and information. For example, the AWS Documentation MCP server provides tools to search, read, and get recommendations from AWS documentation directly within Kiro. With MCP, you can: * Access specialized knowledge bases and documentation * Integrate with external services and APIs * Extend Kiro's capabilities with domain-specific tools * Create custom tools for your specific workflows [Copied!](https://kiro.dev/docs/mcp/#setting-up-mcp) Setting Up MCP ------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/#prerequisites) Prerequisites Before using MCP, make sure you have: 1. The latest version of Kiro installed 2. Any specific prerequisites for the MCP servers you want to use (listed in each server's documentation) [Copied!](https://kiro.dev/docs/mcp/#managing-mcp-servers) Managing MCP Servers ------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/#enabling-mcp-support) Enabling MCP Support After creating your configuration file: 1. Open Settings with `Cmd + ,` (Mac) or `Ctrl + ,` (Windows/Linux) 2. Search for "MCP" 3. Enable the MCP support setting 4. Restart Kiro to apply changes ### [Copied!](https://kiro.dev/docs/mcp/#using-the-mcp-servers-tab) Using the MCP Servers Tab The Kiro panel includes an MCP servers tab that shows: * All configured MCP servers * Connection status indicators * Quick access to server tools To use this feature: 1. Select the Kiro icon in the activity bar 2. Navigate to the MCP servers tab 3. Click any tool name to insert a placeholder prompt in the chat [Copied!](https://kiro.dev/docs/mcp/#troubleshooting) Troubleshooting --------------------------------------------------------------------- If you encounter issues with MCP servers: ### [Copied!](https://kiro.dev/docs/mcp/#checking-mcp-logs) Checking MCP Logs 1. Open the Kiro panel 2. Select the Output tab 3. Choose "Kiro - MCP Logs" from the dropdown ### [Copied!](https://kiro.dev/docs/mcp/#common-issues-and-solutions) Common Issues and Solutions | Issue | Solution | | --- | --- | | Connection failures | Verify prerequisites are installed correctly | | Permission errors | Check that tokens and API keys are valid | | Tool not responding | Review MCP logs for specific error messages | | Configuration not loading | Validate JSON syntax and restart Kiro | [Copied!](https://kiro.dev/docs/mcp/#additional-resources) Additional Resources ------------------------------------------------------------------------------- * [Official MCP Documentation](https://modelcontextprotocol.io/introduction) [Copied!](https://kiro.dev/docs/mcp/#next-steps) Next Steps ----------------------------------------------------------- Now that you have created a hook file, you can further learn about hooks here: * **[Configuring MCPs](https://kiro.dev/docs/mcp/configuration/) ** - Learn about configuring Model Context Protocol (MCP) servers * **[MCP Server management](https://kiro.dev/docs/mcp/servers/) ** - Learn how to use common MCP servers with examples * **[Using MCP Tools](https://kiro.dev/docs/mcp/usage/) ** - Learn how to effectively use MCP tools with Kiro * **[Best Practices](https://kiro.dev/docs/mcp/security/) ** - Best practices for effective MCP usage Page updated: July 14, 2025 [Steering](https://kiro.dev/docs/steering/) [Configuration](https://kiro.dev/docs/mcp/configuration/) * * * --- # Hook Types - Docs - Kiro Documentation Hook Types ========== Agent Hooks support various trigger types, each designed for specific automation scenarios. Understanding these types helps you choose the right approach for your workflow needs. [Copied!](https://kiro.dev/docs/hooks/types/#on-file-create) On File Create --------------------------------------------------------------------------- Trigger when new files matching specific patterns are created in your workspace. **Use Cases:** * Generate boilerplate code for new components * Add license headers to new files * Set up test files when creating implementation files **Example: React Component Setup** `When a new React component file is created, add: 1. Import statements for React and necessary hooks 2. A functional component with TypeScript props interface 3. Export statement 4. Basic styling if applicable 5. A skeleton test file in the appropriate directory` [Copied!](https://kiro.dev/docs/hooks/types/#on-file-save) On File Save ----------------------------------------------------------------------- Trigger when files matching specific patterns are saved. **Use Cases:** * Run linting and formatting * Update related files * Generate documentation * Run tests for changed files **Example: Update Test Coverage** `When a JavaScript/TypeScript file is saved: 1. Identify the corresponding test file 2. Update tests to maintain coverage for any new functions 3. Run the tests to verify they pass 4. Update any snapshots if necessary` [Copied!](https://kiro.dev/docs/hooks/types/#on-file-delete) On File Delete --------------------------------------------------------------------------- Trigger when files matching specific patterns are deleted. **Use Cases:** * Clean up related files * Update import references in other files * Maintain project integrity **Example: Clean Up References** `When a component file is deleted: 1. Find all imports of this component across the codebase 2. Remove or comment out those import statements 3. Suggest replacements if appropriate` [Copied!](https://kiro.dev/docs/hooks/types/#manual-trigger) Manual Trigger --------------------------------------------------------------------------- Manually execute a hook. **Use Cases:** * On-demand code reviews * Documentation generation * Security scanning * Performance optimization **Example: Code Review Button** `Review the current file for: 1. Code quality issues 2. Potential bugs 3. Performance optimizations 4. Security vulnerabilities 5. Accessibility concerns` Page updated: July 11, 2025 [Hooks](https://kiro.dev/docs/hooks/) [Management](https://kiro.dev/docs/hooks/management/) * * * --- # Best Practices - Docs - Kiro Documentation Best Practices ============== Following these best practices will help you create reliable, efficient, and maintainable hooks that enhance your development workflow. [Copied!](https://kiro.dev/docs/hooks/best-practices/#hook-design) Hook Design ------------------------------------------------------------------------------ ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#be-specific-and-clear) Be Specific and Clear * Write detailed, unambiguous instructions * Focus on one specific task per hook * Use numbered steps for complex operations ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#test-thoroughly) Test Thoroughly * Test hooks on sample files before deploying * Verify hooks work with edge cases * Start with limited file patterns before expanding ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#monitor-performance) Monitor Performance * Ensure hooks don't slow down your workflow * Consider the frequency of trigger events * Optimize prompts for efficiency [Copied!](https://kiro.dev/docs/hooks/best-practices/#security-considerations) Security Considerations ------------------------------------------------------------------------------------------------------ ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#validate-inputs) Validate Inputs * Ensure hooks handle unexpected file content gracefully * Consider potential edge cases in file formats * Test with malformed or unexpected input ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#limit-scope) Limit Scope * Target specific file types or directories when possible * Use precise file patterns to avoid unnecessary executions * Consider the impact of hooks on your entire codebase ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#review-regularly) Review Regularly * Update hook logic as your project evolves * Remove hooks that are no longer needed * Refine prompts based on actual results [Copied!](https://kiro.dev/docs/hooks/best-practices/#team-collaboration) Team Collaboration -------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#document-hooks) Document Hooks * Maintain clear documentation of hook purposes * Include examples of expected behavior * Document any limitations or edge cases ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#share-configurations) Share Configurations * Use consistent hooks across team members * Store hook configurations in version control * Create standard hooks for common team workflows ### [Copied!](https://kiro.dev/docs/hooks/best-practices/#version-control-integration) Version Control Integration * Consider hooks that integrate with your version control system * Create hooks for code review workflows * Use hooks to enforce team standards Page updated: July 11, 2025 [Management](https://kiro.dev/docs/hooks/management/) [Examples](https://kiro.dev/docs/hooks/examples/) * * * --- # Hook Management - Docs - Kiro Documentation Hook Management =============== Effective hook management ensures your automation workflows remain organized, maintainable, and efficient as your project grows. [Copied!](https://kiro.dev/docs/hooks/management/#managing-your-hooks) Managing Your Hooks ------------------------------------------------------------------------------------------ Access all your hooks through the Agent Hooks section in the Kiro panel. ### [Copied!](https://kiro.dev/docs/hooks/management/#enabledisable-hooks) Enable/Disable Hooks Toggle hooks on/off without deleting them: * **Quick toggle**: Click the `eye icon` next to any hook in the Agent Hooks panel * **From hook view**: Select a hook and use the `Hook Enabled` switch in the top-right corner ### [Copied!](https://kiro.dev/docs/hooks/management/#edit-existing-hooks) Edit Existing Hooks Hooks evolve with your workflow. Update them anytime by selecting your hook in the Agent Hooks panel and modifying settings like triggers, file patterns, instructions, or descriptions. Updates apply immediately. ### [Copied!](https://kiro.dev/docs/hooks/management/#delete-hooks) Delete Hooks Select the hook in the Agent Hooks panel, click `Delete Hook` located at the bottom view, then click `delete`. This action cannot be undone. ### [Copied!](https://kiro.dev/docs/hooks/management/#run-manual-trigger-hooks) Run Manual Trigger Hooks You can execute a manual trigger hook using: * **Quick run**: Click the `play button (▷)` next to the hook name in the Agent Hooks panel * **From hook view**: Select the hook and click `Start Hook` in the top-right corner Page updated: July 11, 2025 [Hook Types](https://kiro.dev/docs/hooks/types/) [Best Practices](https://kiro.dev/docs/hooks/best-practices/) * * * --- # Troubleshooting Hooks - Docs - Kiro Documentation Troubleshooting Hooks ===================== ### [Copied!](https://kiro.dev/docs/hooks/troubleshooting/#common-issues) Common Issues **Hook Not Triggering** * Verify the file pattern matches your target files * Check that the hook is enabled * Ensure the event type is correct **Unexpected Hook Behavior** * Review the hook instructions for clarity * Check for conflicting hooks * Verify file patterns aren't too broad **Performance Issues** * Limit hook scope with more specific file patterns * Simplify complex hook instructions * Reduce the frequency of triggering events For additional information, consult the [troubleshooting guide](https://kiro.dev/docs/reference/troubleshooting) Page updated: July 11, 2025 [Examples](https://kiro.dev/docs/hooks/examples/) [Steering](https://kiro.dev/docs/steering/) * * * --- # Hook Examples - Docs - Kiro Documentation Hook Examples ============= These examples demonstrate real-world hook implementations that you can adapt for your own projects. Each example includes the trigger type, target patterns, and complete hook instructions. [Copied!](https://kiro.dev/docs/hooks/examples/#security-pre-commit-scanner) Security Pre-Commit Scanner -------------------------------------------------------------------------------------------------------- This hook helps prevent security leaks by scanning files before they're committed. **Trigger Type:** File Save **Target:** `**/*` **Hook Instructions:** `Review changed files for potential security issues: 1. Look for API keys, tokens, or credentials in source code 2. Check for private keys or sensitive credentials 3. Scan for encryption keys or certificates 4. Identify authentication tokens or session IDs 5. Flag passwords or secrets in configuration files 6. Detect IP addresses containing sensitive data 7. Find hardcoded internal URLs 8. Spot database connection credentials For each issue found: 1. Highlight the specific security risk 2. Suggest a secure alternative approach 3. Recommend security best practices` [Copied!](https://kiro.dev/docs/hooks/examples/#internationalization-helper) Internationalization Helper -------------------------------------------------------------------------------------------------------- This hook ensures that when you update text in your primary language file, translations are kept in sync. **Trigger Type:** File Save **Target:** `src/locales/en/*.json` **Hook Instructions:** `When an English locale file is updated: 1. Identify which string keys were added or modified 2. Check all other language files for these keys 3. For missing keys, add them with a "NEEDS_TRANSLATION" marker 4. For modified keys, mark them as "NEEDS_REVIEW" 5. Generate a summary of changes needed across all languages` [Copied!](https://kiro.dev/docs/hooks/examples/#documentation-generator) Documentation Generator ------------------------------------------------------------------------------------------------ This hook automatically updates documentation when code changes. **Trigger Type:** Manual Trigger **Hook Instructions:** `Generate comprehensive documentation for the current file: 1. Extract function and class signatures 2. Document parameters and return types 3. Provide usage examples based on existing code 4. Update the README.md with any new exports 5. Ensure documentation follows project standards` [Copied!](https://kiro.dev/docs/hooks/examples/#test-coverage-maintainer) Test Coverage Maintainer -------------------------------------------------------------------------------------------------- This hook ensures test coverage remains high as code evolves. **Trigger Type:** File Save **Target:** `src/**/*.{js,ts,jsx,tsx}` **Hook Instructions:** `When a source file is modified: 1. Identify new or modified functions and methods 2. Check if corresponding tests exist and cover the changes 3. If coverage is missing, generate test cases for the new code 4. Run the tests to verify they pass 5. Update coverage reports` [Copied!](https://kiro.dev/docs/hooks/examples/#integration-with-mcp) Integration with MCP ------------------------------------------------------------------------------------------ Agent Hooks can be enhanced with Model Context Protocol (MCP) capabilities to extend their functionality: 1. **Access to External Tools**: Hooks can leverage MCP servers to access specialized tools and APIs 2. **Enhanced Context**: MCP provides additional context for more intelligent hook actions 3. **Domain-Specific Knowledge**: Specialized MCP servers can provide domain expertise To use MCP with hooks: 1. [Configure MCP servers](https://kiro.dev/docs/mcp/configuration) 2. Reference MCP tools in your hook instructions 3. Set appropriate auto-approval settings for frequently used tools **Use Cases:** * Make sure that your Figma design system is respected * Update ticket status after a task is done * Sync a database from sample files within the project folder ### [Copied!](https://kiro.dev/docs/hooks/examples/#example-validate-figma-design) Example: Validate Figma Design This hook monitors HTML and CSS files and validates that they follow a Figma design using the Figma MCP. **Trigger Type:** File Save Hook **Target:** `*.css` `*.html` **Hook Instructions:** `Use the Figma MCP to analyze the updated html or css files and check that they follow established design patterns in the figma design. Verify elements like hero sections, feature highlights, navigation elements, colors, and button placements align.` Page updated: July 11, 2025 [Best Practices](https://kiro.dev/docs/hooks/best-practices/) [Troubleshooting](https://kiro.dev/docs/hooks/troubleshooting/) * * * --- # Configuration - Docs - Kiro Documentation Configuration ============= This guide provides detailed information on configuring Model Context Protocol (MCP) servers with Kiro, including configuration file structure, server setup, and best practices. [Copied!](https://kiro.dev/docs/mcp/configuration/#configuration-file-structure) Configuration File Structure ------------------------------------------------------------------------------------------------------------- MCP configuration files use JSON format with the following structure: json `{ "mcpServers": { "server-name": { "command": "command-to-run-server", "args": ["arg1", "arg2"], "env": { "ENV_VAR1": "value1", "ENV_VAR2": "value2" }, "disabled": false, "autoApprove": ["tool_name1", "tool_name2"] } } }` ### [Copied!](https://kiro.dev/docs/mcp/configuration/#configuration-properties) Configuration Properties | Property | Type | Required | Description | | --- | --- | --- | --- | | `command` | String | Yes | The command to run the MCP server | | `args` | Array | Yes | Arguments to pass to the command | | `env` | Object | No | Environment variables for the server process | | `disabled` | Boolean | No | Whether the server is disabled (default: false) | | `autoApprove` | Array | No | Tool names to auto-approve without prompting | [Copied!](https://kiro.dev/docs/mcp/configuration/#configuration-locations) Configuration Locations --------------------------------------------------------------------------------------------------- You can configure MCP servers at two levels: 1. **Workspace Level**: `.kiro/settings/mcp.json` * Applies only to the current workspace * Ideal for project-specific MCP servers 2. **User Level**: `~/.kiro/settings/mcp.json` * Applies globally across all workspaces * Best for MCP servers you use frequently If both files exist, configurations are merged with workspace settings taking precedence. [Copied!](https://kiro.dev/docs/mcp/configuration/#creating-configuration-files) Creating Configuration Files ------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/configuration/#using-the-command-palette) Using the Command Palette 1. Open the command palette: * Mac: `Cmd + Shift + P` * Windows/Linux: `Ctrl + Shift + P` 2. Search for "MCP" and select one of these options: * **Kiro: Open workspace MCP config (JSON)** - For workspace-level configuration * **Kiro: Open user MCP config (JSON)** - For user-level configuration ### [Copied!](https://kiro.dev/docs/mcp/configuration/#using-the-kiro-panel) Using the Kiro Panel 1. Open the Kiro panel 2. Select the **Open MCP Config** icon json `{ "mcpServers": { "web-search": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-bravesearch" ], "env": { "BRAVE_API_KEY": "your-api-key" } } } }` [Copied!](https://kiro.dev/docs/mcp/configuration/#environment-variables) Environment Variables ----------------------------------------------------------------------------------------------- Many MCP servers require environment variables for authentication or configuration: json `{ "mcpServers": { "server-name": { "env": { "API_KEY": "your-api-key", "DEBUG": "true", "TIMEOUT": "30000" } } } }` [Copied!](https://kiro.dev/docs/mcp/configuration/#disabling-servers-temporarily) Disabling Servers Temporarily --------------------------------------------------------------------------------------------------------------- To temporarily disable an MCP server without removing its configuration: json `{ "mcpServers": { "server-name": { "disabled": true } } }` [Copied!](https://kiro.dev/docs/mcp/configuration/#security-best-practices) Security Best Practices --------------------------------------------------------------------------------------------------- When configuring MCP servers: * **Don't commit configuration files** with sensitive tokens to version control * **Use environment variables** for sensitive information when possible * **Review tool permissions** before adding them to `autoApprove` * **Use workspace-level configs** for project-specific servers * **Regularly rotate API keys and tokens** used in configurations [Copied!](https://kiro.dev/docs/mcp/configuration/#troubleshooting-configuration-issues) Troubleshooting Configuration Issues ----------------------------------------------------------------------------------------------------------------------------- If your MCP configuration isn't working: 1. **Validate JSON syntax**: * Ensure your JSON is valid with no syntax errors * Check for missing commas, quotes, or brackets 2. **Verify command paths**: * Make sure the command specified exists in your PATH * Try running the command directly in your terminal 3. **Check environment variables**: * Verify that all required environment variables are set * Check for typos in environment variable names 4. **Restart Kiro**: * Changes to MCP configuration require a restart * Close and reopen Kiro to apply changes Page updated: July 8, 2025 [MCP](https://kiro.dev/docs/mcp/) [Servers](https://kiro.dev/docs/mcp/servers/) * * * --- # Guides - Docs - Kiro Documentation Guides ====== [### Learn by Playing\ \ Build a real game project while learning Kiro's powerful features through hands-on interactive tutorials\ \ Learn more](https://kiro.dev/docs/guides/learn-by-playing/) [### Languages support\ \ Framework-specific guides for React, Python, Go, and more to help you get the most out of Kiro with your tech stack\ \ Learn more](https://kiro.dev/docs/guides/languages-and-frameworks/) [### Migrating from VS Code\ \ Seamlessly transition from VS Code to Kiro with one-click migration including all your extensions and settings\ \ Learn more](https://kiro.dev/docs/guides/migrating-from-vscode/) Page updated: July 14, 2025 [Best Practices](https://kiro.dev/docs/mcp/security/) [Language support](https://kiro.dev/docs/guides/languages-and-frameworks/) * * * --- # Hooks - Docs - Kiro Documentation Hooks ===== Agent Hooks are powerful automation tools that streamline your development workflow by automatically executing predefined agent actions when specific events occur in your IDE. With hooks, you eliminate the need to manually request routine tasks and ensure consistency across your codebase. [Copied!](https://kiro.dev/docs/hooks/#what-are-agent-hooks) What are Agent Hooks? ---------------------------------------------------------------------------------- Agent Hooks are automated triggers that execute predefined agent actions when specific events occur in your IDE. Rather than manually asking for routine tasks to be performed, hooks set up automated responses to events such as: * Saving files * Creating new files * Deleting files Agent Hooks transform your development workflow through intelligent automation. By setting up hooks for common tasks, you can: * Maintain consistent code quality * Prevent security vulnerabilities * Reduce manual overhead * Standardize team processes * Create faster development cycles Whether you're working on a small project or managing a large codebase, Agent Hooks help ensure that routine tasks are handled automatically and consistently, allowing you to focus on building great software. [Copied!](https://kiro.dev/docs/hooks/#how-agent-hooks-work) How Agent Hooks Work --------------------------------------------------------------------------------- The Agent Hook system follows a simple three-step process: 1. **Event Detection**: The system monitors for specific events in your IDE 2. **Prompt Execution**: When an event occurs, a predefined prompt is sent to the agent 3. **Automated Action**: The agent processes the prompt and performs the requested actions This automation flow eliminates repetitive tasks and ensures consistency across your codebase. [Copied!](https://kiro.dev/docs/hooks/#setting-up-agent-hooks) Setting Up Agent Hooks ------------------------------------------------------------------------------------- Creating and managing hooks is straightforward: ### [Copied!](https://kiro.dev/docs/hooks/#using-the-explorer-view) Using the Explorer View 1. Navigate to the **Agent Hooks** section in the Kiro panel 2. Click the **+** button to create a new hook 3. Define the hook workflow using natural language in the input field 4. Press **Enter** or click **Submit** to proceed 5. Configure the hook settings and save ### [Copied!](https://kiro.dev/docs/hooks/#using-the-command-palette) Using the Command Palette You can also use the Command Palette to navigate to the Hook UI: 1. Open the command palette with `Cmd + Shift + P` (Mac) or `Ctrl + Shift + P` (Windows/Linux) 2. Type `Kiro: Open Kiro Hook UI` 3. Follow the on-screen instructions to create your hook [Copied!](https://kiro.dev/docs/hooks/#next-steps) Next Steps ------------------------------------------------------------- Now that you have created a hook file, you can further learn about hooks here: * **[Hook Types](https://kiro.dev/docs/hooks/types) ** - Learn about different trigger types and their use cases * **[Management](https://kiro.dev/docs/hooks/management) ** - Learn how to organize, edit, and maintain your hooks * **[Best Practices](https://kiro.dev/docs/hooks/best-practices) ** - Follow patterns for effective hook design * **[Examples](https://kiro.dev/docs/hooks/examples) ** - See examples and templates you can use Page updated: July 14, 2025 [Terminal](https://kiro.dev/docs/chat/terminal/) [Hook Types](https://kiro.dev/docs/hooks/types/) * * * --- # Language Support - Docs - Kiro Documentation Language Support ================ Kiro provides powerful AI-assisted development capabilities for your projects, helping you write, debug, and maintain code more efficiently. The following guides will help you get started creating with Kiro. [### TypeScript & JavaScript\ \ Best practices for TypeScript and JavaScript development with Kiro\ \ Learn more](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/) [### Python\ \ Optimize your Python workflow with Kiro's intelligent assistance\ \ Learn more](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/) [### Java\ \ Enterprise Java development enhanced with AI-powered features\ \ Learn more](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/) Page updated: July 14, 2025 [Guides](https://kiro.dev/docs/guides/) [TypeScript and JavaScript](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/) * * * --- # Best Practices - Docs - Kiro Documentation Best Practices ============== This guide outlines security best practices for configuring and using Model Context Protocol (MCP) servers with Kiro, helping you protect sensitive information and maintain system security. [Copied!](https://kiro.dev/docs/mcp/security/#understanding-mcp-security) Understanding MCP Security ---------------------------------------------------------------------------------------------------- MCP servers extend Kiro's capabilities by connecting to external services and APIs. This introduces potential security considerations that should be addressed: * **Access to sensitive information**: MCP servers may require API keys or tokens * **External code execution**: MCP servers run code outside of Kiro's sandbox * **Data transmission**: Information flows between Kiro and external services [Copied!](https://kiro.dev/docs/mcp/security/#secure-configuration) Secure Configuration ---------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/security/#protecting-api-keys-and-tokens) Protecting API Keys and Tokens 1. **Never commit configuration files** with sensitive tokens to version control 2. **Use environment variables** when possible instead of hardcoding values 3. **Create tokens with minimal permissions** necessary for the MCP server to function 4. **Regularly rotate API keys and tokens** used in configurations ### [Copied!](https://kiro.dev/docs/mcp/security/#example-using-environment-variables) Example: Using Environment Variables Instead of hardcoding tokens in your configuration: json `{ "mcpServers": { "github": { "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } } } }` Set the environment variable in your shell: bash `export GITHUB_TOKEN=your-token-value` ### [Copied!](https://kiro.dev/docs/mcp/security/#configuration-file-permissions) Configuration File Permissions Restrict access to your MCP configuration files: bash `# Set restrictive permissions on user-level config chmod 600 ~/.kiro/settings/mcp.json # Set restrictive permissions on workspace-level config chmod 600 .kiro/settings/mcp.json` [Copied!](https://kiro.dev/docs/mcp/security/#safe-tool-usage) Safe Tool Usage ------------------------------------------------------------------------------ ### [Copied!](https://kiro.dev/docs/mcp/security/#tool-approval-process) Tool Approval Process 1. **Review each tool request** carefully before approval 2. **Check the parameters** being passed to the tool 3. **Understand what the tool will do** before approving it 4. **Deny any suspicious requests** that don't match your current task ### [Copied!](https://kiro.dev/docs/mcp/security/#auto-approval-guidelines) Auto-approval Guidelines Only auto-approve tools that: 1. **Don't have write access** to sensitive systems 2. **Come from trusted sources** with verified code 3. **Are used frequently** in your workflow 4. **Have limited scope** of what they can access json `{ "mcpServers": { "aws-docs": { "autoApprove": [ "mcp_aws_docs_search_documentation", "mcp_aws_docs_read_documentation" ] } } }` [Copied!](https://kiro.dev/docs/mcp/security/#server-specific-security) Server-Specific Security ------------------------------------------------------------------------------------------------ ### [Copied!](https://kiro.dev/docs/mcp/security/#aws-documentation-server) AWS Documentation Server The AWS Documentation server is generally safe as it: * Only reads public documentation * Doesn't access your AWS account or resources * Doesn't require AWS credentials ### [Copied!](https://kiro.dev/docs/mcp/security/#github-mcp-server) GitHub MCP Server When using the GitHub MCP server: 1. **Create a dedicated token** for Kiro with minimal permissions 2. **Limit repository access** to only those needed 3. **Don't grant delete permissions** unless absolutely necessary 4. **Consider using a fine-grained personal access token** instead of a classic token ### [Copied!](https://kiro.dev/docs/mcp/security/#custom-mcp-servers) Custom MCP Servers When creating or using custom MCP servers: 1. **Review the source code** before using 2. **Run in isolated environments** when possible 3. **Limit the permissions** granted to the server 4. **Monitor the server's activity** for unexpected behavior [Copied!](https://kiro.dev/docs/mcp/security/#workspace-isolation) Workspace Isolation -------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/security/#using-workspace-level-configurations) Using Workspace-Level Configurations Use workspace-level configurations for project-specific MCP servers: `project-a/ ├── .kiro/ │ └── settings/ │ └── mcp.json # Project A specific servers project-b/ ├── .kiro/ │ └── settings/ │ └── mcp.json # Project B specific servers` This ensures that: * MCP servers only run when working in the relevant project * Tokens and configurations are isolated between projects * Security risks are contained to specific workspaces [Copied!](https://kiro.dev/docs/mcp/security/#monitoring-and-auditing) Monitoring and Auditing ---------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/security/#checking-mcp-logs) Checking MCP Logs Regularly review MCP logs to monitor server activity: 1. Open the Kiro panel 2. Select the Output tab 3. Choose "Kiro - MCP Logs" from the dropdown ### [Copied!](https://kiro.dev/docs/mcp/security/#auditing-tool-usage) Auditing Tool Usage Periodically review which tools you've approved: 1. Check your MCP configuration for auto-approved tools 2. Review the MCP logs for tool usage patterns 3. Remove auto-approval for tools you no longer use frequently [Copied!](https://kiro.dev/docs/mcp/security/#responding-to-security-incidents) Responding to Security Incidents ---------------------------------------------------------------------------------------------------------------- If you suspect a security issue with an MCP server: 1. **Disable the server** immediately in your configuration 2. **Revoke any tokens or API keys** associated with the server 3. **Check for unauthorized activity** in the connected services 4. **Report the issue** to the MCP server maintainer [Copied!](https://kiro.dev/docs/mcp/security/#additional-security-measures) Additional Security Measures -------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/security/#network-security) Network Security 1. **Use firewalls** to restrict outbound connections from MCP servers 2. **Consider using a VPN** for sensitive MCP server connections 3. **Monitor network traffic** to and from MCP servers ### [Copied!](https://kiro.dev/docs/mcp/security/#system-security) System Security 1. **Keep your system updated** with security patches 2. **Run MCP servers with minimal privileges** 3. **Use separate user accounts** for running sensitive MCP servers * * * _For information on configuring MCP servers, see the [MCP Configuration](https://kiro.dev/docs/mcp/configuration) page._ Page updated: June 20, 2025 [Tools](https://kiro.dev/docs/mcp/usage/) [Guides](https://kiro.dev/docs/guides/) * * * --- # Servers - Docs - Kiro Documentation Servers ======= This guide provides information about available Model Context Protocol (MCP) servers, their capabilities, and how to set them up with Kiro. Warning Only add MCP servers from trusted sources, and review all applicable server licensing information and documentation. Kiro is not responsible for any third-party MCP servers or other packages. [Copied!](https://kiro.dev/docs/mcp/servers/#aws-documentation-server) AWS Documentation Server ----------------------------------------------------------------------------------------------- The AWS Documentation server provides access to AWS documentation, search capabilities, and content recommendations. ### [Copied!](https://kiro.dev/docs/mcp/servers/#capabilities) Capabilities * **Search AWS documentation** across all services * **Read documentation pages** in markdown format * **Get content recommendations** related to specific documentation pages ### [Copied!](https://kiro.dev/docs/mcp/servers/#setup-instructions) Setup Instructions #### [Copied!](https://kiro.dev/docs/mcp/servers/#prerequisites) Prerequisites 1. **Install uv** from Astral: bash `# On macOS/Linux curl -LsSf https://astral.sh/uv/install.sh | sh # On Windows PowerShell irm https://astral.sh/uv/install.ps1 | iex` 2. **Install Python 3.10 or newer**: bash `uv python install 3.10` #### [Copied!](https://kiro.dev/docs/mcp/servers/#configuration) Configuration For macOS/Linux: json `{ "mcpServers": { "aws-docs": { "command": "uvx", "args": ["awslabs.aws-documentation-mcp-server@latest"], "env": { "FASTMCP_LOG_LEVEL": "ERROR" }, "disabled": false, "autoApprove": [] } } }` For Windows: json `{ "mcpServers": { "aws-docs": { "command": "uv", "args": [ "tool", "run", "--from", "awslabs.aws-documentation-mcp-server@latest", "awslabs.aws-documentation-mcp-server.exe" ], "env": { "FASTMCP_LOG_LEVEL": "ERROR" } } } }` ### [Copied!](https://kiro.dev/docs/mcp/servers/#available-tools) Available Tools | Tool Name | Description | | --- | --- | | `mcp_aws_docs_search_documentation` | Search AWS documentation for specific topics | | `mcp_aws_docs_read_documentation` | Read AWS documentation pages in markdown format | | `mcp_aws_docs_recommend` | Get content recommendations related to a documentation page | ### [Copied!](https://kiro.dev/docs/mcp/servers/#usage-examples) Usage Examples `# Search for information about S3 bucket policies Search AWS documentation for S3 bucket policies # Read specific documentation Read the AWS Lambda function URLs documentation # Get recommendations Find related content to AWS ECS task definitions` [Copied!](https://kiro.dev/docs/mcp/servers/#github-mcp-server) GitHub MCP Server --------------------------------------------------------------------------------- The GitHub MCP server allows Kiro to interact with GitHub repositories, issues, and pull requests. ### [Copied!](https://kiro.dev/docs/mcp/servers/#capabilities-1) Capabilities * **Access repository information** including files, commits, and branches * **Create and manage issues** and pull requests * **Search repositories** for specific content ### [Copied!](https://kiro.dev/docs/mcp/servers/#setup-instructions-1) Setup Instructions #### [Copied!](https://kiro.dev/docs/mcp/servers/#prerequisites-1) Prerequisites 1. **Create a GitHub Personal Access Token**: * Go to GitHub Settings > Developer settings > Personal access tokens * Generate a new token with `repo` and `user` scopes #### [Copied!](https://kiro.dev/docs/mcp/servers/#configuration-1) Configuration json `{ "mcpServers": { "github": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-github" ], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "your-token" } } } }` ### [Copied!](https://kiro.dev/docs/mcp/servers/#available-tools-1) Available Tools | Tool Name | Description | | --- | --- | | `github_get_repository` | Get information about a repository | | `github_get_file` | Get the contents of a file from a repository | | `github_search_code` | Search for code in repositories | | `github_create_issue` | Create a new issue in a repository | | `github_create_pull_request` | Create a new pull request | ### [Copied!](https://kiro.dev/docs/mcp/servers/#usage-examples-1) Usage Examples `# Get repository information Show me information about the tensorflow/tensorflow repository # Search for code Find examples of React hooks in facebook/react # Create an issue Create an issue in my repository about the login bug` [Copied!](https://kiro.dev/docs/mcp/servers/#web-search-server) Web Search Server --------------------------------------------------------------------------------- The Web Search MCP server provides access to web search results using the Brave Search API. ### [Copied!](https://kiro.dev/docs/mcp/servers/#capabilities-2) Capabilities * **Search the web** for information * **Get real-time information** not available in Kiro's training data ### [Copied!](https://kiro.dev/docs/mcp/servers/#setup-instructions-2) Setup Instructions #### [Copied!](https://kiro.dev/docs/mcp/servers/#prerequisites-2) Prerequisites 1. **Get a Brave Search API key**: * Sign up at [https://brave.com/search/api/](https://brave.com/search/api/) * Generate an API key #### [Copied!](https://kiro.dev/docs/mcp/servers/#configuration-2) Configuration json `{ "mcpServers": { "web-search": { "command": "npx", "args": [ "-y", "@modelcontextprotocol/server-bravesearch" ], "env": { "BRAVE_API_KEY": "your-api-key" } } } }` ### [Copied!](https://kiro.dev/docs/mcp/servers/#available-tools-2) Available Tools | Tool Name | Description | | --- | --- | | `brave_search` | Search the web using Brave Search | | `brave_search_news` | Search for news articles | ### [Copied!](https://kiro.dev/docs/mcp/servers/#usage-examples-2) Usage Examples `# Search for information Find the latest information about TypeScript 5.0 features # Search for news What are the latest developments in quantum computing?` [Copied!](https://kiro.dev/docs/mcp/servers/#remote-mcp-servers) Remote MCP Servers ----------------------------------------------------------------------------------- Kiro currently supports local stdio MCP servers, however you can add remote MCP servers by leveraging the [`mcp-remote`](https://www.npmjs.com/package/mcp-remote) npm package to make requests to the remote MCP endpoint. ### [Copied!](https://kiro.dev/docs/mcp/servers/#setup-instructions-3) Setup Instructions #### [Copied!](https://kiro.dev/docs/mcp/servers/#prerequisites-3) Prerequisites 1. **Install Node.js and NPM** if not already installed. #### [Copied!](https://kiro.dev/docs/mcp/servers/#configuration-3) Configuration json `{ "mcpServers": { "my-remote-mcp": { "command": "npx", "args": [ "mcp-remote", "https://", "--transport", "sse" ], "disabled": false } } }` [Copied!](https://kiro.dev/docs/mcp/servers/#custom-mcp-servers) Custom MCP Servers ----------------------------------------------------------------------------------- You can create your own MCP servers to extend Kiro's capabilities for your specific needs. ### [Copied!](https://kiro.dev/docs/mcp/servers/#creating-a-custom-server) Creating a Custom Server 1. **Choose a programming language** (Python, Node.js, etc.) 2. **Implement the MCP protocol** using available libraries 3. **Define your tools** and their capabilities 4. **Package and distribute** your server ### [Copied!](https://kiro.dev/docs/mcp/servers/#resources-for-custom-server-development) Resources for Custom Server Development * [MCP Protocol Specification](https://mcp.dev/spec) * [MCP Server Template (Python)](https://github.com/modelcontextprotocol/python-server-template) * [MCP Server Template (Node.js)](https://github.com/modelcontextprotocol/node-server-template) [Copied!](https://kiro.dev/docs/mcp/servers/#additional-mcp-servers) Additional MCP Servers ------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/servers/#database-servers) Database Servers * **PostgreSQL MCP Server**: Query and manage PostgreSQL databases * **MongoDB MCP Server**: Interact with MongoDB databases ### [Copied!](https://kiro.dev/docs/mcp/servers/#development-tools) Development Tools * **Docker MCP Server**: Manage Docker containers and images * **Kubernetes MCP Server**: Interact with Kubernetes clusters ### [Copied!](https://kiro.dev/docs/mcp/servers/#cloud-providers) Cloud Providers * **Azure MCP Server**: Interact with Azure services and resources * **GCP MCP Server**: Manage Google Cloud Platform resources [Copied!](https://kiro.dev/docs/mcp/servers/#finding-more-mcp-servers) Finding More MCP Servers ----------------------------------------------------------------------------------------------- To discover additional MCP servers: 1. Visit the [MCP Registry](https://mcp.dev/registry) 2. Check the [GitHub MCP Organization](https://github.com/modelcontextprotocol) 3. Search for "mcp-server" on npm or PyPI * * * _For information on configuring MCP servers, see the [MCP Configuration](https://kiro.dev/docs/mcp/configuration) page._ Page updated: July 11, 2025 [Configuration](https://kiro.dev/docs/mcp/configuration/) [Tools](https://kiro.dev/docs/mcp/usage/) * * * --- # Migrating from VSCode - Docs - Kiro Documentation Migrating from VSCode ===================== Built on Visual Studio Code's open source foundation, Kiro delivers AI-enhanced development capabilities while preserving the familiar interface you know. This shared architecture ensures a smooth transition when bringing your existing VS Code configuration to Kiro. [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#profile-migration) Profile Migration -------------------------------------------------------------------------------------------------- Kiro's VS Code foundation enables complete compatibility with your development environment. You can transfer your personalized setup—extensions, themes, configurations, and shortcuts—with no compatibility concerns. ### [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#manual-profile-migration) Manual Profile Migration For cross-machine transfers or granular control over your configuration, leverage VS Code's native profile export/import capabilities. #### [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#exporting-a-profile-from-vs-code) Exporting a Profile from VS Code 1. Launch the **Command Palette** in VS Code (`⌘`/`Ctrl` + `Shift` + `P`). 2. In the **Command Palette**, enter and select "Preferences: Open Profiles (UI)". 3. Locate your desired profile in the sidebar. 4. Access the 3-dot menu and choose **Export**. 5. Save locally or publish to a GitHub Gist. ![VS Code profile export interface showing the export options](https://kiro.dev/images/vscode-migrate-1-export-profile.png) #### [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#importing-a-profile-to-kiro) Importing a Profile to Kiro 1. Access Kiro's **Command Palette** (`⌘`/`Ctrl` + `Shift` + `P`). 2. In the **Command Palette**, enter and select "Preferences: Open Profiles (UI)". 3. Open the dropdown beside **New Profile** and select **Import Profile**. 4. Provide the GitHub Gist URL or browse for your local export file. 5. Confirm by choosing **Import** to save your configuration. 6. Activate your profile by selecting it in the sidebar and selecting the checkmark. Your imported profile includes: * Color themes and UI preferences * Editor and workspace settings * Custom keyboard shortcuts and keybindings [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#settings-and-interface) Settings and Interface ------------------------------------------------------------------------------------------------------------ ### [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#settings-menus) Settings Menus Kiro extends VS Code's settings architecture with dedicated controls for AI capabilities: **Kiro Settings** * Open Settings: **Command Palette** (`⌘`/`Ctrl` + `Shift` + `P`) → "Preferences: Open Settings (UI)" * Navigate to **Kiro Agent** section within the settings UI * Manage AI behaviors, agent automation, trusted commands, and Kiro-exclusive features ![Kiro Agent settings within the VS Code settings UI](https://kiro.dev/images/vscode-migrate-5-kiro-settings.png) **VS Code Settings** * Access the same way: **Command Palette** (`⌘`/`Ctrl` + `Shift` + `P`) → "Preferences: Open Settings (UI)" * Your standard VS Code preferences remain fully functional alongside Kiro settings ### [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#version-updates) Version Updates Kiro stays synchronized with VS Code's development cycle through regular rebasing. While we incorporate the latest features and improvements, we strategically select stable VS Code releases to ensure reliability alongside our AI enhancements. [Copied!](https://kiro.dev/docs/guides/migrating-from-vscode/#extension-compatibility) Extension Compatibility -------------------------------------------------------------------------------------------------------------- Kiro uses the OpenVSX extension registry, ensuring compatibility with open-source extensions. Extensions available in OpenVSX will migrate seamlessly, with many gaining enhanced capabilities through Kiro's AI integration: * **Language extensions**: Full functionality preserved for OpenVSX-available extensions * **Theme extensions**: Complete visual compatibility with OpenVSX themes * **Debugging extensions**: Uninterrupted debugging workflows for compatible extensions * **Git extensions**: Augmented with intelligent commit generation and automated code review Info Only extensions available in the OpenVSX registry can be imported. Some VS Code Marketplace exclusives may not be available in Kiro. Page updated: July 14, 2025 [Conclusion](https://kiro.dev/docs/guides/learn-by-playing/99-conclusion/) [Troubleshooting](https://kiro.dev/docs/reference/troubleshooting/) * * * --- # Tools - Docs - Kiro Documentation Tools ===== This guide explains how to effectively use Model Context Protocol (MCP) tools with Kiro to enhance your productivity and access specialized capabilities. [Copied!](https://kiro.dev/docs/mcp/usage/#interacting-with-mcp-tools) Interacting with MCP Tools ------------------------------------------------------------------------------------------------- Once you've [configured MCP servers](https://kiro.dev/docs/mcp/configuration) , you can interact with their tools in several ways: ### [Copied!](https://kiro.dev/docs/mcp/usage/#direct-questions) Direct Questions The simplest way to use MCP tools is to ask questions related to the server's domain: `Tell me about Amazon Bedrock` `How do I configure S3 bucket policies?` Kiro automatically selects the appropriate MCP tool based on your question. ### [Copied!](https://kiro.dev/docs/mcp/usage/#specific-tool-requests) Specific Tool Requests You can request specific MCP tools by describing what you want to do: `Search AWS documentation for information about ECS task definitions` `Get recommendations for AWS CloudFormation best practices` ### [Copied!](https://kiro.dev/docs/mcp/usage/#explicit-context) Explicit Context For more control, provide explicit context to the tool picker: `#[aws-docs] search_documentation Tell me about AWS Lambda` This format specifies both the server (`aws-docs`) and the tool (`search_documentation`). [Copied!](https://kiro.dev/docs/mcp/usage/#mcp-tools-panel) MCP Tools Panel --------------------------------------------------------------------------- The Kiro panel includes an MCP servers tab that provides: * A list of all configured MCP servers * Connection status indicators * Quick access to server tools To use this feature: 1. Select the Kiro icon in the activity bar 2. Navigate to the MCP servers tab 3. Click any tool name to insert a placeholder prompt in the chat [Copied!](https://kiro.dev/docs/mcp/usage/#tool-approval-process) Tool Approval Process --------------------------------------------------------------------------------------- When Kiro wants to use an MCP tool, it requests your approval first: 1. You'll see a prompt describing the tool and its purpose 2. Review the tool details and parameters 3. Click "Approve" to allow the tool to run, or "Deny" to prevent it ### [Copied!](https://kiro.dev/docs/mcp/usage/#auto-approving-trusted-tools) Auto-approving Trusted Tools To avoid repeated approval prompts for tools you trust: 1. Edit your MCP configuration file 2. Add tool names to the `autoApprove` array: json `{ "mcpServers": { "aws-docs": { "autoApprove": [ "mcp_aws_docs_search_documentation", "mcp_aws_docs_read_documentation" ] } } }` 3. Restart Kiro to apply changes [Copied!](https://kiro.dev/docs/mcp/usage/#examples-by-server-type) Examples by Server Type ------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/usage/#aws-documentation-server) AWS Documentation Server #### [Copied!](https://kiro.dev/docs/mcp/usage/#searching-documentation) Searching Documentation `Search AWS documentation for S3 bucket versioning` This uses the `mcp_aws_docs_search_documentation` tool to find relevant AWS documentation. #### [Copied!](https://kiro.dev/docs/mcp/usage/#reading-documentation) Reading Documentation `Read the AWS Lambda function URLs documentation` This uses the `mcp_aws_docs_read_documentation` tool to retrieve and display documentation content. #### [Copied!](https://kiro.dev/docs/mcp/usage/#getting-recommendations) Getting Recommendations `Find related content to AWS ECS task definitions` This uses the `mcp_aws_docs_recommend` tool to suggest related documentation. ### [Copied!](https://kiro.dev/docs/mcp/usage/#github-mcp-server) GitHub MCP Server #### [Copied!](https://kiro.dev/docs/mcp/usage/#repository-information) Repository Information `Show me information about the tensorflow/tensorflow repository` This retrieves details about the specified GitHub repository. #### [Copied!](https://kiro.dev/docs/mcp/usage/#code-search) Code Search `Find examples of React hooks in facebook/react` This searches for code matching your query in the specified repository. #### [Copied!](https://kiro.dev/docs/mcp/usage/#issue-management) Issue Management `Create an issue in my repository about the login bug` This helps you create a new GitHub issue with appropriate details. [Copied!](https://kiro.dev/docs/mcp/usage/#advanced-usage-techniques) Advanced Usage Techniques ----------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/mcp/usage/#chaining-mcp-tools) Chaining MCP Tools You can use multiple MCP tools in sequence for complex tasks: `First search AWS documentation for ECS task definitions, then find related content about service discovery` ### [Copied!](https://kiro.dev/docs/mcp/usage/#combining-with-local-context) Combining with Local Context MCP tools work best when combined with your local context: `Based on my Terraform code, help me optimize my AWS Lambda configuration using best practices from AWS documentation` ### [Copied!](https://kiro.dev/docs/mcp/usage/#using-mcp-tools-in-specs) Using MCP Tools in Specs You can use MCP tools within [Kiro Specs](https://kiro.dev/docs/specs) to enhance your development workflow: `In the implementation phase, use AWS documentation to ensure our S3 bucket configuration follows best practices` [Copied!](https://kiro.dev/docs/mcp/usage/#troubleshooting-tool-usage) Troubleshooting Tool Usage ------------------------------------------------------------------------------------------------- If you encounter issues when using MCP tools: ### [Copied!](https://kiro.dev/docs/mcp/usage/#tool-not-responding) Tool Not Responding 1. Check the MCP server status in the Kiro panel 2. Review the MCP logs for error messages 3. Restart the MCP server if necessary ### [Copied!](https://kiro.dev/docs/mcp/usage/#incorrect-results) Incorrect Results 1. Try rephrasing your request to be more specific 2. Check that you're using the appropriate tool for your task 3. Verify that the MCP server has the necessary permissions ### [Copied!](https://kiro.dev/docs/mcp/usage/#tool-not-available) Tool Not Available 1. Ensure the MCP server is properly configured 2. Check that the server is running and connected 3. Verify that you have the necessary permissions to use the tool [Copied!](https://kiro.dev/docs/mcp/usage/#best-practices) Best Practices ------------------------------------------------------------------------- * **Be specific** in your requests to get the most relevant results * **Start with direct questions** before using explicit tool references * **Auto-approve only tools** you trust and use frequently * **Combine MCP tools** with local context for best results * **Check tool parameters** before approval to ensure they're correct * * * _For information on available MCP servers and their tools, see the [MCP Servers](https://kiro.dev/docs/mcp/servers) page._ Page updated: June 20, 2025 [Servers](https://kiro.dev/docs/mcp/servers/) [Best Practices](https://kiro.dev/docs/mcp/security/) * * * --- # Privacy & Security - Docs - Kiro Documentation Privacy & Security ================== Kiro is an AWS application that works as a standalone agentic IDE. Kiro's security framework is built around AWS's security infrastructure and follows practices to protect your development environment and data. Cloud security at AWS is the highest priority. As an AWS customer, you benefit from a data center and network architecture that is built to meet the requirements of the most security-sensitive organizations. Security is a shared responsibility between AWS and you. The [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) describes this as security of the cloud and security in the cloud: * Security of the cloud – AWS is responsible for protecting the infrastructure that runs AWS services in the AWS Cloud. AWS also provides you with services that you can use securely. Third-party auditors regularly test and verify the effectiveness of our security as part of the [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/) . To learn about the compliance programs that apply to Kiro, see [AWS Services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) . * Security in the cloud – Your responsibility is determined by the AWS service that you use. You are also responsible for other factors including the sensitivity of your data, your company’s requirements, and applicable laws and regulations This documentation helps you understand how to apply the shared responsibility model when using Kiro. It shows you how to configure Kiro to meet your security and compliance objectives. You also learn how to use other AWS services that help you to monitor and secure your Kiro resources. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#data-protection) Data protection ------------------------------------------------------------------------------------------------ The AWS [shared responsibility model](https://aws.amazon.com/compliance/shared-responsibility-model/) applies to data protection in Kiro. As described in this model, AWS is responsible for protecting the global infrastructure that runs all of the AWS Cloud. You are responsible for maintaining control over your content that is hosted on this infrastructure. You are also responsible for the security configuration and management tasks for the AWS services that you use. For more information about data privacy, see the [Data Privacy FAQ](https://aws.amazon.com/compliance/data-privacy-faq/) . ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#data-storage) Data storage Kiro stores your questions, its responses, and additional context, such as code, to generate new responses to your requests. For information about how data is encrypted, see [Data encryption](https://kiro.dev/docs/reference/privacy-and-security/#data-encryption) . For information about how AWS may use some questions that you ask Kiro and its responses to improve our services, see [Kiro service improvement](https://kiro.dev/docs/reference/privacy-and-security/#service-improvement) . #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#aws-regions-where-content-is-stored-and-processed) AWS Regions where content is stored and processed Your content, such as prompts and responses, will be stored in the US East (N. Virginia) Region. When you use any features in Kiro, your user content will be processed in a US Region. For more information, see [Cross-region processing](https://kiro.dev/docs/reference/privacy-and-security/#cross-region-processing) . ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#cross-region-processing) Cross-region processing The following sections describe how cross-region inference and cross-region calls are used to provide the Kiro service. #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#cross-region-inference) Cross-region inference Kiro is powered by Amazon Bedrock, and uses cross-region inference to distribute traffic across different AWS Regions to enhance large language model (LLM) inference performance and reliability. With cross-region inference, you get increased throughput and resilience during high demand periods, as well as improved performance. Cross region inference doesn’t affect where your data is stored. For information on where data is stored when you use Kiro, see [Data protection](https://kiro.dev/docs/reference/privacy-and-security/#data-protection) . #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#supported-regions-for-kiro-cross-region-inference) Supported regions for Kiro cross-region inference | Supported Kiro geography | Inference regions | | --- | --- | | United States | * US East (N. Virginia) (`us-east-1`)
* US West (Oregon) (`us-west-2`)
* US East (Ohio) (`us-east-2`) | ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#data-encryption) Data encryption This topic provides information specific to Kiro about encryption in transit and encryption at rest. #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#encryption-in-transit) Encryption in transit All communication between customers and Kiro and between Kiro and its downstream dependencies is protected using TLS 1.2 or higher connections. #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#encryption-at-rest) Encryption at rest Kiro encrypts your data using AWS owned encryption keys from AWS Key Management Service (AWS KMS). You don’t have to take any action to protect the AWS managed keys that encrypt your data. For more information, see [AWS owned keys](https://docs.aws.amazon.com/kms/latest/developerguide/concepts.html#aws-owned-cmk) in the _AWS Key Management Service Developer Guide_. ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#service-improvement) Service improvement To help Kiro provide the most relevant information, we may use certain content from Kiro, such as questions that you ask Kiro and its responses, for service improvement. This page explains what content we use and how to opt out. #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#kiro-content-used-for-service-improvement) Kiro content used for service improvement We may use certain content from Kiro for service improvement. Kiro may use this content, for example, to provide better responses to common questions, fix Kiro operational issues, for de-bugging, or for model training. Content that Kiro may use for service improvement includes, for example, your questions to Kiro and the responses and code that Kiro generates. Info If you have an Amazon Q Developer Pro subscription and access Kiro through your AWS account with the Amazon Q Developer Pro subscription, then Kiro will not use your content for service improvement. #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#how-to-opt-out) How to opt out In Kiro, for the Free Tier, adjust your settings in the IDE. For more information, see [Opt out of data sharing in the IDE](https://kiro.dev/docs/reference/privacy-and-security/#opt-out-of-data-sharing-in-the-ide) . ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#opt-out-of-data-sharing-in-the-ide) Opt out of data sharing in the IDE By default, Kiro collects usage data, errors, crash reports, and content for service improvement. This page explains how to opt out of sharing your data in Kiro, including the core application, first-party extensions, and participating third-party extensions. Note that if you opt out, you'll be opting out of sharing both your telemetry and content. For information on how Kiro uses this data, see [Kiro service improvement](https://kiro.dev/docs/reference/privacy-and-security/#service-improvement) . #### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#opting-out-of-sharing-your-client-side-telemetry-and-content) Opting out of sharing your client-side telemetry and content To opt out of sharing your telemetry data in Kiro, use this procedure: 1. Open **Settings** in Kiro. 2. Switch to the **User** sub-tab. 3. Choose **Application**, and from the drop-down choose **Telemetry and Content**. 4. In the **Telemetry and Content** drop-down field, select **Disabled** to disable all product telemetry and user data collection.\\ ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#types-of-telemetry-collected) Types of telemetry collected * **Usage data** — Information such as the Kiro version, operation system (Windows, Linux, or macOS), and the anonymous machine ID. * **Performance metrics** — The request count, errors, and latency for various features: * Login * Tab completion * Code generation * Steering * Hooks * Spec generation * Tools * MCP [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#monitoring-and-tracking-the-use-of-kiro) Monitoring and tracking the use of Kiro ------------------------------------------------------------------------------------------------------------------------------------------------ Monitoring is an important part of maintaining the reliability, availability, and performance of Kiro. AWS provides the following monitoring tools and features to monitor and record Kiro activity: * AWS CloudTrail captures API calls and related events made by or on behalf of your AWS account and delivers the log files to an Amazon Simple Storage Service (Amazon S3) bucket that you specify. You can identify which users and accounts called AWS, the source IP address from which the calls were made, and when the calls occurred. All Kiro actions are logged by CloudTrail and generate entries in the CloudTrail log files. * Amazon CloudWatch monitors your AWS resources and the applications you run on AWS in real time. You can collect and track metrics, create customized dashboards, and set alarms that notify you or take actions when a specified metric reaches a threshold that you specify. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#compliance-validation-for-kiro) Compliance validation for Kiro ------------------------------------------------------------------------------------------------------------------------------ To learn whether an AWS service is within the scope of specific compliance programs, see [AWS services in Scope by Compliance Program](https://aws.amazon.com/compliance/services-in-scope/) and choose the compliance program that you are interested in. For general information, see [AWS Compliance Programs](https://aws.amazon.com/compliance/programs/) . You can download third-party audit reports using AWS Artifact. For more information, see [Downloading Reports in AWS Artifact](https://docs.aws.amazon.com/artifact/latest/ug/downloading-documents.html) . If you are signing in to Kiro with GitHub or Google, you will not be able to download third-party audit reports using AWS Artifact. Your compliance responsibility when using AWS services is determined by the sensitivity of your data, your company's compliance objectives, and applicable laws and regulations. AWS provides the following resources to help with compliance: * [Security Compliance & Governance](https://aws.amazon.com/solutions/security/security-compliance-governance/) – These solution implementation guides discuss architectural considerations and provide steps for deploying security and compliance features. * [HIPAA Eligible Services Reference](https://aws.amazon.com/compliance/hipaa-eligible-services-reference/) – Lists HIPAA eligible services. Not all AWS services are HIPAA eligible. * [AWS Compliance Resources](https://aws.amazon.com/compliance/resources/) – This collection of workbooks and guides might apply to your industry and location. * [AWS Customer Compliance Guides](https://d1.awsstatic.com/whitepapers/compliance/AWS_Customer_Compliance_Guides.pdf) in the _AWS Config Developer Guide_ – Understand the shared responsibility model through the lens of compliance. The guides summarize the best practices for securing AWS services and map the guidance to security controls across multiple frameworks (including National Institute of Standards and Technology (NIST), Payment Card Industry Security Standards Council (PCI), and International Organization for Standardization (ISO)). * [Evaluating Resources with Rules](https://docs.aws.amazon.com/config/latest/developerguide/evaluate-config.html) – The AWS Config service assesses how well your resource configurations comply with internal practices, industry guidelines, and regulations. * [AWS Security Hub](https://docs.aws.amazon.com/securityhub/latest/userguide/what-is-securityhub.html) – This AWS service provides a comprehensive view of your security state within AWS. Security Hub uses security controls to evaluate your AWS resources and to check your compliance against security industry standards and best practices. For a list of supported services and controls, see [Security Hub controls reference](https://docs.aws.amazon.com/securityhub/latest/userguide/securityhub-controls-reference.html) . * [Amazon GuardDuty](https://docs.aws.amazon.com/guardduty/latest/ug/what-is-guardduty.html) – This AWS service detects potential threats to your AWS accounts, workloads, containers, and data by monitoring your environment for suspicious and malicious activities. GuardDuty can help you address various compliance requirements, like PCI DSS, by meeting intrusion detection requirements mandated by certain compliance frameworks. * [AWS Audit Manager](https://docs.aws.amazon.com/audit-manager/latest/userguide/what-is.html) – This AWS service helps you continuously audit your AWS usage to simplify how you manage risk and compliance with regulations and industry standards. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#resilience-in-kiro) Resilience in Kiro ------------------------------------------------------------------------------------------------------ The AWS global infrastructure is built around AWS Regions and Availability Zones. AWS Regions provide multiple physically separated and isolated Availability Zones, which are connected with low-latency, high-throughput, and highly redundant networking. With Availability Zones, you can design and operate applications and databases that automatically fail over between zones without interruption. Availability Zones are more highly available, fault tolerant, and scalable than traditional single or multiple data center infrastructures. For more information about AWS Regions and Availability Zones, see [AWS Global Infrastructure](http://aws.amazon.com/about-aws/global-infrastructure/) . ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#infrastructure-security-in-kiro) Infrastructure security in Kiro As a managed service, Kiro is protected by AWS global network security. For information about AWS security services and how AWS protects infrastructure, see [AWS Cloud Security](https://aws.amazon.com/security/) . To design your AWS environment using the best practices for infrastructure security, see [Infrastructure Protection](https://docs.aws.amazon.com/wellarchitected/latest/security-pillar/infrastructure-protection.html) in _Security Pillar AWS Well‐Architected Framework_. You use AWS published API calls to access Kiro through the network. Clients must support the following: * Transport Layer Security (TLS). We require TLS 1.2 and recommend TLS 1.3. * Cipher suites with perfect forward secrecy (PFS) such as DHE (Ephemeral Diffie-Hellman) or ECDHE (Elliptic Curve Ephemeral Diffie-Hellman). Most modern systems such as Java 7 and later support these modes. Additionally, requests must be signed by using an access key ID and a secret access key that is associated with an IAM principal. Or you can use the [AWS Security Token Service](https://docs.aws.amazon.com/STS/latest/APIReference/welcome.html) (AWS STS) to generate temporary security credentials to sign requests. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#url-fetching) URL fetching ------------------------------------------------------------------------------------------ In the Kiro chat module, you can paste a specific URL for your device to fetch and use it as context to help Kiro answer your query or solve your task. You are responsible for the URL content that you fetch and ensuring that your use complies with any applicable third-party terms and laws. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#autopilot-versus-supervised-mode) Autopilot versus Supervised Mode ---------------------------------------------------------------------------------------------------------------------------------- In Kiro, Autopilot is enabled by default. You can toggle between Autopilot and Supervised mode at any time. Autopilot mode enables the agent to execute code changes, such as creating, modifying, searching, and deleting files in your codebase and run commands that impact the filesystem. ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#autopilot-mode) Autopilot Mode In Autopilot mode, Kiro works autonomously: * Kiro executes multiple steps without requiring approval for each one * Kiro makes decisions based on its understanding of your requirements * You can toggle autopilot on/off in the chat interface * You can interrupt autopilot at any time to regain manual control ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#supervised-mode) Supervised Mode In supervised mode, Kiro works interactively with the user, requiring their approval and guidance at each step: * Kiro suggests actions such as file creation, modification and deletion, but waits for user confirmation before proceeding * Kiro asks clarifying questions when needed * You can review and approve each generated document or code change, thus maintaining full control over the development process When operating in either of these modes, you can view individual or all file changes made by the agent by selecting **View all changes** in the **Chat** module. Additionally, you can also select **Revert all changes** to restore your files to their previous state in the filesystem locally. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#trusted-commands) Trusted commands -------------------------------------------------------------------------------------------------- By default, the Kiro agent in Autopilot or Supervised mode is only allowed to run the following read-only commands without human approval: * `ls` * `cat` * `echo` * `pwd` * `which` * `head` * `tail` * `find` * `grep` Any command that needs to be executed outside the above list will require human approval prior to execution. Additionally, you can create your own trusted commands list by searching for **Kiro Agent: Trusted Commands** in your settings. You can add shell commands to auto-accept if requested by the Kiro Agent, and all other commands will be auto-denied. [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#security-best-practices) Security best practices ---------------------------------------------------------------------------------------------------------------- Kiro provides a number of security features to consider as you develop and implement your own security policies. The following best practices are general guidelines and don’t represent a complete security solution. Because these best practices might not be appropriate or sufficient for your environment, treat them as helpful considerations rather than prescriptions. ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#protecting-your-resources) Protecting your resources When using GitHub or Google authentication with Kiro, be aware that the Kiro agent operates within your local environment and may access: * Local files and repositories * Environment variables * AWS credentials stored in your environment * Other configuration files with sensitive information ### [Copied!](https://kiro.dev/docs/reference/privacy-and-security/#recommendations) Recommendations 1. **Workspace Isolation** * Keep sensitive projects in separate workspaces * Use .gitignore to prevent access to sensitive files * Consider using workspace trust features in your IDE 2. **Use a Clean Environment** * Consider creating a dedicated user account or container environment for Kiro * Limit access to only the repositories and resources needed for your current project 3. **Manage AWS Credentials Carefully** * Use temporary credentials with appropriate permissions * Consider using AWS named profiles to isolate Kiro's access * For sensitive work, remove AWS credentials from your environment when not needed 4. **Repository Access Control** * When using GitHub authentication, review which repositories Kiro can access * Use repository-specific access tokens when possible * Regularly audit access permissions By following these practices, you can enjoy Kiro's capabilities while maintaining appropriate security boundaries for your development environment. Page updated: July 14, 2025 [Auth Methods](https://kiro.dev/docs/reference/auth-methods/) * * * --- # Authentication Methods - Docs - Kiro Documentation Authentication Methods ====================== Kiro supports the following authentication providers: * GitHub: Seamless integration with your GitHub account * Google: Sign in with your Google credentials * AWS Builder ID: Quick setup for individual developers * AWS IAM Identity Center: Enterprise-grade authentication with Amazon Q Dev Pro subscription Kiro is an AWS application that works as a standalone agentic IDE without needing to set up an AWS account. You can download and use Kiro immediately without any external account setup - it handles AI interactions and code assistance directly through the application itself. Whether you're developing with other AWS services or not, you can leverage Kiro's full capabilities to enhance your development workflow. [Copied!](https://kiro.dev/docs/reference/auth-methods/#available-authentication-methods) Available Authentication Methods -------------------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/auth-methods/#github) GitHub Use the following instructions to sign in to Kiro using GitHub. **To sign in with GitHub** 1. In Kiro, choose **Sign in with GitHub**. You will be redirected to your default web browser to complete the sign in process. 2. Enter your username or email address and your password and then choose **Sign in**. 3. Choose **Authorize kirodotdev** to authorize the Kiro App with your GitHub account. ### [Copied!](https://kiro.dev/docs/reference/auth-methods/#google) Google Use the following instructions to sign in to Kiro using Google. **To sign in with Google** 1. In Kiro, choose **Sign in with Google**. You will be redirected to your default web browser to complete the sign in process. 2. Choose a Google account that you’d like to use with Kiro. 3. Choose **Continue** to authorize the Kiro App with your Google account. ### [Copied!](https://kiro.dev/docs/reference/auth-methods/#aws-builder-id) AWS Builder ID Use the following instructions to sign in to Kiro using AWS Builder ID. **To sign in with AWS Builder ID** 1. In Kiro, choose **Login with AWS Builder ID**. You will be redirected to your default web browser to complete the sign in process. 2. Enter your email address and then choose **Next**. 3. Enter your password and then choose **Sign in**. 4. Choose **Allow access** to authorize the Kiro App. ### [Copied!](https://kiro.dev/docs/reference/auth-methods/#aws-iam-identity-center) AWS IAM Identity Center Use the following instructions to sign in to Kiro using AWS IAM Identity Center. **To sign in with AWS IAM Identity Center** 1. In Kiro, choose **Sign in with AWS IAM Identity Center**. 2. In **Start URL**, enter the start URL provided by your admin or help desk. 3. In **Region**, enter the AWS Region that hosts the identity directory, and then choose **Continue**. [Copied!](https://kiro.dev/docs/reference/auth-methods/#troubleshooting-authentication-issues) Troubleshooting Authentication Issues ------------------------------------------------------------------------------------------------------------------------------------ If you encounter problems during the authentication process, such as browser redirect failures or sign-in errors, check our [troubleshooting guide](https://kiro.dev/docs/reference/troubleshooting#authentication-issues) for platform-specific solutions and common fixes. [Copied!](https://kiro.dev/docs/reference/auth-methods/#next-steps) Next Steps ------------------------------------------------------------------------------ * [Review FAQ](https://kiro.dev/faq) * [Explore Agent features](https://kiro.dev/docs/chat) * [Get started with Kiro](https://kiro.dev/docs/getting-started) Page updated: July 14, 2025 [Troubleshooting](https://kiro.dev/docs/reference/troubleshooting/) [Privacy & Security](https://kiro.dev/docs/reference/privacy-and-security/) * * * --- # TypeScript and JavaScript - Docs - Kiro Documentation TypeScript and JavaScript ========================= Kiro provides powerful AI-assisted development capabilities for TypeScript and JavaScript projects, helping you write, debug, and maintain code more efficiently. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#prerequisites) Prerequisites ------------------------------------------------------------------------------------------------------------------------- Before diving into TypeScript and JavaScript development with Kiro, ensure you have: * [**Node.js**](https://nodejs.org/) : Install the latest version for your platform * [**TypeScript**](https://www.typescriptlang.org/) : Install globally or locally in your project * **Package Manager**: npm (comes with Node.js) or your preferred package manager * [**Git**](https://git-scm.com/) : For version control and collaboration [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#suggested-extensions) Suggested Extensions --------------------------------------------------------------------------------------------------------------------------------------- To enhance your TypeScript and JavaScript development experience with Kiro, consider installing these helpful extensions: * [**ESLint**](https://open-vsx.org/extension/dbaeumer/vscode-eslint) - Real-time code quality feedback and linting for JavaScript/TypeScript * [**Prettier - Code Formatter**](https://open-vsx.org/extension/esbenp/prettier-vscode) - Automatic code formatting for consistent style across your project * [**Auto Rename Tag**](https://open-vsx.org/extension/formulahendry/auto-rename-tag) - Automatically renames paired HTML/JSX tags when editing * [**JavaScript (ES6) code snippets**](https://open-vsx.org/extension/xabikos/JavaScriptSnippets) - Provides useful code snippets for modern JavaScript and TypeScript development [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#working-with-your-environment) Working With Your Environment --------------------------------------------------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#project-configuration-and-structure) Project Configuration and Structure Kiro can help you set up and maintain configuration files for your TypeScript and JavaScript projects, as well as organize your project following Kiro's best practices. For example, you can ask Kiro: `"Create a tsconfig.json for a React TypeScript project using ES6 modules" "Update my ESLint config to enforce React best practices" "Set up a monorepo structure for my frontend and backend TypeScript code"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#code-analysis-and-refactoring) Code Analysis and Refactoring Kiro can analyze your TypeScript and JavaScript code to identify issues and suggest improvements: * **Code Quality Analysis**: Ask Kiro to review your code for potential bugs, performance issues, or style issues. * **Refactoring Assistance**: Get help extracting functions, renaming variables, or restructuring code. * **Type Inference**: Kiro can suggest TypeScript types based on your JavaScript code. Example prompts: `"Analyze this function for potential bugs" "Refactor this code to use async/await instead of promises" "Convert this JavaScript file to TypeScript with proper types"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#debugging-assistance) Debugging Assistance When you encounter errors in your TypeScript or JavaScript code: * **Error Explanation**: Kiro can explain cryptic error messages in plain language * **Solution Suggestions**: Kiro can suggest actionable fixes for common errors * **Runtime Debugging**: Kiro can help set up debugging configurations Examples: `"Explain this TypeScript error: TS2339: Property 'value' does not exist on type 'never'" "Help me debug this React useEffect infinite loop"` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#steering) Steering --------------------------------------------------------------------------------------------------------------- [Steering](https://kiro.dev/docs/steering) allows you to provide Kiro with project specific context and guidelines. Kiro can generate steering files which you can refine: 1. **Product brief** (`product.md`) - Contains information about the product, its purpose, and key features 2. **Technical Stack** (`tech.md`) - Details the technologies, frameworks, and development guidelines 3. **Project Structure** (`structure.md`) - Provides information about how the project is organized For TypeScript and JavaScript projects, you can create additional custom steering files to provide more specific guidance. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#creating-custom-steering-files) Creating Custom Steering Files Use the following instructions to add new steering documents to your project. **To add new steering documents** 1. Navigate to the **Kiro** view in the sidebar. 2. In the **Agent Steering** section, choose the `+` button to create a new steering file. 3. Enter a name for your file with a descriptive title. 4. Add your custom steering content following markdown conventions. Custom steering files are stored in the `.kiro/steering/` directory and are automatically recognized by Kiro during interactions. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#code-style-and-conventions) Code Style and Conventions You can define custom naming conventions, file structure, or practices for your project. You can create a `js-conventions.md` steering file to define your team's coding standards: markdown `# TypeScript/JavaScript Conventions ## Naming Conventions - Use camelCase for variables and functions - Use PascalCase for classes and React components - Use UPPER_SNAKE_CASE for constants ## File Structure - One component per file - Group related components in folders - Use index.ts files for exports ## TypeScript Practices - Prefer interfaces over types for public APIs - Use explicit return types for exported functions - Avoid using 'any' type` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#framework-specific-guidelines) Framework Specific Guidelines For React projects, you can create a `react-patterns.md` steering file: markdown `# React Development Guidelines ## Component Structure - Use functional components with hooks - Separate business logic from UI components - Follow the container/presentational pattern ## State Management - Use React Context for global state - Prefer useState for local component state - Use useReducer for complex state logic ## Performance Optimization - Memoize expensive calculations with useMemo - Prevent unnecessary re-renders with React.memo - Use useCallback for event handlers passed to child components` These steering files help Kiro generate code that follows your team's specific conventions and best practices. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#agent-hooks) Agent Hooks --------------------------------------------------------------------------------------------------------------------- Kiro's [Agent Hooks](https://kiro.dev/docs/hooks) can automate common TypeScript and JavaScript development tasks: 1. Navigate to the **Agent Hooks** section in the Kiro panel 2. Click the **+** button to create a new hook 3. Define the hook workflow in natural language Here are some hook examples: ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#test-generation-hook) Test Generation Hook You can automatically generate tests when you save a TypeScript or JavaScript file: `"Create a hook that generates Jest tests when I save a new component"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#type-checking-hook) Type Checking Hook You can run TypeScript type checking in the background: `"Set up a hook to run TypeScript type checking when I save files"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#dependency-update-hook) Dependency Update Hook You can keep your dependencies up to date: `"Create a hook that checks for outdated npm packages"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#eslint-auto-fix-hook) ESLint Auto-Fix Hook `When a JavaScript or TypeScript file is saved: 1. Run ESLint with auto-fix on the file 2. Report any remaining issues that couldn't be fixed automatically 3. Suggest fixes for complex issues` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#component-documentation-hook) Component Documentation Hook `When a React component file is saved: 1. Extract the component's props interface 2. Update or create a documentation comment above the component 3. Generate usage examples based on the props 4. Update the component's README.md if it exists` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#mcp-servers) MCP Servers --------------------------------------------------------------------------------------------------------------------- Kiro's support for Model Context Protocol (MCP) servers enhance your TypeScript and JavaScript development experience by providing specialized tools and capabilities. For a complete guide on setting up and using MCP, see the [MCP documentation](https://kiro.dev/docs/mcp) . ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#frontend-mcp-server) Frontend MCP Server The AWS Labs Frontend MCP Server provides specialized tools for modern web application development, offering comprehensive documentation and guidance for React applications: json `{ "mcpServers": { "frontend": { "command": "uvx", "args": ["awslabs.frontend-mcp-server@latest"], "env": { "FASTMCP_LOG_LEVEL": "ERROR" } } } }` Example usage: `"Get essential knowledge for React development" "Help me troubleshoot this React component issue" "Show me best practices for modern React applications"` Explore more MCP servers in the [AWS MCP Servers](https://awslabs.github.io/mcp/) and [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) collection. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#documentation-access-with-docs) Documentation Access with #docs ------------------------------------------------------------------------------------------------------------------------------------------------------------ Kiro provides built-in access to documentation for JavaScript, TypeScript, and popular frameworks through the `#docs` reference system. This allows you to quickly bring relevant documentation into your conversations with Kiro. Simply type `#docs` in the chat and select from the available documentation sources, such as: * **#Node.js** - Node.js runtime documentation * **#TypeScript** - TypeScript language documentation * **#React** - React library documentation * **#Svelte** - Svelte framework documentation * **#Express** - Express.js framework documentation * **#Vue.js** - Vue.js framework documentation * **#Alpine.js** - Alpine.js framework documentation Example usage: `"#TypeScript How do I create a generic function?" "#React What's the best way to handle form state?"` You can also reference specific documentation URLs using `#URL`: `"#URL https://react.dev/reference/react/useState"` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#debugging-issues) Debugging Issues ------------------------------------------------------------------------------------------------------------------------------- When you encounter issues, Kiro can help diagnose and fix them: 1. **Inline Chat**: * Type `Cmd/Ctrl + I` to open the inline chat. * Ask Kiro to help debug your code with natural language. 2. **Add to Chat**: * Type `Cmd/Ctrl + L` to add the current file to the chat. * Ask Kiro to help debug your code with natural language. 3. **Quick Fix**: * Hover on an error or warning, then select `Quick fix` and `Ask Kiro`. * Kiro will automatically add the code to the chat and start debugging. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/#resources) Resources ----------------------------------------------------------------------------------------------------------------- * [TypeScript Documentation](https://www.typescriptlang.org/docs/) * [JavaScript MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript) * [Node.js Documentation](https://nodejs.org/en/docs/) Page updated: July 14, 2025 [Language support](https://kiro.dev/docs/guides/languages-and-frameworks/) [Python](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/) * * * --- # Python - Docs - Kiro Documentation Python ====== Kiro provides powerful AI-assisted development capabilities for Python projects, helping you write, debug, and maintain code more efficiently. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#prerequisites) Prerequisites ---------------------------------------------------------------------------------------------------------- Before diving into Python development with Kiro, ensure you have: * **Python**: Install the [latest version](https://www.python.org/downloads/) for your platform (Python 3.8+ recommended) * **pip**: Package installer for Python (comes with Python) * **Virtual Environment**: Use `venv`, `virtualenv`, or `conda` for dependency management * **Git**: For version control and collaboration [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#extensions) Extensions ---------------------------------------------------------------------------------------------------- Kiro supports extensions from Open VSX that can enhance your Python development experience. Here are some helpful extensions you can install: * [**Python**](https://open-vsx.org/extension/ms-python/python) - Python language support with extension access points for IntelliSense (Pylance), Debugging (Python Debugger), linting, formatting, refactoring, unit tests, and more. * [**PyLint**](https://open-vsx.org/extension/ms-python/pylint) - Linting support for Python files. * [**Jupyter**](https://open-vsx.org/extension/ms-toolsai/jupyter) - Jupyter notebook support, interactive programming and computing that supports Intellisense, debugging and more. * [**Python Debugger**](https://open-vsx.org/extension/ms-python/debugpy) - Python debugger (debugpy) extension providing debugging capabilities for Python applications. * [**Rainbow CSV**](https://open-vsx.org/extension/mechatroner/rainbow-csv) - Highlight CSV and TSV files, Run SQL-like queries You can install these extensions in Kiro, use the Extensions panel and search for the extension names listed above. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#working-with-your-environment) Working With Your Environment ------------------------------------------------------------------------------------------------------------------------------------------ With Kiro, you can leverage the chat capabilities to setup a new project or work on an existing one. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#project-configuration-and-structure) Project Configuration and Structure Kiro can help you set up and maintain configuration files for your Python projects, and organize your project following Python best practices. * **Initialize configuration files**: Ask Kiro to initialize default configuration files based on the project. * **Create project structure**: Ask Kiro to create the structure of your project based on needs and best practices. Example prompts: `"Set up a requirements.txt with development dependencies" "Configure a .env file for my Django application" "Set up a Python package structure with proper __init__.py files" "Create a Flask project structure with blueprints" "Organize my data science project with notebooks and modules" "Create a pyproject.toml for a FastAPI project with pytest and black"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#code-analysis-and-refactoring) Code Analysis and Refactoring Kiro can analyze your Python code to identify issues and suggest improvements: * **Code Quality Analysis**: Ask Kiro to review your code for potential bugs, performance issues, or PEP 8 compliance * **Refactoring Assistance**: Get help extracting functions, renaming variables, or restructuring code * **Type Hints**: Kiro can suggest type annotations to improve code clarity and catch errors Example prompts: `"Analyze this function for potential bugs and performance issues" "Refactor this code to follow PEP 8 style guidelines" "Add type hints to this Python module" "Convert this synchronous code to use async/await"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#debugging-assistance) Debugging Assistance When you encounter errors in your Python code: * **Error Explanation**: Kiro can explain Python tracebacks and error messages in plain language * **Solution Suggestions**: Get actionable fixes for common Python errors * **Runtime Debugging**: Kiro can help set up debugging configurations and breakpoints Examples: `"Explain this Python error: AttributeError: 'NoneType' object has no attribute 'split'" "Help me debug this Django view that's returning a 500 error" "Why is my pandas DataFrame operation so slow?"` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#steering) Steering ------------------------------------------------------------------------------------------------ [Steering](https://kiro.dev/docs/steering) allows you to provide Kiro with project specific context and guidelines. Kiro can generate steering files which you can refine: 1. **Product brief** (`product.md`) - Contains information about the product, its purpose, and key features 2. **Technical Stack** (`tech.md`) - Details the technologies, frameworks, and development guidelines 3. **Project Structure** (`structure.md`) - Provides information about how the project is organized For Python projects, you can create additional custom steering files to provide more specific guidance: ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#creating-custom-steering-files) Creating Custom Steering Files Use the following instructions to add new steering documents to your project. **To add new steering documents** 1. Navigate to the **Kiro** view in the sidebar. 2. In the **Agent Steering** section, choose the `+` button to create a new steering file. 3. Enter a name for your file with a descriptive title. 4. Add your custom steering content following markdown conventions. Custom steering files are stored in the `.kiro/steering/` directory and are automatically recognized by Kiro during interactions. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#code-style-and-conventions) Code Style and Conventions For example, you can define custom naming conventions, file structure, or practices for your project. Create a `python-conventions.md` steering file to define your team's coding standards: markdown `Python Conventions Naming Conventions - Use snake_case for variables and functions - Use PascalCase for classes - Use UPPER_SNAKE_CASE for constants - Use descriptive names that explain purpose Code Style - Follow PEP 8 guidelines - Use Black for code formatting - Maximum line length of 88 characters - Use type hints for all public functions File Structure - One class per file for large classes - Group related functions in modules - Use __init__.py files for package organization - Separate tests in tests/ directory Documentation - Use docstrings for all public functions and classes - Follow Google or NumPy docstring style - Include type information in docstrings` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#framework-specific-guidelines) Framework Specific Guidelines For Django projects, create a `django-patterns.md` steering file: markdown `Django Development Guidelines Model Design - Use descriptive model names - Add __str__ methods to all models - Use model managers for complex queries - Follow Django naming conventions for fields View Structure - Prefer class-based views for complex logic - Use function-based views for simple operations - Keep business logic in models or services - Use proper HTTP status codes Template Organization - Use template inheritance effectively - Keep templates DRY with includes and tags - Use meaningful template names - Organize templates by app Performance Best Practices - Use select_related and prefetch_related for queries - Implement database indexing for frequently queried fields - Use caching for expensive operations - Profile database queries in development` For data science projects, create a `data-science-patterns.md` steering file: markdown `Data Science Development Guidelines Notebook Organization - Use clear section headers and markdown cells - Keep notebooks focused on single analyses - Export reusable code to Python modules - Include data source documentation Data Handling - Validate data quality early in pipelines - Use consistent column naming conventions - Document data transformations clearly - Handle missing values explicitly Model Development - Use cross-validation for model evaluation - Track experiments with clear versioning - Document model assumptions and limitations - Implement proper train/validation/test splits Code Organization - Separate data processing, modeling, and visualization - Use configuration files for parameters - Implement logging for long-running processes - Create reproducible environments with requirements files` These steering files help Kiro generate code that follows your team's specific conventions and best practices. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#agent-hooks) Agent Hooks ------------------------------------------------------------------------------------------------------ Kiro's [Agent Hooks](https://kiro.dev/docs/hooks) can automate common Python development tasks: 1. Navigate to the **Agent Hooks** section in the Kiro panel 2. Click the **+** button to create a new hook 3. Define the hook workflow in natural language Here are some hook examples: ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#test-generation-hook) Test Generation Hook Automatically generate tests when you save a Python file: `"Create a hook that generates pytest tests when I save a new Python module"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#dependency-update-hook) Dependency Update Hook Keep your dependencies up to date: `"Create a hook that checks for outdated pip packages and suggests updates"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#linting-hook) Linting Hook `When a Python file is saved: 1. Run flake8 or pylint on the file 2. Report any style or quality issues 3. Suggest fixes for common problems 4. Update docstrings if missing` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#virtual-environment-hook) Virtual Environment Hook `When requirements.txt or pyproject.toml is modified: 1. Check if virtual environment is activated 2. Install or update dependencies automatically 3. Report any dependency conflicts 4. Update requirements-dev.txt if needed` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#documentation-access-with-docs) Documentation Access with `#docs` ----------------------------------------------------------------------------------------------------------------------------------------------- Kiro provides built-in access to documentation for Python and popular frameworks through the `#docs` reference system. This allows you to quickly bring relevant documentation into your conversations with Kiro. Simply type `#docs` in the chat and select from the available documentation sources, such as: * **#Python** - Python language documentation * **#Pytorch** - PyTorch framework documentation * **#PySide6** - Python library for creating GUI Example usage: `"#Python How do I use context managers effectively?" "#Pytorch how can I add a custom operator?" "#PySide6 What is the best way to add a button?"` You can also reference specific documentation URLs using `#URL`: `"#URL https://docs.python.org/3/library/asyncio.html"` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#debugging-issues) Debugging Issues ---------------------------------------------------------------------------------------------------------------- When you encounter issues, Kiro can help diagnose and fix them: 1. **Inline Chat**: * Type `Cmd/Ctrl + I` to open the inline chat. * Ask Kiro to help debug your code with natural language. 2. **Add to Chat**: * Type `Cmd/Ctrl + L` to add the current file to the chat. * Ask Kiro to help debug your code with natural language. 3. **Quick Fix**: * Hover on an error or warning, then select `Quick fix` and `Ask Kiro`. * Kiro will automatically add the code to the chat and start debugging. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/#resources) Resources -------------------------------------------------------------------------------------------------- * [Python Documentation](https://docs.python.org/3/) * [Python Package Index (PyPI)](https://pypi.org/) * [Python Enhancement Proposals (PEPs)](https://peps.python.org/) Page updated: July 14, 2025 [TypeScript and JavaScript](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide/) [Java](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/) * * * --- # Java - Docs - Kiro Documentation Java ==== Kiro provides powerful AI-assisted development capabilities for Java projects, helping you write, debug, and maintain Java code more efficiently. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#prerequisites) Prerequisites -------------------------------------------------------------------------------------------------------- Before diving into Java development with Kiro, ensure you have: * **Java Development Kit (JDK)**: Install the [latest LTS version](https://aws.amazon.com/corretto/) (JDK 17 or newer recommended). We recommend Amazon Corretto for a free, production-ready distribution of OpenJDK. * **Build Tool**: Maven or Gradle for dependency management and build automation. * **Git**: For version control and collaboration. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#extensions) Extensions -------------------------------------------------------------------------------------------------- Kiro supports extensions from Open VSX that can enhance your Java development experience. Here are some helpful extensions you can install: * **[Extension Pack for Java](https://open-vsx.org/extension/vscjava/vscode-java-pack) **: Popular extensions for Java development in Visual Studio Code. Includes Language Support for Java, Debugger for Java, Test Runner for Java, Maven for Java, Project Manager for Java, and IntelliCode. * **[Spring Boot Extension Pack](https://open-vsx.org/extension/vmware/vscode-spring-boot) **: A collection of extensions for Spring Boot development including Spring Boot Tools, Spring Initializr Java Support, and Spring Boot Dashboard. * **[Gradle for Java](https://open-vsx.org/extension/vscjava/vscode-gradle) **: Manage Gradle projects, run Gradle tasks and provide better Gradle file authoring experience in Kiro. * **[Maven for Java](https://open-vsx.org/extension/vscjava/vscode-maven) **: Manage Maven projects, run Maven tasks and provide better Maven project authoring experience in Kiro. * **[Markdown Preview Enhanced](https://open-vsx.org/extension/shd101wyy/markdown-preview-enhanced) **: For viewing and editing markdown files with live preview. You can install these extensions in Kiro by using the Extensions panel and searching for the extension names listed above. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#working-with-your-environment) Working With Your Environment ---------------------------------------------------------------------------------------------------------------------------------------- With Kiro, you can leverage the chat capabilities to setup a new project or work on an existing one. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#project-configuration-and-structure) Project Configuration and Structure Kiro can help you set up and maintain configuration files for your Java projects, and organize your project following Java best practices. * **Initialize configuration files**: Ask Kiro to initialize default configuration files based on the project. * **Create project structure**: Ask Kiro to create the structure of your project based on needs and best practices. * **Environment setup**: Get help configuring your Java development environment. Example prompts: `"Create a new Maven project for a Spring Boot application" "Set up a Gradle build file with JUnit 5 and Mockito dependencies" "Configure a multi-module Maven project structure" "Help me install and configure the latest JDK for my operating system" "Set up a Spring Boot project with proper layered architecture" "Create a pom.xml with Spring Security and JPA dependencies"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#code-analysis-and-refactoring) Code Analysis and Refactoring Kiro can analyze your Java code to identify issues and suggest improvements: * **Code Quality Analysis**: Ask Kiro to review your code for potential bugs, performance issues, or style issues. * **Refactoring Assistance**: Get help extracting methods, renaming variables, or restructuring code. * **Design Pattern Implementation**: Kiro can help implement common design patterns in your Java code. Example prompts: `"Analyze this method for potential bugs or performance issues" "Refactor this code to use the Builder pattern" "Convert this imperative code to use Java Streams"` ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#debugging-assistance) Debugging Assistance When you encounter errors in your Java code: * **Error Explanation**: Kiro can explain cryptic error messages in plain language * **Solution Suggestions**: Get actionable fixes for common errors * **Runtime Debugging**: Kiro can help set up debugging configurations Examples: `"Explain this NullPointerException in my code" "Help me debug this ConcurrentModificationException" "Analyze this stack trace and suggest a fix"` [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#steering) Steering ---------------------------------------------------------------------------------------------- [Steering](https://kiro.dev/docs/steering) allows you to provide Kiro with project specific context and guidelines. Kiro can generate steering files which you can refine: 1. **Product brief** (`product.md`) - Contains information about the product, its purpose, and key features 2. **Technical Stack** (`tech.md`) - Details the technologies, frameworks, and development guidelines 3. **Project Structure** (`structure.md`) - Provides information about how the project is organized For Java projects, you can create additional custom steering files to provide more specific guidance: ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#creating-custom-steering-files) Creating Custom Steering Files Use the following instructions to add new steering documents to your project. **To add new steering documents** 1. Navigate to the **Kiro** view in the sidebar. 2. In the **Agent Steering** section, choose the `+` button to create a new steering file. 3. Enter a name for your file with a descriptive title. 4. Add your custom steering content following markdown conventions. Custom steering files are stored in the `.kiro/steering/` directory and are automatically recognized by Kiro during interactions. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#project-specific-conventions) Project-Specific Conventions Create a `java-conventions.md` steering file to define your team's specific practices and architectural decisions: markdown `# Java Project Conventions ## Architecture Patterns - Use hexagonal architecture for complex domains - Implement CQRS for read/write separation when needed - Apply Domain-Driven Design principles for business logic ## Testing Strategy - Write unit tests for all business logic - Use TestContainers for integration tests - Maintain 80% code coverage minimum - Follow the AAA pattern (Arrange, Act, Assert) ## Error Handling - Use custom exceptions for business logic errors - Implement global exception handlers with @ControllerAdvice - Log errors with correlation IDs for traceability - Return consistent error response formats ## Performance Guidelines - Use connection pooling for database access - Implement caching strategies for frequently accessed data - Use async processing for long-running operations - Monitor and optimize database queries` This type of steering provides Kiro with context about your specific architectural decisions and practices, rather than basic code formatting which is better handled by automated tools like Checkstyle or Spotless. ### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#framework-specific-guidelines) Framework Specific Guidelines For Spring Boot projects, create a `spring-boot-patterns.md` steering file: markdown `# Spring Boot Development Guidelines ## Component Structure - Use @RestController for REST endpoints - Use @Service for business logic - Use @Repository for data access - Use @Component for other beans ## Dependency Injection - Prefer constructor injection over field injection - Use final fields for injected dependencies - Avoid circular dependencies ## API Design - Follow REST principles for endpoint design - Use appropriate HTTP methods (GET, POST, PUT, DELETE) - Return appropriate HTTP status codes - Use DTOs for request/response objects` These steering files help Kiro generate code that follows your team's specific conventions and best practices. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#agent-hooks) Agent Hooks ---------------------------------------------------------------------------------------------------- Kiro's [Agent Hooks](https://kiro.dev/docs/hooks) can automate common Java development tasks. For example, you can create hooks that: * Automatically generate JUnit tests when you save a Java file * Run code quality checks with Checkstyle or SpotBugs * Check for outdated Maven or Gradle dependencies * Generate or update JavaDoc comments for public methods * Validate Spring Boot configuration files * Format code with Google Java Format or similar tools [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#mcp-servers) MCP Servers ---------------------------------------------------------------------------------------------------- Kiro's support for Model Context Protocol (MCP) servers enhance your Java development experience by providing specialized tools and capabilities. For a complete guide on setting up and using MCP, see the [MCP documentation](https://kiro.dev/docs/mcp) . #### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#maven-mcp-server) Maven MCP Server The Maven MCP server allows you to manage Maven projects directly within Kiro: json `{ "mcpServers": { "maven": { "command": "uvx", "args": ["maven-mcp-server@latest"] } } }` With this server configured, you can: * Run Maven commands with Kiro * Get AI powered explanations for build issues * Manage dependencies and project configuration Example usage: `"Run Maven tests for my project" "Add Spring Boot starter dependencies to my pom.xml"` #### [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#additional-useful-mcp-servers) Additional Useful MCP Servers Explore more MCP servers in the [AWS MCP Servers](https://awslabs.github.io/mcp/) and [Awesome MCP Servers](https://github.com/punkpeye/awesome-mcp-servers) collection. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#debugging-issues) Debugging Issues -------------------------------------------------------------------------------------------------------------- When you encounter issues, Kiro can help diagnose and fix them: 1. **Inline Chat**: * Type `Cmd/Ctrl + I` to open the inline chat. * Ask Kiro to explain specific errors or suggest fixes for the current code. 2. **Add to Chat**: * Type `Cmd/Ctrl + L` to add the current file to the chat. * Ask Kiro to analyze the entire file for potential issues or improvements. 3. **Quick Fix**: * Hover on an error or warning, then select `Quick fix` and `Ask Kiro`. * Kiro will automatically add the code to the chat and start debugging. [Copied!](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/#resources) Resources ------------------------------------------------------------------------------------------------ * [Java Documentation](https://docs.oracle.com/en/java/) * [Spring Framework Documentation](https://docs.spring.io/spring-framework/reference/) * [Spring Boot Documentation](https://docs.spring.io/spring-boot/docs/current/reference/html/) * [Maven Documentation](https://maven.apache.org/guides/) * [Gradle Documentation](https://docs.gradle.org/current/userguide/userguide.html) Page updated: July 11, 2025 [Python](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide/) [Learn by Playing](https://kiro.dev/docs/guides/learn-by-playing/) * * * --- # Troubleshooting - Docs - Kiro Documentation Troubleshooting =============== This guide helps you resolve common issues with Kiro, including shell integration and MCP server connection problems. [Copied!](https://kiro.dev/docs/reference/troubleshooting/#kiro-installation-issues) Kiro Installation Issues ------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#kiro-is-damaged-and-cant-be-opened) Kiro is damaged and can't be opened **Issue:** On macOS, you may encounter this error when trying to open Kiro: `Kiro is damaged and can't be opened. You should move it to the Trash.` **Possible cause:** This pop-up is due to a false positive in macOS security features. **Recommended solutions:** Here are several solutions to resolve this error, listed in order of simplicity. * Go to **System Settings** → **Privacy & Security** and click **Allow** or **Open** anyway for Kiro. * Drag `Kiro.app` to your desktop, and then drag it from your desktop to the **Applications** folder. * Restart your computer. * Open your terminal and run: `sudo xattr -d com.apple.quarantine /Applications/Kiro.app` [Copied!](https://kiro.dev/docs/reference/troubleshooting/#authentication-issues) Authentication Issues ------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#browser-redirect-failures-during-authentication) Browser Redirect Failures During Authentication If while authenticating with Kiro you are not redirected to the browser, try these platform-specific solutions: #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#windows) Windows Run Kiro with logging enabled to identify potential issues: 1. Open Command Prompt as administrator 2. Run the following command (replace with your actual Kiro installation path): `C:\path\to\app.exe --enable-logging` 3. Check the logs for any errors 4. If you see access denied errors, ensure your user has administrator permissions to run the app #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#macos) macOS Use the developer tools to diagnose the issue: 1. Open Kiro 2. Go to **Help** → **Toggle Developer Tools** 3. Navigate to the **Console** tab 4. Observe any errors reported during the sign-in process 5. If the error indicates a missing dependency, ensure it's available in your PATH * One common issue is the missing `ioreg` command * Verify `ioreg` is included in your PATH variable: bash `echo $PATH which ioreg` * If `ioreg` is missing, it's typically located at `/usr/sbin/ioreg` ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#aws-iam-identity-center-issues) AWS IAM Identity Center Issues #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#q-developer-pro-subscription-required) Q Developer Pro Subscription Required If you see an error `There was an error signing you in` when attempting to authenticate with Identity Center, ensure you have a valid Q Developer Pro subscription. You need an active Pro subscription to use Identity Center authentication with Kiro. Here is a [guide on how to view your subscription status and upgrade to Pro](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/q-admin-setup-subscribe-general.html) . #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#regional-limitations-for-q-developer-profiles) Regional Limitations for Q Developer Profiles If you're unable to sign in with Identity Center despite having valid credentials, this may be due to regional limitations. Kiro defaults to the US East (N. Virginia) region for Identity Center authentication. If you have a Q Developer profile in a different region, you won't be able to sign in with Identity Center. As an alternative, use a different login method such as Builder ID or social providers such as Google or GitHub. We're working on addressing this regional limitation in future releases. #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#session-duration-and-timeouts) Session Duration and Timeouts Identity Center sessions have a default timeout of 8 hours, which means you'll need to re-authenticate periodically. To extend session duration, administrators can configure longer session timeouts. For detailed configuration instructions, see the [AWS documentation on configuring user session duration](https://docs.aws.amazon.com/singlesignon/latest/userguide/user-session-duration-how-to-configure.html) . [Copied!](https://kiro.dev/docs/reference/troubleshooting/#shell-integration-issues) Shell Integration Issues ------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#what-is-shell-integration) What is Shell Integration? Shell integration connects Kiro directly with your terminal, allowing you to work more efficiently with command-line tools. It gives Kiro the ability to see terminal activity and interact with it. Without shell integration, you need to manually copy-paste terminal outputs to Kiro. With it enabled, Kiro can: * Run terminal commands and process the results automatically * Monitor development servers and help fix problems in real time * Understand your project environment through command outputs * Complete tasks that require terminal interaction Shell integration works like having a pair programmer who can see your terminal and assist you immediately. ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#fixing-shell-integration-unavailable-error) Fixing "Shell Integration Unavailable" Error If you encounter this error, follow these steps: #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#step-1-update-your-ide) Step 1: Update Your IDE Make sure you're using the latest version: 1. Open the Command Palette: * Mac: Press `Cmd + Shift + P` * Windows/Linux: Press `Ctrl + Shift + P` 2. Type `Kiro: Check for Updates` and select it 3. Restart your IDE after updating #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#step-2-configure-the-shell) Step 2: Configure the Shell 1. Open the Command Palette (`Cmd + Shift + P` or `Ctrl + Shift + P`) 2. Type `Kiro: Enable Shell Integration` and select it 3. Kiro will configure the following shells: * zsh * bash * fish * PowerShell #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#step-3-restart-your-ide) Step 3: Restart Your IDE 1. Quit the application completely 2. Reopen Kiro and start a new chat session ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#manual-shell-integration-installation) Manual Shell Integration Installation If automatic shell integration fails, install it manually: #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#for-zsh-users) For Zsh Users bash `# Add to ~/.zshrc [[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path zsh)"` #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#for-bash-users) For Bash Users bash `# Add to ~/.bashrc [[ "$TERM_PROGRAM" == "kiro" ]] && . "$(kiro --locate-shell-integration-path bash)"` #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#for-fish-users) For Fish Users bash `# Open the file kiro $__fish_config_dir/config.fish # Add to config.fish string match -q "$TERM_PROGRAM" "kiro" and . (kiro --locate-shell-integration-path fish)` #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#for-powershell-users) For PowerShell Users bash `# Open the file kiro $Profile # Add to your PowerShell profile if ($env:TERM_PROGRAM -eq "kiro") { . "$(code --locate-shell-integration-path pwsh)" }` [Copied!](https://kiro.dev/docs/reference/troubleshooting/#windows-specific-issues) Windows-Specific Issues ----------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#powershell-configuration) PowerShell Configuration If you prefer PowerShell: 1. Use PowerShell 7+ for best compatibility 2. Adjust execution policies if needed: powershell `# Check current policy Get-ExecutionPolicy # Set to RemoteSigned (recommended for development) Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser` #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#understanding-powershell-execution-policies) Understanding PowerShell Execution Policies PowerShell uses execution policies to determine which scripts can run on your system: | Policy | Description | | --- | --- | | Restricted | Blocks all scripts | | AllSigned | Runs scripts signed by trusted publishers | | RemoteSigned | Runs local scripts and signed remote scripts | | Unrestricted | Runs all scripts (not recommended) | For development work, `RemoteSigned` provides a good balance of security and functionality. ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#onedrive-path-issues) OneDrive Path Issues If you use OneDrive on Windows, your desktop path might cause issues: 1. Launch Command Prompt as administrator 2. Create a symbolic link: `mklink /J "C:\Users\\Desktop" "C:\Users\\OneDrive\Desktop"` 3. Restart your IDE ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#unusual-terminal-output) Unusual Terminal Output If you see strange characters, escape sequences, or formatting issues: 1. Check for terminal customization tools that might conflict: * Oh My Zsh themes * Starship prompt * Custom PS1 configurations * PowerShell prompt customizations 2. Temporarily disable these tools in your shell configuration file: bash `# For Zsh, comment out in ~/.zshrc # source ~/.p10k.zsh` 3. For PowerShell users, check your profile: powershell `# View your profile location echo $PROFILE # Edit your profile and comment out prompt customizations` [Copied!](https://kiro.dev/docs/reference/troubleshooting/#mcp-server-connection-issues) MCP Server Connection Issues --------------------------------------------------------------------------------------------------------------------- ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#common-mcp-connection-problems) Common MCP Connection Problems If you're having trouble connecting to MCP servers: 1. **Check server status**: * Open the Kiro panel and navigate to the MCP servers tab * Check the connection status indicator for your server 2. **Verify configuration**: * Ensure your MCP configuration file has the correct syntax * Check that the server command and arguments are correct 3. **Check prerequisites**: * Make sure all required dependencies are installed * For AWS Documentation server, verify Python 3.10+ and uv are installed 4. **Review logs**: * Open the Output panel in Kiro * Select "Kiro - MCP Logs" from the dropdown * Look for specific error messages ### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#fixing-specific-mcp-issues) Fixing Specific MCP Issues #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#aws-documentation-server) AWS Documentation Server 1. **Connection failures**: bash `# Verify uv installation uv --version # Verify Python version python --version # Test server directly uvx awslabs.aws-documentation-mcp-server@latest --help` 2. **Search or read failures**: * Check your internet connection * Verify the URL format for documentation pages * Try with a simpler search query #### [Copied!](https://kiro.dev/docs/reference/troubleshooting/#github-mcp-server) GitHub MCP Server 1. **Authentication errors**: * Verify your personal access token is valid * Ensure the token has the required scopes (repo, user) * Generate a new token if necessary 2. **Rate limiting issues**: * GitHub API has usage limits * Check the rate limit status in the MCP logs * Consider using a token with higher rate limits [Copied!](https://kiro.dev/docs/reference/troubleshooting/#getting-help) Getting Help ------------------------------------------------------------------------------------- If you've tried the troubleshooting steps above and still need assistance: 1. Check our [FAQ](https://kiro.dev/faq) for common questions 2. Join our [community Discord](https://discord.gg/kirodotdev) for help 3. Submit an issue on [GitHub](https://github.com/kirodotdev/Kiro/issues) with: * Your operating system details * Kiro version * Steps you've already tried * Error messages (if any) Page updated: July 16, 2025 [Migrating from VSCode](https://kiro.dev/docs/guides/migrating-from-vscode/) [Auth Methods](https://kiro.dev/docs/reference/auth-methods/) * * * --- # Steering Kiro, and improving the game homepage - Docs - Kiro Documentation Steering Kiro, and improving the game homepage ============================================== This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . 1 #### Understand the problem Load up `localhost:5173` in your browser to see the home page. As you can see this homepage starts out very minimalistic. There are no graphics, explanations of what the game is, and there is no marketing copy. This is a perfect task for "vibe coding". 2 #### Setup Kiro steering files But before we "vibe" we must prepare. Because this game is fairly complex, it will be very useful to prepare Kiro to properly understand what the project is, what tech it utilizes, and how to navigate the code. Use `Control/Command + Shift + P` to open the command palette, then search for the word “Steering”. Select the option “Kiro: Setup Steering for Project” ![alt !!alt](https://kiro.dev/images/video-game-guide/setup-steering.png) The Kiro agent will go to work exploring key files from the repository and creating some “steering” files that describe the project purpose, structure, and tech. These files will help guide all future runs of the agent interactions, making them faster and more accurate. ![alt !!alt](https://kiro.dev/images/video-game-guide/steering-run.png) Take a moment to look at the `.kiro` folder that has been created. You should see a few files: * `product.md` - Describes what the project is. This helps Kiro understand the big picture view of what is going on when you ask it to do something. * `tech.md` - Describes all the tech used in this project. This helps Kiro stick to your existing tech choices, instead of recommending divergent options. * `structure.md` - Describes key folders and areas of the project. This helps Kiro get to the right place faster when it is working. 3 #### Make some improvements Now that the steering files are setup, try a basic “vibe coding” prompt like “I want you to make my homepage better.” The game client is being served by Vite, so you will be able to see changes reflected in real time as Kiro makes modifications to the page. 4 #### Get creative! Ask Kiro a question like: `Give me 20 potential themes for a game landing page.` Then ask Kiro to reimagine the landing page in that theme. Tip AI can be very imaginative, and is perfect for prototyping designs, even if you don’t yet have a solid plan in your head. Try out asking it to make the home page have different styles such as: "Apple product marketing page", "Retro", or "Startup" and/or ask for specific features that you want on the page like a "carousel", "quotes", or "animations". In this module we learned two core concepts: 1. Steering files help guide an AI through your project. Your first step should always be to collect and setup this basic context for the AI. 2. AI can be very creative, and it significantly lowers the barrier to experimentation. Try out several different prototypes very quickly, then throw away takes you don't like. Let's move on to the next task: [Fixing a subtle physics bug](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) Page updated: June 18, 2025 [Setup dev environment and launch the game](https://kiro.dev/docs/guides/learn-by-playing/00-setup/) [Fixing a subtle physics bug](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug/) * * * --- # Setting up for development on Spirit of Kiro - Docs - Kiro Documentation Setting up for development on Spirit of Kiro ============================================ [Copied!](https://kiro.dev/docs/guides/learn-by-playing/00-setup/#setup-local-development-environment) Setup Local Development Environment ------------------------------------------------------------------------------------------------------------------------------------------ First, you need to launch a local copy of the game client and server, connected to an AWS account. This way, when you use Kiro to modify the codebase, you can make sure that your changes actually work. 1 #### Clone the Repository Clone the [open source code repository](https://github.com/kirodotdev/kiro-demo-game) and switch to the `challenge` branch: bash `git clone git@github.com:kirodotdev/kiro-demo-game.git git checkout challenge` After you clone, check out a few key files to understand the project: * [`architecture.md`](https://github.com/kirodotdev/kiro-demo-game/blob/main/docs/architecture.md) - An overview of the architecture * [`appsec-overview.md`](https://github.com/kirodotdev/kiro-demo-game/blob/main/docs/appsec-overview.md) - Details about how specific components of the game fit together. 2 #### Prerequisite Dependencies You'll need the following dependencies installed: * [Docker Desktop](https://docs.docker.com/desktop/) or [Podman](https://podman.io/) (recommended). * AWS Setup: * An [AWS account](https://aws.amazon.com/free/) * The [AWS CLI installed locally](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) * Configure [authentication to AWS](https://docs.aws.amazon.com/cli/latest/userguide/cli-chap-authentication.html) * [AWS Bedrock model access](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access-modify.html) to one or more of: * Amazon Nova Pro * Anthropic Claude Sonnet 3.7 * Anthropic Claude Sonnet 4 3 #### Verify Dependencies Run the dependency check script to verify everything is set up correctly: sh `./scripts/check-dependencies.sh` ![alt !!alt](https://kiro.dev/images/video-game-guide/check-dependencies.gif) 4 #### Deploy Cognito User Pool Deploy an Amazon Cognito user pool for authentication (available in AWS Free Tier): bash `./scripts/deploy-cognito.sh game-auth` Info You can substitute 'game-auth' with your own custom CloudFormation stack name. ![alt !!alt](https://kiro.dev/images/video-game-guide/cognito.gif) 5 #### Build and Launch Build and launch the game stack using either Docker or Podman: bash `podman compose build && podman compose up \ --watch \ --remove-orphans \ --timeout 0 \ --force-recreate` The first time you run this command it may take a couple minutes. Subsequent runs should complete in seconds. ![[alt !!alt]](https://kiro.dev/images/video-game-guide/build-and-run.gif) Tip If this is your first time using Podman, you will need to run `podman machine init && podman machine start` before using Podman. After completion, you should see the game containers running in your container interface. The following example shows the Podman UI: ![[alt !!alt]](https://kiro.dev/images/video-game-guide/podman.png) You can use `Control + C` or `Command + C` to stop the entire stack. Info When using Podman, on some operating systems the virtual machine can experience a time desync issue on system sleep. This will cause issues with the applications ability to communicate with AWS. If you encounter this you can fix it with the following command: sh `podman machine ssh sudo systemctl restart chronyd.service` 6 #### Bootstrap database When your stack launches locally, it also launches [DynamoDB local](https://docs.aws.amazon.com/amazondynamodb/latest/developerguide/DynamoDBLocal.html) , a special container that imitates the DynamoDB AWS service, but running locally on your own machine. The game is expecting several tables to be created in this DynamoDB container. While the game stack is still running, open a new terminal and use the following commands to automatically create the necessary tables: sh `podman exec server mkdir -p /app/server/iac && podman cp scripts/bootstrap-local-dynamodb.js server:/app/ && podman cp server/iac/dynamodb.yml server:/app/server/iac/ && podman exec server bun run /app/bootstrap-local-dynamodb.js` ![[alt !!alt]](https://kiro.dev/images/video-game-guide/create-tables.gif) Info The DynamoDB database is persisted across restarts, by saving it to the file `docker/dynamodb/shared-local-instance.db`. If you wish to clear it out or change the structure of a table, then delete this file, restart the game stack, and rerun this database bootstrap command. 7 #### Test it out It’s time to verify that everything is working properly. Try the following command first to make sure that the game server is running locally: sh `curl localhost:8080` You should see the response `OK` Next open your web browser and put the following address into the address bar: `localhost:5173` You should see the homepage of the game client. Create an account and start playing. [Copied!](https://kiro.dev/docs/guides/learn-by-playing/00-setup/#game-guide) Game guide ---------------------------------------------------------------------------------------- Here are some basic things to try in the game: * `WASD` to move around, `E` to interact * Pull random items using the red "PULL" lever * Pick up items and carry them around with E. Throw a held item with T. Hint: Items can be thrown out the door at the bottom. * Carry an item to the workbench and use E to put it on the workbench. Drag items around to move them up to the tool wall on the back, or down to the working area at the bottom. Click an item on the tool wall to cast one of it's "quirks", then select one or more targets for the "quirk". Both the tool and the targets will transform based on the quirk. Get creative with this, there are near infinite possibilities, and you can make some truly bizarre things. * If you are smashing items or otherwise cutting or breaking them into pieces, and there are a lot of items in the working area of the workbench they will overflow and fall off onto the ground around the workbench. Try not to let the ground get too messy! * The chest is for storage when you have too many items. * When an item is thrown out the door at the bottom of the shop keeper will judge it and you'll get money for it. He likes items that are fun, unusual, in good condition, or that seem like rare collectables. * The computer shows items that have been discarded or given to the appraiser, both by yourself and by other players. This serves as a randomized “shop” where you can indirectly buy from other players, or buy back things you lost. Done playing with your copy of the game? Let's get to work on the first task: [Steering Kiro, and improving the game homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) Page updated: July 11, 2025 [Learn by Playing](https://kiro.dev/docs/guides/learn-by-playing/) [Steering Kiro, and improving the game homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage/) * * * --- # Conclusion - Docs - Kiro Documentation Conclusion ========== In this guide you got hands on with a range of Kiro features including: * **Steering files**, to guide AI agents through a complex project * **Basic vibe coding**, for bug fixes and simple changes or refactors * **Specification driven development**, to plan the requirements, design, and tasks for large changes * **Hooks**, for when you want to automate common boilerplate tasks in your project * **MCP**, for when you want to extend Kiro with new abilities and behaviors [Copied!](https://kiro.dev/docs/guides/learn-by-playing/99-conclusion/#next-steps) Next Steps --------------------------------------------------------------------------------------------- Although you have completed this guide, there is still plenty to build. Check out [the game roadmap](https://github.com/kirodotdev/kiro-demo-game/blob/main/docs/ROADMAP.md) for ideas. See if you can build any of these new features using Kiro, and open a PR back to the project to contribute! Page updated: June 16, 2025 [Extending Kiro with MCP](https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp/) [Migrating from VSCode](https://kiro.dev/docs/guides/migrating-from-vscode/) * * * --- # Investigating and fixing a subtle bug with physics - Docs - Kiro Documentation Investigating and fixing a subtle bug with physics ================================================== This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In the previous module we completed [a simple task to improve the game's home page](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) , but this was mostly just HTML and CSS task. Let's try working with some more complex JavaScript code that is part of the game engine core. 1 #### Understand the problem Players of the game report that sometimes game physics go haywire and items bounce really high. One player has provided the following recording: ![alt !!alt](https://kiro.dev/images/video-game-guide/physics-bug.gif) 2 #### Ask Kiro to investigate Try a prompt that describes the issue in as much detail as you can: `When something is moving or colliding, and the player tabs out then back in, the items do a tremendous bounce. Players report "items go haywire".` Kiro will start investigating project files, and will identify the cause. For example: > The problem is in the physics-system.ts file. When a user tabs out and back in, the lastTimestamp value becomes stale, and when the animation frame resumes, the calculated deltaTime can be extremely large (several seconds instead of milliseconds). This large delta is then used in physics calculations, causing objects to move much farther than they should in a single frame, resulting in the "haywire" behavior. 3 #### Dig deeper Based on your initial description, Kiro probably coded a basic fix right away. However, we aren't done yet. Try asking Kiro: `What other potential solutions or mitigations should I consider?` You may be surprised to see the AI come up with many additional potential fixes beyond what it originally implemented. 4 #### Explore even deeper Now that you have the model into a specific latent space of exploring potential improvements to the game's physics system it is a great time to ask a question like: `Do you see anything else that looks like it could be improved?` Info Large language models contain an incredible breadth of knowledge. However, they require a human to push the model a bit futher to unlock the true potential. Don't stop prompting on the first answer. Ask questions like "why?", "what else?", and "what then?" In this module we learned one key AI engineering concept: Don't just treat AI as a task solving machine. Use the AI's depth and breadth of knowledge to explore gaps in your own knowledge. Let's move on to the next task: [Fixing an interactions bug across several files](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) Page updated: June 24, 2025 [Steering Kiro, and improving the game homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage/) [Fixing an interactions bug across several files](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug/) * * * --- # Fixing a complex issue across multiple files - Docs - Kiro Documentation Fixing a complex issue across multiple files ============================================ This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In previous modules we: * [Wrote HTML and CSS to improve the homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) * [Fixed a physics bug in the core of the game's physics engine](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) Both of these tasks were fairly self contained. Let's try something a bit more complicated, spanning multiple files. 1 #### Understand the problem Players of the game report that sometimes the "E" prompt doesn't work as expected. This seems to happen when standing near walls: ![alt !!alt](https://kiro.dev/images/video-game-guide/interactions-bug.gif) In this recording you can see that the "E" prompt disappears even though the player is close enough to the chest and to the item. Try asking Kiro to solve this. For example: `Sometimes when the player is closer to the wall than to an interactive object like an item or the chest, then the interact prompt does not appear over the interactive object.` 2 #### Think about the proposed solution Kiro should be able to correctly identify the issue. The function which finds which object is nearest to the player is not filtering out walls, therefore when the player is close to a wall it marks the wall as the nearest object, even though the wall is not actually interactive. ![alt !!alt](https://kiro.dev/images/video-game-guide/interact-single-file-solution.png) The model has proposed to fix the bug by introducing a check to exclude objects that have a physics mass of `Infinity`. While this technically works to solve the problem in the short term, is this the best fix? What if there are non interactive objects that have a finite mass? Or what if there are objects that have an `Infinity` mass but are still interactive? This proposed code solution is adding logic triggered by a property whose semantic meaning is not directly related to that logic. While this fix works temporarily, the overloaded behavior will absolutely break or cause subtle bugs later on. Tip When using an AI, you must stay mentally engaged. Don't just blindly accept the first AI suggestion. Think about best practices and simpler solutions that the AI might have overlooked. 3 #### Refactoring across the project Instead of trying to treat this as a problem entirely self contained in the file `game-object-system.ts`, let's do a bigger refactor. Everywhere that game objects are created, we should probably indicate up front whether the created object is intended to be interactive. Try a prompt like: ``In #GameObject add a new required property `interactive`. In #updatePlayerProximity filter out non interactive objects All calls to #addObject throughout the code need to set interactive to true or false`` Tip Try using `#` to bring up the context picker. You can reference types, classes, functions, and other code primitives in your prompt, increasing the accuracy of results by ensuring that the model can jump straight to looking at the right context. Your results should look something similar to this: ![alt !!alt](https://kiro.dev/images/video-game-guide/extensive-refactor.png) Instead of one change, there are 22 changes spanning many files in the project. This refactor will ensure that the API for game objects contains proper semantic meaning for expressing whether an object is intended to be interactive. The LLM will be able to utilize this semantic meaning going forward, any time it needs to implement a feature. In this module you have learned three key concepts: 1. Check AI generated code prior to moving on. While code may work fine today, you still need to think a few steps ahead, because the LLM is only thinking about the problem it sees right now. 2. When prompting in Kiro, use the context picker to mention specific functions, classes, or types in your code. This enhances model context, and produces more accurate results. 3. Naming is important. Make sure that the "API" for your code has accurate semantic meaning. Avoid overloading properties with multiple types of behavior that aren't directly related to their semantic meanings. Let's move on to the next task: [Vibe refactoring is 50% of vibe coding](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor) Page updated: June 18, 2025 [Fixing a subtle physics bug](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug/) [Vibe refactoring is 50% of vibe coding](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor/) * * * --- # Vibe refactoring is 50% of vibe coding - Docs - Kiro Documentation Vibe refactoring is 50% of vibe coding ====================================== This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In previous modules we: * [Wrote HTML and CSS to improve the homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) * [Fixed a physics bug in the core of the game's physics engine](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) * [Fixed an interactions bug through an logic refactor](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) Now it's time to explore a hidden truth about vibe coding. If at least half of your prompts aren't "vibe refactors" you are probably messing up. 1 #### Understand the problem AI is very good at using example context to implement new solutions. Unfortunately, this tends to lead to a lot of duplicated code. In the previous module we started looking at the "E" prompt. It's time to take an even closer look. Try a prompt like: `Where is the interact prompt implemented in the components?` You should see that Kiro locates multiple copies of the interact prompt: > The interact prompt is consistently implemented across multiple interactive game objects (Computer, Workbench, Chest, Garbage, GameItem, PullLever, Dispenser) If you open these files: `Computer.vue`, `Workbench.vue`, `Chest.vue`, etc you will notice that each component has a very similar implemention of the interact prompt with similar CSS. But then if you move the ghost around the game play area, you will also notice subtle differences. For example, the size of the pull lever's interact prompt is slightly different from the size of the workbench interact prompt. We can improve the code by deduplicating a repeated pattern is a lot of duplication here, so this would be much better if we refactored the interact prompt as a single component shared by all these components. 2 #### Do a refactor Let's ask Kiro to refactor this. Open a file that contains an "E" prompt such as "Chest.vue". Then try a prompt like: `I want to DRY the "interact-prompt" into a separate component with standardized styles, reused across my components` ![alt !!alt](https://kiro.dev/images/video-game-guide/refactor.png) Tip Kiro, and other AI enabled IDE's, use your currently open files as context. Consider opening relevant files prior to sending a prompt. 3 #### Verify the results Kiro should discover all the components that have an "interact-prompt" element and refactor them to make use of a new shared component instead: ![alt !!alt](https://kiro.dev/images/video-game-guide/refactor-results.png) Things to check for: * The original implementation has interact prompts with different locations relative to the parent component: above, left, right, etc. Did that get lost in the refactor? * There were two diffrent approaches to ensuring that the interact prompts text stayed at an appropriate size, no matter what the screen dimension was. Which approach, if any, did the AI model choose? Tip Trust, but also verify. While AI models can do a fantastic job at refactoring, its always necessary to double check generated code to ensure that functionality did not degrade during that refactor. 4 #### Find more to do Try asking Kiro: `Look through my components. Do you see any things that should be refactored or opportunities to implement best practices?` Tip AI models are trained via reinforcement learning to be friendly and compliant. Therefore a model will rarely, if ever, initiate criticism or question what you ask it to do. Models will do as you ask, even if what you asked was flawed. However, you can still use AI as a code reviewer or critic by explictly asking it to tell you what it sees wrong or in need of improvement. In this module you have learned two key concepts: * Vibe coding works, but just like regular coding, it requires regular refactors. Do "vibe refactoring" as well. * AI won't directly contradict you or push back on your asks, but that doesn't it isn't capable of seeing the mistakes. You just need to ask it to double check the work. Let's move on to the next task: [Using specification for complex work](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work) Page updated: June 18, 2025 [Fixing an interactions bug across several files](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug/) [Using specifications for complex work](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work/) * * * --- # Using specificiations for complex work - Docs - Kiro Documentation Using specificiations for complex work ====================================== This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In previous modules we: * [Wrote HTML and CSS to improve the homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) * [Fixed a physics bug in the core of the game's physics engine](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) * [Fixed an interactions bug through an logic refactor](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) * [Did a DRY refactor across many components](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor/) So far we've mostly done minor modifications and refactors, but what about more complex new features? Kiro is here to help with that too. 1 #### Understand the problem You may notice that on the login page of the game there is no "Forgot Password" link. The game is using [Amazon Cognito](https://aws.amazon.com/cognito/) for authentication, however the implementation is currently still fairly minimal. In order to send password reset emails, Cognito requres the email to be verified, so we also need to implement email verification as well. So we are looking at a tree of tasks that need to be completed: * Email verification implementation * Frontend client side components * Backend server routes and Cognito integration * Password reset implementation * Frontend client side screens * Backend server routes and Cognito integration 2 #### Ask for a specification Try the following prompt in Kiro: `I need a specification for email verification and password reset` Kiro will go to work collecting information about the project and designing a specification for this complex task. 3 #### Review requirements Kiro will expand your initial ask into a detailed set of requirements based on user stories. In most cases these user stories, and the resulting requirements, will help expand vague asks and highlight edge cases that you might not have initially expected: ![alt !!alt](https://kiro.dev/images/video-game-guide/requirements.png) After you read through the requirements you can either provide detailed feedback on how to rewrite the requirements or you can just type something like "LGTM" in the prompt to move on. 4 #### Review design Now Kiro will compare the existing code to the requirements and start imagining how to fit these requirements into the codebase: ![alt !!alt](https://kiro.dev/images/video-game-guide/design.png) Tip In the upper right corner of the design doc you can click the "Preview" button to open a rendered copy of the design document. This will properly show the flow diagram. The design document likely includes some example code snippets that are similar to what Kiro plans to write to solve this problem. Don't worry too much about the specifics of this code. Think of it more as pseudocode that is imagining the API. The actual implementation may end slightly different. After you read through the design document you can either provide detailed feedback on how to rethink the design or you can just type something like "LGTM" in the prompt to move on. 5 #### Review tasks Kiro will use the requirements and design document to plan a series of tasks to execute. Think of each of these tasks as a step along the journey towards the new feature. ![alt !!alt](https://kiro.dev/images/video-game-guide/tasks.png) Tip The task list may not match up with your preferred order of operations when vibe coding. For example, the task list often has test development last, while you may prefer test driven development. You can use steering files to modify Kiro behaviors. For example, try creating a file `.kiro/steering/specs.md` with instructions to always write tests first before writing code. You can either provide feedback in the prompt to modify the task list, or type something like "LGTM" to move on. 6 #### Work on a task To start working on a task, click the "Start Task" link above the task. Kiro will go to work on that task. ![alt !!alt](https://kiro.dev/images/video-game-guide/task-work.png) Tip You will likely still need to review, test, and iterate on generated code for each task, even though the task list marks the task as "Task completed". 7 #### Specification as history You may have noticed that specifications are stored under `.kiro/specs`. By design, you should commit these specification files to the repo, alongside the code. Over time, you can accumulate a large collection of specification documents that describe the intent and design behind the code. This will serve as a guide for future developers, as well as a reference for Kiro if it ever needs to revisit these features. In this module you have learned two key concepts: * While vibe coding is fun, sometimes you need to build something a bit more complex. Then it is helpful to use Kiro specifications to plan the requirements, design the implementation, and lay out a series of steps for the implementation. * Steering files aren't just to teach Kiro about the project, they can also be used to modify Kiro's behavior, such as adjusting how it plans tasks. Let's move on to the next task: [Managing assets with agent hooks](https://kiro.dev/docs/guides/learn-by-playing/06-managing-assets-with-agent-hooks) Page updated: June 18, 2025 [Vibe refactoring is 50% of vibe coding](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor/) [Managing game assets with agent hooks](https://kiro.dev/docs/guides/learn-by-playing/06-managing-assets-with-agent-hooks/) * * * --- # Extending Kiro with MCP - Docs - Kiro Documentation Extending Kiro with MCP ======================= This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In previous modules we: * [Wrote HTML and CSS to improve the homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) * [Fixed a physics bug in the core of the game's physics engine](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) * [Fixed an interactions bug through an logic refactor](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) * [Did a DRY refactor across many components](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor/) * [Built a more complex feature using specifications](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work/) * [Setup an automatation for asset management using agent hooks](https://kiro.dev/docs/guides/learn-by-playing/06-managing-assets-with-agent-hooks/) Now it's time to customize Kiro itself, to adjust it's behavior for more advanced use cases. To do this, we are going to add some new abilities to Kiro via [Model Context Protocol](https://modelcontextprotocol.io/introduction) (MCP). 1 #### Setup an MCP server Kiro comes with built-in MCP support. Click the Kiro "ghost" tab and look for "MCP Servers" on the list. Click "+" to start adding an MCP server. ![alt !!alt](https://kiro.dev/images/video-game-guide/mcp-basics.png) Modify the contents of the `mcp.json` file that is opened. Because this guide is using Podman throughout, we are going to run the MCP server as a container using Podman. This will help keep the MCP server isolated from our host machine: json `{ "mcpServers": { "memory": { "enabled": true, "command": "podman", "args": [ "run", "-i", "--rm", "-v", "memories:/memories", "--env", "MEMORY_FILE_PATH=/memories/memory.json", "mcp/memory" ], "autoApprove": [ "create_entities", "create_relations", "add_observations", "delete_entities", "delete_observations", "delete_relations", "read_graph", "search_nodes", "open_nodes" ] }, "sequentialthinking": { "command": "podman", "args": [ "run", "-i", "--rm", "mcp/sequentialthinking" ], "autoApprove": [ "sequentialthinking" ] } } }` This configuration adds two new MCP servers to Kiro. The first MCP server contains tools for tracking and querying long term memories. The memories will be stored in a local Podman volume, and can therefore persist across Kiro sessions. You can even reuse these memories from outside of Kiro or bring in memories that were generated from other external sources. The second server helps Kiro to extend it's thinking and spend more time planning prior to getting to work on a task. 2 #### Add memories to Kiro You can now modify Kiro's behaviors to make use of the new MCP server tools. Create a file at `.kiro/steering/behavior.md` Put the following content into the file: md ``Each time you start working, put a `user_request` type entity into the knowledge graph using the `create_entities` tool. After you work, add observations to that entity about what you did, how many files you touched, how many lines, etc.`` Now ask Kiro to do something in the project: `Rewrite the README.md as if it was written by a pirate.` ![alt !!alt](https://kiro.dev/images/video-game-guide/memory-behavior.png) Now you can use a followup prompt to query the knowledge graph: `Search nodes for user_request and write me a commit message based on what you see` Example output: md `docs: transform README.md with pirate-themed language - Rewrote entire README.md in pirate style - Added nautical references and pirate slang throughout - Maintained all original information and links - Changed section titles to pirate-appropriate terms - Added humorous pirate expressions and threats - Preserved functionality while enhancing user experience with thematic language` 3 #### Modify thinking behavior Modify the file at `.kiro/steering/behavior.md` Put the following content into the file: md `When planning how to do something, use the sequentialthinking tool to plan the next several steps.` Now try asking the chat: `Let's do something super cool in this project` ![alt !!alt](https://kiro.dev/images/video-game-guide/steering-mcp.png) 4 #### Find more MCP servers * [Awesome MCP Servers](https://github.com/wong2/awesome-mcp-servers) * [AWS MCP Servers](https://awslabs.github.io/mcp/) In this module you have learned the basics of how to extend Kiro with additional context sources, tools, and behaviors. There are countless MCP servers available, and they can be combined together in fascinating ways to augment Kiro's abilities to work on your project. Go have fun! Onward to the [conclusion](https://kiro.dev/docs/guides/learn-by-playing/99-conclusion) Page updated: June 18, 2025 [Managing game assets with agent hooks](https://kiro.dev/docs/guides/learn-by-playing/06-managing-assets-with-agent-hooks/) [Conclusion](https://kiro.dev/docs/guides/learn-by-playing/99-conclusion/) * * * --- # Managing assets with hooks - Docs - Kiro Documentation Managing assets with hooks ========================== This module assumes you have already launched the game locally, by following [the setup instructions](https://kiro.dev/docs/guides/learn-by-playing/00-setup) . In previous modules we: * [Wrote HTML and CSS to improve the homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) * [Fixed a physics bug in the core of the game's physics engine](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) * [Fixed an interactions bug through an logic refactor](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) * [Did a DRY refactor across many components](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor/) * [Built a more complex feature using specifications](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work/) Now we are going to use Kiro to setup an automation that will help remove boilerplate work involved with coding this game. 1 #### Understand the problem Open the file `client/src/systems/preloader-system.ts`. This file is a standalone system which ensures that all the game assets are preloaded prior to the game starting. It has a few clever features like initiating the predownload while the user is still on the authentication screen, and detecting new assets to load via server events. But the preloader system also relies on a list of static assets that is imported from `/client/src/assets/index.ts`. The preloader system is fully decoupled from the game components themselves. This is a clean design that ensures that individual game components don't have to manually implement calls to the preloader. However it introduces a potential issue: a developer could add a new game component, with new asset(s), and forget to add them to the list of static assets for the preloader. Let's add an automated hook that can help avoid this, while also saving the game devs some time. 2 #### Create an asset indexer hook Click the ghost icon in your IDE sidebar to open the Kiro panel. Locate the "Agent Hooks" section and click the plus icon to start writing a new hook. Let's use a custom prompt for the hook. You can type in natural language to describe what you want to happen. For example: `When a file is created in the assets folder, ensure that the assets folder index.ts file is appropriately updated` ![alt !!alt](https://kiro.dev/images/video-game-guide/create-hook.png) Kiro will expand your natural language query into an agent hook configuration for the behavior you described. The hook will be stored in your `.kiro/hooks` folder. It should look something like this: ![alt !!alt](https://kiro.dev/images/video-game-guide/asset-create.png) json `{ "name": "Image Asset Indexer", "description": "Automatically adds references to newly added image files in the assets folder to the index.ts file", "version": "1", "when": { "type": "fileCreated", "patterns": [ "client/src/assets/*.png", "client/src/assets/*.jpg", "client/src/assets/*.jpeg", "client/src/assets/*.gif", "client/src/assets/*.svg" ] }, "then": { "type": "askAgent", "prompt": "A new image file has been added to the assets folder. Please update the index.ts file in the assets folder to include a reference to this new image. First, check the current structure of the index.ts file to understand how images are referenced. Then add an appropriate export statement for the new image file following the existing pattern. Make sure to maintain alphabetical order if that's the current convention." } }` 3 #### Create an asset removal hook Now that we have an example template for an agent hook, you can also create new hooks manually by just creating new files in the `.kiro/hooks` folder. Let's try this out by cloning the asset indexer hook and editing it into an asset removal hook. Copy the existing hook and paste it as `image-asset-remover.kiro.hook` with content like this: json `{ "name": "Image Asset Remover", "description": "Automatically removes references to newly deleted image files in the assets folder to the index.ts file", "version": "1", "when": { "type": "fileDeleted", "patterns": [ "client/src/assets/*.png", "client/src/assets/*.jpg", "client/src/assets/*.jpeg", "client/src/assets/*.gif", "client/src/assets/*.svg" ] }, "then": { "type": "askAgent", "prompt": "An image file has been removed from the assets folder. Please update the index.ts file in the assets folder to remove any references to this removed image." } }` ![alt !!alt](https://kiro.dev/images/video-game-guide/asset-delete.png) You should now have two hook configurations, and two hooks showing up under "Agent Hooks" in the Kiro panel. 4 #### Test the hooks out Drag and drop an image file into the `client/src/assets` folder. You will see the asset indexer hook go to work. ![alt !!alt](https://kiro.dev/images/video-game-guide/hook-run-create.png) Then delete that asset from the folder. ![alt !!alt](https://kiro.dev/images/video-game-guide/hook-run-delete.png) Tip To view the agent messages for a hook, click the "Task list" button at the top of chat panel and click on an active "Current Task". Or you can click the "History" button to go back and view the agent messages for a hook that has already completed. In this module you learned how to create and configure agent hooks to help automate common tasks in your project. These hooks can be used both to save time, and increase accuracy of boilerplate tasks. Let's move on to the next task: [Extending Kiro with MCP](https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp) Page updated: June 18, 2025 [Using specifications for complex work](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work/) [Extending Kiro with MCP](https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp/) * * * --- # Learn by Playing - Docs - Kiro Documentation Learn by Playing ================ In this guide, you will learn how to use Kiro by completing tasks in the [codebase](https://github.com/kirodotdev/kiro-demo-game) for a sample video game called Spirit of Kiro. 95% of the code for Spirit of Kiro has been written by prompting Kiro. You are going to be using Kiro to fix bugs and add features to the game to complete it. ![A cartoon ghost stands in front of a large industrial lever labeled "PULL"\ and a workbench with tools. The ghost is next to a glowing card and a prompt\ showing the "E" key.](https://kiro.dev/images/video-game-guide/intro.png) Spirit of Kiro is an infinite crafting game in which you can: 1. Discover unique, randomly generated objects 2. Utilize these items on each other via simulated interactions like "cut", "paint", "glue", "enchant". Item's combine, break apart, and change in response to these interactions. 3. Sell your resulting creations to an AI appraiser. Every object in the game is generated by AI. Interactions between objects are also simulated by AI. This gives Spirit of Kiro infinite replayability and potential. In the following diagram you can see how the game's core crafting mechanic works. The player has discovered two items: a spoon, and a glass jar of vegetables. The player can use the spoon to extract a sample of the vegetables. ![A crafting workbench interface from a game, showing a grid of unique items\ and pop-up descriptions for items like a botanical extraction spoon, and jar of vegetables,\ Purple arrows connect the workbench to detailed item info\ panels, with the text 'Discover Unique Items' and 'Add items to workbench',\ and "Freeform crafting outcomes" above.](https://kiro.dev/images/video-game-guide/crafting.png) While the game’s core loop is complete, the game is not quite done yet. There is an [extensive roadmap for the game](https://github.com/kirodotdev/kiro-demo-game/blob/main/docs/ROADMAP.md) , full of additional ideas to build, and there a few bugs that have been left in the game on purpose so you can try out solving them using Kiro. In this guide you will learn to use Kiro by completing a series of tasks on a `challenge` branch of the open source code for this game. Ready to get started? Let's go! 1 #### Setup First, we ensure that you have an AWS account. We setup a Cognito user pool for authentication, build and launch the game stack using a Docker Compose file, then bootstrap DynamoDB tables. Then we verify that the game runs on your local machine: * [Setup dev environment and launch the game](https://kiro.dev/docs/guides/learn-by-playing/00-setup) 2 #### Task: Improve game homepage We setup steering files to help Kiro understand the project. With a full understanding of the project, we put Kiro to work improving the home landing page for the game. * [Steering Kiro, and improving the game homepage](https://kiro.dev/docs/guides/learn-by-playing/01-improve-the-homepage) 3 #### Bug Fix: Physics Glitch When we tab out of game, the phsyics goes haywire when tabbing back in. Can Kiro fix it? * [Investigating and fixing a subtle bug with physics](https://kiro.dev/docs/guides/learn-by-playing/02-physics-bug) 4 #### Bug Fix: Interactions Oversight The original pass at game interactions was "vibe coded". But it looks like AI missed something. Can Kiro correct its own mistake? * [Fixing a complex issue across multiple files](https://kiro.dev/docs/guides/learn-by-playing/03-interactions-bug) 5 #### Refactor: DRY up code with Kiro It's not just vibe coding, we do vibe refactoring here as well. * [Vibe refactoring is 50% of vibe coding](https://kiro.dev/docs/guides/learn-by-playing/04-dry-code-refactor) 6 #### New Feature: Implementing something complex The game is currently missing email verification and password reset. We implement this relatively complex new feature across client and server. * [Using specifications for complex work](https://kiro.dev/docs/guides/learn-by-playing/05-using-specs-for-complex-work) 7 #### Automation: Managing assets with agent hooks We identify some boilerplate asset management work that that is error prone. Fortunately Kiro agent hooks can help us automate this. * [Managing assets with agent hooks](https://kiro.dev/docs/guides/learn-by-playing/06-managing-assets-with-agent-hooks) 8 #### Extending Kiro with MCP Not only can you make this game your own, you can also make Kiro your own, by extending its context and behaviors with Model Context Protocol (MCP). * [Extending Kiro with MCP](https://kiro.dev/docs/guides/learn-by-playing/07-extending-kiro-with-mcp) 9 #### Conclusion Wrap up your learning journey and explore next steps. * [Conclusion](https://kiro.dev/docs/guides/learn-by-playing/99-conclusion) Page updated: July 14, 2025 [Java](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide/) [Setup dev environment and launch the game](https://kiro.dev/docs/guides/learn-by-playing/00-setup/) * * * ---