A multi-platform AI coding agent for Slack, Telegram, Discord, and GitHub.
Warning
Pre-1.0 status — the overall framework stabilizes at 1.0.0. Until then, releases may change settings and on-disk data formats without migrations: upgrading between pre-1.0 versions can require resetting or manually adjusting existing state and workspace data.
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 structured context under
sessions/*.jsonl. - mikan agent harness (
src/harness/, built on pi-agent-core and pi-ai) runs the model loop, session persistence, compaction, and calls mikan tools. - Sandbox runtime is where tool commands execute: host, Docker container/image, local Gondolin microVM, Firecracker, or Cloudflare bridge.
- Vault provides runtime credentials as env vars and mounted secret files.
- Multi-platform — Slack, Telegram, Discord, and GitHub 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 —
/loginstores credentials under--state-dirand 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
- Node.js >= 22.19.0
npm install -g @geminixiang/mikanOr from source:
npm install && npm run buildRun mikan under PM2 so it stays up, restarts after failures, and starts on boot:
npm i -g @geminixiang/mikan pm2
# One-time setup: create the state directory and settings
mikan --onboard --state-dir=~/.mikan
# Secrets live in ~/.mikan/mikan.env (0600), outside any repo tree
curl -o ~/.mikan/mikan.env https://raw.githubusercontent.com/geminixiang/mikan/main/deploy/pm2/mikan.env.example
chmod 600 ~/.mikan/mikan.env # then fill in your tokens
# Grab the maintained ecosystem file (supervision only), edit `args`
curl -O https://raw.githubusercontent.com/geminixiang/mikan/main/deploy/pm2/ecosystem.config.cjs
pm2 start ecosystem.config.cjs
pm2 save
pm2 startup # run the printed command to enable boot autostartEach file has one job: settings.json holds behavior (model, sandbox limits, reply modes — the Admin surface), ~/.mikan/mikan.env holds secrets and platform tokens, and ecosystem.config.cjs holds process supervision only. In ecosystem.config.cjs, point args at your state dir, sandbox mode, and working directory (mikan --help documents the flags):
args: "--state-dir=/srv/mikan/state --sandbox=host /srv/mikan/workspace",Set the platform tokens you need in ~/.mikan/mikan.env; you can run multiple platforms at once. mikan env prints the full inventory and what is currently set:
SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
TELEGRAM_BOT_TOKEN=123456:ABC-...
DISCORD_BOT_TOKEN=MTI...Tail logs with pm2 logs mikan; upgrade with npm i -g @geminixiang/mikan && pm2 reload mikan. See the deployment guide for sandbox images, graceful shutdown, and the health endpoint.
For a one-off foreground run, the same CLI works directly:
mikan [--state-dir=~/.mikan] [--sandbox=<mode>] [<working-directory>]The working directory is optional: it defaults to <state-dir>/workspace (so ~/.mikan/workspace with the default state dir) and is created on first run.
- Slack — create a Socket Mode app using src/content/docs/slack-bot-minimal-guide.md. The bot responds when
@mentionedin 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 src/content/docs/sessions.mdx.
| 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 src/content/docs/sandbox.mdx.
| 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 / /pi-new |
Reset the current session |
/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 (works on every platform) |
session is the only command accepted without a leading slash. See src/content/docs/commands.mdx for the full command reference and web session viewer setup.
mikan reads global settings from <state-dir>/settings.json; host-only per-conversation overrides live at <state-dir>/conversations/<conversationId>/settings.json. Legacy workspace settings are migrated once, then ignored.
{
"llm": {
"provider": "anthropic",
"model": "claude-sonnet-4-6",
"thinkingLevel": "off"
}
}See src/content/docs/configuration.md for all fields.
<state-dir>/
├── settings.json
├── conversations/
│ └── <conversation-id>/
│ └── settings.json
└── vaults/
<working-directory>/
├── MEMORY.md
├── SYSTEM.md
├── skills/
├── events/
└── <conversation-id>/
├── log.jsonl
├── attachments/
├── scratch/
├── skills/
└── sessions/
mikan --download C0123456789npm run dev
npm test
npm run lint
npm run fmt:check
npm run buildSee src/content/docs/development.md for E2E tests.
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.
MIT — see LICENSE.