kiro-acp-client

An unofficial Agent Client Protocol (ACP) client for the kiro CLI tool.

Note: This project is in early development (v0.0.1). APIs may change.

Features

• 🚀 Interactive multi-turn chat interface with kiro-cli
• 📂 Session management - resume previous conversations
• 🔍 Session history search and filtering by directory
• 🔧 Real-time tool call monitoring with status updates
• 🎯 Interactive permission request handling
• 📊 Context usage tracking with visual progress bar
• 📝 Optional protocol logging for debugging
• 🎨 Rich terminal UI with streaming message output
• 🔌 Extensible callback-based architecture
• ⚡ Wildcard callbacks for unknown session updates and notifications

Prerequisites

• Node.js (ES2022+ compatible)
• kiro-cli installed and available in PATH

Installation

npm install kiro-acp-client

Or install globally to use the CLI:

npm install -g kiro-acp-client

Usage

CLI Mode

Run the interactive chat interface:

kiro-acp-client

Or if installed locally:

npx kiro-acp-client

CLI Features

• Session Management: Choose to create a new session or resume an existing one
  • Browse up to 20 most recent sessions
  • Filter sessions by working directory
  • View session timestamps and paths
• Multi-turn conversations: Chat naturally with the agent across multiple turns
• Tool call visualization: See when tools are called with emoji indicators:
  • 🔧 Tool starting
  • ✓ Tool completed successfully
  • ✗ Tool failed
  • ⋯ Tool in progress
• Interactive permissions: Approve or deny permission requests with numbered options
• Context tracking: Monitor context usage with a visual progress bar
• Graceful shutdown: Press Ctrl+C to exit cleanly

Example Session

You: What's the weather like?
Agent: I'll check the weather for you using the weather tool...
🔧 Calling: get_weather
✓ Completed: get_weather

Based on the weather data, it's currently sunny and 72°F...

Context Usage: [████████░░] 78%

You: Thanks!

Programmatic Usage

Use the client as a library in your own TypeScript/JavaScript projects:

import { KiroClient, SessionManager } from 'kiro-acp-client'
import { spawn } from 'child_process'
import { Readable, Writable } from 'stream'

// Create client with callbacks
const client = new KiroClient({
  onMessageChunk: async (chunk) => {
    if (chunk.type === 'text') {
      process.stdout.write(chunk.text)
    }
  },
  onToolCall: async (toolCall) => {
    console.log(`🔧 Tool: ${toolCall.name}`)
  },
  onPermissionRequest: async (request) => {
    return { approved: true, selectedIndexes: [0] }
  }
})

// Spawn kiro-cli and initialize
const kiroProcess = spawn('kiro-cli', ['acp'], {
  stdio: ['pipe', 'pipe', 'inherit']
})

const input = Readable.toWeb(kiroProcess.stdout)
const output = Writable.toWeb(kiroProcess.stdin)

await client.initialize(input, output)
const sessionId = await client.newSession()
await client.sendPrompt(sessionId, 'Hello, kiro!')

// Work with session history
const manager = new SessionManager()
const sessions = manager.listAllSessions()
console.log(`Found ${sessions.length} sessions`)

For detailed API documentation, callback specifications, and comprehensive examples, see API_REFERENCE.md.

Session Management

The SessionManager class provides utilities to search, filter, and load Kiro CLI session history:

import { SessionManager } from 'kiro-acp-client'

const manager = new SessionManager() // Reads from ~/.kiro/sessions/cli/

// List all sessions
const sessions = manager.listAllSessions()

// Find sessions in a specific directory
const projectSessions = manager.findSessionsByCwd('/path/to/project')

// Filter by date range
const recentSessions = manager.filterSessions({
  updatedAfter: new Date('2024-01-01')
})

// Load conversation history
const fullSession = manager.getFullSession(sessionId)
if (fullSession) {
  SessionManager.printConversation(fullSession.messages)
}

// Search across all sessions
const results = manager.searchMessageContent('error handling')

Key Features:

• Browse and resume previous conversations
• Search by directory, date range, or message content
• Load full conversation history with metadata
• Export session data for analysis

See API_REFERENCE.md for complete SessionManager documentation, including 8+ detailed use cases (session browsing, filtering, resuming, exporting, etc.) and full type specifications.

Development

Setup

Clone the repository and install dependencies:

git clone https://github.com/k2sebeom/kiro-acp-client.git
cd kiro-acp-client
npm install

Available Scripts

# Build
npm run build         # Compile TypeScript to JavaScript
npm run clean         # Remove the dist/ directory
npm run dev           # Watch mode - recompile on file changes

# Code Quality
npm run lint          # Check code with ESLint
npm run lint:fix      # Fix ESLint issues automatically
npm run format        # Format code with Prettier
npm run format:check  # Check formatting without changing files

# Testing
npm test              # Run tests (not yet implemented)

Project Structure

kiro-acp-client/
├── src/
│   ├── index.ts          # Library entry point
│   ├── cli.ts            # CLI implementation
│   ├── kiroClient.ts     # KiroClient class
│   └── sessionManager.ts # Session history management
├── examples/
│   ├── sessionManagerExample.ts     # Basic session management demo
│   └── sessionManagerUseCases.ts    # Comprehensive use case examples
├── dist/                 # Compiled output (generated)
├── API_REFERENCE.md      # Detailed API documentation and types
├── CLAUDE.md             # Project guidance for Claude Code
├── package.json
├── tsconfig.json
└── README.md

Architecture

The project consists of four main components:

1. KiroClient (src/kiroClient.ts): Core ACP client implementation

   • Implements the acp.Client interface from @agentclientprotocol/sdk
   • Provides callback-based architecture for handling ACP events
   • Handles permission requests, session updates, and notifications

2. SessionManager (src/sessionManager.ts): Session history management

   • Reads and parses Kiro CLI session files from ~/.kiro/sessions/cli/
   • Provides search and filtering capabilities by directory, date, and content
   • Loads conversation history and metadata for session resumption

3. CLI (src/cli.ts): Interactive command-line interface

   • Spawns kiro-cli as a child process
   • Session selection menu (new or resume existing)
   • Implements rich terminal UI with streaming output
   • Handles user input and graceful shutdown

4. Library Entry Point (src/index.ts): Module exports

   • Exports KiroClient and SessionManager for programmatic usage
   • Supports direct module execution

For detailed API specifications, type definitions, and debugging guidance, see API_REFERENCE.md.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Style

• Follow the existing code style (enforced by ESLint and Prettier)
• Run npm run lint and npm run format before committing
• Write meaningful commit messages
• Add tests for new features (when test infrastructure is ready)

Known Limitations

• Tests not yet implemented
• No error recovery for kiro-cli process crashes
• Permission requests block until user responds (no timeout)
• Context usage bar assumes 0-100 percentage range

License

ISC © SeBeom Lee

Links

• API Reference - Detailed API documentation and types
• GitHub Repository
• Issue Tracker
• Agent Client Protocol Specification
• kiro-cli

Acknowledgments

This project uses the Agent Client Protocol SDK and is designed to work with kiro-cli.