diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 289a712fc1ac..757baeb61cd1 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -33,12 +33,13 @@ goose operates autonomously by default. Combined with the Developer extension's ### Built-in Platform Extensions -Platform extensions are built-in extensions that provide global features like conversation search, task tracking, and extension management. These extensions are always available, enabled by default, and can be toggled on or off. +Platform extensions are built-in extensions that provide global features like conversation search, task tracking, and extension management. These extensions are always available and can be toggled on or off as needed. - [Chat Recall](/docs/mcp/chatrecall-mcp): Search conversation content across all your session history -- [Extension Manager](/docs/mcp/extension-manager-mcp): Discover, enable, and disable extensions dynamically during sessions -- [Skills](/docs/mcp/skills-mcp): Load and use skills from the `.claude/skills` or `.goose/skills` directories -- [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions +- [Code Execution](/docs/mcp/code-execution-mcp): Execute JavaScript code for tool discovery and tool calling +- [Extension Manager](/docs/mcp/extension-manager-mcp): Discover, enable, and disable extensions dynamically during sessions (enabled by default) +- [Skills](/docs/mcp/skills-mcp): Load and use agent skills from various project and global skill directories (enabled by default) +- [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions (enabled by default) ### Toggling Built-in Extensions diff --git a/documentation/docs/guides/code-mode.md b/documentation/docs/guides/code-mode.md new file mode 100644 index 000000000000..ed1c733564c1 --- /dev/null +++ b/documentation/docs/guides/code-mode.md @@ -0,0 +1,71 @@ +--- +sidebar_position: 52 +title: Code Mode +sidebar_label: Code Mode +description: Understanding how Code Mode handles tool discovery and tool calling +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Code Mode is a method of interacting with MCP tools programmatically instead of calling them directly. Code Mode is particularly useful when working with many enabled extensions, as it can help manage context window usage more efficiently. + +:::info +This functionality requires the built-in [Code Execution extension](/docs/mcp/code-execution-mcp) to be enabled. +::: + +Code Mode controls how tools are discovered and called: +- Tools from enabled extensions are discovered on-demand and loaded into context as needed +- Multiple tool calls are batched in one execution +- Intermediate results are chained (output from one tool as input to the next) + +## How Code Mode Works + +The [Code Execution extension](/docs/mcp/code-execution-mcp) is an MCP server that uses the MCP protocol to expose three foundational meta-tools. When Code Execution is enabled, goose switches to Code Mode. For every request, the LLM writes JavaScript code that goose runs in a sandbox environment to: +- Discover available tools from your enabled extensions (if needed) +- Learn how to work with the tools it needs for the current task +- Call those tools programmatically to complete the task + +### Traditional vs. Code Mode Tool Calling + +Traditional MCP tool calling and Code Mode are two different approaches to the same goal: giving goose access to tools. + +| Aspect | Traditional | Code Mode | +|--------|------------------|-----------| +| **Tool Discovery** | All tools from enabled extensions, for example:
• `developer.shell`
• `developer.text_editor`
• `github.list_issues`
• `github.get_pull_request`
• `slack.send_message`
• ... *potentially many more* | Code Execution extension's meta-tools:
• `search_modules`
• `read_module`
• `execute_code`

