> ## 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.
# Chat and projects
> Sessions, projects and worktrees, the composer, attachments, voice, models, approvals, checkpoints, and everything that happens inside a conversation
This page follows a conversation from the sidebar to the composer to the answer, and everything in between.
## Sessions
Every conversation is a **session**. The left sidebar lists them, and the same history is shared with every other Mibyan surface.
### Find and organize
| To do this | Do this |
| - | - |
| Start a chat | **New chat**, or `Cmd`/`Ctrl` with `N`. `T` opens a new tab, `Shift` with `N` a new window |
| Search chats | The search box, or `Cmd`/`Ctrl` with `Shift` and `F`. The titlebar search also finds views and actions |
| Pin a chat | **Pin**, or `Shift`-click the chat. Pinned chats stay at the top and are never auto-archived |
| Switch quickly | `Ctrl` with `1` to `9` jumps to a recent session; `Ctrl` with `Tab` cycles |
| Group by project | Toggle **Group by workspace** to see chats under their project, or as one list |
| Mark read or unread | From the row menu, or **Mark all as read** |
Chats are divided by date (earlier today, yesterday, earlier this week, last week, earlier this month) and by status (**Working** and **Done**). A row tells you what is happening without opening it:
| Row state | Meaning |
| - | - |
| Session running | The agent is working now |
| Needs your input | It is waiting for an answer or an approval |
| Finished, unread | A turn finished while you were elsewhere |
| Background task running | A backgrounded command is still going |
| Draft | Nothing has been sent yet |
| Handed off from a platform | The chat began on Telegram, Slack, or another channel |
| Profile | Which [profile](/products/desktop-guide/connections-and-profiles#profiles) owns it |
The row menu also offers **Copy ID**, **Export**, **Branch**, **Rename**, **Archive**, **New window**, **Open in terminal**, **Open in new tab**, and **Open in split**.
### Archive, delete, and clean up
* **Archive** hides a chat from the sidebar and keeps every message. `Ctrl` or `Cmd`-click a chat to archive it. Restore it from **Settings, Archived Chats**.
* **Auto-archive stale chats** archives chats you have not touched for a number of days you choose. Pinned chats are never archived and nothing is deleted.
* **Delete** removes a chat permanently and cannot be undone. It always asks first.
## Chat mode and Dev mode
For thinking, questions, drafting, and research. No project is needed.
For work on files. Pick a project and the agent reads, edits, runs, and previews inside it.
The Dev start screen shows **Recent projects**, **Open project**, **New project**, and **Terminal**.
## Projects
A **project** is a named workspace of one or more folders. Chats can belong to a project, so the agent works in the right place.
Choose **New project** to name a workspace and add folders, or **Open folder as project** (`Cmd`/`Ctrl` with `O`) to use a folder you already have.
A project can hold several folders. One is marked **primary**, and new chats start there.
The **Idea** field saves to `IDEA.md` in the project. **Generate idea** drafts one for you, and **Shuffle templates** offers starting points.
Use **New chat in this project**, or drag existing chats into it with **Move to project**.
From a project's menu you can rename it, give it a color, add a folder, set it active, or delete it. Deleting removes only the saved project from Mibyan. **Your files, git repositories, and worktrees stay untouched.**
### Worktrees and branches
Worktrees let the agent work on a branch without disturbing your current checkout.
| Action | What it does |
| - | - |
| **New worktree** (`Cmd`/`Ctrl` with `Shift` and `B`) | Name a branch and pick the base branch to branch off |
| **Convert a branch** | Open branches already checked out, create a worktree for a free branch, or track a remote branch |
| **Remove worktree** | Removes the worktree directory from git (the branch stays), or just hides the lane from the sidebar and leaves it on disk |
| **Force remove** | Needed when the worktree has uncommitted changes. It discards them |
Over a remote connection, worktrees and project creation need an up-to-date backend. The app tells you when yours is older.
### Built-in database tools for Dev projects
Dev projects include a **Database** view:
* **Local database (SQLite).** Create a project database or add an existing `.db` file. Browse the schema, run queries (read-only, limited to 200 rows), and write **migrations**: you review the impact first, Mibyan makes an automatic backup, and destructive changes get an extra confirmation.
* **Your Supabase project.** Enter the project URL and the publishable key. The key is kept in secure device storage. The browser is read-only, shows up to 100 rows allowed by your Supabase policies, and never needs a `service_role` key.
Switching data source does not move or delete your data.
## The composer
The composer is the box at the bottom. Type a request and send it. `Enter` sends and `Shift` with `Enter` adds a new line.
### Give it context
| Way | What happens |
| - | - |
| **Files, Folder, Images** | Attach from the attach menu or by dragging files in |
| **Paste image** | Paste from the clipboard |
| **URL** | Mibyan fetches the page and includes it as context for that turn |
| **`@` mention** | Reference files, folders, URLs, and git inline while you type |
| **Drop a chat** | Drop another chat on the composer to link it |
| **Prompt snippets** | Starter prompts: Code review, Implementation plan, Explain this |
Slash commands start with `/` and open a palette. See [Shortcuts and commands](/products/desktop-guide/shortcuts-and-commands).
### Suggestions that appear as you type
The composer offers one-click chips when your words suggest something:
* **Add an MCP server** when you mention a service, such as connecting a tool your message needs.
* **Use a skill** when you mention one by name.
* **Set up GitHub** if you mention it and are not signed in.
* **Reconnect a server** right after a tool fails with a connection error.
* **Schedule this** when something sounds recurring, so it becomes a scheduled job instead.
### While the agent is working
| Control | What it does |
| - | - |
| **Stop** | Stops the current turn |
| **Steer** | Redirects the running turn after its next tool call |
| **Queue** | Adds a message to send after the current turn. You can edit, reorder to next, steer with, or delete a queued turn |
| **Pause and resume queue** | **Stop** pauses the queue; **Resume** sends the queued turns again |
If a queued message keeps failing to send, it stays in the queue and you are told, so nothing is lost.
### Voice
Mibyan Desktop supports three voice features, all from the composer:
Speak instead of typing. Recording is transcribed into the composer.
A hands-free back and forth. The state shows as **Listening**, **Thinking**, **Speaking**, or **Muted**. You can mute the microphone, stop listening and send, or **End** the conversation. Start or stop with `Ctrl` and `B` on macOS.
Turn on reading aloud for replies, or use **Read aloud** on a single message.
A **wake word** can start voice hands-free: `/wake on`, `/wake off`, and `/wake status`. It pauses while a voice chat is running.
Voice needs a speech-to-text provider configured, and microphone permission from your system. If it does not work, see [Troubleshooting](/products/desktop-guide/troubleshooting#voice-problems).
## Choose the model
Open the model picker from the status bar or with `Cmd`/`Ctrl` with `Shift` and `M`. It lists the providers you have signed in to, with a filter box.
* **Mibyan** models run through your account. Some **Pro** models need a paid Mibyan subscription.
* Each model shows its input and output price per million tokens.
* **Options** depend on the model: **Thinking**, **Fast** mode, and **Effort** (Minimal, Low, Medium, High, Extra High, Max, Ultra).
* Picking a model for a chat **pins** it for that chat. New chats use the default from Settings.
You can also add fallback models in Settings, so a chat continues if the main model fails.
## Reading the conversation
* **Thinking.** Streamed reasoning shows as "Thinking" and then "Thought for ...". You can collapse it by default in Settings.
* **Tool activity.** Steps such as reading a file, searching the web, or running a command appear live. **Product** view summarizes them in plain language, and **Technical** view shows the raw input and output. Steps that failed and were recovered are marked **Recovered**.
* **Files changed.** When a turn edits files, a summary links to **Review**.
* **Message actions.** Copy, refresh (regenerate), **Branch in new chat**, react with an emoji, **Read aloud**, edit, and expand a long message.
* **Timing.** Each turn shows how long it took.
### Edit, branch, and restore
Edit one of your earlier messages and send the edited version. If that turn is no longer in the server history (it may have been compressed away), you are told.
**Branch in new chat** starts a new chat from a message, saved as a draft named Branch and a number. Stop the current turn first.
**Restore checkpoint** rewinds to an earlier prompt. Everything after it is removed from the conversation, and the prompt runs again from there. You can move to the previous or next checkpoint, and go forward again.
`/retry` resends your last message, `/undo` removes the last exchange, and `/rollback` lists or restores filesystem checkpoints.
## Approvals and safety
Mibyan asks before it does something that needs your permission. You choose how much to be asked:
| Approval mode | Behavior |
| - | - |
| **Manual** | Asks before every action that requires approval |
| **Smart** | Assesses each action automatically and asks only when needed |
| **Off** | Runs without approval prompts |
Set it from the status bar or with `/approvals manual`, `/approvals smart`, or `/approvals off`.
An approval card shows the exact **command**. Your choices are **Run**, **Reject**, **Allow this session**, or **Always allow**, which adds a pattern to your permanent allowlist so similar commands are never asked about again. Always allow asks you to confirm because it lasts across sessions.
**YOLO mode** auto-approves dangerous commands. `/yolo` turns it on for the current chat, and `Shift`-click on its indicator toggles it globally. Use it only in a folder and environment where a mistake is cheap.
Some requests come as their own prompts:
* **Administrator password.** When a privileged command needs `sudo`, Mibyan asks for the password and sends it **only to your local agent**.
* **Secret required.** A credential prompt for a value the agent needs.
* **Questions.** The agent can ask you one or several questions with choices, an "Other" free-text answer, or Skip. If you answer after the prompt has expired, you can draft it as a follow-up message.
* **MCP setup.** The agent can offer to install, enable, or authorize an MCP server from the Mibyan-approved catalog, and asks first. Required credentials must be filled in before installing.
When Mibyan is in the background you get a system notification for **Approval needed** with **Approve** and **Reject** buttons, **Input needed**, **Response ready**, and **Turn failed**.
## Long-running work
| Feature | What it does |
| - | - |
| `/goal` | Set a standing goal for the session. It shows as Goal active, paused, waiting, or done |
| `/loop` | Re-run a prompt on a recurring interval inside this session |
| `/background` | Run a prompt in the background. The chat resumes when background tasks finish |
| **Tasks** | The agent's own todo list appears as tasks completed out of total |
| **Subagents** | When the agent delegates, child agents stream their progress in the **Agents** view (a spawn tree with running, failed, and done counts, tools used, and files touched) |
| `/compress` | Compresses the conversation to free context |
The **context meter** in the status bar shows how full the context is. Open it for a breakdown by conversation, system prompt, tool definitions, skills, MCP, memory, rules, and subagent definitions, with tokens used out of the maximum.
## Continue elsewhere
* **Handoff.** `/handoff` sends the session to a messaging platform such as Telegram. You can resume it in Desktop any time. This needs the messaging gateway running.
* **Export.** Save a session from its menu, or `/save` for the transcript as JSON.
* **New window, tab, or split.** Open the same chat beside itself.
## When a turn fails
Failures say which layer failed: authentication, out of credits, disk full, custom endpoint, gateway, provider, local runtime, or streaming connection. You get the right next step, such as **Retry**, **Switch provider**, **Open logs**, **Copy error details**, or **Send diagnostics**. See [Troubleshooting](/products/desktop-guide/troubleshooting).
The file browser, review pane, terminals, live preview, layouts, and HUD mode.