Bots

A bot is a long-lived AI assistant with a fixed system prompt, scoped to a workspace or shared globally. Bots back Chat-mode sessions for fast Q&A, triage, or guided support — perfect for "the company codebase expert", "the QA helper", "the docs writer".

Configuration

Setting	Description
Name	Display name (uniqueness checked at creation)
System Prompt	Instructions defining the bot's behavior
Provider	Polygent Code, Claude Code, Gemini CLI, OpenCode, Kilo CLI, Codex, Qwen Code
Model	Specific model
Category	Optional grouping for the manage page + New Chat modal
Greeting / Icon / Color	Optional opener message and a sidebar icon + color for the bot
Read-Only Mode	Bot cannot edit files — Q&A only
Allowed Tools	Restrict which built-in tools the bot may use (supported providers only)
MCP Servers	Restrict which registered MCP servers the bot may reach
Polygent MCP Tools	Restrict which built-in Polygent MCP tools the bot may call
Workspace Scoping	Global (all workspaces) or per-workspace
Allowed Permissions / Roles	Restrict which users can see and use the bot
Lock Provider & Model	When on, users cannot change provider or model in this bot's conversations
Enabled / Disabled	Toggle without deleting

Categories and reordering

Organize bots into categories and drag to reorder.

• The Bots page renders bots in a card grid grouped by category. User categories appear in your chosen order; an Uncategorized section shows any bot without a category. Empty sections are hidden. Built-in system bots appear in their assigned category alongside your own bots — there is no separate "System" section.
• The Manage Categories button (Bots page header) opens a modal where you can create, rename, delete, and drag-reorder categories.
• Drag a bot card to reorder it inside its category, or drop it onto a different section to move it. System bots can be dragged too — drag is the only way to recategorize them (the bot edit form leaves their category alone).
• Drag a category header to reorder user categories.
• Deleting a category requires it to be empty. Move every bot out first (drag, or edit each bot's Category) — otherwise the delete is rejected.
• Reorder is disabled when filters or search are active, since reordering a filtered subset would corrupt the global order.
• The New Chat modal uses the same grouped 3-per-row layout, with a pinned "Start" section that always shows Regular Chat and Develop Session on top.
• System bot categories: each built-in system bot ships with a default category (for example, a debugging assistant lands in QA). The category is created automatically the first time it's needed; once you reassign a system bot manually, your choice is preserved on later updates.

Management

• Create a new bot
• Edit name, prompt, provider, model, scope
• Clone an existing bot
• Enable / Disable to take a bot offline without deleting it
• Delete — soft-deletes any sessions linked to the bot

Conversations

Bots run inside Chat-mode sessions. Open a bot to see:

• Chat Mode Sessions — all conversations with this bot
• Conversation History — full transcript, persistent
• Initial Auto-Message — optional opener the bot sends first
• Public Shared URL — a read-only link you can share to expose a conversation transcript

Public shared URLs are useful for: documenting "how we resolved X" without exposing the live workspace, sharing a Q&A trail with a stakeholder, posting fix walk-throughs.

Bot selection modal

When starting a new conversation:

• Two-step flow — first pick a workspace, then pick a bot in that workspace
• Last-Used Workspace — remembered in your browser, auto-selected on reopen

Sidebar section

Bots appear in the sidebar with:

• Bot list — quick access to every enabled bot you can use
• Conversation history — recent chats per bot
• New conversation button on each bot

When to build a bot

Use case	Bot setup
Codebase Q&A	Read-only mode, full repo access, prompt: "answer questions about this repo"
QA helper	Read-only mode, prompt: "explain testing patterns and help write test cases"
Docs writer	Edit mode, scoped to docs folder
Onboarding bot	Read-only, prompt: "explain how to set up the project"
Triage bot	Read-only mode, prompt: "given a bug report, suggest steps to reproduce and likely cause"

Worked example: a locked-down support bot

1. Bots → New Bot. Name it Support Helper.
2. System prompt: "You answer questions about this repository. Cite files and line numbers. Never edit files."
3. Pick a tool-capable provider (Claude Code, Qwen Code, or Polygent Code) and turn Read-Only Mode on.
4. Under Allowed Tools, select only Read, Glob, and Grep so the bot can read and search but never run shell commands.
5. Under Polygent MCP Tools, allow search_tickets and get_ticket_details so it can answer "is there a ticket for this?" — but leave create_ticket out so it can't open tickets on its own.
6. Scope it to the relevant workspace, and set Allowed Roles to your support team's role so only they see it.
7. Optionally enable Lock Provider & Model so every conversation uses the tuned model.
8. Save, then start a conversation and ask "where do we handle retries on failed API calls?" — the bot reads the repo and answers, with no ability to change code, run commands, or create tickets.

Read-only mode

Set Read-Only Mode to prevent the bot from editing files. The bot can still read files, run searches, and answer questions, but it cannot mutate the repo. Use this for support and Q&A bots.

Allowed tools

By default a bot can use its provider's standard set of chat tools. The Allowed Tools picker lets you narrow that to an explicit allowlist — for example, give a read-only research bot only Read, Glob, and Grep so it can never run a shell command or edit a file.

• Leave the picker empty to use the provider's default tool set.
• The available tools depend on the selected provider; the picker shows exactly what that provider exposes.
• Tool selection is only supported on some providers — currently Claude Code, Qwen Code, and Polygent Code. For other providers the form shows "Tools selection for this provider is not supported" and the bot uses the provider's defaults.

Read-Only Mode vs. Allowed Tools: Read-Only Mode is a blanket "no file edits" switch. Allowed Tools is finer-grained — use it when you want to permit, say, reading and searching but nothing else, or to remove web access from a bot that should only look at the repo.

MCP servers

If your team has registered user-defined MCP servers, a bot uses all enabled servers by default. Use the MCP Servers allowlist to restrict a bot to a specific subset.

• Empty = the bot reaches every enabled MCP server (default).
• Pick one or more servers to limit the bot to just those — useful for a support bot that should reach your docs MCP but nothing that can change state.

Polygent MCP tools

The built-in Polygent MCP exposes tools such as create_ticket, write_plan, ask_user_question, and the memory tools. By default a bot can call all of them. The Polygent MCP Tools allowlist restricts a bot to a named subset.

• Empty = all built-in Polygent tools available (default).
• Pick specific tools to limit the bot — for example, allow a triage bot to search_tickets and get_ticket_details but not create_ticket.

Subagents (Polygent Code only)

When a bot uses the Polygent Code provider, a Subagents picker appears. Select which custom subagents this bot's sessions can delegate to via the Agent tool. The two built-in subagents (general, explorer) are always available and don't need to be selected.

Access control (permissions & roles)

By default a bot is visible to every user who can view bots. To restrict a bot to a subset of the team, set Allowed Permissions and/or Allowed Roles:

• Allowed Permissions — a user sees the bot if they hold any of the listed permission keys.
• Allowed Roles — a user sees the bot if they are assigned any of the listed roles.
• The two gates are OR-combined: when either or both are set, a user is allowed in if they match any listed permission or any listed role.
• Leave both empty to make the bot public to all bot-viewers.
• Users with the Manage Bots permission always see every bot, regardless of these gates.

Example: A "Release Manager" bot that can cut release branches should only be available to leads. Set Allowed Roles to your Lead role — everyone else simply won't see it in the bot list or the New Chat modal.

Lock provider & model

Enable Lock Provider & Model in the bot's Provider Settings to enforce the bot's chosen provider and model for every conversation. When locked:

• The bot's Provider/Model are pinned on the session at creation (the session starts on the locked model from the first message).
• The provider button in the session sidebar is disabled with tooltip "Provider locked by bot".
• The model dropdown above the chat composer is disabled with tooltip "Model locked by bot".

This is useful when a bot's behavior is tuned to a specific model (or when cost/governance requires the choice to stay fixed). The flag can be toggled for any bot, including system bots.

Permissions

Permission	Capability
bots.view	See bots you can access
bots.manage	Create / edit / delete / clone bots

Permissions vs. workflows

A bot is the right tool when you need a persistent persona for conversation. A workflow is the right tool when you need a multi-step procedure. They're complementary — bots have unstructured chat, workflows have structured steps.