diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 3def3d362790..bf2074baadb0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,23 +9,7 @@ We welcome pull requests for general contributions! If you have a larger new fea --- -## πŸŽ‰ Hacktoberfest 2025 πŸŽ‰ - -`goose` is a participating in Hacktoberfest 2025! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone. - -### Here's how you can get started: - -1. Read the [code of conduct](https://github.com/block/.github/blob/main/CODE_OF_CONDUCT.md). -2. Skim the quick AI contribution tips below (and see the [full Responsible AI-Assisted Coding Guide](./ai-assisted-coding-guide.md) for details). -3. Choose a task from this project's Hacktoberfest issues in our [Project Hub](https://github.com/block/goose/issues/4705). Each issue has the 🏷️ `hacktoberfest` label. -4. Comment ".take" on the corresponding issue to get assigned the task. -5. Fork the repository and create a new branch for your work. -6. Make your changes and submit a pull request. -7. Wait for review and address any feedback. - ---- - -### πŸ€– Quick Responsible AI Tips +## πŸ€– Quick Responsible AI Tips If you use Goose, Copilot, Claude, or other AI tools to help with your PRs: @@ -55,34 +39,6 @@ If you use Goose, Copilot, Claude, or other AI tools to help with your PRs: --- -### πŸ† Leaderboard & Prizes - -Every hacktoberfest PR and contribution will earn you points on our [leaderboard](https://github.com/block/goose/issues/4775). Those who end up in the top 20 participants with the most points by the end of October will earn exclusive swag and LLM credits! As you have issues merged, here is a brief explanation on how our automatic points system works. - -#### Point System - -| Weight | Points Awarded | Description | -|---------|-------------|-------------| -| 🐭 **Small** | 5 points | For smaller tasks that take limited time to complete and/or don't require any product knowledge. | -| 🐰 **Medium** | 10 points | For average tasks that take additional time to complete and/or require some product knowledge. | -| πŸ‚ **Large** | 15 points | For heavy tasks that takes lots of time to complete and/or possibly require deep product knowledge. | - -#### Prizes You Can Win - -- **Top 5**: $100 gift card to our [brand new goose swag shop](https://www.gooseswag.xyz/) and $100 of LLM credits! -- **Top 6-10**: $50 gift cards for goose swag shop and $50 of LLM credits! -- **Top 11-20**: $25 of LLM credits! - -Keep an eye on your progress via our [Leaderboard](https://github.com/block/goose/issues/4775). - -### πŸ‘©β€ Need help? - -Need help or have questions? Feel free to reach out by connecting with us in our [Discord community](https://discord.gg/goose-oss) to get direct help from our team in the `#hacktoberfest` project channel. - -Happy contributing! - ---- - ## Prerequisites goose includes rust binaries alongside an electron app for the GUI. To work diff --git a/README.md b/README.md index db7b7f55dd14..df5c911c338c 100644 --- a/README.md +++ b/README.md @@ -17,20 +17,6 @@ _a local, extensible, open source AI agent that automates engineering tasks_

