npm package: @kibibit/kibi
Description: Local-first AI agent CLI tool with TUI and MCP integration
Author: Kibibit
Latest version: 1.10.0

# Kibi


A local-first AI agent CLI tool with TUI (Terminal User Interface) and MCP (Model Context Protocol) integration.

## Description

Kibi is a command-line AI agent that connects to local LLM endpoints (like LM Studio, LiteLLM) or cloud providers (OpenAI-compatible APIs). It provides an interactive terminal UI for chatting with AI models and executing tools, with support for MCP servers for extensibility.

## Features

- **Local-First**: Works with local LLM endpoints (LM Studio, LiteLLM) or cloud providers
- **Interactive TUI**: Beautiful terminal user interface built with Ink/React
- **Tool Execution**: Built-in tools (file operations, bash commands) with approval workflow
- **MCP Integration**: Connect to Model Context Protocol servers for extensibility
- **Chat Persistence**: Save and resume chat sessions
- **Print Mode**: Non-interactive mode for scripting and automation
- **Streaming Responses**: Real-time streaming of LLM responses

## Installation

### Prerequisites

- Node.js 18+ and npm
- TypeScript 5.0+

### Install Dependencies

```bash
npm install
```

### Build

```bash
npm run build
```

### Development

Run in watch mode during development:

```bash
npm run dev
```

## Usage

### Basic Usage

Start the interactive TUI:

```bash
npm start
# or
node bin/kibi
```

### Print Mode

Run in non-interactive mode (for scripting):

```bash
node bin/kibi --print "Your prompt here"
```

### Available Commands

- `kibi agent [prompt]` - Start AI agent (default command)
- `kibi chat list` - List saved chats
- `kibi chat resume <chatId>` - Resume a saved chat
- `kibi mcp status` - Show MCP server status
- `kibi login` - Authenticate with API provider
- `kibi status` - Show current configuration and status

### Configuration

Configuration is stored in `~/.kibi/config.json`. You can configure:

- Default model and provider
- API keys (stored securely)
- MCP server connections
- Tool approval settings
- UI preferences

## Project Structure

```
kibi/
├── src/
│   ├── cli/          # CLI command parsing and routing
│   ├── agent/        # Core agent logic and LLM integration
│   ├── tools/        # Tool execution and management
│   ├── mcp/          # MCP server integration
│   ├── chat/         # Chat persistence
│   ├── config/       # Configuration management
│   ├── output/       # Output formatters (print mode)
│   ├── tui/          # Terminal UI components
│   ├── types/        # Shared TypeScript types
│   └── utils/        # Shared utilities
├── bin/              # Executable scripts
├── tests/            # Test files
└── docs/             # Documentation
```

## Development

### Scripts

- `npm run build` - Compile TypeScript to JavaScript
- `npm run dev` - Run in watch mode with tsx
- `npm start` - Run compiled code
- `npm test` - Run tests with vitest
- `npm run lint` - Run linter (when configured)

### Architecture

Kibi follows a modular architecture with clear boundaries:

- **CLI Module**: Command-line interface and argument parsing
- **TUI Module**: Interactive terminal UI (Ink/React)
- **Agent Core**: LLM integration and conversation management
- **Tools Module**: Tool execution with approval workflow
- **MCP Integration**: Model Context Protocol server management
- **Chat Persistence**: File-based chat storage
- **Configuration**: Settings and credential management
- **Output Formatters**: Print mode output formatting

See `docs/kibi-cli-agent-v1/planning/system-architecture.md` for detailed architecture documentation.

## License

ISC

## Contributing

This project is in active development. See the documentation in `docs/` for implementation specifications and architecture details.