Your Digital Companion. Not a Tool. A Partner.
Self-hosted, asynchronous Telegram bot that orchestrates multiple AI providers, tools, and sub-agents to get real work done.

🌍 Read this in other languages:
Español • Português (Brasil) • Українська • Bahasa Indonesia • Türkçe • Русский • 日本語 • 繁體中文 • 简体中文

Chibi is built for the moment you realize you need more than “an AI tool.” You need a partner that can coordinate models, run work in the background, and integrate with your systems - without you babysitting prompts.

Chibi is an asynchronous, self-hosted Telegram-based digital companion that orchestrates multiple AI providers and tools to deliver outcomes: code changes, research syntheses, media generation, and operational tasks.

Why Chibi

• One interface (Telegram). Mobile/desktop/web, always with you.
• Provider-agnostic. Use the best model for each task - without vendor lock-in.
• Autonomous execution. Sub-agents work in parallel; long tasks run asynchronously.
• Tool-connected. Filesystem + terminal + MCP integrations (GitHub, browser, DBs, etc.).
• Self-hosted. Your data, your keys, your rules.

Supported AI providers (and endpoints)

Chibi supports multiple providers behind a single conversation. Add one key or many - Chibi can route per task.

LLM providers

• OpenAI (GPT models)
• Anthropic (Claude)
• Google (Gemini)
• DeepSeek
• Alibaba Cloud (Qwen)
• xAI (Grok)
• Mistral AI
• Moonshot AI
• MiniMax
• ZhipuAI (GLM models)
• OpenRouter (unified access to many models)
• Cloudflare Workers AI (many open-source models)

OpenAI-compatible endpoints (self-host / local)

• Ollama
• vLLM
• LM Studio
• Any OpenAI-compatible API

Multimodal providers (optional)

• Images: Google (Imagen, Nano Banana), OpenAI (DALL·E), Alibaba (Qwen Image), xAI (Grok Image), Wan, ZhipuAI (CogView), MiniMax
• Music: Suno
• Voice: ElevenLabs, MiniMax, OpenAI (Whisper)

Exact model availability depends on your configured provider keys and enabled features.

🚀 Quick Start (pip)

Install Chibi via pip and run it as a command-line application:

# Install the package
pip install chibi-bot

# Set up the agent (add API keys, update settings, etc)
chibi config

# Start the bot
chibi start

The bot will run as a background service. Use CLI commands to manage it.

CLI Commands

VS Code IDE client

Chibi can serve the VS Code extension over its versioned local JSONL protocol:

chibi ide --stdio

The command is intended to be started by the Chibi VS Code extension, not used interactively. Chibi owns the v1 IDE protocol and supports compatible clients that negotiate the same version. The stdio process writes protocol frames only to stdout and diagnostics to stderr. Existing Chibi command, tool, permission and moderation behavior remains authoritative; the IDE adds no tool policy layer.

See the extension repository for installation, VSIX release instructions, client troubleshooting and its supported Chibi version range.

🚀 Quick start (Docker)

Create docker-compose.yml:

version: '3.8'

services:
  chibi:
    image: pysergio/chibi:latest
    restart: unless-stopped
    environment:
      TELEGRAM_BOT_TOKEN: ${TELEGRAM_BOT_TOKEN}  # Required
      OPENAI_API_KEY: ${OPENAI_API_KEY}          # Or any other provider
      # Add more API keys as needed
    volumes:
      - chibi_data:/app/data

volumes:
  chibi_data: {}

1. Get a bot token from @BotFather

2. Put secrets into .env

3. Run:

docker-compose up -d

Next:

• Installation guide: https://chibi.bot/installation
• Configuration reference: https://chibi.bot/configuration

🔑 Getting API Keys

Each provider requires its own API key. Here are the direct links:

Major Providers:

