Skip to content

kiro-cli — A Code Walkthrough

kiro-cli is a terminal-based AI coding assistant that runs entirely on your machine. When you type kiro-cli, a React-powered TUI launches and connects over a JSON-RPC protocol to a Rust backend that orchestrates conversations with an LLM. The LLM can read your code, write files, run commands, and call external plugins — all through a modular tool system you can extend. Think of it as having a senior engineer pair-programming with you, right inside your terminal.

This tutorial walks you through the 10 core abstractions of the kiro-cli codebase, one chapter at a time. We start at the outside (what you see when you press a key) and peel inward until you reach the specialized subsystems that let the LLM read your repository and search your knowledge base.

Architecture at a Glance

graph TD
  TUI["TUI<br/>(React + TS)"] -->|"Sends user input via"| ACP["Agent Client Protocol<br/>(JSON-RPC/stdio)"]
  ACP -->|"Streams responses to"| TUI
  TUI -->|"Renders through"| TWINKI["Twinki<br/>(Custom React Renderer)"]
  ACP -->|"Routes messages to"| SM["Session Manager"]
  SM -->|"Loads config from"| CFG["Agent Configuration"]
  SM -->|"Dispatches prompts to"| LOOP["Agent Loop"]
  CFG -->|"Declares servers for"| MCP["MCP Manager"]
  CFG -->|"Permits tools in"| TOOLS["Tool System"]
  LOOP -->|"Reads permissions from"| CFG
  LOOP -->|"Executes tools via"| TOOLS
  LOOP -->|"Dispatches MCP tools via"| MCP
  TOOLS -->|"Invokes"| CODEINT["Code Intelligence<br/>(code-agent-sdk)"]
  TOOLS -->|"Queries"| SEARCH["Semantic Search"]
  MCP -->|"Hosts as MCP server"| CODEINT

How to Read This Tutorial

The chapters are ordered from user-facing (what you see and touch) to deep internals (how the LLM queries your code). Each chapter:

  • Opens with a welcoming motivation and a concrete use case.
  • Uses a beginner-friendly analogy to make the concept stick.
  • Shows short real code snippets (<10 lines each) pointing to actual files in ~/Documents/kiro-cli/.
  • Includes a mermaid sequence diagram of the key interaction.
  • Links forward to the next chapter and backward to previously covered concepts.

Reading time: ~45–60 minutes cover-to-cover, or pick any chapter as a reference.

Table of Contents

  1. Chapter 1: TUI — The React-based terminal front end that captures your keystrokes and paints your screen.
  2. Chapter 2: Twinki — The custom React renderer that turns React components into ANSI-terminal characters without flicker.
  3. Chapter 3: Agent Client Protocol (ACP) — The JSON-RPC-over-stdio bridge between the TypeScript TUI and the Rust backend.
  4. Chapter 4: Session Manager — The backend coordinator that owns sessions, routes messages, and manages lifecycle.
  5. Chapter 5: Agent Configuration — The JSON config that declares each agent's personality, permitted tools, and MCP servers.
  6. Chapter 6: Agent Loop — The heartbeat: prompt → model → tool → result → repeat, until the conversation settles.
  7. Chapter 7: Tool System — Trait-based built-in tools with permission gates and async execution.
  8. Chapter 8: MCP Manager — The plugin system that lets external processes contribute tools via the MCP protocol.
  9. Chapter 9: Code Intelligence — code-agent-sdk: Tree-sitter + LSP for semantic code navigation exposed as MCP tools.
  10. Chapter 10: Semantic Search & Knowledge — Local embeddings (Candle ML) + HNSW vector index for offline RAG.

Repository Map (for context)

Path What Lives There
crates/chat-cli/ V1 monolithic binary (entry main.rs)
crates/chat-cli-v2/ V2 backend (ACP, session manager, agent hosting)
crates/agent/ Agent Loop implementation (shared by V1 and V2)
crates/code-agent-sdk/ Tree-sitter + LSP MCP server
crates/semantic-search-client/ Embeddings + vector index
crates/mock-mcp-server/ Reference MCP server for testing
packages/tui/ V2 TypeScript TUI (React + Twinki)
packages/twinki/ Custom React reconciler for terminals
packages/ink/ Forked Ink library (used by some views)

This walkthrough skips the generated AWS SDK crates (amzn-*-client, aws-toolkit-telemetry-definitions) and build tooling. Open a chapter to dive in.

Generated by the code-walkthrough skill. Source: ~/Documents/kiro-cli/.