{"slug":"cherry-tool-guide","title":"cherry-tool-guide","summary":"Cherry Studio first-party tool and bundled-shell routing for general agents. For straightforward local work in shell-capable sessions, run JS/TS with `bun ` and one-off JS tools with `bun x`; run Python with `uv run [--with ] python` and one-off Python CLIs with `uvx`;","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-08-23T10:49:18.245065Z","repo":{"url":"https://github.com/CherryHQ/cherry-studio","stars":52186,"forks":5015,"license":"AGPL-3.0","updatedAt":"2026-09-27T14:44:58Z"},"bodyHtml":"
\n

name: cherry-tool-guide\ndescription: Cherry Studio first-party tool and bundled-shell routing for general agents. For straightforward local work in shell-capable sessions, run JS/TS with bun <file> and one-off JS tools with bun x; run Python with uv run [--with <pkg>] python and one-off Python CLIs with uvx; search with rg. Load this guide before changing project dependencies, deciding whether a tool should be ephemeral or reusable, reading or converting local Office/PDF files, coordinating or delegating across Agent Sessions, or using Cherry-owned web/browser, knowledge, persistent memory, schedules/notifications, IM channels, image generation, artifact reporting, managed CLI, skill, or MCP-server-registration capabilities—even if the user names no tool. Consult it before shell/file workarounds; live tool schemas are authoritative.\nversion: 1.4.0

\n

Cherry Tool Guide

\n

Cherry Studio injects first-party tools into your session over four MCP servers\n(mcp__cherry-tools__*, mcp__agent-memory__*, mcp__skills__*, mcp__mcp-manager__*)\nand gives shell-capable general agents bundled runtimes for local execution. The MCP\ntools act on the running app — the user's knowledge bases, IM channels, schedules,\nmanaged CLIs, skill library, and MCP server registry — through boundaries only Cherry\nowns. Shell and file tools cannot reach those app boundaries correctly; use the bundled\nruntimes only for the local execution cases routed below.

\n

This file is a router. It carries only the global rules and the intent → tool →\nreference table. Each reference holds that domain's prerequisites, sequencing,\nconditional availability, output interpretation, recovery, and examples. Read the one\nreference the task needs (and any it cross-links to) before calling — don't work from\nthis page alone.

\n

Tool names here are fully qualified (mcp__server__tool); the exact names exposed in\nyour session are authoritative if they ever differ. This guide never restates argument\nshapes — the live tool schema in your session is the authoritative source for\nparameter names, enums, and required fields. Read it before every call.

\n

Global rules

\n\n

Routing table

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
User intentRoute toReference
Look up current/online facts, news, docsmcp__cherry-tools__web_search → mcp__cherry-tools__web_fetchweb.md
Browser interaction (click, forms, screenshots)(unavailable via web built-ins)web.md
Answer from the user's own documentsmcp__cherry-tools__kb_list → mcp__cherry-tools__kb_search → mcp__cherry-tools__kb_readknowledge.md
Add / delete / re-index knowledgemcp__cherry-tools__kb_manage (resolve IDs first; needs approval)knowledge.md
Read or convert a local documentmcp__cherry-tools__to_markdown → read the returned temporary Markdown path as neededdocuments.md
Recall a past fact, correction, or preferencemcp__agent-memory__memory (search) before re-askingmemory.md
Save durable knowledge vs. a one-off eventmcp__agent-memory__memory (update vs. append)memory.md
Schedule a recurring / future taskmcp__cherry-tools__cron (Cherry scheduling only)autonomy.md
Proactively message the user or send a filemcp__cherry-tools__notifyautonomy.md
Inspect / connect / repair IM channels, rename agentmcp__cherry-tools__configautonomy.md
Find, create, message, or inspect work across Agent Sessionsmcp__cherry-tools__session_list / session_search / session_create / session_send / session_deliveriessessions.md
Generate an imagemcp__cherry-tools__generate_image (needs a painting model)outputs.md
Declare final deliverable file(s)mcp__cherry-tools__report_artifactsoutputs.md
Run JS/TS or Python, invoke a one-off package, search local code/filesbundled bun, uv / uvx, or rg according to task lifetimecli.md
Find / install a command-line toolcommand -v check → mcp__cherry-tools__cli_list → mcp__cherry-tools__cli_search → mcp__cherry-tools__cli_install (approval)cli.md
Find / install a new capability skillmcp__skills__search_skills → mcp__skills__install_skill (approval)skills.md
Register a new MCP server the user suppliedmcp__mcp-manager__install_mcp_server (approval; never invent the config)mcp.md
\n

When a tool isn't there

\n

Two different situations, don't confuse them:

\n\n

On any tool error result (bad ID, unsupported channel/file, invalid recipe), read\nthe message and correct the call; don't silently retry the same arguments. On declined\napproval, stop and report — never re-attempt the mutation through a different route.

\n

Out of scope

\n

Not covered here: SDK-native Read/Edit/Bash and orchestration tools; calling the\ntools of a third-party (user-configured) MCP server — only registering one is in scope,\nsee mcp.md; the AI-SDK chat read_file attachment reader (a\nchat-path tool, not exposed on this MCP surface); and the role-specific\nmcp__assistant__* navigation/diagnosis tools, which belong to the Cherry Assistant and\nits own guide.

\n","files":[{"path":"references/autonomy.md","sizeBytes":4453,"isText":true},{"path":"references/cli.md","sizeBytes":4366,"isText":true},{"path":"references/documents.md","sizeBytes":3205,"isText":true},{"path":"references/knowledge.md","sizeBytes":2707,"isText":true},{"path":"references/mcp.md","sizeBytes":2918,"isText":true},{"path":"references/memory.md","sizeBytes":1688,"isText":true},{"path":"references/outputs.md","sizeBytes":1506,"isText":true},{"path":"references/sessions.md","sizeBytes":4710,"isText":true},{"path":"references/skills.md","sizeBytes":1959,"isText":true},{"path":"references/web.md","sizeBytes":2099,"isText":true},{"path":"SKILL.md","sizeBytes":7840,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-08-23T10:49:36.452177Z","sha256":"BBB66C6E99BE1844F5978C4695083632984AF1A255A000357F22CBBC68BCC455","sizeBytes":18097},"review":null,"source":{"repositoryUrl":"https://github.com/CherryHQ/cherry-studio","path":"resources/skills/cherry-tool-guide","license":"AGPL-3.0","commit":"5846b0e6b71adfd46baf094259823e1519e3afd6","subtreeSha":"E0AC51781C5C96828A08F27BC78CF662C99544A497347A49F9546BB666045156","lastSyncedAt":"2026-09-27T19:30:10.437151Z"},"reviewedAt":"2026-08-23T10:50:55.48783Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/CherryHQ/cherry-studio/tree/main/resources/skills/cherry-tool-guide"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install cherryhq-cherry-studio@llmmart"},{"target":"git","command":"git clone https://github.com/CherryHQ/cherry-studio.git"}]}