Project 1: Kiro CLI Session Explorer

Project 1: Kiro CLI Session Explorer

Understanding the Chat Runtime: Master the foundation of all Kiro CLI interactions


Project Metadata

Attribute Value
Difficulty Level 1: Beginner
Time Estimate Weekend (8-12 hours)
Primary Language Shell/Bash
Alternative Languages Python, TypeScript
Prerequisites Basic terminal usage, shell scripting fundamentals
Main Reference โ€œEffective Shellโ€ by Dave Kerr

Learning Objectives

By completing this project, you will:

  1. Understand the Kiro CLI session lifecycle - from initialization through termination, including how state is preserved and restored
  2. Master context management commands - /chat, /context, /model and their role in session behavior
  3. Develop intuition for token budgets - recognizing what consumes context and when to manage it
  4. Build practical automation skills - creating wrapper scripts that enhance CLI workflows
  5. Learn JSON data manipulation - parsing and transforming session data with jq

Deep Theoretical Foundation

What Is a Chat Session?

Before the age of AI terminals, a โ€œsessionโ€ simply meant the time between logging in and logging out. Your shell remembered nothing between sessions - every bash invocation started fresh.

Kiro CLI introduces a fundamentally different concept: cognitive sessions. These are persistent, stateful conversations where the AI maintains memory of what youโ€™ve discussed, which files youโ€™ve added to context, and what decisions youโ€™ve made together.

