Kigo CLI (Node.js)

AI coding assistant for the terminal, built with Node.js and TypeScript

Kigo is a CLI-based AI coding assistant designed to bring agentic capabilities directly to your terminal. It integrates with multiple LLM providers, uses a tool system for file/shell/web tasks, and stores sessions locally for persistent context.

Built with a modular monorepo architecture, Kigo includes a CLI app, core agent/session logic, tool implementations, MCP client support, OAuth helpers, and an optional LSP server for editor integrations.

• Multi-Provider Support - OpenAI, Anthropic, Azure, plus OpenAI-compatible providers via base URL.
• Agentic Tooling - File editing, shell commands, directory listing, search, and web fetch/search tools.
• Persistent Sessions - SQLite-backed session storage with local history.
• MCP Integration - Extensible tool ecosystem support via the Model Context Protocol.
• Skills System - Load specialized knowledge on-demand via SKILL.md.
• LSP Server - Optional kigo lsp command to start a stdio language server.

pnpm add -g @kingiol/kigo-cli

npm install -g @kingiol/kigo-cli

For other installation methods, see docs/INSTALLATION.md.

# 1. Set your API key
export OPENAI_API_KEY="your-api-key"

# 2. Run Kigo
kigo

# Interactive mode
kigo

# Named session (persists conversation)
kigo -s my-project "help me implement a new feature"

# Use a different model
KIGO_MODEL="claude-opus-4-20250514" kigo "your prompt"

Single-prompt execution works in the CLI; interactive mode remains the primary workflow for multi-step tasks.

Interactive runs now include:

• Risk-based tool approvals with allow once, allow always, deny once, and deny always
• A gated plan workflow: /plan on → draft the plan (auto-saved) → /plan approve → /plan apply
• Project task graph commands: /task board|ready|create|show|history|claim|execute
• Task nodes now keep bounded execution summaries, so recent run state survives on the node itself

Kigo can be configured via (in priority order):

1. CLI arguments - Highest priority
2. Environment variables - KIGO_MODEL, KIGO_REASONING_EFFORT
3. Config file - ~/.kigo/config.yaml

model:
  name: "gpt-4o"
  provider: "openai"
  reasoningEffort: null

cli:
  session: null
  stream: true

mcpServers: []

skills:
  enabled: true
  projectSkillsDir: ".kigo/skills"
  userSkillsDir: "~/.kigo/skills"

kigo config show          # Show current config
kigo config path          # Show config file path
kigo config edit          # Edit config file
kigo config init          # Initialize config with defaults
kigo config set <key> <value>  # Set a config value
kigo auth login google    # OAuth login (Google)
kigo auth status          # Auth status
kigo mcp list             # List MCP servers
kigo lsp                  # Start LSP server (stdio)
/plan on                  # Enter read-only planning mode in the interactive CLI
/task history 12          # Show recent task events for task node #12
/task output 12           # Read the latest known execution summary for task node #12
/task resume 12           # Resume task node #12 even if its session run file is gone
/permissions show         # Show current runtime permission rules

Model Context Protocol (MCP) servers extend Kigo with additional tools.

# Add servers
kigo mcp add myserver "python -m my_mcp_server"
kigo mcp add myserver "python -m server" -e API_KEY=xxx

# HTTP/SSE transport
kigo mcp add webserver --transport http --url http://localhost:8000

# Manage servers
kigo mcp list
kigo mcp get myserver
kigo mcp remove myserver

mcpServers:
  - name: "filesystem"
    transportType: "stdio"
    command: "python"
    args: ["-m", "mcp.server.filesystem"]
    envVars:
      ROOT_PATH: "/home/user/projects"
    cacheToolsList: true
    allowedTools:
      - "read_file"
      - "write_file"

Skills provide specialized knowledge loaded on-demand, saving tokens via progressive disclosure.

Skills are loaded from (project skills take priority):

1. Project: .kigo/skills/
2. User: ~/.kigo/skills/

Create a SKILL.md with YAML frontmatter:

---
name: api-design
description: Best practices for designing RESTful APIs
allowed-tools:
  - read_file
  - write_file
---

# API Design Guidelines

## RESTful Principles

Use nouns for resources, HTTP verbs for actions...

kigo-node/
├── packages/
│   ├── core/         # Core framework
│   ├── tools/        # Built-in tools
│   ├── mcp/          # MCP client
│   ├── auth/         # OAuth authentication
│   └── lsp/          # LSP server
└── apps/
    └── cli/          # Main CLI application

git clone <this-repo>
cd kigo-node
pnpm install
pnpm build

pnpm lint              # Lint code
pnpm test              # Run tests

• API Keys: Stored in environment variables, never in code
• Local Storage: Sessions stored in ~/.kigo/
• No Telemetry: Only API requests to your chosen provider
• Shell Commands: Require explicit user confirmation

Contributions are welcome!

1. Fork the repository
2. Create a 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

MIT License - see LICENSE for details.

_{Built with TypeScript and curiosity}