• OpenAI (GPT, DALL·E): platform.openai.com/api-keys
• Anthropic (Claude): console.anthropic.com
• Google (Gemini, Nano Banana, Imagen, Voice): aistudio.google.com/apikey
• DeepSeek: platform.deepseek.com
• xAI (Grok): console.x.ai
• Alibaba (Qwen, Wan): modelstudio.console.alibabacloud.com
• Mistral AI: console.mistral.ai
• Moonshot (Kimi): platform.moonshot.cn
• MiniMax (Voice, MiniMax-M2.x): minimax.io
• ZhipuAI (GLM, CogView): z.ai/manage-apikey/apikey-list
• OpenRouter (unified access to many models): openrouter.ai/settings/keys
• Cloudflare Workers AI: dash.cloudflare.com/profile/api-tokens

Creative Tools:

• ElevenLabs (Voice): elevenlabs.io
• Suno (Music, unofficial): sunoapi.org

📖 Full guide with setup instructions: chibi.bot/guides/get-api-keys

Try this in the first 5 minutes

Paste these into Telegram after you deploy.

1. Planning + execution

Ask me 3 questions to clarify my goal, then propose a plan and execute step 1.

2. Parallel work (sub-agents)

Spawn 3 sub-agents: one to research options, one to draft a recommendation, one to list risks. Return a single decision.

3. Agent mode (tools)

Inspect the project files and summarize what this repo does. Then propose 5 improvements and open a checklist.

4. Background task

Start a background task: gather sources on X and deliver a synthesis in 30 minutes. Keep me updated.

What makes Chibi different

🎭 Multi-provider orchestration

Chibi can keep context while switching providers mid-thread, or choose the best model per step - balancing cost, capability, and speed.

🤖 Autonomous agent capabilities

• Recursive delegation: spawn sub-agents that can spawn their own sub-agents
• Background processing: long-running tasks execute asynchronously
• Filesystem access: read/write/search/organize files
• Terminal execution: run commands with LLM-moderated security
• Persistent memory: conversation history survives restarts with context management/summarization

🔌 Extensible via MCP (Model Context Protocol)

Connect Chibi to external tools and services (or build your own):

• GitHub (PRs, issues, code review)
• Browser automation
• Docker / cloud services
• Databases
• Creative tools (Blender, Figma)

If a tool can be exposed via MCP, Chibi can learn to use it.

🎨 Rich content generation

• Images: Nano Banana, Imagen, Qwen, Wan, DALL·E, Grok
• Music: Suno (including custom mode: style/lyrics/vocals)
• Voice: transcription + text-to-speech (ElevenLabs, MiniMax, OpenAI)

Use cases

Developers

You: “Run the tests and fix what’s broken. I’ll work on the frontend.”
Chibi: *spawns sub-agent, executes tests, analyzes failures, proposes fixes*

Researchers

You: “Research the latest developments in quantum computing. I need a synthesis by tomorrow.”
Chibi: *spawns multiple research agents, aggregates sources, delivers a report*

Creators

You: “Generate a cyberpunk cityscape and compose a synthwave track to match.”
Chibi: *generates an image, creates music, delivers both*

Teams

You: “Review this PR and update the documentation accordingly.”
Chibi: *analyzes changes, suggests improvements, updates docs via MCP*

Privacy, control, and safety

• Self-hosted: your data stays on your infrastructure
• Public Mode: users can bring their own API keys (no shared master key required)
• Access control: whitelist users/groups/models
• Storage options: local volumes, Redis, or DynamoDB
• Tool safety: agent tools are configurable; terminal execution is moderated and can be restricted

MAX_HISTORY_TOKENS — context summarization threshold (breaking default change)

MAX_HISTORY_TOKENS is the threshold at which Chibi auto-summarizes a conversation to keep context manageable. Its semantics changed: it now compares against the real, provider-reported prompt token count (the entire outgoing request: system prompt + activated skills + tool schemas + tool-call arguments + per-message structural overhead + conversation content) instead of the old heuristic that measured only conversation content + role. The real figure is ~4.8x larger than the old estimate for an identical conversation (see fix_context_size/context_size_accounting_analysis.md for the measured breakdown).

