ikie

Agentic coding CLI — your AI pair programmer in the terminal.

ikie is a TypeScript/Node.js CLI that reads, writes, and refactors code, runs commands, searches the web, and drives multi-step engineering tasks autonomously via an OpenAI-compatible API. It features a polished interactive REPL, one-shot mode, a skills system, MCP protocol support, TF-IDF code retrieval, and 7 color themes.

npm install -g ikie-cli
ikie login
ikie "add input validation to src/api/users.ts and write tests"

Project structure

src/
  index.ts           Entry point — CLI arg parsing, config load, dispatch
  agent.ts           Core agent loop — model calls, tool orchestration, plan/agent mode
  repl.ts            Interactive REPL — slash commands, model/theme pickers, session mgmt
  tools.ts           28+ tool implementations — read/write/edit files, bash, git, web, grep
  config.ts          Global (~/.ikie/config.json) + project-level (.ikie.json) config
  context.ts         Project context detection — git, manifests, README, instructions
  skills.ts          Skills system — discover, install (git/path), remove, render
  mcp-manager.ts     MCP client — stdio/HTTP/SSE transports, JSON-RPC, server lifecycle
  renderer.ts        Markdown renderer — syntax highlighting, tables, code blocks
  theme.ts           7 color themes, banner, prompt header, spinner, diff rendering
  memory.ts          Persistent memory — project (./.ikie/memory.md) and global (~/.ikie/memory.md)
  attachments.ts     Image handling — clipboard (cross-platform) and file-based
  auth.ts            Device-code OAuth login against the hosted API
  onboarding.ts      First-time onboarding flow (3-step tutorial)
  tree.ts            File tree visualization (/tree command)
  utils.ts           Token estimation (char-based heuristic), project root detection
  utils/
    retriever.ts     TF-IDF code retrieval — chunking, tokenization, cosine similarity search
mcps/
  github-server.js   Example MCP GitHub server
  filesystem-server.js Example MCP filesystem server
dist/                Compiled output (tsc)

Architecture

The entry point (index.ts) loads config, detects project context, discovers skills, builds a system prompt, then hands control to the REPL (repl.ts). The REPL creates an Agent instance (agent.ts) which manages the conversation loop.

index.ts → loadConfig → detectProjectContext → discoverSkills → buildSystemPrompt → startREPL
                                                                                          ↓
                                                                                     Agent.send()
                                                                                          ↓
                                                                                   callModel() ──→ streaming/non-streaming API
                                                                                          ↓
                                                                                  executeTool() ──→ read/write/bash/git/web/etc.
                                                                                          ↓
                                                                                   result → conversation.push → feedback loop

Agent loop (agent.ts)

The Agent class manages:

• Conversation history — array of ChatCompletionMessageParam with dangling-tool-call repair
• Two modes — plan (read-only, filtered toolset) and agent (full access)
• Streaming API — calls model with stream: true, accumulates text + tool calls
• Tool grouping — consecutive same-name tool calls execute as a batch with a single permission prompt
• Reflection — when edits fail, feeds the error back for up to 3 retries
• Self-healing — runs testCommand from .ikie.json after mutating edits and retries on failure
• Stepped execution — per-turn step budget (DEFAULT_MAX_STEPS = 60) prevents runaway loops
• Rate limiting — configurable requests-per-minute throttle
• Retry with backoff — transient failures (5xx, 429, network) retry up to 2× with exponential backoff

Tool system (tools.ts)

Each tool is defined as an OpenAI ChatCompletionTool with a JSON schema. executeTool dispatches by name:

| Category | Tools | |----------|-------| | File | read_file, write_file, edit_file (with whitespace-normalized + ... elision matching) | | Search | search_files (glob), grep (regex) | | Shell | bash (with interactive, streaming, session-based, and background modes) | | Git | git_status, git_diff, git_log, git_commit, git_branch | | Web | fetch_url (HTML→text), web_search | | Memory | memory_write | | Skills | use_skill, install_skill, remove_skill | | MCP | mcp_list, mcp_add | | Meta | switch_mode, ask_user, update_plan |

Safety: Mutating tools (bash, write_file, edit_file) require permission. Reading credential files (.env, .ssh, keys) prompts first. Commands targeting ikie's own port get an extra warning.

MCP client (mcp-manager.ts)

Implements the Model Context Protocol with three transport clients:

• StdioClient — spawns a subprocess, JSON-RPC over stdin/stdout
• HttpClient — HTTP POST with optional SSE response streaming
• SseClient — SSE event stream for endpoint discovery, then HTTP POST

Config loaded from three scopes (user → project → local), merged with mergeScopes.

Skills system (skills.ts)

Compatible with Claude Code skill format. Skills are directories containing SKILL.md with YAML frontmatter (name, description, allowed-tools, etc.). Discovered from .ikie/skills/ and .claude/skills/ (both project-level and user-level). Skills can be installed from git URLs or local paths.

Smart retrieval (utils/retriever.ts)

TF-IDF based code retrieval that:

1. Scans project files (text extensions only, excluding binaries and common build dirs)
2. Chunks files at blank-line boundaries (target 45 lines, range 12-80)
3. Tokenizes with camelCase/PascalCase/snake_case splitting
4. Indexes with TF-IDF vectors and cosine similarity scoring
5. Returns top matching chunks as XML context for the model

Configuration (config.ts)

| File | Scope | |------|-------| | ~/.ikie/config.json | Global user config (model, theme, API key, rate limits) | | .ikie.json | Project-level config (testCommand, autoTest, smartRetrieval) |

Theme system (theme.ts)

7 themes: nebula, cyberpunk, dracula, forest, slate, amber, aurora. Each defines colors for primary/secondary/accent/success/error/warning/info/muted, plus banner art and gradient colors. Active theme persisted to config.

Development

# Install dependencies
npm install

# Run in development mode (with tsx hot-reload)
npm run dev

# Build
npm run build

# Run tests
npm test

# Start compiled version
npm start

Requirements

• Node.js 20+
• An ikie account (npm install -g ikie-cli && ikie login), or a compatible OpenAI API endpoint

Commands

| Script | Description | |--------|-------------| | npm run build | tsc — compile to dist/ | | npm run dev | tsx src/index.ts — run directly with tsx | | npm start | node dist/index.js — run compiled output | | npm test | Run test files with node --import tsx |

Key design decisions

• OpenAI SDK as the provider-agnostic API layer (works with any OpenAI-compatible endpoint)
• edit_file with fuzzy matching — tries exact match → whitespace-normalized → ... elision, reducing retries
• No BPE tokenizer dependency — char-based heuristic (4 chars/token prose, 3 chars/token code) keeps the install lean
• Dangling tool call repair — guarantees conversation history is always replayable, even after cancellation
• Fail-fast for mutating batches — if a write/edit in a batch fails, subsequent ops are skipped to prevent inconsistent state
• Built-in MCP vs subprocess — MCP clients run in-process (no CLI subprocess), with config file scoping

License

MIT — see LICENSE.