> ## Documentation Index
> Fetch the complete documentation index at: https://kiro.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup & First Run

> What to expect when you launch Kiro IDE for the first time - onboarding, settings import, and getting oriented

After [installing Kiro](https://kiro.dev/docs/getting-started/installation.md), 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](https://kiro.dev/docs/getting-started/authentication.md).

2. **Import settings (optional)** - If you're coming from VS Code, you can [import your settings and extensions](https://kiro.dev/docs/upgrade-guides/migrating-from-vscode.md). 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](https://kiro.dev/videos/kiro_3.mp4)
  
    **Video transcript**
    <p>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…"</p>
  

## 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

[Video](https://kiro.dev/videos/open-your-project-ide.mp4)

## 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](https://kiro.dev/docs/getting-started/first-project.md) 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 structured workflow upfront. You can also switch between agents at any point 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 workflow** - select from the built-in workflow agents:

| Workflow | What it does |
|----------|-------------|
| **Spec** | Structured feature development (requirements → design → tasks with approval gates) |
| **Plan** | Read-only planning mode - explores your codebase and produces an implementation plan without making changes |
| **Bug Fix** | Structured bug investigation (root cause → fix design → implementation) |
| **Quick Spec** | Fast spec workflow - auto-generates requirements, design, and tasks without approval gates |

Selecting a workflow switches the session to that agent. The agent handles the structured process from there. As a rule of thumb, reach for [specs](https://kiro.dev/docs/specs.md) 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](https://kiro.dev/docs/custom-agents/built-in.md) for the full list and invocation details.

**ℹ️ Info:** In IDE 0.x, sessions required choosing between "Vibe mode" (conversational) and "Spec mode" (structured) at session start. This binary picker has been removed - you now start in conversational mode by default and can invoke structured workflows or switch agents at any point. See [0.x reference](https://kiro.dev/docs/ide/0x-reference.md#vibe-and-spec-session-types) for the legacy behavior.

## Language support

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

- [TypeScript and JavaScript](https://kiro.dev/docs/guides/languages-and-frameworks/typescript-javascript-guide.md)
- [Java](https://kiro.dev/docs/guides/languages-and-frameworks/java-guide.md)
- [Python](https://kiro.dev/docs/guides/languages-and-frameworks/python-guide.md)

## Next steps

- [Your first project](https://kiro.dev/docs/getting-started/first-project.md) - guided walkthrough of steering, specs, hooks, and MCP
- [Interface overview](https://kiro.dev/docs/ide/editor/interface.md) - learn the IDE layout and panels
- [Keyboard shortcuts](https://kiro.dev/docs/ide/editor/keyboard-shortcuts.md) - speed up your workflow