Traditional Shell Session              Kiro CLI Cognitive Session
========================              ==========================

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”               โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚ $ command           โ”‚               โ”‚ $ kiro-cli chat             โ”‚
โ”‚ > output            โ”‚               โ”‚                             โ”‚
โ”‚ $ command           โ”‚               โ”‚ > "Explain auth flow"       โ”‚
โ”‚ > output            โ”‚               โ”‚ [AI responds with context]  โ”‚
โ”‚ $ exit              โ”‚               โ”‚                             โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜               โ”‚ > /context add src/auth/*   โ”‚
        โ”‚                             โ”‚ [Files added to memory]     โ”‚
        โ–ผ                             โ”‚                             โ”‚
   State Lost                         โ”‚ > "Refactor this"           โ”‚
                                      โ”‚ [AI remembers everything]   โ”‚
                                      โ”‚                             โ”‚
                                      โ”‚ > /chat save                โ”‚
                                      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                                                    โ”‚
                                                    โ–ผ
                                              State Preserved
                                                    โ”‚
                                      โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
                                      โ”‚ $ kiro-cli /chat resume     โ”‚
                                      โ”‚ [Continue exactly where     โ”‚
                                      โ”‚  you left off]              โ”‚
                                      โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

The Session State Machine

Every Kiro CLI session transitions through well-defined states:

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    KIRO SESSION STATE MACHINE                       โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                    โ”‚
โ”‚   โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    kiro-cli chat    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”               โ”‚
โ”‚   โ”‚   IDLE   โ”‚ โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ–ถ  โ”‚ INITIALIZING โ”‚               โ”‚
โ”‚   โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                     โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”˜               โ”‚
โ”‚        โ–ฒ                                   โ”‚                       โ”‚
โ”‚        โ”‚                                   โ–ผ                       โ”‚
โ”‚        โ”‚                           โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”               โ”‚
โ”‚        โ”‚            exit           โ”‚    ACTIVE    โ”‚โ—€โ”€โ”€โ”           โ”‚
โ”‚        โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค              โ”‚   โ”‚           โ”‚
โ”‚                                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜   โ”‚           โ”‚
โ”‚                                           โ”‚           โ”‚           โ”‚
โ”‚                              /context add โ”‚    user   โ”‚           โ”‚
โ”‚                              /model set   โ”‚  prompts  โ”‚           โ”‚
โ”‚                              /compact     โ”‚           โ”‚           โ”‚
โ”‚                                           โ–ผ           โ”‚           โ”‚
โ”‚                                    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”   โ”‚           โ”‚
โ”‚                                    โ”‚  PROCESSING  โ”‚โ”€โ”€โ”€โ”˜           โ”‚
โ”‚                                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜               โ”‚
โ”‚                                           โ”‚                       โ”‚
โ”‚                                    /chat save                     โ”‚
โ”‚                                           โ”‚                       โ”‚
โ”‚                                           โ–ผ                       โ”‚
โ”‚                                    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”               โ”‚
โ”‚                                    โ”‚    SAVED     โ”‚               โ”‚
โ”‚                                    โ”‚  (Dormant)   โ”‚               โ”‚
โ”‚                                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜               โ”‚
โ”‚                                           โ”‚                       โ”‚
โ”‚                                    /chat resume                   โ”‚
โ”‚                                           โ”‚                       โ”‚
โ”‚                                           โ–ผ                       โ”‚
โ”‚                                    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”               โ”‚
โ”‚                                    โ”‚   RESTORED   โ”‚               โ”‚
โ”‚                                    โ”‚   (Active)   โ”‚               โ”‚
โ”‚                                    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜               โ”‚
โ”‚                                                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Context: The Scarcest Resource

Think of context like the desk space in a cramped office. You can only have so many documents open before things start falling off the edge. In AI terms, this โ€œdesk spaceโ€ is measured in tokens.

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    CONTEXT WINDOW ANATOMY                           โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                    โ”‚
โ”‚  TOTAL CONTEXT WINDOW: ~200,000 tokens                             โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  SYSTEM PROMPT (~2,000 tokens)          โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚  Always present, defines AI behavior    โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                                          โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                              โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚  STEERING RULES              โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚  (~5,000 tokens typical)     โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  Project standards/rules     โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”          โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚          โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚ CONTEXT  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚ FILES    โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ–ˆโ”‚          โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜          โ”‚  โ”‚
โ”‚  โ”‚                    (~50,000 tokens)                          โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ”‚  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ”‚  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ”‚  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ”‚  โ”‚  โ”‚
โ”‚  โ”‚  โ”‚โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ–‘โ”‚  โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚  โ”‚
โ”‚  โ”‚                    CHAT HISTORY                              โ”‚  โ”‚
โ”‚  โ”‚                    (~143,000 tokens available)               โ”‚  โ”‚
โ”‚  โ”‚                    Grows with each exchange                  โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                                                                    โ”‚
โ”‚  โ–ˆโ–ˆโ–ˆโ–ˆ = Fixed overhead                                             โ”‚
โ”‚  โ–‘โ–‘โ–‘โ–‘ = Dynamic/growing content                                    โ”‚
โ”‚                                                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Real-World Analogy: Imagine youโ€™re a detective with a case board. The board can only hold so many photos, notes, and strings connecting clues. At some point, you need to archive old evidence to make room for new leads. Context management in Kiro is exactly this - strategic curation of what the AI โ€œremembersโ€ at any moment.

Historical Context: From Stateless to Stateful

The evolution of terminal intelligence follows a clear arc:

Era Tool State Model
1970s sh/bash Stateless (environment vars only)
1990s Screen/tmux Session persistence (terminal state)
2010s Fish/Zsh Enhanced history, autosuggestions
2023 ChatGPT CLI Stateless conversations
2025 Kiro CLI Full cognitive sessions with persistence

Kiro represents the first time a CLI tool maintains semantic memory - not just command history, but understanding of your project, your decisions, and your intent.


Complete Project Specification

What You Are Building

A Session Management Toolkit that enhances Kiro CLIโ€™s native session handling with:

  1. Semantic Naming: Save sessions with meaningful names and descriptions
  2. Metadata Tracking: Record token usage, duration, model distribution
  3. Session Discovery: List, search, and filter saved sessions
  4. Export Capabilities: Convert sessions to markdown documentation
  5. Usage Analytics: Visualize token consumption patterns

Architecture Overview

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                   SESSION EXPLORER ARCHITECTURE                      โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                     โ”‚
โ”‚  User                                                               โ”‚
โ”‚   โ”‚                                                                 โ”‚
โ”‚   โ–ผ                                                                 โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                      โ”‚
โ”‚  โ”‚           kiro-session (wrapper)           โ”‚                      โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚ Commands:                             โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚   save    - Save with metadata        โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚   resume  - Restore by name           โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚   list    - Show all sessions         โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚   export  - Generate markdown         โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ”‚   stats   - Token analytics           โ”‚โ”‚                      โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚                      โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                      โ”‚
โ”‚                        โ”‚                                            โ”‚
โ”‚            โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                                โ”‚
โ”‚            โ”‚                       โ”‚                                โ”‚
โ”‚            โ–ผ                       โ–ผ                                โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”    โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”                     โ”‚
โ”‚  โ”‚   kiro-cli      โ”‚    โ”‚   ~/.kiro-sessions/ โ”‚                     โ”‚
โ”‚  โ”‚   (Native CLI)  โ”‚    โ”‚   โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚                     โ”‚
โ”‚  โ”‚                 โ”‚    โ”‚   โ”‚ metadata.json โ”‚ โ”‚                     โ”‚
โ”‚  โ”‚  /chat save     โ”‚    โ”‚   โ”‚ session-1.jsonโ”‚ โ”‚                     โ”‚
โ”‚  โ”‚  /chat resume   โ”‚    โ”‚   โ”‚ session-2.jsonโ”‚ โ”‚                     โ”‚
โ”‚  โ”‚  /context show  โ”‚    โ”‚   โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ โ”‚                     โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜    โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜                     โ”‚
โ”‚                                                                     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Expected Deliverables

~/.local/bin/
โ””โ”€โ”€ kiro-session        # Main wrapper script

~/.kiro-sessions/
โ”œโ”€โ”€ metadata.json       # Index of all sessions
โ”œโ”€โ”€ oauth-refactor-2025-12-22/
โ”‚   โ”œโ”€โ”€ session.json    # Kiro native session data
โ”‚   โ”œโ”€โ”€ meta.json       # Your enriched metadata
โ”‚   โ””โ”€โ”€ export.md       # Generated documentation
โ””โ”€โ”€ api-design-2025-12-21/
    โ”œโ”€โ”€ session.json
    โ”œโ”€โ”€ meta.json
    โ””โ”€โ”€ export.md

Solution Architecture

Component Design

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    COMPONENT ARCHITECTURE                           โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                      CLI Interface Layer                      โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚  โ”‚
โ”‚  โ”‚  โ”‚  kiro-session [command] [options]                        โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚                                                          โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚  Commands:                                               โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    save    --name <name> --summary <text> --tags <list>  โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    resume  <name|id>                                     โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    list    [--filter <tag>] [--sort <field>]             โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    export  <name> --format <md|json|html>                โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    stats   [--range <days>]                              โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚    delete  <name> [--force]                              โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                     Command Dispatcher                        โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚  โ”‚
โ”‚  โ”‚  โ”‚  save   โ”‚ โ”‚ resume  โ”‚ โ”‚  list   โ”‚ โ”‚ export  โ”‚ โ”‚  stats  โ”‚ โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ””โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”˜ โ”‚  โ”‚
โ”‚  โ”‚       โ”‚           โ”‚           โ”‚           โ”‚           โ”‚      โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚          โ”‚           โ”‚           โ”‚           โ”‚           โ”‚         โ”‚
โ”‚          โ–ผ           โ–ผ           โ–ผ           โ–ผ           โ–ผ         โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                     Data Layer                                โ”‚  โ”‚
โ”‚  โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”โ”‚  โ”‚
โ”‚  โ”‚  โ”‚   Metadata Store    โ”‚  โ”‚      Session Storage            โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚   (metadata.json)   โ”‚  โ”‚   (Individual session dirs)     โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚                     โ”‚  โ”‚                                 โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚   - Session index   โ”‚  โ”‚   - Native Kiro data            โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚   - Quick lookups   โ”‚  โ”‚   - Enriched metadata           โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ”‚   - Tag mappings    โ”‚  โ”‚   - Exports                     โ”‚โ”‚  โ”‚
โ”‚  โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚                     Kiro CLI Integration                      โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ”‚   kiro-cli chat                   (Start sessions)           โ”‚  โ”‚
โ”‚  โ”‚   kiro-cli /chat save             (Native save)              โ”‚  โ”‚
โ”‚  โ”‚   kiro-cli /chat resume           (Native restore)           โ”‚  โ”‚
โ”‚  โ”‚   kiro-cli /context show          (Get token usage)          โ”‚  โ”‚
โ”‚  โ”‚                                                              โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                                                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Data Flow: Save Operation

โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                    SAVE OPERATION DATA FLOW                         โ”‚
โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค
โ”‚                                                                    โ”‚
โ”‚  User: kiro-session save --name "oauth-work" --summary "..."       โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 1. VALIDATE INPUT                                             โ”‚  โ”‚
โ”‚  โ”‚    - Check name uniqueness                                    โ”‚  โ”‚
โ”‚  โ”‚    - Sanitize special characters                              โ”‚  โ”‚
โ”‚  โ”‚    - Verify active Kiro session exists                        โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 2. CAPTURE CONTEXT                                            โ”‚  โ”‚
โ”‚  โ”‚    - Run: kiro-cli /context show --format json                โ”‚  โ”‚
โ”‚  โ”‚    - Parse token usage                                        โ”‚  โ”‚
โ”‚  โ”‚    - Extract file list                                        โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 3. INVOKE NATIVE SAVE                                         โ”‚  โ”‚
โ”‚  โ”‚    - Run: kiro-cli /chat save                                 โ”‚  โ”‚
โ”‚  โ”‚    - Capture session ID                                       โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 4. CREATE SESSION DIRECTORY                                   โ”‚  โ”‚
โ”‚  โ”‚    mkdir ~/.kiro-sessions/{name}-{date}/                      โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 5. WRITE METADATA                                             โ”‚  โ”‚
โ”‚  โ”‚    {                                                          โ”‚  โ”‚
โ”‚  โ”‚      "name": "oauth-work",                                    โ”‚  โ”‚
โ”‚  โ”‚      "summary": "...",                                        โ”‚  โ”‚
โ”‚  โ”‚      "created": "2025-12-22T10:30:00Z",                       โ”‚  โ”‚
โ”‚  โ”‚      "tokens": { "used": 12450, "limit": 200000 },            โ”‚  โ”‚
โ”‚  โ”‚      "models": { "haiku": 35, "sonnet": 55, "opus": 10 },     โ”‚  โ”‚
โ”‚  โ”‚      "files": ["src/auth/oauth.ts", "src/auth/session.ts"]    โ”‚  โ”‚
โ”‚  โ”‚    }                                                          โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”  โ”‚
โ”‚  โ”‚ 6. UPDATE INDEX                                               โ”‚  โ”‚
โ”‚  โ”‚    - Add entry to metadata.json                               โ”‚  โ”‚
โ”‚  โ”‚    - Rebuild tag index                                        โ”‚  โ”‚
โ”‚  โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜  โ”‚
โ”‚                               โ”‚                                    โ”‚
โ”‚                               โ–ผ                                    โ”‚
โ”‚  OUTPUT: "Session saved: oauth-work (12,450 tokens)"               โ”‚
โ”‚                                                                    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜

Key Interfaces

Metadata Schema (meta.json):

{
  "version": "1.0",
  "name": "oauth-work",
  "summary": "Working on Google OAuth integration",
  "tags": ["auth", "oauth", "google"],
  "created": "2025-12-22T10:30:00Z",
  "lastAccessed": "2025-12-22T14:45:00Z",
  "duration": {
    "total": 8100,
    "active": 5400
  },
  "tokens": {
    "used": 12450,
    "limit": 200000,
    "percentage": 6.2
  },
  "models": {
    "haiku": { "count": 12, "percentage": 35 },
    "sonnet": { "count": 18, "percentage": 55 },
    "opus": { "count": 3, "percentage": 10 }
  },
  "context": {
    "files": [
      { "path": "src/auth/oauth.ts", "tokens": 3200 },
      { "path": "src/auth/session.ts", "tokens": 2800 }
    ],
    "steering": ["tech.md", "security.md"]
  },
  "kiroSessionId": "abc123-def456"
}

Technology Choices

Component Choice Rationale
Primary Language Bash Native to terminal, no dependencies
JSON Processing jq Industry standard, powerful queries
Date Handling date (GNU) Available on all systems
Output Formatting printf Precise control, no dependencies
Alternative Python For complex analytics/visualization

Phased Implementation Guide

Phase 1: Foundation (2-3 hours)

Goal: Create the basic script structure and save functionality

What to Build:

  1. Script skeleton with argument parsing
  2. Configuration directory setup
  3. Basic save command that wraps Kiroโ€™s native save

Hint 1: Start by exploring ~/.kiro/ to understand what Kiro already creates:

find ~/.kiro -name "*.json" -type f 2>/dev/null | head -20

Hint 2: Use getopts for argument parsing in bash:

while getopts "n:s:t:" opt; do
  case $opt in
    n) name="$OPTARG" ;;
    s) summary="$OPTARG" ;;
    t) tags="$OPTARG" ;;
  esac
done

Hint 3: Create the directory structure first:

SESSIONS_DIR="${HOME}/.kiro-sessions"
mkdir -p "$SESSIONS_DIR"

Validation Checkpoint: You can run kiro-session save --name test and see a directory created.


Phase 2: Core Functionality (3-4 hours)

Goal: Implement list, resume, and metadata capture

What to Build:

  1. List command with formatted table output
  2. Resume command that finds session by name
  3. Token usage capture from /context show

Hint 1: Use jq to build formatted output:

jq -r '.sessions[] | "\(.name)\t\(.date)\t\(.tokens)"' metadata.json | column -t

Hint 2: Session resume needs to find the Kiro session ID:

kiro_id=$(jq -r '.kiroSessionId' "${session_dir}/meta.json")
kiro-cli /chat resume "$kiro_id"

Hint 3: Capture context with timeout to avoid hanging:

timeout 5s kiro-cli /context show --format json 2>/dev/null || echo '{}'

Validation Checkpoint: You can list sessions and resume one by name.


Phase 3: Polish and Edge Cases (2-3 hours)

Goal: Handle errors gracefully and add export functionality

What to Build:

  1. Export command generating markdown documentation
  2. Error handling for all edge cases
  3. Statistics/analytics summary

Hint 1: Generate markdown from session data:

cat << EOF > export.md
# Session: ${name}

**Summary**: ${summary}
**Date**: ${date}
**Tokens Used**: ${tokens}

## Files in Context
$(jq -r '.context.files[] | "- \(.path) (\(.tokens) tokens)"' meta.json)

## Conversation Highlights
[Export from native Kiro session]
EOF

Hint 2: Calculate statistics with jq:

jq -s 'map(.tokens.used) | add / length' ~/.kiro-sessions/*/meta.json