-## πŸŽ‰ Hacktoberfest 2025 πŸŽ‰ - -`goose` is a participating project in Hacktoberfest 2025! We’re so excited for your contributions, and have created a wide variety of issues so that anyone can contribute. Whether you're a seasoned developer or a first-time open source contributor, there's something for everyone. - -### To get started: -1. Read the [contributing guide](https://github.com/block/goose/blob/main/CONTRIBUTING.md). -2. Read the [code of conduct](https://github.com/block/.github/blob/main/CODE_OF_CONDUCT.md). -3. Read the [full Responsible AI-Assisted Coding Guide](./ai-assisted-coding-guide.md). -4. Choose a task from this project's Hacktoberfest issues in our [Project Hub](https://github.com/block/goose/issues/4705) and follow the instructions. Each issue has the 🏷️ `hacktoberfest` label. - -Have questions? Connecting with us in our [Discord community](https://discord.gg/goose-oss) in the `#hacktoberfest` project channel. - ---- - goose is your on-machine AI agent, capable of automating complex development tasks from start to finish. More than just code suggestions, goose can build entire projects from scratch, write and execute code, debug failures, orchestrate workflows, and interact with external APIs - _autonomously_. Whether you're prototyping an idea, refining existing code, or managing intricate engineering pipelines, goose adapts to your workflow and executes tasks with precision. @@ -44,8 +30,13 @@ Designed for maximum flexibility, goose works with any LLM and supports multi-mo - [Installation](https://block.github.io/goose/docs/getting-started/installation) - [Tutorials](https://block.github.io/goose/docs/category/tutorials) - [Documentation](https://block.github.io/goose/docs/category/getting-started) +- [Responsible AI-Assisted Coding Guide](https://github.com/block/goose/blob/main/ai-assisted-coding-guide.md) - [Governance](https://github.com/block/goose/blob/main/GOVERNANCE.md) +## Need Help? +- [Diagnostics & Reporting](https://block.github.io/goose/docs/troubleshooting/diagnostics-and-reporting) +- [Known Issues](https://block.github.io/goose/docs/troubleshooting/known-issues) + # a little goose humor 🦒 > Why did the developer choose goose as their AI agent? diff --git a/documentation/docs/getting-started/installation.md b/documentation/docs/getting-started/installation.md index 93392be7a137..0b521acacff5 100644 --- a/documentation/docs/getting-started/installation.md +++ b/documentation/docs/getting-started/installation.md @@ -44,7 +44,7 @@ import { PanelLeft } from 'lucide-react'; Ensure the `~/.config` directory has read and write access. - Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the [Troubleshooting Guide](/docs/troubleshooting.md#macos-permission-issues) + Goose needs this access to create the log directory and file. Once permissions are granted, the app should load correctly. For steps on how to do this, refer to the [Known Issues Guide](/docs/troubleshooting/known-issues#macos-permission-issues) ::: diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 763f6193f138..3606498446cc 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -12,7 +12,7 @@ Extensions are add-ons that provide a way to extend the functionality of Goose b Extensions are based on the [Model Context Protocol (MCP)](https://github.com/modelcontextprotocol), so you can connect Goose to a wide ecosystem of capabilities. -Goose automatically checks external extensions for known malware before activation. If a malicious package is detected, the [extension will be blocked](/docs/troubleshooting#malicious-package-detected) with a clear error message. +Goose automatically checks external extensions for known malware before activation. If a malicious package is detected, the [extension will be blocked](/docs/troubleshooting/known-issues#malicious-package-detected) with a clear error message. :::tip Tutorials Check out the [step-by-step tutorials](/docs/category/mcp-servers) for adding and using several Goose Extensions @@ -108,7 +108,7 @@ You can also add any other [MCP Server](#mcp-servers) as a Goose extension, even Extensions can be installed directly via the [extensions directory][extensions-directory], CLI, or UI. :::warning Airgapped Environments -If you're in a corporate or airgapped environment and extensions fail to activate, see [Airgapped/Offline Environments](/docs/troubleshooting#airgappedoffline-environment-issues) for workarounds. +If you're in a corporate or airgapped environment and extensions fail to activate, see [Airgapped/Offline Environments](/docs/troubleshooting/known-issues#airgappedoffline-environment-issues) for workarounds. ::: ### MCP Servers diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index e137fdc99b05..f1d28e03eea2 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -207,6 +207,45 @@ goose session export --path ./my-session.jsonl --output exported.md --- +#### session diagnostics [options] +Generate a comprehensive diagnostics bundle for troubleshooting issues with a specific session. + +**Options:** +- **`-i, --id `**: Generate diagnostics for a specific session by ID +- **`-n, --name `**: Generate diagnostics for a specific session by name +- **`-o, --output `**: Save diagnostics bundle to a specific file path (default: `diagnostics_{session_id}.zip`) + +**What's included:** +- **System Information**: App version, operating system, architecture, and timestamp +- **Session Data**: Complete conversation messages and history for the specified session +- **Configuration Files**: Your [configuration files](/docs/guides/config-files) (if they exist) +- **Log Files**: Recent application logs for debugging + +**Usage:** +```bash +# Generate diagnostics for a specific session by ID +goose session diagnostics --id 20250305_113223 + +# Generate diagnostics for a session by name +goose session diagnostics --name my-project-session + +# Save diagnostics to a custom location +goose session diagnostics --id 20250305_113223 --output /path/to/my-diagnostics.zip + +# Interactive selection (prompts you to choose a session) +goose session diagnostics +``` + +:::warning Privacy Notice +Diagnostics bundles contain your session messages and system information. If your session includes sensitive data (API keys, personal information, proprietary code), review the contents before sharing publicly. +::: + +:::tip +Generate diagnostics before reporting bugs to provide technical details that help with faster resolution. The ZIP file can be attached to GitHub issues or shared with support. +::: + +--- + ### Task Execution #### run [options] diff --git a/documentation/docs/guides/security/prompt-injection-detection.md b/documentation/docs/guides/security/prompt-injection-detection.md index 9d82f57887a5..35d565cd530a 100644 --- a/documentation/docs/guides/security/prompt-injection-detection.md +++ b/documentation/docs/guides/security/prompt-injection-detection.md @@ -78,7 +78,7 @@ When in doubt, deny. Beyond prompt injection detection, goose automatically: - Warns you before running new or updated recipes - Warns you when importing recipes that contain invisible Unicode Tag Block characters -- [Checks for known malware](/docs/troubleshooting#malicious-package-detected) when installing extensions for locally-run MCP servers +- [Checks for known malware](/docs/troubleshooting/known-issues#malicious-package-detected) when installing extensions for locally-run MCP servers ::: ### Configuring Detection Threshold diff --git a/documentation/docs/guides/sessions/session-management.md b/documentation/docs/guides/sessions/session-management.md index a2bd8cffea27..1e261d0e12b3 100644 --- a/documentation/docs/guides/sessions/session-management.md +++ b/documentation/docs/guides/sessions/session-management.md @@ -263,7 +263,7 @@ Search allows you to find specific content within sessions or find specific sess ``` :::tip - While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting#stuck-in-a-loop-or-unresponsive). + While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of [doom spiraling](/docs/troubleshooting/known-issues#stuck-in-a-loop-or-unresponsive). ::: diff --git a/documentation/docs/guides/tips.md b/documentation/docs/guides/tips.md index 22622f05291e..7b1b29c0a5a4 100644 --- a/documentation/docs/guides/tips.md +++ b/documentation/docs/guides/tips.md @@ -54,4 +54,4 @@ Use [lead/worker model](/docs/tutorials/lead-worker/) to have goose use a "lead" Write [recipes](/docs/guides/recipes/session-recipes) that check your current state before acting, so they can be run multiple times without causing any errors or duplication. ### Add Logging to Recipes -Inlcude informative log messages in your recipes for each major step to make debugging and troubleshooting easier should something fail. +Include informative log messages in your recipes for each major step to make debugging and troubleshooting easier should something fail. diff --git a/documentation/docs/troubleshooting/_category_.json b/documentation/docs/troubleshooting/_category_.json new file mode 100644 index 000000000000..3b23b8df446d --- /dev/null +++ b/documentation/docs/troubleshooting/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Troubleshooting", + "position": 40, + "description": "Get help, report issues, and troubleshoot common problems with goose." +} diff --git a/documentation/docs/troubleshooting/diagnostics-and-reporting.md b/documentation/docs/troubleshooting/diagnostics-and-reporting.md new file mode 100644 index 000000000000..5b36565d90fd --- /dev/null +++ b/documentation/docs/troubleshooting/diagnostics-and-reporting.md @@ -0,0 +1,149 @@ +--- +title: Diagnostics and Reporting +sidebar_label: Diagnostics and Reporting +description: Use built-in diagnostics, report bugs, and request new features with goose's integrated support tools. +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import { PanelLeft, Bug, MessageSquarePlus, Download } from 'lucide-react'; + +goose provides several built-in features to help you get support, report issues, and request new functionality. This guide covers the diagnostics system, bug reporting, and feature request tools. + +| Feature | Purpose | Location | Output | +|---------|---------|----------|---------| +| **Diagnostics** | Generate troubleshooting data | Chat input toolbar | ZIP file with system info, logs, and session data | +| **Report a Bug** | Submit bug reports | Settings β†’ Help & feedback | Opens GitHub issue template | +| **Request a Feature** | Suggest new features | Settings β†’ Help & feedback | Opens GitHub issue template | + +## Diagnostics System + +The diagnostics feature creates a comprehensive troubleshooting bundle that includes system information, session data, configuration files, and recent logs. This is invaluable for debugging issues or getting technical support. + +### Generating Diagnostics + + + + 1. In an active chat session, look for the icon in the bottom toolbar + 2. Click the diagnostics button + 3. Review the information in the modal about what data will be collected + 4. Click `Download` to generate and save the diagnostics bundle + 5. The ZIP file will be saved as `diagnostics_{session_id}.zip` + + :::tip + The diagnostics button is only available when you have an active session, as it needs a session ID to generate the bundle. + ::: + + + Use the session diagnostics command to generate a troubleshooting bundle. For complete details and all available options, see the [CLI Commands guide](/docs/guides/goose-cli-commands#session-diagnostics-options). + + ```sh + # Generate diagnostics for a specific session + goose session diagnostics --id + + # Interactive selection (prompts you to choose a session) + goose session diagnostics + + # Save to a custom location + goose session diagnostics --id --output /path/to/diagnostics.zip + ``` + + To find your session ID, first list available sessions: + + ```sh + goose session list + ``` + + Example output: + ``` + Available sessions: + abc123def - My coding session - 2024-01-15 14:30:22 + xyz789ghi - Documentation work - 2024-01-15 10:15:45 + ``` + + + +### Using Diagnostics Data + +The diagnostics ZIP file contains several folders: + +``` +diagnostics_abc123def.zip +β”œβ”€β”€ logs/ +β”‚ β”œβ”€β”€ goose-2024-01-15.jsonl +β”‚ β”œβ”€β”€ goose-2024-01-14.jsonl +β”‚ └── ... +β”œβ”€β”€ session.json # Your session messages +β”œβ”€β”€ config.yaml # Configuration files (if they exist) +└── system.txt # System information +``` + +**When to generate diagnostics:** +- Experiencing crashes or unexpected behavior +- Getting error messages you don't understand +- Performance issues or slow responses +- Before reporting bugs to include technical details + +**What's included in diagnostics:** +- **System Information**: App version, operating system, architecture, and timestamp +- **Session Data**: Your current conversation messages and history +- **Configuration Files**: Your [configuration files](/docs/guides/config-files) (if they exist) +- **Log Files**: Recent application logs for debugging + +:::warning Privacy Notice +Diagnostics bundles contain your session messages and system information. If your session includes sensitive data (API keys, personal information, proprietary code), review the contents before sharing publicly. +::: + +## Bug Reports + +The bug report feature opens a structured GitHub issue template to help you provide all necessary information for effective bug reporting. + +### Creating Bug Reports + + + + 1. Click the button in the top-left to open the sidebar + 2. Click `Settings` in the sidebar + 3. Scroll down to the `Help & feedback` section + 4. Click `Report a Bug` + 5. This opens GitHub in your browser with a pre-filled bug report template + + + For CLI users, navigate directly to the GitHub repository: + + ``` + https://github.com/block/goose/issues/new?template=bug_report.md + ``` + + + +## Feature Requests + +The feature request system helps you suggest improvements and new functionality for goose. + +### Submitting Feature Requests + + + + 1. Click the button in the top-left to open the sidebar + 2. Click `Settings` in the sidebar + 3. Scroll down to the `Help & feedback` section + 4. Click `Request a Feature` + 5. This opens GitHub in your browser with a feature request template + + + Navigate directly to the GitHub repository: + + ``` + https://github.com/block/goose/issues/new?template=feature_request.md + ``` + + + +## Additional Debugging + +For issues not resolved by diagnostics: + +- **[Session and System Logs](/docs/guides/logs)**: View detailed logs for debugging individual sessions +- **[Telemetry Export](/docs/guides/environment-variables#observability)**: Configure telemetry for performance analysis and production monitoring + diff --git a/documentation/docs/troubleshooting/index.mdx b/documentation/docs/troubleshooting/index.mdx new file mode 100644 index 000000000000..533defbe3275 --- /dev/null +++ b/documentation/docs/troubleshooting/index.mdx @@ -0,0 +1,50 @@ +--- +title: Troubleshooting +hide_title: true +description: Get help, report issues, and troubleshoot common problems with goose. +--- + +import Card from '@site/src/components/Card'; +import styles from '@site/src/components/Card/styles.module.css'; + +