• Default re-based: 64000 -> 100000. The new value protects the smallest commonly-supported context window (128k tokens): 100000 is ~78% of a 128k window (so summarization fires before a 128k model overflows) and ~50% of a 200k window (leaving comfortable headroom). The old 64000 was a history-only estimate that was never hit before a real overflow, because the estimate under-counts Cyrillic ~2x and excludes the fixed per-turn overhead (system prompt ~3.7k, tool schemas ~6.8k, activated skills ~5.9k, user_info ~0.75–3k) — so a 128k model overflowed at ~128k real tokens while the heuristic still reported well under 64k.
• Migration: if you set MAX_HISTORY_TOKENS explicitly in your .env, your old value was tuned against the old history-only estimate and now compares against a truthful figure that is ~4.8x larger for the same conversation. Re-tune it to the ~100k scale (e.g. 64000 -> 100000) so summarization fires before your smallest model's context window overflows, not after. If you never set it, the new default applies automatically.
• The cold-start fallback (first turn after a process restart, when no provider data is cached yet) still uses the old heuristic so summarization remains functional.

REACTIVE_CONTEXT_RECOVERY — one-shot retry after context overflow

REACTIVE_CONTEXT_RECOVERY (default: true) is the reactive safety net that complements the proactive MAX_HISTORY_TOKENS threshold. When a provider rejects a request with a typed context_length_exceeded error, Chibi automatically summarizes the conversation history and retries the turn exactly once. If the retry succeeds, the user receives a normal answer (with a short note that context was compressed). If the retry overflows again or recovery fails for any reason, the turn falls back to the existing apology path — the summarization+retry loop can never run more than once per original turn. Set to false to disable reactive recovery and keep the pre-existing behavior (log + apology, no retry).

Working directory is thread-scoped (WORKING_DIR)

The agent's working directory - used for terminal commands and reported to the model as its current CWD - is thread-scoped, mirroring how the selected LLM model is bound per thread.

• Default: comes from the WORKING_DIR setting (default ~/chibi) through the legacy user-level value; fresh deployments inherit the setting directly.
• Per-thread override: any thread/conversation can override its working directory in isolation via the agent's set_working_dir tool (LLM-driven only - there is no slash command, available when FILESYSTEM_ACCESS is enabled). This lets two agents in different threads work on different projects simultaneously without interfering.
• Resolution order: thread override → legacy user-level directory → WORKING_DIR setting.
• Path normalization: values you set are expanded to absolute paths on save (~/x becomes /abs/x); untouched defaults keep their raw form.
• Sub-agents spawned within a thread share that thread's working directory - the same effective path is injected into their system prompts and tool calls.
• Overrides survive thread cloning: /new_thread_with_current_context carries the working directory over together with messages and model preferences.

Documentation

• Start here: https://chibi.bot
• Introduction & philosophy: https://chibi.bot/introduction
• Installation: https://chibi.bot/installation
• Configuration: https://chibi.bot/configuration
• Agent mode: https://chibi.bot/agent-mode
• MCP guide: https://chibi.bot/guides/mcp
• Support / troubleshooting: https://chibi.bot/support

System requirements

• Minimum: Raspberry Pi 4 / AWS EC2 t4g.nano (2 vCPU, 512MB RAM)
• Architectures: linux/amd64, linux/arm64
• Dependencies: Docker (and optionally Docker Compose)

Contributing

• Issues: https://github.com/s-nagaev/chibi/issues
• PRs: https://github.com/s-nagaev/chibi/pulls
• Discussions: https://github.com/s-nagaev/chibi/discussions

Please read CONTRIBUTING.md before submitting.

License

MIT - see LICENSE.

Ready to meet your digital companion?
Get Started →