From 0bfedd2cea03a858dfb9518c79e92d64cfb3c2ec Mon Sep 17 00:00:00 2001 From: Douwe M Osinga Date: Thu, 2 Jul 2026 13:31:45 -0400 Subject: [PATCH] docs: update environment and config references --- documentation/docs/guides/config-files.md | 83 +++++++++++++++---- .../docs/guides/enhanced-code-editing.md | 81 ------------------ .../docs/guides/environment-variables.md | 68 +++------------ documentation/docs/mcp/developer-mcp.md | 8 +- 4 files changed, 81 insertions(+), 159 deletions(-) delete mode 100644 documentation/docs/guides/enhanced-code-editing.md diff --git a/documentation/docs/guides/config-files.md b/documentation/docs/guides/config-files.md index 89f0042668..51e0fafb28 100644 --- a/documentation/docs/guides/config-files.md +++ b/documentation/docs/guides/config-files.md @@ -25,14 +25,27 @@ In addition to editing configuration files directly, many settings can be manage - **goose Desktop**: From the `Settings` page and the bottom toolbar - **goose CLI**: Run the `goose configure` command +## Provider Configuration + +Provider settings are stored in the `active_provider` and `providers` keys: + +```yaml +active_provider: anthropic +providers: + anthropic: + enabled: true + model: claude-sonnet-4-5-20250929 + configured: true +``` + +`GOOSE_PROVIDER` and `GOOSE_MODEL` are still supported as environment variables and override the config file for that process. Older config files that use flat `GOOSE_PROVIDER` and `GOOSE_MODEL` keys are read for compatibility and migrated when goose updates the provider settings. + ## Global Settings The following settings can be configured at the root level of your config.yaml file: | Setting | Purpose | Values | Default | Required | |---------|---------|---------|---------|-----------| -| `GOOSE_PROVIDER` | Primary [LLM provider](/docs/getting-started/providers) | "anthropic", "openai", etc. | None | Yes | -| `GOOSE_MODEL` | Default model to use | Model name (e.g., "claude-3.5-sonnet", "gpt-4") | None | Yes | | `GOOSE_TEMPERATURE` | Model response randomness | Float between 0.0 and 1.0 | Model-specific | No | | `GOOSE_MAX_TOKENS` | Maximum number of tokens for each model response (truncates longer responses) | Positive integer | Model-specific | No | | `GOOSE_MODE` | [Tool execution behavior](/docs/guides/managing-tools/goose-permissions) | "auto", "approve", "chat", "smart_approve" | "auto" | No | @@ -43,13 +56,13 @@ The following settings can be configured at the root level of your config.yaml f | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Model for tool interpretation | Model name (e.g., "llama3.2") | System default | No | | `GOOSE_INPUT_LIMIT` | Override input token limit for Ollama (maps to `num_ctx`) | Positive integer | Model default | No | | `GOOSE_CLI_MIN_PRIORITY` | Tool output verbosity | Float between 0.0 and 1.0 | 0.0 | No | -| `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "dark" | No | +| `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "ansi" | No | | `GOOSE_CLI_LIGHT_THEME` | Custom syntax highlighting theme for light mode | [bat theme name](https://github.com/sharkdp/bat#adding-new-themes) | "GitHub" | No | | `GOOSE_CLI_DARK_THEME` | Custom syntax highlighting theme for dark mode | [bat theme name](https://github.com/sharkdp/bat#adding-new-themes) | "zenburn" | No | | `GOOSE_CLI_SHOW_COST` | Show estimated cost for token use in the CLI | true/false | false | No | | `GOOSE_ALLOWLIST` | URL for allowed extensions | Valid URL | None | No | | `GOOSE_RECIPE_GITHUB_REPO` | GitHub repository for recipes | Format: "org/repo" | None | No | -| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0)| 0.8 | No | +| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically compacts your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0)| 0.8 | No | | `SECURITY_PROMPT_ENABLED` | Enable [prompt injection detection](/docs/guides/security/prompt-injection-detection) to identify potentially harmful commands | true/false | false | No | | `SECURITY_PROMPT_THRESHOLD` | Sensitivity threshold for prompt injection detection (higher = stricter) | Float between 0.01 and 1.0 | 0.8 | No | | `SECURITY_PROMPT_CLASSIFIER_ENABLED` | Enable ML-based prompt injection detection for advanced threat identification | true/false | false | No | @@ -65,8 +78,12 @@ Here's a basic example of a config.yaml file: ```yaml # Model Configuration -GOOSE_PROVIDER: "anthropic" -GOOSE_MODEL: "claude-4.5-sonnet" +active_provider: anthropic +providers: + anthropic: + enabled: true + model: claude-sonnet-4-5-20250929 + configured: true GOOSE_TEMPERATURE: 0.7 # Planning Configuration @@ -119,15 +136,49 @@ extensions: enabled: true/false # Whether the extension is active name: "extension_name" # Internal name timeout: 300 # Operation timeout in seconds - type: "builtin"/"stdio" # Extension type + type: "builtin" # Extension type available_tools: [] # Filter to specific tools (empty = all) - - # Additional settings for stdio extensions: - cmd: "command" # Command to execute - args: ["arg1", "arg2"] # Command arguments - description: "text" # Extension description - env_keys: [] # Required environment variables - envs: {} # Environment values +``` + +Supported extension types are `builtin`, `platform`, `stdio`, `streamable_http`, `frontend`, and `inline_python`. `sse` may appear in older configs, but is kept only for compatibility. + +Common extension shapes: + +```yaml +extensions: + developer: + type: builtin + name: developer + enabled: true + bundled: true + timeout: 300 + + computercontroller: + type: platform + name: computercontroller + display_name: Computer Controller + enabled: true + bundled: true + + filesystem: + type: stdio + name: filesystem + enabled: true + cmd: npx + args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] + env_keys: [] + envs: {} + timeout: 300 + + remote-tools: + type: streamable_http + name: remote-tools + enabled: true + uri: "https://example.com/mcp" + headers: {} + env_keys: [] + envs: {} + timeout: 300 ``` ### Tool Filtering @@ -136,7 +187,7 @@ Use the `available_tools` field to limit which tools are loaded from an extensio ## Search Path Configuration -Extensions may need to execute external commands or tools. By default, goose uses your system's PATH environment variable. You can add additional search directories in your config file: +Extensions may need to execute external commands or tools. Goose builds the command search path from any `GOOSE_SEARCH_PATHS` entries, built-in fallback paths, and then your system PATH. You can add additional search directories in your config file: ```yaml GOOSE_SEARCH_PATHS: @@ -145,7 +196,7 @@ GOOSE_SEARCH_PATHS: - "/opt/homebrew/bin" ``` -These paths are prepended to the system PATH when running extension commands, ensuring your custom tools are found without modifying your global PATH. +These paths are checked before the built-in fallback paths and system PATH when running extension commands, ensuring your custom tools are found without modifying your global PATH. ## Observability Configuration diff --git a/documentation/docs/guides/enhanced-code-editing.md b/documentation/docs/guides/enhanced-code-editing.md deleted file mode 100644 index ee27909c64..0000000000 --- a/documentation/docs/guides/enhanced-code-editing.md +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: Enhanced Code Editing with AI Models -sidebar_label: Enhanced Code Editing -description: Use AI models to intelligently apply code changes -sidebar_position: 110 ---- - -The [Developer extension](/docs/mcp/developer-mcp) supports using AI models for enhanced code editing through the `str_replace` command. When configured, it intelligently applies code changes using an AI model instead of simple string replacement. - -The use of models specializing in code editing can reduce the load on the main LLM providers while increasing accuracy, quality, and speed and lowering cost. This enhanced approach provides: - -- **Context-aware editing**: The AI understands code structure and can make more intelligent changes -- **Better formatting**: Maintains consistent code style and formatting -- **Error prevention**: Can catch and fix potential issues during the edit -- **Flexible model support**: Works with any OpenAI-compatible API -- **Clean implementation**: Uses proper control flow instead of exception handling for configuration checks - -## Configuration - -Set these [environment variables](/docs/guides/environment-variables#enhanced-code-editing) to enable AI-powered code editing: - -```bash -export GOOSE_EDITOR_API_KEY="your-api-key-here" -export GOOSE_EDITOR_HOST="https://api.openai.com/v1" -export GOOSE_EDITOR_MODEL="gpt-4o" -``` - -**All three environment variables must be set and non-empty for the feature to activate.** - -This optional feature is completely backwards compatible - if not configured, the extension works exactly as before with simple string replacement. - -### Supported Providers - -Any OpenAI-compatible API endpoint should work. Examples: - -**OpenAI:** -```bash -export GOOSE_EDITOR_API_KEY="sk-..." -export GOOSE_EDITOR_HOST="https://api.openai.com/v1" -export GOOSE_EDITOR_MODEL="gpt-4o" -``` - -**Anthropic (via OpenAI-compatible proxy):** -```bash -export GOOSE_EDITOR_API_KEY="sk-ant-..." -export GOOSE_EDITOR_HOST="https://api.anthropic.com/v1" -export GOOSE_EDITOR_MODEL="claude-3-5-sonnet-20241022" -``` - -**Morph:** -```bash -export GOOSE_EDITOR_API_KEY="sk-..." -export GOOSE_EDITOR_HOST="https://api.morphllm.com/v1" -export GOOSE_EDITOR_MODEL="morph-v0" -``` - -**Relace:** -```bash -export GOOSE_EDITOR_API_KEY="rlc-..." -export GOOSE_EDITOR_HOST="https://instantapply.endpoint.relace.run/v1/apply" -export GOOSE_EDITOR_MODEL="auto" -``` - -**Local/Custom endpoints:** -```bash -export GOOSE_EDITOR_API_KEY="your-key" -export GOOSE_EDITOR_HOST="http://localhost:8000/v1" -export GOOSE_EDITOR_MODEL="your-model" -``` - -## How It Works - -When the `str_replace` tool is used to edit code: - -1. **Configuration Check**: goose checks if all three environment variables are properly set and non-empty. - -2. **With AI Enabled**: If configured, goose sends the original code and your requested change to the configured AI model for processing. - -3. **Fallback**: If the AI API is not configured or the API call fails, it falls back to simple string replacement. - -4. **User Feedback**: The first time you use `str_replace` without AI configuration, you'll see a helpful message explaining how to enable the feature. diff --git a/documentation/docs/guides/environment-variables.md b/documentation/docs/guides/environment-variables.md index ce6c62b9f8..5575690012 100644 --- a/documentation/docs/guides/environment-variables.md +++ b/documentation/docs/guides/environment-variables.md @@ -154,16 +154,15 @@ These variables control how goose manages conversation sessions and context. | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_CONTEXT_STRATEGY` | Controls how goose handles context limit exceeded situations | "summarize", "truncate", "clear", "prompt" | "prompt" (interactive), "summarize" (headless) | | `GOOSE_MAX_TURNS` | [Maximum number of turns](/docs/guides/sessions/smart-context-management#maximum-turns) allowed without user input | Integer (e.g., 10, 50, 100) | 1000 | | `GOOSE_GATEWAY_MAX_TURNS` | Maximum number of turns for gateway sessions (e.g., Telegram). Overrides `GOOSE_MAX_TURNS` for gateway traffic only, so chat platforms can keep a stricter cap than CLI/desktop sessions. | Integer (e.g., 5, 10, 25) | Falls back to `GOOSE_MAX_TURNS`, then 5 | | `GOOSE_SUBAGENT_MAX_TURNS` | Sets the maximum turns allowed for a [subagent](/docs/guides/context-engineering/subagents) to complete before timeout. Can be overridden by [`settings.max_turns`](/docs/guides/recipes/recipe-reference#settings) in recipes or subagent tool calls. | Integer (e.g., 25) | 25 | | `GOOSE_MAX_BACKGROUND_TASKS` | Sets the maximum number of concurrent background [subagent](/docs/guides/context-engineering/subagents) tasks goose can run at once | Integer (e.g., 1, 5, 10) | 5 | -| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints"]` | +| `CONTEXT_FILE_NAMES` | Specifies custom filenames for [hint/context files](/docs/guides/context-engineering/using-goosehints#custom-context-files) | JSON array of strings (e.g., `["CLAUDE.md", ".goosehints"]`) | `[".goosehints", "AGENTS.md"]` | | `GOOSE_DISABLE_SESSION_NAMING` | Disables automatic AI-generated session naming; avoids the background model call and keeps the default "CLI Session" (goose CLI) or "New Chat" (goose Desktop) | "1", "true" (case-insensitive) to enable | false | | `GOOSE_DISABLE_TOOL_CALL_SUMMARY` | Disables the per-tool-call AI-generated summary title, keeping the fallback title instead. Saves one provider call per tool invocation. | "1", "true" (case-insensitive) to enable | false | | `GOOSE_PROMPT_EDITOR` | [External editor](/docs/guides/goose-cli-commands#external-editor-mode) to use for composing prompts instead of CLI input | Editor command (e.g., "vim", "code --wait") | Unset (uses CLI input) | -| `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "dark" | +| `GOOSE_CLI_THEME` | [Theme](/docs/guides/goose-cli-commands#themes) for CLI response markdown | "light", "dark", "ansi" | "ansi" | | `GOOSE_CLI_LIGHT_THEME` | Custom [bat theme](https://github.com/sharkdp/bat#adding-new-themes) for syntax highlighting when using light mode | bat theme name (e.g., "Solarized (light)", "OneHalfLight") | "GitHub" | | `GOOSE_CLI_DARK_THEME` | Custom [bat theme](https://github.com/sharkdp/bat#adding-new-themes) for syntax highlighting when using dark mode | bat theme name (e.g., "Dracula", "Nord") | "zenburn" | | `GOOSE_CLI_NEWLINE_KEY` | Customize the keyboard shortcut for [inserting newlines in CLI input](/docs/guides/goose-cli-commands#keyboard-shortcuts) | Single character (e.g., "n", "m") | "j" (Ctrl+J) | @@ -173,20 +172,14 @@ These variables control how goose manages conversation sessions and context. | `GOOSE_MAX_CODE_BLOCK_LINES` | Line count threshold before code blocks are truncated in CLI output. Full content is saved to a temp file. | Positive integer | 50 | | `GOOSE_TRUNCATED_SHOW_LINES` | Number of lines shown before the "... (N more lines)" message when a code block is truncated | Positive integer | 20 | | `GOOSE_NO_CODE_TRUNCATION` | Disable code block truncation entirely — all code blocks are shown in full | "1", "true" (case-insensitive) to enable | false | -| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically summarizes your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 | -| `GOOSE_TOOL_CALL_CUTOFF` | Number of tool calls to keep in full detail before summarizing older tool outputs to help maintain efficient context usage | Integer (e.g., 5, 10, 20) | 10 | +| `GOOSE_AUTO_COMPACT_THRESHOLD` | Set the percentage threshold at which goose [automatically compacts your session](/docs/guides/sessions/smart-context-management#automatic-compaction). | Float between 0.0 and 1.0 (disabled at 0.0) | 0.8 | +| `GOOSE_TOOL_CALL_CUTOFF` | Number of tool calls to keep in full detail before summarizing older tool outputs to help maintain efficient context usage | Integer (e.g., 5, 10, 20) | Computed from the model context limit and auto-compaction threshold | | `GOOSE_MOIM_MESSAGE_TEXT` | Injects persistent text into goose's [working memory](/docs/guides/context-engineering/using-persistent-instructions) every turn. Useful for behavioral guardrails or persistent reminders. | Any text string | Not set | | `GOOSE_MOIM_MESSAGE_FILE` | Path to a file whose contents are injected into goose's [working memory](/docs/guides/context-engineering/using-persistent-instructions) every turn. Supports `~/`. Max 64 KB per file. | File path | Not set | **Examples** ```bash -# Automatically summarize when context limit is reached -export GOOSE_CONTEXT_STRATEGY=summarize - -# Always prompt user to choose (default for interactive mode) -export GOOSE_CONTEXT_STRATEGY=prompt - # Set a low limit for step-by-step control export GOOSE_MAX_TURNS=5 @@ -281,15 +274,15 @@ These variables control how goose handles [tool execution](/docs/guides/managing | Variable | Purpose | Values | Default | |----------|---------|---------|---------| -| `GOOSE_MODE` | Controls how goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "smart_approve" | +| `GOOSE_MODE` | Controls how goose handles tool execution | "auto", "approve", "chat", "smart_approve" | "auto" | | `GOOSE_TOOLSHIM` | Enables/disables tool call interpretation | "1", "true" (case-insensitive) to enable | false | | `GOOSE_TOOLSHIM_OLLAMA_MODEL` | Specifies the model for [tool call interpretation](/docs/experimental/ollama) | Model name (e.g. llama3.2, qwen2.5) | System default | | `GOOSE_CLI_MIN_PRIORITY` | Controls verbosity of [tool output](/docs/guides/managing-tools/adjust-tool-output) | Float between 0.0 and 1.0 | 0.0 | -| `GOOSE_CLI_TOOL_PARAMS_TRUNCATION_MAX_LENGTH` | Maximum length for tool parameter values before truncation in CLI output (not in debug mode) | Integer | 40 | | `GOOSE_DEBUG` | Enables debug mode to show full tool parameters without truncation. Can also be toggled during a session using the `/r` [slash command](/docs/guides/goose-cli-commands#slash-commands) | "1", "true" (case-insensitive) to enable | false | -| `GOOSE_SEARCH_PATHS` | Prepends additional directories to PATH for extension commands | JSON array of paths (for example, `["/usr/local/bin", "~/custom/bin"]`) | System PATH only | +| `GOOSE_SHOW_FULL_OUTPUT` | Shows full tool parameters in CLI output instead of truncating them to the terminal width | true/false | false | +| `GOOSE_SEARCH_PATHS` | Prepends additional directories to PATH for extension commands | JSON array of paths (for example, `["/usr/local/bin", "~/custom/bin"]`) | Built-in search paths followed by the system PATH | | `GOOSE_MAX_TOOL_RESPONSE_SIZE` | Maximum character count for a single tool response before it is written to a temporary file instead of being included inline in the conversation | Positive integer (e.g., 100000, 200000) | 200000 | -| `GOOSE_SHELL` | Overrides the shell used for Developer extension shell commands | Shell executable path or name (for example, `/bin/zsh`, `pwsh`, `C:\cygwin64\bin\bash.exe`) | Unix: `/bin/bash` if present, otherwise `$SHELL`, otherwise `sh`. Windows: `cmd` | +| `GOOSE_SHELL` | Overrides the shell used for Developer extension shell commands | Shell executable path or name (for example, `/bin/zsh`, `pwsh`, `C:\cygwin64\bin\bash.exe`) | Unix: `bash` if found on PATH, otherwise `sh`. Windows: `cmd` | **Examples** @@ -299,11 +292,15 @@ export GOOSE_TOOLSHIM=true export GOOSE_TOOLSHIM_OLLAMA_MODEL=llama3.2 export GOOSE_MODE="auto" export GOOSE_CLI_MIN_PRIORITY=0.2 # Show only medium and high importance output -export GOOSE_CLI_TOOL_PARAMS_MAX_LENGTH=100 # Show up to 100 characters for tool parameters in CLI output +export GOOSE_SHOW_FULL_OUTPUT=true # Show full tool parameters in CLI output # Add custom tool directories for extensions export GOOSE_SEARCH_PATHS='["/usr/local/bin", "~/custom/tools", "/opt/homebrew/bin"]' +# These custom paths are checked before built-in fallback paths such as +# ~/.local/bin, /usr/local/bin on Unix, Homebrew/MacPorts paths on macOS, +# and finally the inherited system PATH. + # Lower the tool response size limit for smaller-context models export GOOSE_MAX_TOOL_RESPONSE_SIZE=100000 @@ -316,37 +313,6 @@ REM Windows: use a POSIX-like shell instead of cmd.exe set GOOSE_SHELL=C:\cygwin64\bin\bash.exe ``` -### Enhanced Code Editing - -These variables configure [AI-powered code editing](/docs/guides/enhanced-code-editing) for the Developer extension's `str_replace` tool. All three variables must be set and non-empty for the feature to activate. - -| Variable | Purpose | Values | Default | -|----------|---------|---------|---------| -| `GOOSE_EDITOR_API_KEY` | API key for the code editing model | API key string | None | -| `GOOSE_EDITOR_HOST` | API endpoint for the code editing model | URL (e.g., "https://api.openai.com/v1") | None | -| `GOOSE_EDITOR_MODEL` | Model to use for code editing | Model name (e.g., "gpt-4o", "claude-sonnet-4") | None | - -**Examples** - -This feature works with any OpenAI-compatible API endpoint, for example: - -```bash -# OpenAI configuration -export GOOSE_EDITOR_API_KEY="sk-..." -export GOOSE_EDITOR_HOST="https://api.openai.com/v1" -export GOOSE_EDITOR_MODEL="gpt-4o" - -# Anthropic configuration (via OpenAI-compatible proxy) -export GOOSE_EDITOR_API_KEY="sk-ant-..." -export GOOSE_EDITOR_HOST="https://api.anthropic.com/v1" -export GOOSE_EDITOR_MODEL="claude-sonnet-4-20250514" - -# Local model configuration -export GOOSE_EDITOR_API_KEY="your-key" -export GOOSE_EDITOR_HOST="http://localhost:8000/v1" -export GOOSE_EDITOR_MODEL="your-model" -``` - ## Security and Privacy These variables control security features, credential storage, and anonymous usage data collection. @@ -390,14 +356,6 @@ When the keyring is disabled (or cannot be accessed and goose [falls back to fil * Windows: `%APPDATA%\Block\goose\config\secrets.yaml` ::: -### macOS Sandbox for goose Desktop - -Optional [macOS sandbox](/docs/guides/sandbox) for goose Desktop that restricts file access, network connections, and process execution using Apple's `sandbox-exec` technology. - -| Variable | Purpose | Values | Default | -|----------|---------|--------|---------| -| `GOOSE_SANDBOX` | Enable the sandbox with [customizable security controls](/docs/guides/sandbox#configuration) | `true` or `1` to enable | `false` | - ## Network Configuration These variables configure network proxy settings for goose. diff --git a/documentation/docs/mcp/developer-mcp.md b/documentation/docs/mcp/developer-mcp.md index 88049d1171..edbac9b036 100644 --- a/documentation/docs/mcp/developer-mcp.md +++ b/documentation/docs/mcp/developer-mcp.md @@ -11,7 +11,7 @@ import { Tornado } from 'lucide-react'; -The Developer extension allows goose to automate developer-centric tasks such as file editing, shell command execution, and project setup. It also provides tools for [enhanced code editing](/docs/guides/enhanced-code-editing) and [codebase analysis](/docs/guides/codebase-analysis). +The Developer extension allows goose to automate developer-centric tasks such as file editing, shell command execution, and project setup. It also provides tools for [codebase analysis](/docs/guides/codebase-analysis). This tutorial will cover enabling and using the Developer MCP Server, which is a built-in goose extension. @@ -247,12 +247,6 @@ import ContentCardCarousel from '@site/src/components/ContentCardCarousel';