Chikoo

Minimal WhatsApp agent for India with Hinglish support and learning capabilities.

Features

Core

WhatsApp Integration via Baileys (no business API needed)
Multi-Provider Support: Anthropic, OpenAI, Google Gemini, Ollama
Hinglish (Roman Hindi + English) by default
IST timezone awareness
Indian cultural context (festivals, expressions)

Media

Image Understanding: Vision APIs describe images sent to the agent
Voice Transcription: OpenAI Whisper transcribes voice messages
Media Captions: Combines image/caption for contextual responses

Conversation

Streaming Responses: Progressive message delivery with paragraph-aware chunking
Message Chunking: Auto-splits long responses (WhatsApp 4096 char limit)
Context Management: Token tracking with auto-summarization when near limit
Message Queue: Debouncing and concurrency control for rapid messages

Memory & Learning

File-based Memory: MEMORY.md stores remembered facts
Auto-Insights: Learns preferences from conversations
Daily Logs: Conversation history per day

Customization

Skill System: Extend capabilities with markdown-based skills
Persona Files: USER.md, SOUL.md, INSTRUCTIONS.md
Web Dashboard: Monitor and interact via browser

Installation

Requires Node.js 22 or newer.

From npm

npm install -g chikoo

From source

git clone https://github.com/AltSlate-Labs/chikoo.git
cd chikoo
npm install
npm run build
npm link

Quick Start

# 1. Set API key
chikoo config set apiKey sk-ant-...

# 2. Login to WhatsApp
chikoo login

# 3. Run the agent
chikoo run

# With dashboard
chikoo run --dashboard

Configuration

Provider Setup

# Anthropic (default)
chikoo config set provider anthropic
chikoo config set apiKey sk-ant-...

# OpenAI
chikoo config set provider openai
chikoo config set apiKey sk-...
chikoo config set model gpt-4o

# Google Gemini
chikoo config set provider google
chikoo config set apiKey AIza...
chikoo config set model gemini-2.0-flash

# Ollama (local)
chikoo config set provider ollama
chikoo config set baseUrl http://localhost:11434/v1
chikoo config set model llama3.2

# Groq (fast inference)
chikoo config set provider openai
chikoo config set baseUrl https://api.groq.com/openai/v1
chikoo config set apiKey gsk_...
chikoo config set model llama-3.3-70b-versatile

Streaming & Context

# Disable streaming (send full response at once)
chikoo config set streaming false

# Streaming chunk config
chikoo config set streamingConfig '{"minChars":200,"maxChars":1000,"idleMs":800}'

# Context window management
chikoo config set contextCompactThreshold 0.8  # Compact at 80% of limit
chikoo config set contextKeepRecent 6          # Keep 6 recent messages

Message Queue

chikoo config set queueDebounceMs 1000    # Wait 1s for rapid messages
chikoo config set queueMaxConcurrent 3    # Max parallel chats
chikoo config set queueMaxSize 5          # Max queue per chat

Access Control

# Allow only specific numbers
chikoo config set allowFrom '["+919876543210","+911234567890"]'

# Self-only mode (empty array)
chikoo config set allowFrom '[]'

# Allow all (default)
chikoo config set allowFrom '["*"]'

# Ignore groups
chikoo config set allowGroups false

# Only respond when @mentioned in groups
chikoo config set groupMentionOnly true

Transcription

# Use separate API key for Whisper
chikoo config set transcriptionApiKey sk-...

Runtime

# Disable daemon startup update checks
chikoo config set runtime.updateCheck false

# Check for updates at most once per hour (default: 3600)
chikoo config set runtime.updateCheckIntervalSec 3600

Commands

# Login
chikoo login

# Run agent
chikoo run [-v|--verbose] [-d|--dashboard [port]]

# Daemon lifecycle (always-on mode)
chikoo start [-v|--verbose] [-d|--dashboard [port]]
chikoo stop
chikoo restart [-v|--verbose] [-d|--dashboard [port]]
chikoo status

# Configuration
chikoo config set <key> <value>
chikoo config get <key>
chikoo config show

# Persona
chikoo init                    # Create default persona files
chikoo edit user|soul|instructions

# Skills
chikoo skills list
chikoo skills install <path>
chikoo skills create <name>

# Runtime logs (daemon stdout/stderr)
chikoo logs
chikoo logs --follow
chikoo logs --lines 200

# Memory logs
chikoo logs list
chikoo logs show [date]
chikoo logs insights
chikoo logs clear-insights

Skills

Skills are markdown files with YAML frontmatter that extend the agent's capabilities.

Bundled Skills

Skill	Description
Weather	Indian city weather forecasts
Cricket	Live scores and updates
Cooking	Indian recipes and cooking tips
Holidays	Indian festival dates
UPI	Payment assistance
Languages	Regional language help
Local Services	Find nearby services
Web Search	Up-to-date info from the web via search and page fetch
Apple Reminders	Manage macOS Reminders via `remindctl` (macOS-only; needs Reminders permission)

Note: Apple Reminders loads only on macOS when remindctl is on PATH (brew install steipete/tap/remindctl). The first run may prompt for Reminders access in macOS Privacy settings.

Skill Gating

Skills can declare requirements:

---
name: weather
description: Get weather forecasts
metadata: {"chikoo":{"os":["darwin","linux"],"requires":{"bins":["curl"],"env":["WEATHER_API_KEY"]}}}
---

Gate	Description
`os`	Platform filter
`requires.bins`	Required binaries
`requires.anyBins`	At least one required
`requires.env`	Required env vars
`requires.config`	Required config paths
`always`	Skip all gates