Hint 3: Handle missing files gracefully:

if [[ ! -f "$file" ]]; then
  echo "Error: Session not found" >&2
  exit 1
fi

Validation Checkpoint: You can export a session as markdown and view usage stats.


Testing Strategy

Unit Testing Sessions

#!/bin/bash
# test_session_explorer.sh

# Test 1: Save creates directory
test_save_creates_directory() {
  ./kiro-session save --name "test-session" --summary "Test"
  if [[ -d ~/.kiro-sessions/test-session-* ]]; then
    echo "PASS: Directory created"
  else
    echo "FAIL: Directory not created"
    exit 1
  fi
}

# Test 2: List shows saved session
test_list_shows_session() {
  output=$(./kiro-session list)
  if echo "$output" | grep -q "test-session"; then
    echo "PASS: Session appears in list"
  else
    echo "FAIL: Session not in list"
    exit 1
  fi
}

# Test 3: Invalid name rejected
test_invalid_name_rejected() {
  output=$(./kiro-session save --name "test/invalid" 2>&1)
  if echo "$output" | grep -qi "error\|invalid"; then
    echo "PASS: Invalid name rejected"
  else
    echo "FAIL: Invalid name accepted"
    exit 1
  fi
}

# Run tests
test_save_creates_directory
test_list_shows_session
test_invalid_name_rejected
echo "All tests passed!"

