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:
- Understand the Kiro CLI session lifecycle - from initialization through termination, including how state is preserved and restored
- Master context management commands -
/chat,/context,/modeland their role in session behavior - Develop intuition for token budgets - recognizing what consumes context and when to manage it
- Build practical automation skills - creating wrapper scripts that enhance CLI workflows
- 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:
- Semantic Naming: Save sessions with meaningful names and descriptions
- Metadata Tracking: Record token usage, duration, model distribution
- Session Discovery: List, search, and filter saved sessions
- Export Capabilities: Convert sessions to markdown documentation
- 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:
- Script skeleton with argument parsing
- Configuration directory setup
- 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:
- List command with formatted table output
- Resume command that finds session by name
- 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:
- Export command generating markdown documentation
- Error handling for all edge cases
- 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
- Fresh Start Test: Delete
~/.kiro-sessions/, run save, verify creation - Round-Trip Test: Save session, exit, resume, verify context restored
- Concurrent Session Test: Save two sessions, list both, resume correct one
- 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
- Consulting Firms: Save sessions per client/project for billing and knowledge management
- Open Source Maintainers: Document AI-assisted code reviews as session exports
- Security Teams: Archive sessions for audit trails of AI-assisted vulnerability analysis
- 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
- 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)
- 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
- How does
/compactaffect your session?- Summarizes chat history to reduce token usage
- Preserves meaning while freeing context space
- 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:
- โHow would you design session persistence for an AI tool?โ
- โWhat are the tradeoffs between ephemeral and persistent context?โ
- โHow do token budgets affect AI application design?โ
- โHow would you implement session sharing across a team?โ
Recommended Reading
| 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:
- A Working Tool:
kiro-sessioncommand in your PATH that enhances Kiro workflows - Deep Understanding: Intuition for session lifecycle and context management
- Practical Skills: Shell scripting and JSON manipulation expertise
- Documentation: Exported sessions that serve as knowledge artifacts
- 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.