View as Markdown

Setup & First Run

After installing Kiro, here's what the first launch looks like and how to get oriented in the IDE.

First launch

When you open Kiro for the first time, you'll walk through a short onboarding flow:

  1. Sign in - Choose a provider (Google, GitHub, AWS Builder ID, or your organization's identity provider). Learn more about authentication.

  2. Import settings (optional) - If you're coming from VS Code, you can import your settings and extensions. Otherwise, skip this step.

  3. Choose a theme - Select Kiro Dark or Kiro Light. You can change this anytime in settings.

  4. Shell integration - Allow Kiro to set up shell integration so the agent can execute commands on your behalf.

Video transcript

The video walks through the Kiro IDE onboarding flow on a dark background. It opens on a sign-in screen displaying the purple KIRO logo, the tagline "An agentic IDE that helps you do your best work," and four authentication buttons: Sign in with Google, GitHub, AWS Builder ID, and organization identity. It then advances to an Import configuration screen offering Import from VS Code and Skip options, followed by a Choose your theme screen with selectable Kiro Dark and Kiro Light preview cards and a Continue button. The sequence ends on a loading screen with the text "Loading - Setting up your IDE…"

Open a project

From the welcome page:

  • Use File > Open Folder to select your project directory
  • Or drag and drop your project folder into Kiro
  • Or run kiro . from your project directory in the terminal

Get oriented

  1. Kiro Panel - Click the Kiro Ghost icon in the activity bar (left sidebar). This panel gives you access to Specs, Agent Hooks, Steering, and MCP Servers.

  2. Chat pane - Open by default. This is where you interact with the AI agent conversationally.

  3. Start working - Type a message in the chat pane to begin. See Your first project for a guided walkthrough.

Starting a session

Every session starts with the default agent - a general-purpose coding assistant. You can begin working immediately with free-flow conversation, or select a built-in workflow agent upfront. You can also switch between agents during a session.

When you open a new session, the "Let's build" screen gives you two paths:

  1. Free-flow chat - type directly in the chat input to start working with the default agent. No setup needed.
  2. Start with a built-in workflow agent - select one of the session modes:
Built-in workflowWhat it does
SpecStructured feature development (requirements → design → tasks with approval gates)
PlanRead-only planning mode - explores your codebase and produces an implementation plan without making changes
Bug FixStructured bug investigation (root cause → fix design → implementation)
Quick SpecFast spec workflow - auto-generates requirements, design, and tasks without approval gates

Selecting a built-in workflow switches the session to that agent. The agent handles its structured process from there. These built-in session modes are distinct from declarative workflows, which execute reusable JSON or YAML recipes across separate step sessions.

As a rule of thumb, reach for Specs when you're building complex features or fixing bugs where regressions are costly, and stay in free-flow chat for quick exploratory work.

Switching agents mid-session

You don't need to decide at session start - switch agents at any time:

  • Click the agent name (e.g., "Default") in the bottom bar of the chat input to open the agent picker
  • Click Build with spec in the chat input area to invoke a spec workflow mid-conversation
  • Your custom agents appear in the picker under WORKSPACE or GLOBAL sections

This means you can start with a quick question in free-flow mode, then switch to the Plan agent when the task gets complex, then switch back to Default for implementation. Kiro also ships with several pre-configured agents - see Built-in agents for the full list and invocation details.

Language support

Kiro supports most popular programming languages. These guides help set up your environment and cover best practices:

Next steps

Page updated: September 30, 2026