Integration Testing

  1. Fresh Start Test: Delete ~/.kiro-sessions/, run save, verify creation
  2. Round-Trip Test: Save session, exit, resume, verify context restored
  3. Concurrent Session Test: Save two sessions, list both, resume correct one
  4. Edge Case Test: Save with maximum length name, special characters

Manual Verification Checklist

  • Save a session with metadata
  • List all sessions, verify formatting
  • Resume a session by name
  • Export to markdown, verify content
  • View statistics across multiple sessions
  • Delete a session and verify removal from index

Common Pitfalls and Debugging

Pitfall 1: Kiro Session Not Found

Symptom: kiro-session save fails with โ€œno active sessionโ€

Cause: Trying to save when no Kiro chat session is running

Debug:

# Check if Kiro process is running
pgrep -f "kiro-cli" || echo "No Kiro session active"

Solution: Ensure you run kiro-cli chat before trying to save


Pitfall 2: jq Parse Errors

Symptom: jq: parse error (unexpected end of input)

Cause: Empty or malformed JSON from Kiro commands

Debug:

# Check raw output
kiro-cli /context show --format json | cat -A

Solution: Add fallback for empty responses:

output=$(kiro-cli /context show --format json 2>/dev/null)
if ! echo "$output" | jq empty 2>/dev/null; then
  output='{"tokens":{"used":0}}'
