mikan

A multi-platform AI coding agent for Slack, Telegram, and Discord.

Architecture

mikan keeps the chat record, agent session, and execution runtime separate:

• 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

npm install -g @geminixiang/mikan

Or from source:

npm install && npm run build

Quick Start

All platforms share the same CLI:

mikan [--state-dir=~/.mikan] [--sandbox=<mode>] <working-directory>

Set the platform tokens you need; you can run multiple platforms at once:

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 docs/slack-bot-minimal-guide.md. The bot responds when @mentioned in channels and to all DMs.
• Telegram — create a bot via @BotFather. The bot responds to private messages, @mention, and reply chains in groups.
• Discord — create an application in the Discord Developer Portal, 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 docs/sessions.md.

Sandbox

| Mode | Description | | ---------------------------- | ---------------------------------------------------------------------- | | host (default) | Run on host; no vault env injection | | container:<name> | Run in an existing shared container; uses vault key container-<name> | | image:<image> | Auto-provision one Docker container per resolved vault/user | | firecracker:<vm-id>:<path> | Firecracker microVM (alpha; not recommended) | | cloudflare:<sandbox-id> | Cloudflare Worker bridge (experimental; no auto workspace sync) |

For routing, mounts, vault behavior, managed container details, and Firecracker/Cloudflare notes, see 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 docs/commands.md for command details and web session viewer setup.

Configuration

mikan reads global settings from <state-dir>/settings.json; per-conversation overrides live at <working-directory>/<conversationId>/settings.json.

{
  "llm": {
    "provider": "anthropic",
    "model": "claude-sonnet-4-6",
    "thinkingLevel": "off"
  }
}

See docs/configuration.md for all fields.

Data layout

<state-dir>/
├── settings.json
└── vaults/

<working-directory>/
├── MEMORY.md
├── SYSTEM.md
├── skills/
├── events/
└── <conversation-id>/
    ├── log.jsonl
    ├── attachments/
    ├── scratch/
    ├── skills/
    └── sessions/

More docs

• Events
• Skills
• Deployment
• Development
• Sandbox

Slack: Download channel history

mikan --download C0123456789

Development

npm run dev
npm test
npm run lint
npm run fmt:check
npm run build

See docs/development.md for E2E tests.

Contributing

PRs welcome — see 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.