{"_id":"@abhilov/kairo","_rev":"5-f28f07654004fff3240090eb8910c900","name":"@abhilov/kairo","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@abhilov/kairo","version":"1.0.0","keywords":[],"author":"","license":"ISC","_id":"@abhilov/kairo@1.0.0","maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"bin":{"kairo":"dist/index.js"},"dist":{"shasum":"84291d4c8287880e511664e6f6000c103a86f96b","tarball":"https://registry.npmjs.org/@abhilov/kairo/-/kairo-1.0.0.tgz","fileCount":34,"integrity":"sha512-4ibex1noe/g6rEmIttIoiU8lVeXVHWRW2+FpiLUZzebLPDdRjW1S2HAl1jArXs1W1nk4sT7KPOWTHujTfbRpCA==","signatures":[{"sig":"MEQCIDTdnJnM3x2esCMsqq8OxD07r+gq+IAgnQQncvi7LEjNAiALw8i9Wjn8mWEYGCJXw+ZqUuFhD4/UqGh2SlS4NJ/hCg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":44108},"main":"./dist/index.js","type":"module","gitHead":"8baf00bf7b57f0496b160a5083b9d7f3e9a7a9ec","scripts":{"dev":"tsx index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","setup":"tsx index.ts setup","start":"node dist/index.js","format":"prettier --write ."},"_npmUser":{"name":"abhilov","email":"abhilov01@gmail.com"},"_npmVersion":"10.8.2","description":"A terminal-native AI coding assistant built with TypeScript, LangChain, and NVIDIA NIM.","directories":{},"_nodeVersion":"20.20.1","dependencies":{"ora":"^9.4.0","zod":"^4.4.3","diff":"^9.0.0","boxen":"^8.0.1","chalk":"^5.6.2","dotenv":"^17.4.2","marked":"^18.0.3","langchain":"^1.4.0","prompt-sync":"^4.2.0","terminal-kit":"^3.1.2","@langchain/core":"^1.1.45","marked-terminal":"^7.3.0","@langchain/ollama":"^1.2.7","@langchain/openai":"^1.4.5","@langchain/anthropic":"^1.3.29"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.4","devDependencies":{"tsx":"^4.21.0","prettier":"^3.8.3","typescript":"^6.0.3","@types/node":"^25.6.2"},"_npmOperationalInternal":{"tmp":"tmp/kairo_1.0.0_1778494618511_0.5962130037806361","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@abhilov/kairo","version":"1.0.1","keywords":[],"author":"","license":"ISC","_id":"@abhilov/kairo@1.0.1","maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"bin":{"kairo":"dist/index.js"},"dist":{"shasum":"bb230963a6634c9d1da0e7073e2cbe48aaed08c0","tarball":"https://registry.npmjs.org/@abhilov/kairo/-/kairo-1.0.1.tgz","fileCount":34,"integrity":"sha512-+Yz8AKLAPFfPGs5nzglCNWjI9/yMU0PQ1A2Nu3H3KnBn26hMsobl52qYHObTrEfPoVMylCqdbzqJzzDsrfc6rQ==","signatures":[{"sig":"MEYCIQDWNUsShF39++OKc4Rz3X6dfWajZydwQpZocyA6Ec67ggIhAN/2OsgxfJ5owkSqxTHEJ8cVLBDJvSnnBTNrhkLW7nrE","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41549},"main":"./dist/index.js","type":"module","gitHead":"76175e8ed8363852aaea5883d7b3e65310f67d78","scripts":{"dev":"tsx index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","setup":"tsx index.ts setup","start":"node dist/index.js","format":"prettier --write ."},"_npmUser":{"name":"abhilov","email":"abhilov01@gmail.com"},"_npmVersion":"10.8.2","description":"KairoCLI is a terminal-native AI coding assistant built with TypeScript and LangChain.","directories":{},"_nodeVersion":"20.20.1","dependencies":{"ora":"^9.4.0","zod":"^4.4.3","diff":"^9.0.0","boxen":"^8.0.1","chalk":"^5.6.2","dotenv":"^17.4.2","marked":"^18.0.3","langchain":"^1.4.0","prompt-sync":"^4.2.0","terminal-kit":"^3.1.2","@langchain/core":"^1.1.45","marked-terminal":"^7.3.0","@langchain/ollama":"^1.2.7","@langchain/openai":"^1.4.5","@langchain/anthropic":"^1.3.29"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.4","devDependencies":{"tsx":"^4.21.0","prettier":"^3.8.3","typescript":"^6.0.3","@types/node":"^25.6.2"},"_npmOperationalInternal":{"tmp":"tmp/kairo_1.0.1_1778503940632_0.5633783787516322","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@abhilov/kairo","version":"1.0.2","keywords":[],"author":"","license":"ISC","_id":"@abhilov/kairo@1.0.2","maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"bin":{"kairo":"dist/index.js"},"dist":{"shasum":"c35d842d24541bf9cd8680fba32e3ff2b8dbeee0","tarball":"https://registry.npmjs.org/@abhilov/kairo/-/kairo-1.0.2.tgz","fileCount":34,"integrity":"sha512-RoemEEFAF/PHnX00k7HSjfUKYLhySdt2SmEmwxCeKRVSNIkpwp1QEPClgw+AZQFmvRMfZPRA8gJ1Vthf19Dc9Q==","signatures":[{"sig":"MEUCIFkyh/DdrtS+2IBWQflyGMu0iOjLU5yyIDuuodWfCp5/AiEAvyo9h8Q2rqWTpuBjL1Sbk6Ka7g4iFv/zVAZnIWPWIBs=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41807},"main":"./dist/index.js","type":"module","gitHead":"f8ce466f8cad6d9194c872e13a382c6aa0e5a3e3","scripts":{"dev":"tsx index.ts","test":"echo \"Error: no test specified\" && exit 1","build":"tsc","setup":"tsx index.ts setup","start":"node dist/index.js","format":"prettier --write ."},"_npmUser":{"name":"abhilov","email":"abhilov01@gmail.com"},"_npmVersion":"10.8.2","description":"KairoCLI is a terminal-native AI coding assistant built with TypeScript and LangChain.","directories":{},"_nodeVersion":"20.20.1","dependencies":{"ora":"^9.4.0","zod":"^4.4.3","diff":"^9.0.0","boxen":"^8.0.1","chalk":"^5.6.2","dotenv":"^17.4.2","marked":"^18.0.3","langchain":"^1.4.0","prompt-sync":"^4.2.0","terminal-kit":"^3.1.2","@langchain/core":"^1.1.45","marked-terminal":"^7.3.0","@langchain/ollama":"^1.2.7","@langchain/openai":"^1.4.5","@langchain/anthropic":"^1.3.29"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.4","devDependencies":{"tsx":"^4.21.0","prettier":"^3.8.3","typescript":"^6.0.3","@types/node":"^25.6.2"},"_npmOperationalInternal":{"tmp":"tmp/kairo_1.0.2_1778504991990_0.7026419729279925","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@abhilov/kairo","version":"1.1.0","keywords":[],"author":"","license":"ISC","_id":"@abhilov/kairo@1.1.0","maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"bin":{"kairo":"dist/index.js"},"dist":{"shasum":"eefce68f43ecf2ece07a43c3c1a5eaddf8c73314","tarball":"https://registry.npmjs.org/@abhilov/kairo/-/kairo-1.1.0.tgz","fileCount":52,"integrity":"sha512-QxTzZy9QhTEHH61aDDa7RNxYKWlVDFfTeVqzqBv+0GGwm4R/jREDRquuVNWko8EbteLlLmcHFiYQMBmze+Yn3A==","signatures":[{"sig":"MEUCIGKzcE1nlwjLg1Mm/y0e5vkxeI3w4RALYzi7ik3wGSw4AiEA78S3UMHSesgtHl3GheIcyht4Wd+7FPWrz95TVkJnYoQ=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":100729},"main":"./dist/index.js","type":"module","gitHead":"6de4264672cadb4494f41f7050b4cfe1b2a92f7b","scripts":{"dev":"tsx index.ts","test":"vitest run","build":"tsc","setup":"tsx index.ts setup","start":"node dist/index.js","format":"prettier --write ."},"_npmUser":{"name":"abhilov","email":"abhilov01@gmail.com"},"_npmVersion":"10.9.3","description":"A terminal-native AI coding assistant built with TypeScript and the OpenAI SDK.","directories":{},"_nodeVersion":"22.18.0","dependencies":{"ora":"^9.4.0","zod":"^4.4.3","diff":"^9.0.0","boxen":"^8.0.1","chalk":"^5.6.2","dotenv":"^17.4.2","marked":"^18.0.3","openai":"^6.42.0","marked-terminal":"^7.3.0","zod-to-json-schema":"^3.25.2"},"_hasShrinkwrap":false,"packageManager":"pnpm@10.33.4","devDependencies":{"tsx":"^4.21.0","vitest":"^4.1.8","prettier":"^3.8.3","typescript":"^6.0.3","@types/node":"^25.6.2"},"_npmOperationalInternal":{"tmp":"tmp/kairo_1.1.0_1780596304003_0.004060324281861538","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@abhilov/kairo","version":"1.2.0","description":"A terminal-native AI coding assistant built with TypeScript and the OpenAI SDK.","type":"module","main":"./dist/index.js","bin":{"kairo":"dist/index.js"},"scripts":{"build":"tsc","dev":"tsx index.ts","start":"node dist/index.js","setup":"tsx index.ts setup","test":"vitest run","format":"prettier --write ."},"dependencies":{"@openai/agents":"^0.13.3","boxen":"^8.0.1","chalk":"^5.6.2","diff":"^9.0.0","dotenv":"^17.4.2","marked":"^15.0.12","marked-terminal":"^7.3.0","open":"^11.0.0","openai":"^6.42.0","ora":"^9.4.0","zod":"^4.4.3","zod-to-json-schema":"^3.25.2"},"devDependencies":{"@types/node":"^25.6.2","prettier":"^3.8.3","tsx":"^4.21.0","typescript":"^6.0.3","vitest":"^4.1.8"},"engines":{"node":">=20"},"_id":"@abhilov/kairo@1.2.0","gitHead":"377dfd1626f6d8c47f94b041fbaf051fbf1158a1","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-gZmJe8le67/FfoF7IyDZwTxtCQT6VizECXuGV0wngpJdqn0JBo8H3H7afJ0BDp084hQd3ozQJ2yniY9jwOl0NQ==","shasum":"8dbaa1424a458bb51c3c1baf5585eeb0e3389087","tarball":"https://registry.npmjs.org/@abhilov/kairo/-/kairo-1.2.0.tgz","fileCount":69,"unpackedSize":171224,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQDBY3A3Cw8hsE0tfQ/LnF43B0NpilkVu9mKEDA+dbqzTQIgX2l1KBaLwf8o3UOWEy7E7flwgDqKX1j30em4vwt4Xr0="}]},"_npmUser":{"name":"abhilov","email":"abhilov01@gmail.com"},"directories":{},"maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/kairo_1.2.0_1784129603491_0.3641919352726286"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-11T10:16:58.372Z","modified":"2026-07-15T15:33:23.773Z","1.0.0":"2026-05-11T10:16:58.650Z","1.0.1":"2026-05-11T12:52:20.831Z","1.0.2":"2026-05-11T13:09:52.142Z","1.1.0":"2026-06-04T18:05:04.212Z","1.2.0":"2026-07-15T15:33:23.652Z"},"description":"A terminal-native AI coding assistant built with TypeScript and the OpenAI SDK.","maintainers":[{"name":"abhilov","email":"abhilov01@gmail.com"}],"readme":"# KairoCLI\n\nA terminal-native AI coding assistant built with TypeScript and the OpenAI SDK.\n\nKairoCLI runs as an interactive CLI agent with tool-calling capabilities — reading/writing files, executing commands, searching code, and managing git workflows — all from your terminal.\n\n---\n\n## Demo\n\nhttps://github.com/user-attachments/assets/e95504c1-01e1-4f7d-9eea-ad753c23acb2\n\n---\n\n## Features\n\n- **Interactive terminal assistant** — conversational AI that can act on your codebase\n- **Multi-provider support** — OpenAI, Anthropic, Groq, NVIDIA, Ollama, or any OpenAI-compatible API (Custom)\n- **Streaming responses** — real-time buffered responses with markdown rendering via `marked-terminal`\n- **Tool-calling agent** — 13 tools for filesystem, shell, git, and search operations\n- **Safety system** — dangerous commands (`rm -rf`, `format`, `git reset --hard`, etc.) and protected files (`.env`, `package.json`, `pnpm-lock.yaml`) require interactive confirmation\n- **Runtime session persistence** — conversation history, execution state, task state, and workspace state saved across sessions (up to 200 messages with history trimming)\n- **Workspace-aware execution** — tracks current working directory and execution state\n- **Git-aware tooling** — status, diff, and diff preview tools\n- **Non-interactive mode** — `--task` flag for single-shot automation\n- **Configuration health checks** — `kairo doctor` validates provider setup, API keys, endpoints, and config format\n- **Old config migration** — detects and reports outdated v1.x config format\n- **Web dashboard auth** — `/login`, `/whoami`, `/logout` commands for website-integrated authentication\n- **Session syncing** — syncs CLI sessions to the Kairo website dashboard\n- **Docker support** — containerized runtime for portable execution\n- **CI/CD** — GitHub Actions pipeline with build, typecheck, and test\n\n---\n\n## Architecture\n\n```\nkairo/\n├── index.ts               # CLI entry point — routes commands (setup, doctor, --task, interactive)\n├── config/                # Configuration loading, saving, setup flow\n│   ├── configManager.ts   # Config read/write to ~/.terminal-agent/config.json\n│   ├── authManager.ts     # Auth session persistence (access/jwt tokens, user profile)\n│   └── setup.ts           # Interactive provider/model setup with pre-fill support\n├── core/                  # Agent loop, command routing, streaming, tool execution, safety\n│   ├── agentLoop.ts       # Interactive and non-interactive agent loops\n│   ├── cliCommands.ts     # Help, version, doctor commands\n│   ├── commandRouter.ts   # Routes /-prefixed internal commands (/help, /tools, /clear, /login, /whoami, /logout)\n│   ├── login.ts           # Device-code authentication flow via Kairo website\n│   ├── safety.ts          # Dangerous command patterns & protected file detection\n│   ├── streamHandler.ts   # Streaming response with tool call assembly from delta chunks\n│   ├── syncSessions.ts    # Pushes CLI sessions to the website dashboard API\n│   ├── toolExecutor.ts    # Tool execution with safety checks, spinner, and error handling\n│   └── types.ts           # TypeScript types for streaming deltas and tool calls\n├── prompt/                # System prompt defining agent behavior\n│   └── prompt.ts          # \"Shell Copilot\" system prompt with platform-aware instructions\n├── providers/             # Provider definitions and client initialization\n│   ├── getClient.ts       # OpenAI client creation from config\n│   └── providerMap.ts     # Provider definitions (base URLs, env vars, default models)\n├── runtime/               # Session persistence, execution/task/workspace state\n│   ├── executionState.ts\n│   ├── sessionManager.ts  # Persistent session with message serialization & trimming\n│   ├── taskState.ts\n│   └── workspaceState.ts\n├── tests/                 # Vitest test suite\n│   ├── agentLoop.test.ts\n│   ├── auth.test.ts       # Auth manager read/write/clear tests\n│   ├── config.test.ts     # Config write/read/validation\n│   ├── login.test.ts      # Login flow tests\n│   ├── registry.test.ts   # Tool registry schema generation\n│   ├── setup.test.ts      # Interactive setup with mocked inputs\n│   └── tools.test.ts      # Tool execution (read, list, time)\n├── tools/                 # Tool registry and individual tool implementations\n│   ├── registry.ts        # Zod-based tool registry with OpenAI schema generation\n│   ├── index.ts           # Registers all 13 tools\n│   ├── changeDirectory.ts\n│   ├── currentDirectory.ts\n│   ├── diffPreview.ts     # Unified diff generation via `diff` library\n│   ├── execCommand.ts     # PowerShell-based command execution (Windows-aware)\n│   ├── getTime.ts\n│   ├── gitDiff.ts\n│   ├── gitStatus.ts\n│   ├── listDirectory.ts   # Returns JSON with file names and types\n│   ├── readFile.ts\n│   ├── replaceInFile.ts   # Targeted text replacement with search validation\n│   ├── runScript.ts       # Runs package manager scripts (dev, build, test, lint)\n│   ├── searchText.ts      # Recursive text search with line-level context\n│   └── writeFile.ts       # File creation with directory auto-creation\n├── ui/                    # Terminal UI\n│   ├── book.ts            # Book-style layout: headers, code blocks, status bar, markdown renderer\n│   ├── mascot.ts          # 6-line ASCII mascot with moods + spinner + walk animation\n│   ├── render.ts          # Markdown rendering with marked-terminal\n│   └── ui.ts              # Banner, headers, input prompt, and colored output helpers\n├── scripts/               # Utilities\n│   └── e2e-test.mjs       # E2E test harness for the login flow\n├── demo/                  # Demo assets\n│   ├── diagram.png\n│   └── video.mp4\n├── tsconfig.json          # TypeScript config (ES2022, NodeNext module resolution)\n└── package.json           # pnpm-managed dependencies, bin entry point\n```\n\n---\n\n## Install\n\n### From npm\n\n```bash\nnpm install -g @abhilov/kairo\n```\n\n### From source\n\n```bash\npnpm install\npnpm build\n```\n\n---\n\n## Setup\n\n```bash\nkairo setup\n```\n\nYou'll be prompted to select a provider and configure the model.\n\n### Supported Providers\n\n| # | Provider  | Auth method                   | Default model                          |\n|---|-----------|-------------------------------|----------------------------------------|\n| 1 | OpenAI    | `OPENAI_API_KEY` env var      | `gpt-4o`                               |\n| 2 | Anthropic | `ANTHROPIC_API_KEY` env var   | `claude-sonnet-4-20250514`             |\n| 3 | Groq      | `GROQ_API_KEY` env var        | `llama-3.3-70b-versatile`              |\n| 4 | NVIDIA    | `NVIDIA_API_KEY` env var      | `meta/llama-3.3-70b-instruct`          |\n| 5 | Ollama    | No API key required (local)   | `llama3.2`                             |\n| 6 | Custom    | Set base URL, API key, model  | User-specified                         |\n\n### Configuration\n\nSetup saves your configuration to:\n\n```\n~/.terminal-agent/config.json\n```\n\nExample config:\n```json\n{\n  \"provider\": \"openai\",\n  \"model\": \"gpt-4o\"\n}\n```\n\nFor custom providers with optional base URL override:\n```json\n{\n  \"provider\": \"custom\",\n  \"baseURL\": \"https://api.example.com/v1\",\n  \"apiKey\": \"sk-custom-key\",\n  \"model\": \"gpt-4o\"\n}\n```\n\n### Config Health Check\n\n```bash\nkairo doctor\n```\n\nValidates:\n- Config file exists and is readable\n- Provider is recognized\n- API keys are set (env var or config value)\n- Base URL is valid (for custom providers)\n- Ollama endpoint is reachable (for Ollama provider)\n- Detects old v1.x config format and suggests re-configuration\n\n---\n\n## Run\n\n```bash\n# Interactive session\nkairo\n\n# Non-interactive task\nkairo --task \"show me the git log\"\n\n# Development mode (hot reload)\npnpm dev\n\n# Production build\npnpm build\npnpm start\n\n# Direct invocation from build output\nnode dist/index.js\n```\n\n---\n\n## CLI Commands\n\n| Command              | Description                                |\n|----------------------|--------------------------------------------|\n| `kairo`              | Start interactive assistant                |\n| `kairo setup`        | Configure provider and model               |\n| `kairo doctor`       | Run configuration health checks            |\n| `kairo help`         | Show CLI help                              |\n| `kairo version`      | Show CLI version                           |\n| `kairo --task <txt>` | Execute a single task non-interactively    |\n\n---\n\n## Internal Commands\n\n| Command      | Description                      |\n|--------------|----------------------------------|\n| `/help`      | Show interactive help and tools  |\n| `/tools`     | List available tools             |\n| `/clear`     | Clear conversation memory        |\n| `/login`     | Authenticate via Kairo website   |\n| `/whoami`    | Show current auth session        |\n| `/logout`    | Clear auth session               |\n| `clear`/`cls`| Clear terminal screen            |\n| `exit`       | Exit KairoCLI                    |\n\n---\n\n## Available Tools\n\n| Tool               | Description                              |\n|--------------------|------------------------------------------|\n| `get_time`         | Get current system date and time         |\n| `execute_command`  | Run a terminal command (PowerShell)      |\n| `current_directory`| Get current working directory            |\n| `list_directory`   | List files and folders (JSON output)     |\n| `read_file`        | Read file contents                       |\n| `search_text`      | Recursive text search with context       |\n| `change_directory` | Change working directory                 |\n| `write_file`       | Write text to a file (auto-creates dirs) |\n| `replace_in_file`  | Targeted text replacement in a file      |\n| `run_script`       | Run package manager scripts (`pnpm dev`) |\n| `git_status`       | Show git repository status               |\n| `git_diff`         | Show diff for modified files             |\n| `diff_preview`     | Show unified diff preview for changes    |\n\n---\n\n## Safety System\n\nKairoCLI includes a multi-layered safety system to prevent accidental damage:\n\n### Dangerous Command Detection\n\nCommands matching these patterns trigger an interactive confirmation prompt:\n\n| Category | Examples |\n|----------|----------|\n| **Destructive deletes** | `rm -rf`, `rmdir`, `del /s`, `remove-item -recurse`, `shred`, `dd` |\n| **System operations** | `format`, `shutdown`, `reboot`, `sudo`, `chown /`, `chmod /` |\n| **Git destructive** | `git reset --hard`, `git clean -f`, `git checkout --`, `git restore` |\n| **Windows system** | `bcdedit`, `cipher /w`, `takeown`, `icacls /grant`, `sp delete` |\n| **Linux/macOS system** | `killall`, `pkill`, `launchctl unload`, `systemctl stop` |\n\n### Protected Files\n\nWriting to these files requires confirmation:\n- `.env`\n- `package.json`\n- `pnpm-lock.yaml`\n\n### Confirmation Flow\n\nWhen a dangerous command or protected file is detected, KairoCLI displays the action and asks for confirmation (`y/n`). If declined, the tool returns a cancellation message and the agent continues.\n\n---\n\n## Agent Behavior\n\nThe agent runs as **Shell Copilot** with platform-aware instructions:\n\n- **Windows-aware** — prefers PowerShell-compatible commands, avoids bash-only syntax\n- **Tool-calling native** — uses native API tool-calling (no pseudo-code output); gathers context with read-only tools before writing files\n- **Response style** — concise, bullet-pointed instructions, code blocks for commands, natural conversational responses\n- **Prefer `run_script`** — uses `run_script` tool over `execute_command` for package manager workflows\n\n---\n\n## Runtime State\n\nKairoCLI persists sessions to disk so you can resume where you left off:\n\n```\n~/.terminal-agent/session.json\n```\n\nThe runtime tracks:\n\n- **Conversation messages** — up to 200 recent messages with history trimming and system prompt preservation\n- **Execution state** — turn count, last tool used, last error, last updated timestamp\n- **Task state** — current task, status (`idle` / `in_progress` / `blocked` / `done`)\n- **Workspace state** — current working directory\n\n---\n\n## Auth System\n\nKairoCLI supports device-code authentication via the Kairo website:\n\n```\n/login   — Opens browser for device-code pairing\n/whoami  — Shows current authenticated session details\n/logout  — Clears auth session locally and remotely\n```\n\nAuth sessions are stored in `~/.terminal-agent/auth.json`. Session data can be synced to the website dashboard for tracking.\n\n---\n\n## Scripts\n\n| Command          | Description                          |\n|------------------|--------------------------------------|\n| `pnpm build`     | Compile TypeScript to `dist/`        |\n| `pnpm dev`       | Run with hot reload via `tsx`        |\n| `pnpm start`     | Run compiled output from `dist/`     |\n| `pnpm test`      | Run Vitest test suite                |\n| `pnpm setup`     | Run the interactive setup flow       |\n| `pnpm format`    | Format code with Prettier            |\n\n---\n\n## Tech Stack\n\n- **TypeScript** (v6) — strict mode, ES2022 target, NodeNext module resolution\n- **OpenAI SDK** (v6) — streaming chat completions with tool calling\n- **Zod** (v4) — runtime parameter validation + JSON Schema generation via `zod-to-json-schema`\n- **Chalk** / **Boxen** — terminal styling and banners\n- **Marked** / **marked-terminal** — markdown rendering in the terminal\n- **Diff** — unified diff generation for diff previews\n- **Ora** — spinner UI during tool execution\n- **Dotenv** — environment variable loading from `.env`\n- **Vitest** (v4) — test runner\n- **Prettier** — code formatting\n- **pnpm** — package manager\n\n---\n\n## Tests\n\n```bash\npnpm test\n```\n\nThe test suite covers:\n- **Stream handler** — text-only responses, single/multiple tool call assembly from delta chunks, combined content + tool calls, empty streams\n- **Tool executor** — execution flow, cancellation via safety checks, error handling, multi-tool processing with partial failures\n- **Agent loop integration** — end-to-end text and tool call cycles\n- **Tool registry** — OpenAI schema generation, parameter validation, type coercion\n- **Config** — write/read with optional fields, custom providers, missing file handling\n- **Auth manager** — auth session save/load/clear\n- **Login flow** — device-code authentication flow tests\n- **Setup flow** — all providers, custom provider, invalid input, pre-fill from existing config, field overwrites, provider switching\n\n---\n\n## Docker\n\n```bash\ndocker build -t kairocli .\ndocker run -it kairocli\n```\n\n---\n\n## CI/CD\n\nGitHub Actions runs on every push and PR to `main`:\n\n- `pnpm install` (with caching)\n- `pnpm build`\n- `pnpm test`\n\n---\n\n## Repository\n\n- **GitHub:** https://github.com/abhilov23/KairoCLI\n- **npm:** https://www.npmjs.com/package/@abhilov/kairo\n","readmeFilename":"README.md"}