fi

Pitfall 3: Name Collision

Symptom: Save overwrites existing session

Cause: Not checking for existing session with same name

Debug:

ls ~/.kiro-sessions/ | grep "^${name}-"

Solution: Add timestamp or increment to name:

base_name="$name"
counter=1
while [[ -d "${SESSIONS_DIR}/${name}" ]]; do
  name="${base_name}-${counter}"
  ((counter++))
done

Pitfall 4: Token Count Discrepancy

Symptom: Reported tokens donโ€™t match Kiroโ€™s display

Cause: Timing issue - context changes between capture and save

Debug:

# Capture context immediately before save
kiro-cli /context show --format json > /tmp/context.json
./kiro-session save --context /tmp/context.json

Solution: Capture context as first step of save operation


Extensions and Challenges

Extension 1: Session Diff

Compare two sessions to see what changed:

./kiro-session diff old-session new-session
# Shows: files added/removed, token usage change, model distribution shift

Extension 2: Auto-Archive

Automatically archive sessions older than 30 days:

./kiro-session archive --days 30
# Compresses old sessions to save disk space

Extension 3: Team Sync

Sync session metadata to a shared repository:

./kiro-session sync --repo git@github.com:team/sessions.git
# Enables team knowledge sharing

Extension 4: Visual Timeline