The LLM uses these tools to discover tools from other enabled extensions as needed | +| **Tool Calling** | • Sequential tool calls
• Each result sent to the LLM before the next call | • May require tool discovery calls
• Multiple tool calls batched in one execution
• Intermediate results are chained and processed locally | +| **Context Window** | Every LLM call includes all tool definitions from enabled extensions | Every LLM call includes the 3 meta-tool definitions, plus any tool definitions previously discovered in the session | +| **Best For** | • 1-3 enabled extensions
• Simple tasks using 1-2 tools | • 5+ extensions
• Well-defined multi-step workflows | + +:::info Text-Only Results +Code Mode only supports text content from tool results. Images, binary data, and other content types are ignored. +::: + +## Additional Resources + +import ContentCardCarousel from '@site/src/components/ContentCardCarousel'; +import gooseCodeMode from '@site/blog/2025-12-15-code-mode-mcp/header-image.jpg'; +import notMcpReplacement from '@site/blog/2025-12-21-code-mode-doesnt-replace-mcp/header-image.png'; + + diff --git a/documentation/docs/guides/sessions/session-management.md b/documentation/docs/guides/sessions/session-management.md index c9b3cd5adf08..80c57bd75809 100644 --- a/documentation/docs/guides/sessions/session-management.md +++ b/documentation/docs/guides/sessions/session-management.md @@ -191,7 +191,7 @@ Search allows you to find specific content within sessions or find specific sess goose will search your session history and show relevant conversations with context from matching sessions. :::info - This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default). + This functionality requires the built-in [Chatrecall extension](/docs/mcp/chatrecall-mcp) to be enabled. ::: #### Search Within Historical Session @@ -243,7 +243,7 @@ Search allows you to find specific content within sessions or find specific sess goose will search your session history and show relevant conversations with context from matching sessions. :::info - This functionality requires the built-in `Chatrecall` extension to be enabled (it's enabled by default). + This functionality requires the built-in [Chatrecall extension](/docs/mcp/chatrecall-mcp) to be enabled. ::: #### Search Session Data Directly diff --git a/documentation/docs/guides/tips.md b/documentation/docs/guides/tips.md index c9235a3f194b..24a5a2e7dba4 100644 --- a/documentation/docs/guides/tips.md +++ b/documentation/docs/guides/tips.md @@ -29,6 +29,10 @@ Press `Cmd+Option+Shift+G` (macOS) or `Ctrl+Alt+Shift+G` (Windows/Linux) and sen ### Turn off unnecessary extensions or tool Turning on too many extensions can degrade performance. Enable only essential [extensions and tools](/docs/guides/managing-tools/tool-permissions) to improve tool selection accuracy, save context window space, and stay within provider tool limits. +:::tip Code Execution for Many Extensions +Consider enabling [Code Mode](/docs/guides/code-mode), an alternative approach to tool calling that discovers tools on demand. +::: + ### Teach goose your preferences Help goose remember how you like to work by using [`.goosehints` or other context files](/docs/guides/context-engineering/using-goosehints) or [skills](/docs/guides/context-engineering/using-skills) for permanent project preferences and the [Memory extension](/docs/mcp/memory-mcp) for things you want goose to dynamically recall later. Both can help save valuable context window space while keeping your preferences available. diff --git a/documentation/docs/mcp/chatrecall-mcp.md b/documentation/docs/mcp/chatrecall-mcp.md index b33e3f939914..bb117cc5d7e5 100644 --- a/documentation/docs/mcp/chatrecall-mcp.md +++ b/documentation/docs/mcp/chatrecall-mcp.md @@ -14,7 +14,7 @@ goose automatically uses Chat Recall when you reference past work or ask questio ## Configuration - + @@ -88,4 +88,4 @@ Both sessions were focused on safely updating the database schema in production. :::info Compacted sessions from goose versions prior to v1.14.0 may not be searchable due to a change in how conversation history is stored. -::: \ No newline at end of file +::: diff --git a/documentation/docs/mcp/code-execution-mcp.md b/documentation/docs/mcp/code-execution-mcp.md new file mode 100644 index 000000000000..9ff3ea2c21f6 --- /dev/null +++ b/documentation/docs/mcp/code-execution-mcp.md @@ -0,0 +1,77 @@ +--- +title: Code Execution Extension +description: Execute JavaScript code to interact with multiple MCP tools +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { PlatformExtensionNote } from '@site/src/components/PlatformExtensionNote'; +import GooseBuiltinInstaller from '@site/src/components/GooseBuiltinInstaller'; + +The Code Execution extension enables [Code Mode](/docs/guides/code-mode), a programmatic approach for interacting with MCP tools. + +In Code Mode, the LLM discovers which tools are available from your enabled extensions and writes JavaScript code that goose runs in one execution instead of calling tools directly and one at a time. This helps manage context window usage more efficiently when multiple extensions are enabled and when performing workflows with multiple tool calls. + +## Configuration + + + + + + + + + + 1. Run the `configure` command: + ```sh + goose configure + ``` + + 2. Choose to `Toggle Extensions` + ```sh + ┌ goose-configure + │ + ◇ What would you like to configure? + │ Toggle Extensions + │ + ◆ Enable extensions: (use "space" to toggle and "enter" to submit) + // highlight-start + │ ● code_execution + // highlight-end + └ Extension settings updated successfully + ``` + + + +## Example Usage + +In this example, we'll ask goose to compile a report that requires multiple tool calls. + +### goose Prompt + +``` +Create a LOG.md file with the current git branch, last 3 commits, and the version from package.json +``` + +### goose Output + +:::note Desktop +I'll help you create a LOG.md file with the git branch, last 3 commits, and version from package.json. Let me gather all this information in one operation. + +`Execute Code code: import { shell, text_editor } from "developer" ...` + +Let me check the package.json path first: + +`Execute Code code: import { shell, text_editor } from "developer" ...` + +Perfect! I've created the **LOG.md** file with: + +- ✅ **Current git branch** +- ✅ **Last 3 commits** (with hash, message, author, and relative time) +- ✅ **Version** from ui/desktop/package.json + +The file has been saved to the root directory as `LOG.md`. +::: diff --git a/documentation/src/components/PlatformExtensionNote.js b/documentation/src/components/PlatformExtensionNote.js index d1cf7b60932f..65702cd7015b 100644 --- a/documentation/src/components/PlatformExtensionNote.js +++ b/documentation/src/components/PlatformExtensionNote.js @@ -1,11 +1,10 @@ import React from "react"; import Admonition from '@theme/Admonition'; -export const PlatformExtensionNote = () => { - +export const PlatformExtensionNote = ({ defaultEnabled = true }) => { return ( -

This is a built-in platform extension that's enabled by default. Platform extensions provide core functionality and are used within goose just like MCP server extensions.

+

This is a built-in platform extension{defaultEnabled && " that's enabled by default"}. Platform extensions provide core functionality and are used within goose just like MCP server extensions.

 ); };