Toolsets Reference

Toolsets are named bundles of tools that control what the agent can do. They're the primary mechanism for configuring tool availability per platform, per session, or per task.

How Toolsets Work

Every tool belongs to exactly one toolset. When you enable a toolset, all tools in that bundle become available to the agent. Toolsets come in three kinds:

• Core — A single logical group of related tools (e.g., file bundles read_file, write_file, patch, search_files)
• Composite — Combines multiple core toolsets for a common scenario (e.g., debugging bundles file, terminal, and web tools)
• Platform — A complete tool configuration for a specific deployment context (e.g., kopi-cli is the default for interactive CLI sessions)

Configuring Toolsets

Per-session (CLI)

kopi chat --toolsets web,file,terminal
kopi chat --toolsets debugging        # composite — expands to file + terminal + web
kopi chat --toolsets all              # everything

Per-platform (config.yaml)

toolsets:
  - kopi-cli          # default for CLI
  # - kopi-telegram   # override for Telegram gateway

Interactive management

kopi tools                            # curses UI to enable/disable per platform

Or in-session:

/tools list
/tools disable browser
/tools enable rl

Core Toolsets

Toolset	Tools	Purpose
browser	browser_back, browser_cdp, browser_click, browser_console, browser_dialog, browser_get_images, browser_navigate, browser_press, browser_scroll, browser_snapshot, browser_type, browser_vision, web_search	Core browser automation. Includes web_search as a fallback for quick lookups. browser_cdp and browser_dialog are gated at runtime — registered only when a CDP endpoint is reachable at session start (via /browser connect, browser.cdp_url config, Browserbase, or Camofox). browser_dialog works together with the pending_dialogs and frame_tree fields that browser_snapshot adds when a CDP supervisor is attached.
clarify	clarify	Ask the user a question when the agent needs clarification.
code_execution	execute_code	Run Python scripts that call Kopi tools programmatically.
cronjob	cronjob	Schedule and manage recurring tasks.
debugging	composite (file + terminal + web)	Debug bundle — file, process/terminal, web extract/search.
delegation	delegate_task	Spawn isolated subagent instances for parallel work.
discord	discord	Core Discord text/embed/DM actions (gateway-only). Active on the kopi-discord toolset.
discord_admin	discord_admin	Discord moderation (bans, role changes, channel management). Active on the kopi-discord toolset; requires the bot to hold the relevant Discord permissions.
feishu_doc	feishu_doc_read	Read Feishu/Lark document content. Used by the Feishu document-comment intelligent-reply handler.
feishu_drive	feishu_drive_add_comment, feishu_drive_list_comments, feishu_drive_list_comment_replies, feishu_drive_reply_comment	Feishu/Lark drive comment operations. Scoped to the comment agent; not exposed on kopi-cli or other messaging toolsets.
file	patch, read_file, search_files, write_file	File reading, writing, searching, and editing.
homeassistant	ha_call_service, ha_get_state, ha_list_entities, ha_list_services	Smart home control via Home Assistant. Only available when HASS_TOKEN is set.
computer_use	computer_use	Background macOS desktop control via cua-driver — does not steal cursor/focus. Works with any tool-capable model. macOS only; requires cua-driver on $PATH.
image_gen	image_generate	Text-to-image generation via FAL.ai (with opt-in OpenAI / xAI backends).
kanban	kanban_block, kanban_comment, kanban_complete, kanban_create, kanban_heartbeat, kanban_link, kanban_show	Multi-agent coordination tools — only registered when the agent is spawned by the kanban dispatcher (KOPI_KANBAN_TASK env set). Lets workers mark tasks done with structured handoffs, block for human input, heartbeat during long ops, comment on threads, and (for orchestrators) fan out into child tasks.
memory	memory	Persistent cross-session memory management.
messaging	send_message	Send messages to other platforms (Telegram, Discord, etc.) from within a session.
moa	mixture_of_agents	Multi-model consensus via Mixture of Agents.
rl	rl_check_status, rl_edit_config, rl_get_current_config, rl_get_results, rl_list_environments, rl_list_runs, rl_select_environment, rl_start_training, rl_stop_training, rl_test_inference	RL training environment management (Atropos).
safe	image_generate, vision_analyze, web_extract, web_search (via includes)	Read-only research + media generation. No file writes, no terminal, no code execution.
search	web_search	Web search only (without extract).
session_search	session_search	Search past conversation sessions.
skills	skill_manage, skill_view, skills_list	Skill CRUD and browsing.
spotify	spotify_albums, spotify_devices, spotify_library, spotify_playback, spotify_playlists, spotify_queue, spotify_search	Native Spotify control (playback, queue, search, playlists, albums, library). Registered by the bundled spotify plugin.
terminal	process, terminal	Shell command execution and background process management.
todo	todo	Task list management within a session.
tts	text_to_speech	Text-to-speech audio generation.
vision	vision_analyze	Image analysis via vision-capable models.
video	video_analyze	Video analysis and understanding tools (opt-in, not in the default toolset — add explicitly via --toolsets).
web	web_extract, web_search	Web search and page content extraction.
yuanbao	yb_query_group_info, yb_query_group_members, yb_search_sticker, yb_send_dm, yb_send_sticker	Yuanbao DM/group actions and sticker search. Registered only on kopi-yuanbao.

