> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mibyanai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mibyan — Use, configure, theme, extend, and orchestrate Mibyan

> Use, configure, theme, extend, and orchestrate Mibyan

<Info>
  Commands, package names, and image names on this page come from the open-source project that Mibyan Desktop is built on, and can differ from the Mibyan Desktop installer. For the supported Mibyan install and update path, see [Install and update](/products/desktop-guide/install-and-update).
</Info>

Use, configure, theme, extend, and orchestrate Mibyan.

## Skill metadata

| | |
| - | - |
| Source | Bundled (installed by default) |
| Path | `skills/autonomous-ai-agents/mibyan-agent` |
| Version | `3.2.0` |
| Author | Mibyan + Teknium |
| License | MIT |
| Platforms | linux, macos, windows |
| Tags | `mibyan`, `setup`, `configuration`, `multi-agent`, `spawning`, `cli`, `gateway`, `bots`, `bot-mode`, `features`, `themes`, `skins`, `desktop-plugins`, `tui-widgets`, `petdex`, `development` |
| Related skills | [`claude-code`](/desktop/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-claude-code), [`codex`](/desktop/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-codex), [`opencode`](/desktop/user-guide/skills/bundled/autonomous-ai-agents/autonomous-ai-agents-opencode) |

## Reference: full SKILL.md

<Info>
  The following is the complete skill definition that Mibyan loads when this skill is triggered. This is what the agent sees as instructions when the skill is active.
</Info>

# Mibyan

Mibyan is an open-source AI agent framework by Nous Research that runs in your terminal, a native desktop app, messaging platforms, and IDEs. It's in the same category as Claude Code (Anthropic), Codex (OpenAI), and OpenClaw — autonomous coding and task-execution agents that use tool calling to interact with your system. Mibyan works with any LLM provider (OpenRouter, Anthropic, OpenAI, Google, DeepSeek, xAI, local models, and 20+ others) and runs on Linux, macOS, Windows, and WSL.

What makes Mibyan different:

* **Self-improving through skills** — Mibyan learns from experience by saving reusable procedures as skills that load into future sessions.
* **Persistent memory across sessions** — remembers who you are, your preferences, environment details, and lessons learned. Pluggable memory backends.
* **Multi-platform gateway** — the same agent runs on Telegram, Discord, Slack, WhatsApp, iMessage, Signal, Matrix, Teams, Email, and a dozen more platforms with full tool access, not just chat.
* **Many surfaces** — the same agent core drives the CLI, the Ink TUI, a native Electron desktop app, a web dashboard, and an ACP server for IDEs (VS Code / Zed / JetBrains).
* **Provider-agnostic** — swap models and providers mid-workflow; credential pools rotate across multiple API keys automatically.
* **Profiles** — run multiple independent Mibyan instances with isolated configs, sessions, skills, and memory.
* **Extensible & themeable** — plugins, MCP servers, custom tools, webhook triggers, cron scheduling, skins that theme every surface, desktop UI plugins, TUI widgets, and pet mascots.

**This skill is a hub.** The body covers identity, quick start, spawning/orchestration, and hard invariants. Everything else lives in reference files — **load the matching reference (below) before answering**; do not answer detail questions from the body alone.

