mikan — multi-platform AI coding agent

# @geminixiang/mikan [![npm version](https://img.shields.io/npm/v/@geminixiang/mikan.svg)](https://www.npmjs.com/package/@geminixiang/mikan) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) A multi-platform AI coding agent for Slack, Telegram, and Discord. ## Architecture mikan keeps the chat record, agent session, and execution runtime separate: ![mikan architecture](src/content/docs/assets/architecture.png) - **Chat / conversation data** is the platform-facing record: `log.jsonl`, attachments, and conversation files. - **Session orchestration** turns platform events into agent runs, handles top-level/thread scopes, and persists pi-coding-agent structured context under `sessions/*.jsonl`. - **pi-coding-agent harness** runs the model loop and calls mikan tools. - **Sandbox runtime** is where tool commands execute: host, Docker container/image, Firecracker, or Cloudflare bridge. - **Vault** provides runtime credentials as env vars and mounted secret files. ## Features - **Multi-platform** — Slack, Telegram, Discord adapters - **Concurrent conversations** — Slack threads, Discord replies/threads, and Telegram reply chains run as independent sessions - **Sandbox execution** — host, shared container, per-user managed container, Firecracker (alpha), or Cloudflare bridge (experimental) - **Credential vaults** — `/login` stores credentials under `--state-dir` and injects env into sandbox runs - **Web session viewer** — read-only web view of the current session via `session` / `/session` - **Persistent memory** — workspace-level and channel-level `MEMORY.md` - **Skills** — drop CLI tools into `skills/` - **Events** — schedule one-shot or recurring tasks via JSON files - **Multi-provider** — any provider/model supported by `pi-ai` ## Requirements - Node.js >= 22.19.0 ## Installation ```bash npm install -g @geminixiang/mikan ``` Or from source: ```bash npm install && npm run build ``` ## Quick Start All platforms share the same CLI: ```bash mikan [--state-dir=~/.mikan] [--sandbox=] ``` Set the platform tokens you need; you can run multiple platforms at once: ```bash export SLACK_APP_TOKEN=xapp-... export SLACK_BOT_TOKEN=xoxb-... export TELEGRAM_BOT_TOKEN=123456:ABC-... export DISCORD_BOT_TOKEN=MTI... ``` ## Platforms - **Slack** — create a Socket Mode app using [src/content/docs/slack-bot-minimal-guide.md](src/content/docs/slack-bot-minimal-guide.md). The bot responds when `@mentioned` in channels and to all DMs. - **Telegram** — create a bot via [@BotFather](https://t.me/BotFather). The bot responds to private messages, `@mention`, and reply chains in groups. - **Discord** — create an application in the [Discord Developer Portal](https://discord.com/developers/applications), enable **Message Content Intent**, and invite it with message/file permissions. Slack threads, Discord replies/threads, and Telegram reply chains are mapped to independent session scopes. See [src/content/docs/sessions.md](src/content/docs/sessions.md). ## Sandbox | Mode | Description | | ---------------------------- | ---------------------------------------------------------------------- | | `host` (default) | Run on host; no vault env injection | | `container:` | Run in an existing shared container; uses vault key `container-` | | `image:` | Auto-provision one Docker container per resolved vault/user | | `firecracker::` | Firecracker microVM (alpha; not recommended) | | `cloudflare:` | Cloudflare Worker bridge (experimental; no auto workspace sync) | For routing, mounts, vault behavior, managed container details, and Firecracker/Cloudflare notes, see [src/content/docs/sandbox.md](src/content/docs/sandbox.md). ## Chat commands | Command | Purpose | | ---------------------------------------------------------- | ------------------------------------------------ | | `/login` / `/pi-login` | Store API keys or run built-in OAuth flows | | `session` / `/session` | Open a read-only web view of the current session | | `new` / `/new` | Reset the current session | | `model` / `/model` / `/pi-model provider/model[:thinking]` | Switch the LLM for the current conversation | | `auto-reply` / `/pi-auto-reply on\|off\|status` | Control group/channel auto-reply | | `stop` / `/stop` | Stop the current run | See [src/content/docs/commands.md](src/content/docs/commands.md) for command details and web session viewer setup. ## Configuration mikan reads global settings from `/settings.json`; per-conversation overrides live at `//settings.json`. ```json { "llm": { "provider": "anthropic", "model": "claude-sonnet-4-6", "thinkingLevel": "off" } } ``` See [src/content/docs/configuration.md](src/content/docs/configuration.md) for all fields. ## Data layout ```text / ├── settings.json └── vaults/ / ├── MEMORY.md ├── SYSTEM.md ├── skills/ ├── events/ └── / ├── log.jsonl ├── attachments/ ├── scratch/ ├── skills/ └── sessions/ ``` ## More docs - [Events](src/content/docs/events.md) - [Skills](src/content/docs/skills.md) - [Deployment](src/content/docs/deployment.md) - [Development](src/content/docs/development.md) - [Sandbox](src/content/docs/sandbox.md) ## Slack: Download channel history ```bash mikan --download C0123456789 ``` ## Development ```bash npm run dev npm test npm run lint npm run fmt:check npm run build ``` See [src/content/docs/development.md](src/content/docs/development.md) for E2E tests. ## Contributing PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for dev setup, commit style, and the testing checklist. Bug reports and feature requests go through the GitHub issue templates. ## License MIT — see [LICENSE](LICENSE).