Platform Toolsets

Platform toolsets define the complete tool configuration for a deployment target. Most messaging platforms use the same set as kopi-cli:

Toolset	Differences from kopi-cli
kopi-cli	Full toolset — the default for interactive CLI sessions. Includes file, terminal, web, browser, memory, skills, vision, image_gen, todo, tts, delegation, code_execution, cronjob, session_search, clarify, and safe (read-only) bundles plus the standard messaging tools.
kopi-acp	Drops clarify, cronjob, image_generate, send_message, text_to_speech, and all four Home Assistant tools. Focused on coding tasks in IDE context.
kopi-api-server	Drops clarify, send_message, and text_to_speech. Keeps everything else — suitable for programmatic access where user interaction isn't possible.
kopi-cron	Same as kopi-cli.
kopi-telegram	Same as kopi-cli.
kopi-discord	Adds discord and discord_admin on top of kopi-cli.
kopi-slack	Same as kopi-cli.
kopi-whatsapp	Same as kopi-cli.
kopi-signal	Same as kopi-cli.
kopi-matrix	Same as kopi-cli.
kopi-mattermost	Same as kopi-cli.
kopi-email	Same as kopi-cli.
kopi-sms	Same as kopi-cli.
kopi-bluebubbles	Same as kopi-cli.
kopi-dingtalk	Same as kopi-cli.
kopi-feishu	Adds the five feishu_doc_* / feishu_drive_* tools (only used by the document-comment handler, not the regular chat adapter).
kopi-qqbot	Same as kopi-cli.
kopi-wecom	Same as kopi-cli.
kopi-wecom-callback	Same as kopi-cli.
kopi-weixin	Same as kopi-cli.
kopi-yuanbao	Adds the five yb_* tools (DM/group/sticker) on top of kopi-cli.
kopi-homeassistant	Same as kopi-cli (the Home Assistant tools are already present by default and activate when HASS_TOKEN is set).
kopi-webhook	Same as kopi-cli.
kopi-gateway	Internal gateway orchestrator toolset — union of every kopi-<platform> toolset; used when the gateway needs to accept any message source.

Dynamic Toolsets

MCP server toolsets

Each configured MCP server generates a mcp-<server> toolset at runtime. For example, if you configure a github MCP server, a mcp-github toolset is created containing all tools that server exposes.

# config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]

This creates a mcp-github toolset you can reference in --toolsets or platform configs.

Plugin toolsets

Plugins can register their own toolsets via ctx.register_tool() during plugin initialization. These appear alongside built-in toolsets and can be enabled/disabled the same way.

Custom toolsets

Define custom toolsets in config.yaml to create project-specific bundles:

toolsets:
  - kopi-cli
custom_toolsets:
  data-science:
    - file
    - terminal
    - code_execution
    - web
    - vision

Wildcards

• all or * — expands to every registered toolset (built-in + dynamic + plugin)

Relationship to kopi tools

The kopi tools command provides a curses-based UI for toggling individual tools on or off per platform. This operates at the tool level (finer than toolsets) and persists to config.yaml. Disabled tools are filtered out even if their toolset is enabled.

See also: Tools Reference for the complete list of individual tools and their parameters.