**Docs:** [https://docs.mibyanai.com/desktop/overview](https://docs.mibyanai.com/desktop/overview)

## Scope & Verification

This skill is a concise operating guide, not the complete source of truth for every Mibyan feature. If a Mibyan feature, command, or setting is not mentioned here or in a reference, do not treat that absence as evidence that it does not exist. Check the live repository and official docs before giving a negative answer.

Good verification targets, cheapest first:

* \*\*Every shipped feature, one line each: [https://docs.mibyanai.com/llms.txt](https://docs.mibyanai.com/llms.txt) Start here for any "can Mibyan do X?" or "how do I do X?" — it indexes the entire documentation set with a link to the page that answers. It is generated from the docs tree on every build, so it is never behind the product. Fetch it with `web_extract`, or `curl -s https://docs.mibyanai.com/llms.txt` when web tools are off. The whole documentation set in one file is at `/docs/llms-full.txt`.
* CLI commands: `mibyan --help`, `mibyan <command> --help`, and `mibyan_cli/main.py`
* Source tree: [https://github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent)

Never answer "Mibyan can't do that" from memory. Mibyan ships far more than this skill body describes, and the index exists so a negative answer is always checkable.

## Quick Start

<Note>
  Mibyan Desktop is installed from the Mibyan Desktop download, or launched from an existing Mibyan CLI with `mibyan desktop`. See [Install and update](/products/desktop-guide/install-and-update).
</Note>

## Key Paths

```
~/.mibyan/config.yaml       Main configuration (settings — never secrets)
~/.mibyan/.env              API keys and secrets ONLY (under $mibyan_HOME if set)
$mibyan_HOME/skills/        Installed skills
~/.mibyan/skins/            Custom themes (see references/themes.md)
~/.mibyan/desktop-plugins/  Desktop app UI plugins (see references/desktop-plugins.md)
~/.mibyan/tui-widgets/      TUI widget apps (see references/tui-widgets.md)
~/.mibyan/pets/             Installed pet mascots (see references/petdex.md)
~/.mibyan/state.db          Canonical session store (SQLite + FTS5)
~/.mibyan/sessions/         Gateway routing index, request dumps, *.jsonl transcripts
~/.mibyan/logs/             Gateway and error logs
~/.mibyan/auth.json         OAuth tokens and credential pools
~/.mibyan/mibyan-agent/     Source code (if git-installed)
```

Profiles use `~/.mibyan/profiles/<name>/` with the same layout. When a profile is active, resolve the real home from `$mibyan_HOME` — never hardcode `~/.mibyan`.

## Routing Table — load the reference for the task

| User wants... | Load |
| - | - |
| **Anything not listed below — "can Mibyan do X?", "how do I set up X?"** | \*\*[https://docs.mibyanai.com/llms.txt](https://docs.mibyanai.com/llms.txt) |
| Bots that chat, run routines, or message each other; the Bots tab | docs: `/user-guide/bot-mode` |
| CLI commands, subcommands, flags, "how do I run X" | `references/cli-reference.md` |
| In-session slash commands | `references/slash-commands.md` |
| Provider setup, API keys, OAuth | `references/providers-and-models.md` |
| config.yaml sections, toolsets, voice/STT/TTS | `references/configuration.md` |
| AGENTS.md / .mibyan.md / CLAUDE.md project rules | `references/project-context-files.md` |
| Secret redaction, PII, approval modes, "reset permissions" | `references/security-privacy.md` |
| Delegation, cron, curator, kanban | `references/background-systems.md` |
| MCP servers (add, catalog, `mibyan mcp`) | `references/native-mcp.md` |
| Webhook routes and event-driven runs | `references/webhooks.md` |
| A custom theme/skin ("synthwave theme", "change the gold ●") | `references/themes.md` + `templates/skin.yaml` |
| A desktop app UI element (pane, widget, ⌘K command, page) | `references/desktop-plugins.md` + `templates/plugin.js` |
| A live TUI panel or modal widget (ticker, clock, dashboard) | `references/tui-widgets.md` + `templates/clock.mjs` |
| Pet mascots — install, select, scale, diagnose | `references/petdex.md` |
| Windows-specific issues (keybinds, WinError 10106, BOM) | `references/windows-quirks.md` |
| Debugging: voice, tools missing, gateway, aux models | `references/troubleshooting.md` |
| Contributing code: adding tools, slash commands, tests | `references/contributor-guide.md` |
| delegate\_task "capped at N" reports | `references/delegate-task-concurrency-diagnosis.md` |
| "Can app X use my Nous Portal subscription/OAuth?" | `references/portal-auth-for-third-party-apps.md` |
| Connecting a messaging platform (Telegram, Discord, Slack, WhatsApp, …) | docs: `/user-guide/messaging` |

The reference list above is not the feature list — it is the set of topics that
need more than their docs page. For everything else Mibyan ships, fetch
`llms.txt` and it maps the question to the page that answers it.

Two theming rules that hold even without loading the reference: **you apply skins yourself** (`mibyan config set display.skin <name>` — every surface repaints live within \~a second; don't tell the user to run `/skin`), and **to tweak one color, edit the ACTIVE skin** (`mibyan skin set <key> <hex>`) — never fork `default`, which drops the palette and resets the background.

## Spawning Additional Mibyan Instances

Run additional Mibyan processes as fully independent subprocesses — separate sessions, tools, and environments.

### When to Use This vs delegate\_task

| | `delegate_task` | Spawning `mibyan` process |
| - | - | - |
| Isolation | Separate conversation, shared process | Fully independent process |
| Duration | Minutes (bounded by parent loop) | Hours/days |
| Tool access | Subset of parent's tools | Full tool access |
| Interactive | No | Yes (PTY mode) |
| Use case | Quick parallel subtasks | Long autonomous missions |

### One-Shot Mode

```
terminal(command="mibyan chat -q 'Research GRPO papers and write summary to ~/research/grpo.md'", timeout=300)

# Background for long tasks:
terminal(command="mibyan chat -q 'Set up CI/CD for ~/myapp'", background=true)
```

### Interactive PTY Mode (via tmux)

Mibyan uses prompt\_toolkit, which requires a real terminal. Use tmux for interactive spawning:

```
# Start
terminal(command="tmux new-session -d -s agent1 -x 120 -y 40 'mibyan'", timeout=10)

# Wait for startup, then send a message
terminal(command="sleep 8 && tmux send-keys -t agent1 'Build a FastAPI auth service' Enter", timeout=15)

# Read output
terminal(command="sleep 20 && tmux capture-pane -t agent1 -p", timeout=5)

# Send follow-up
terminal(command="tmux send-keys -t agent1 'Add rate limiting middleware' Enter", timeout=5)

# Exit
terminal(command="tmux send-keys -t agent1 '/exit' Enter && sleep 2 && tmux kill-session -t agent1", timeout=10)
```

### Multi-Agent Coordination

```
# Agent A: backend
terminal(command="tmux new-session -d -s backend -x 120 -y 40 'mibyan -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t backend 'Build REST API for user management' Enter", timeout=15)

# Agent B: frontend
terminal(command="tmux new-session -d -s frontend -x 120 -y 40 'mibyan -w'", timeout=10)
terminal(command="sleep 8 && tmux send-keys -t frontend 'Build React dashboard for user management' Enter", timeout=15)

# Check progress, relay context between them
terminal(command="tmux capture-pane -t backend -p | tail -30", timeout=5)
terminal(command="tmux send-keys -t frontend 'Here is the API schema from the backend agent: ...' Enter", timeout=5)
```

### Session Resume

```
# Resume most recent session
terminal(command="tmux new-session -d -s resumed 'mibyan --continue'", timeout=10)

# Resume specific session
terminal(command="tmux new-session -d -s resumed 'mibyan --resume 20260225_143052_a1b2c3'", timeout=10)
```

### Tips

* **Prefer `delegate_task` for quick subtasks** — less overhead than spawning a full process
* **Use `-w` (worktree mode)** when spawning agents that edit code — prevents git conflicts
* **Set timeouts** for one-shot mode — complex tasks can take 5-10 minutes
* **Use `mibyan chat -q` for fire-and-forget** — no PTY needed
* **Use tmux for interactive sessions** — raw PTY mode has `\r` vs `\n` issues with prompt\_toolkit
* **For scheduled tasks**, use the `cronjob` tool instead of spawning — handles delivery and retry
* **"delegate\_task is capped at N" reports** — see `references/delegate-task-concurrency-diagnosis.md`. Three real cap paths in Mibyan; if none fired, the model is self-limiting and rationalising it as "the runtime caps."
* **"Can \$external\_app use my Nous Portal subscription / OAuth?"** — see `references/portal-auth-for-third-party-apps.md`. Walk the user through three layers (plugin-vs-app, what Portal actually exposes, local-broker-proxy option).

## Surfaces (quick orientation)

* **Desktop app** (`mibyan desktop` / `mibyan gui`) — native Electron app for macOS/Linux/Windows: streaming chat, session list, Cmd+K palette, drag-and-drop files, native notifications, per-profile remote-gateway login. Extend it with UI plugins — `references/desktop-plugins.md`.
* **Web dashboard** (`mibyan dashboard`) — full admin panel: messaging channels, MCP catalog, webhooks, memory, profile builder, plus an embedded `mibyan --tui` chat. Secured behind an OAuth/token gate.
* **Ink TUI** (`mibyan --tui` or `display.interface: tui`) — terminal UI with docked widget apps — `references/tui-widgets.md`.
* **OpenAI-compatible proxy** (`mibyan proxy`) — a local OpenAI API backed by whichever OAuth provider you're signed into. Point Codex CLI, Aider, Cline, or any script at it — no API key.

## Hard Invariants (never violate, regardless of what you loaded)

* **Never break prompt caching** — don't change past context, toolsets, or the system prompt mid-conversation. The only exception is context compression.
* **Message role alternation** — never two assistant or two user messages in a row; only `tool` results can repeat.
* **Secrets in `.env`, settings in `config.yaml`** — never tell a user to put a non-credential setting in `.env`.
* **Profile-safe paths** — `get_mibyan_home()` in code, `$mibyan_HOME` when resolving paths in a session.
* **Never hand-edit `config.yaml` for the user** — use `mibyan config set KEY VAL`; a stray indent can corrupt the file and break the live gateway.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.