Generate a visual timeline of all sessions:

./kiro-session timeline --output timeline.html
# Creates interactive HTML visualization

Challenge: Session Templates

Create session templates with pre-loaded context:

./kiro-session template create --name "security-audit" \
  --files "src/auth/**" \
  --steering "security.md"

./kiro-session start --template "security-audit"

Real-World Connections

How Professionals Use This

  1. Consulting Firms: Save sessions per client/project for billing and knowledge management
  2. Open Source Maintainers: Document AI-assisted code reviews as session exports
  3. Security Teams: Archive sessions for audit trails of AI-assisted vulnerability analysis
  4. Educators: Export sessions as teaching materials showing AI reasoning

Industry Patterns

Configuration Management (DevOps): Session metadata is similar to infrastructure state files (Terraform .tfstate). The pattern of saving state with semantic naming is universal.

Observability (SRE): Token tracking mirrors resource monitoring. Understanding consumption patterns enables optimization.

Documentation as Code (Technical Writing): Exporting sessions as markdown follows the docs-as-code philosophy where documentation lives alongside code.


Self-Assessment Checklist

Understanding Verification

  1. Can you explain the difference between session context and agent resources?
    • Session context is ephemeral (disappears when session ends)
    • Agent resources are persistent (loaded on every agent start)
  2. What happens to context when you close a terminal without saving?
    • Chat history is lost unless auto-save is enabled
    • Context files need to be re-added on next session
  3. How does /compact affect your session?
    • Summarizes chat history to reduce token usage
    • Preserves meaning while freeing context space
  4. Why is token tracking important?
    • Prevents context overflow (hitting limits)
    • Enables cost estimation and optimization
    • Helps identify expensive operations

Skill Demonstration

  • I can save a session with custom metadata
  • I can find and resume a session from days ago
  • I can explain whatโ€™s consuming tokens in a session
  • I can export a session as shareable documentation
  • I can analyze token usage patterns across sessions

Interview Preparation

Be ready to answer:

  1. โ€œHow would you design session persistence for an AI tool?โ€
  2. โ€œWhat are the tradeoffs between ephemeral and persistent context?โ€
  3. โ€œHow do token budgets affect AI application design?โ€
  4. โ€œHow would you implement session sharing across a team?โ€

Topic Resource Why It Helps
Shell Scripting โ€œEffective Shellโ€ by Dave Kerr, Ch. 8-12 Master bash patterns used in wrapper scripts
JSON Processing โ€œjq Manualโ€ (stedolan.github.io/jq) Essential for parsing session data
CLI Design โ€œThe Pragmatic Programmerโ€ Ch. 7 Design principles for command-line tools
Context Windows โ€œAI Engineeringโ€ by Chip Huyen, Ch. 4 Deep understanding of token economics
State Management โ€œDesigning Data-Intensive Applicationsโ€ Ch. 3 Patterns for data persistence

What Success Looks Like

When you complete this project, you will have:

  1. A Working Tool: kiro-session command in your PATH that enhances Kiro workflows
  2. Deep Understanding: Intuition for session lifecycle and context management
  3. Practical Skills: Shell scripting and JSON manipulation expertise
  4. Documentation: Exported sessions that serve as knowledge artifacts
  5. Foundation: Base knowledge for all subsequent Kiro projects

Next Steps: Move to Project 2 (Model Router Analyzer) to understand how Kiro selects between Haiku, Sonnet, and Opus models.