Troubleshooting

+

+ Get help when you need it, report bugs, request features, and find solutions to common issues. goose provides built-in diagnostics and direct links to our support channels. +

+ +
+

πŸ› οΈ Getting Help

+
+ + + +
+
+ +
+

πŸ’¬ Community Support

+
+ + +
+
diff --git a/documentation/docs/troubleshooting.md b/documentation/docs/troubleshooting/known-issues.md similarity index 95% rename from documentation/docs/troubleshooting.md rename to documentation/docs/troubleshooting/known-issues.md index 65452b810c7b..8bb34e0370d1 100644 --- a/documentation/docs/troubleshooting.md +++ b/documentation/docs/troubleshooting/known-issues.md @@ -1,11 +1,15 @@ --- -title: Troubleshooting +title: Known Issues +sidebar_label: Known Issues +description: Comprehensive troubleshooting guide for common goose problems with step-by-step solutions. --- -# Troubleshooting - goose, like any system, may run into occasional issues. This guide provides solutions for common problems. +:::tip Need help with an issue not listed here? +Our [Discord community](https://discord.gg/goose-oss) is here to help! For the fastest support, consider generating a [diagnostic report](/docs/troubleshooting/diagnostics-and-reporting) - it helps us understand your setup quickly. +::: + ### goose Edits Files goose can and will edit files as part of its workflow. To avoid losing personal changes, use version control to stage your personal edits. Leave goose edits unstaged until reviewed. Consider separate commits for goose's edits so you can easily revert them if needed. @@ -38,14 +42,7 @@ You can prevent these issues by customizing your shell to handle these commands --- -### Debugging and Diagnostics - -To help with troubleshooting issues, you can: - -- View [session and system logs](/docs/guides/logs) for debugging individual sessions -- Configure [telemetry export](/docs/guides/environment-variables#observability) for performance analysis, trend monitoring, or production/CI debugging ---- ### Context Length Exceeded Error @@ -466,7 +463,12 @@ goose Desktop uses **"shims"** (packaged versions of `npx` and `uvx`) that autom --- ### Need Further Help? -If you have questions, run into issues, or just need to brainstorm ideas join the [Discord Community][discord]! + +Still running into issues? We're here to help! Join our [Discord Community][discord] where the goose team and community members are happy to assist. + +:::tip +If you can share a [diagnostic report](/docs/troubleshooting/diagnostics-and-reporting#diagnostics-system) along with your question, it helps us understand your setup and provide more targeted solutions. +:::