Skill Precedence

./skills/ (workspace - highest)
~/.chikoo/skills/ (user-installed)
Built-in skills

Persona Files

Customize your agent with persona files:

chikoo init              # Create default files
chikoo edit user         # Your details and preferences
chikoo edit soul         # Agent's personality
chikoo edit instructions # Custom rules

File	Purpose
`~/.chikoo/USER.md`	Your name, preferences, schedule, work context
`~/.chikoo/SOUL.md`	Agent's personality, communication style, values
`~/.chikoo/INSTRUCTIONS.md`	Custom rules and behaviors

Memory

Send "remember X" to save facts. Memory persists in ~/.chikoo/memory/MEMORY.md.

The agent also auto-learns insights from conversations, stored in INSIGHTS.md.

Dashboard

Run with --dashboard to enable the web UI:

chikoo run --dashboard 3000

Open http://localhost:3000 to:

Monitor WhatsApp connection status
View message history
Chat directly with the agent
Browse memory, insights, and logs
Monitor context window usage per conversation
View loaded skills and tools
Check configuration and persona

Architecture

See ARCHITECTURE.md for detailed system design.

Directory Structure

chikoo/
├── src/
│   ├── index.ts              # CLI entry
│   ├── agent/
│   │   ├── runner.ts         # Message processing + tool use
│   │   ├── conversation.ts   # Session/history + token tracking
│   │   ├── system-prompt.ts  # Indian-focused prompt
│   │   └── persona.ts        # Load USER/SOUL/INSTRUCTIONS
│   ├── providers/
│   │   ├── types.ts          # Provider interface
│   │   ├── anthropic.ts      # Claude integration
│   │   ├── openai.ts         # GPT + Ollama/Groq
│   │   ├── google.ts         # Gemini integration
│   │   └── index.ts          # Provider factory
│   ├── whatsapp/
│   │   ├── session.ts        # Baileys socket + auth
│   │   ├── monitor.ts        # Message listener + filtering
│   │   ├── send.ts           # Outbound messages
│   │   └── chunker.ts        # Message splitting
│   ├── media/
│   │   ├── download.ts       # WhatsApp media download
│   │   ├── image.ts          # Vision API integration
│   │   ├── audio.ts          # Whisper transcription
│   │   └── index.ts          # Media orchestration
│   ├── streaming/
│   │   ├── chunker.ts        # Paragraph-aware splitting
│   │   ├── coalescer.ts      # Chunk debouncing
│   │   └── index.ts          # Streaming utilities
│   ├── context/
│   │   ├── tracker.ts        # Token estimation
│   │   ├── compactor.ts      # Conversation summarization
│   │   └── index.ts          # Context management
│   ├── queue/
│   │   ├── chat-queue.ts     # Per-chat message queue
│   │   └── index.ts          # Queue exports
│   ├── skills/
│   │   ├── types.ts          # Skill types
│   │   ├── loader.ts         # Load skills
│   │   ├── gate.ts           # Skill gating
│   │   └── frontmatter.ts    # Parse frontmatter
│   ├── tools/
│   │   ├── registry.ts       # Tool registration
│   │   ├── executor.ts       # Tool execution
│   │   └── builtin/          # Built-in tools
│   ├── memory/
│   │   ├── store.ts          # File-based memory
│   │   ├── insights.ts       # Auto-learning
│   │   └── daily-log.ts      # Conversation logging
│   ├── web/
│   │   ├── server.ts         # Express server
│   │   ├── api.ts            # REST endpoints
│   │   ├── state.ts          # Dashboard state
│   │   └── public/           # Frontend assets
│   └── config/
│       ├── index.ts          # Config loading
│       └── paths.ts          # Path resolution
├── skills/                   # Bundled skills
└── ~/.chikoo/                # Runtime data
    ├── USER.md               # User details
    ├── SOUL.md               # Agent personality
    ├── INSTRUCTIONS.md       # Custom rules
    ├── config.json           # API keys, settings
    ├── auth/                 # WhatsApp credentials
    ├── skills/               # User-installed skills
    ├── memory/
    │   ├── MEMORY.md         # Remembered facts
    │   └── INSIGHTS.md       # Auto-learned insights
    ├── logs/                 # Daily conversation logs
    └── sessions/             # Conversation history

License

MIT

Name		Name	Last commit message	Last commit date
.vscode		.vscode
moltbot		moltbot
public/fonts		public/fonts
skills		skills
src		src
tools		tools
.gitignore		.gitignore
ARCHITECTURE.md		ARCHITECTURE.md
LICENSE		LICENSE
MANUAL-TESTING.md		MANUAL-TESTING.md
README.md		README.md
chikoo.png		chikoo.png
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository navigation

About

Repository files navigation

Chikoo

Features

Core

Media

Conversation

Memory & Learning

Customization

Installation

From npm

From source

Quick Start

Configuration

Provider Setup

Streaming & Context

Message Queue

Access Control

Transcription

Runtime

Commands

Skills

Bundled Skills

Skill Gating

Skill Precedence

Persona Files

Memory

Dashboard

Architecture

Directory Structure

License

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Chikoo

Features

Core

Media

Conversation

Memory & Learning

Customization

Installation

From npm

From source

Quick Start

Configuration

Provider Setup

Streaming & Context

Message Queue

Access Control

Transcription

Runtime

Commands

Skills

Bundled Skills

Skill Gating

Skill Precedence

Persona Files

Memory

Dashboard

Architecture

Directory Structure

License

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages