Learn Kiro CLI in 10 DaysDay 10: Settings, ACP & Real-World Workflows
books.chapter 10Learn Kiro CLI in 10 Days

Settings Management

Kiro CLI offers extensive configuration options. Mastering these settings significantly improves your development experience.

Settings Operations

# Open settings file in editor
kiro-cli settings open

# List configured settings
kiro-cli settings list

# List all settings including defaults
kiro-cli settings list --all

# Get a specific setting
kiro-cli settings chat.defaultModel

# Change a setting
kiro-cli settings chat.defaultModel claude-sonnet-4.5

# Delete a setting (restore default)
kiro-cli settings --delete chat.defaultModel

Settings file locations:

  • macOS: ~/.kiro/settings.json
  • Linux: ~/.config/kiro/settings.json

Key Setting Categories

Chat Interface

Setting Description Default
chat.defaultModel Default AI model auto
chat.defaultAgent Default agent —
chat.diffTool External diff tool —
chat.greeting.enabled Show startup greeting true
chat.editMode Edit mode false
chat.enableNotifications Desktop notifications false
chat.disableMarkdownRendering Disable markdown rendering false
chat.disableAutoCompaction Disable auto-compaction false

Knowledge Base

Setting Description
chat.enableKnowledge Enable/disable knowledge base
knowledge.defaultIncludePatterns Default include patterns
knowledge.defaultExcludePatterns Default exclude patterns
knowledge.maxFiles Maximum files for indexing
knowledge.chunkSize Text chunk size
knowledge.indexType Default index type

Key Bindings

Setting Description
chat.skimCommandKey Fuzzy search key
chat.autocompletionKey Completion accept key
chat.tangentModeKey Tangent mode key
chat.delegateModeKey Delegate key

Feature Toggles

Setting Description
chat.enableThinking Thinking tool
chat.enableTangentMode Tangent mode
chat.enableTodoList TODO lists
chat.enableCheckpoint Checkpointing
chat.enableDelegate Delegate feature

Telemetry

Setting Description
telemetry.enabled Enable/disable telemetry collection

Environment Variables

Variable Description
KIRO_LOG_LEVEL Log level (error, warn, info, debug, trace)
KIRO_LOG_NO_COLOR Disable colored logs (set to 1)

Experimental Features

Kiro CLI includes experimental features under active development. Toggle them with /experiment.

Tangent Mode

Explore side topics without disrupting your main conversation:

> /tangent

Or press Ctrl+T to toggle. Return to the original conversation by running /tangent again.

TODO Lists

Manage task lists within your session:

> /todos add Write unit tests
> /todos add Update API documentation
> /todos complete 1

Thinking Tool

Visualizes the AI's step-by-step reasoning process. Useful for debugging and learning from complex problems.

kiro-cli settings chat.enableThinking true

Checkpointing

Save snapshots of file changes during a session and restore them:

> /checkpoint init        # Initialize checkpointing
> /checkpoint list        # List checkpoints
> /checkpoint diff 1      # View changes at a checkpoint
> /checkpoint restore 1   # Restore to a checkpoint

Automatically enabled in Git repositories.

Context Usage Indicator

Displays context window usage as a color-coded percentage:

kiro-cli settings chat.enableContextUsageIndicator true

Agent Client Protocol (ACP)

ACP is an open standard that standardizes communication between AI agents and editors. Just as LSP (Language Server Protocol) standardized editor-language server communication, ACP standardizes editor-AI agent communication.

ACP Overview

flowchart LR
    subgraph Editors["Editors"]
        JB["JetBrains IDE"]
        Zed["Zed"]
        Other["Other Editors"]
    end
    subgraph ACP["ACP Protocol"]
        JSONRPC["JSON-RPC 2.0<br/>stdin/stdout"]
    end
    subgraph Agent["Kiro CLI"]
        AI["AI Agent"]
    end
    JB <--> JSONRPC
    Zed <--> JSONRPC
    Other <--> JSONRPC
    JSONRPC <--> AI
    style Editors fill:#3b82f6,color:#fff
    style ACP fill:#8b5cf6,color:#fff
    style Agent fill:#22c55e,color:#fff

Starting ACP

# Default agent
kiro-cli acp

# Specific agent
kiro-cli acp --agent my-agent

JetBrains IDE Configuration

Create ~/.jetbrains/acp.json:

{
  "command": "/path/to/kiro-cli",
  "args": ["acp"]
}

Zed Configuration

Add to ~/.config/zed/settings.json:

{
  "assistant": {
    "version": "2",
    "default_model": {
      "provider": "custom",
      "model": "kiro"
    }
  },
  "language_models": {
    "custom": [
      {
        "name": "kiro",
        "type": "custom",
        "command": "/path/to/kiro-cli",
        "args": ["acp"]
      }
    ]
  }
}

ACP Methods

Method Description
initialize Exchange capabilities
session/new Create new session
session/load Load existing session
session/prompt Send a prompt
session/cancel Cancel operation
session/set_mode Switch agent mode
session/set_model Change model

Session Storage

ACP sessions persist to ~/.kiro/sessions/cli/ with metadata and event logs.

Real-World Workflows

Automated Code Review

# Review PR changes
git diff main...HEAD | kiro-cli chat --no-interactive \
  --agent code-reviewer \
  "Review this PR for security, performance, and code quality."

Auto-Fix Build Errors

# Pass build errors for fixing
npm run build 2>&1 | kiro-cli chat --trust-tools "read,write" \
  "Fix these build errors"

Documentation Generation

# Auto-generate API documentation
kiro-cli --agent docs-writer \
  "Generate API documentation for all endpoints in src/api/"

Team-Shared Development Environment

Include these files in your repository:

.kiro/
├── agents/
│   ├── project-dev.json     # Project-specific agent
│   └── code-reviewer.json   # Code review agent
├── steering/
│   ├── product.md           # Product information
│   ├── tech.md              # Technology stack
│   ├── structure.md         # Project structure
│   └── api-standards.md     # API conventions
├── settings/
│   └── mcp.json             # MCP server config
└── hooks/                    # Hook definitions (reference)

Anyone who clones the repository gets the same development environment.

CI/CD Pipeline Integration

# GitHub Actions example
- name: Code Review
  run: |
    git diff ${{ github.event.pull_request.base.sha }}..HEAD \
    | kiro-cli chat --no-interactive --trust-all-tools \
      --agent code-reviewer \
      "Review this PR"

10-Day Recap

flowchart TB
    subgraph Foundation["Foundation (Day 1-3)"]
        D1["Day 1: Installation<br/>Authentication & Basics"]
        D2["Day 2: Chat<br/>Model Selection"]
        D3["Day 3: Sessions<br/>Translate & Autocomplete"]
    end
    subgraph Agents["Agents (Day 4-5)"]
        D4["Day 4: Agent Basics<br/>Config File Structure"]
        D5["Day 5: Agent Practice<br/>toolsSettings & Examples"]
    end
    subgraph Intelligence["Intelligence (Day 6)"]
        D6["Day 6: Code Intelligence<br/>Tree-sitter & LSP"]
    end
    subgraph Context["Context (Day 7-8)"]
        D7["Day 7: Steering<br/>Context Management"]
        D8["Day 8: MCP Integration<br/>Knowledge Management"]
    end
    subgraph Advanced["Advanced (Day 9-10)"]
        D9["Day 9: Hooks<br/>Subagents"]
        D10["Day 10: Settings, ACP<br/>Real-World Workflows"]
    end
    Foundation --> Agents
    Agents --> Intelligence
    Intelligence --> Context
    Context --> Advanced
    style Foundation fill:#3b82f6,color:#fff
    style Agents fill:#8b5cf6,color:#fff
    style Intelligence fill:#22c55e,color:#fff
    style Context fill:#f59e0b,color:#fff
    style Advanced fill:#ef4444,color:#fff

Knowledge Map

Area What You Learned
Foundation Installation, authentication, chat, session management, translate, autocomplete
Agents Config files, tools/allowedTools, toolsSettings, resources, MCP integration
Code understanding Tree-sitter, LSP integration, pattern search/rewrite
Context Steering files, 4 context approaches, knowledge bases
Automation 5 hook types, subagents, delegate
Integration ACP, editor integration, CI/CD, team sharing

Recommended Development Flow

  1. Project setup: Create steering files → Configure agents → Add MCP servers
  2. Daily development: Launch with kiro-cli --agent project-dev → Give natural language instructions → Hooks auto-validate
  3. Review: git diff | kiro-cli --agent code-reviewer for PR review
  4. Team sharing: Commit .kiro/ directory to the repository

Troubleshooting

Common Issues

Problem Solution
Installation failure Run kiro-cli doctor --all for diagnostics
Authentication error Re-login with kiro-cli login
MCP connection error Check with kiro-cli mcp status --name <name>
Hooks not working Verify matcher patterns and triggers
Slow responses Optimize steering files, disable unused MCP
Context overflow Use /compact, migrate to knowledge bases

Diagnostic Commands

# Environment diagnostics
kiro-cli doctor --all

# Detailed diagnostic report
kiro-cli diagnostic --format json

# Bug report
kiro-cli issue

# Diagnostic logs (including MCP)
# In chat:
> /logdump --mcp

Next Steps

  • Official documentation: https://kiro.dev/docs/cli/
  • Changelog: kiro-cli version --changelog
  • Community: Kiro Discord server
  • Practice: Create agents, configure steering, and apply to real projects

You now have the power to harness AI agents from your terminal. Use Kiro CLI to build an efficient and enjoyable development workflow.