diff --git a/documentation/docs/getting-started/using-extensions.md b/documentation/docs/getting-started/using-extensions.md index 23776cb383de..c27ca8fb0380 100644 --- a/documentation/docs/getting-started/using-extensions.md +++ b/documentation/docs/getting-started/using-extensions.md @@ -33,6 +33,7 @@ goose operates autonomously by default. Combined with the Developer extension's In addition, these platform extensions provide core goose functionality. They are also always available and enabled by default: +- Chat Recall: Search conversation content across all your session history - Extension Manager: Discover, enable, and disable extensions dynamically during sessions - [Todo](/docs/mcp/todo-mcp): Manage task lists and track progress across sessions diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 47b18dc3bc6f..c17dd10e38cc 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -5,22 +5,9 @@ sidebar_label: CLI Commands toc_max_heading_level: 4 --- -Goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. This guide covers all available CLI commands and interactive session features. +goose provides a command-line interface (CLI) with several commands for managing sessions, configurations and extensions. This guide covers all available CLI commands and interactive session features. -## Flag Naming Conventions -Goose CLI follows consistent patterns for flag naming to make commands intuitive and predictable: - -- **`--session-id`**: Used for session identifiers (e.g., `20250305_113223`) -- **`--schedule-id`**: Used for schedule job identifiers (e.g., `daily-report`) -- **`-n, --name`**: Used for human-readable names -- **`-p, --path`**: Used for file paths (legacy support) -- **`-o, --output`**: Used for output file paths -- **`-r, --resume` or `-r, --regex`**: Context-dependent (resume for sessions, regex for filters) -- **`-v, --verbose`**: Used for verbose output -- **`-l, --limit`**: Used for limiting result counts -- **`-f, --format`**: Used for specifying output formats -- **`-w, --working-dir`**: Used for working directory filters ### Core Commands @@ -35,7 +22,7 @@ goose --help --- #### configure -Configure Goose settings - providers, extensions, etc. +Configure goose settings - providers, extensions, etc. **Usage:** ```bash @@ -45,7 +32,7 @@ goose configure --- #### info [options] -Shows Goose information, including the version, configuration file location, session storage, and logs. +Shows goose information, including the version, configuration file location, session storage, and logs. **Options:** - **`-v, --verbose`**: Show detailed configuration settings, including environment variables and enabled extensions @@ -58,7 +45,7 @@ goose info --- #### version -Check the current Goose version you have installed. +Check the current goose version you have installed. **Usage:** ```bash @@ -68,11 +55,11 @@ goose --version --- #### update [options] -Update the Goose CLI to a newer version. +Update the goose CLI to a newer version. **Options:** - **`--canary, -c`**: Update to the canary (development) version instead of the stable version -- **`--reconfigure, -r`**: Forces Goose to reset configuration settings during the update process +- **`--reconfigure, -r`**: Forces goose to reset configuration settings during the update process **Usage:** ```bash @@ -90,11 +77,16 @@ goose update --reconfigure ### Session Management +:::info Session Storage Migration +Starting with version 1.10.0, goose uses a SQLite database (`sessions.db`) instead of individual `.jsonl` files. +Your existing sessions are automatically imported to the database. Legacy `.jsonl` files remain on disk but are no longer managed by goose. +::: + #### session [options] Start or resume interactive chat sessions. **Basic Options:** -- **`--session-id `**: Specify a session by its ID (e.g., '20250921_143022') +- **`--session-id `**: Specify a session by its ID (e.g., '20251108_1') - **`-n, --name `**: Give the session a name - **`-p, --path `**: Legacy parameter for specifying session by file path - **`-r, --resume`**: Resume a previous session @@ -114,8 +106,9 @@ goose session -n my-project # Resume a previous session goose session --resume -n my-project -goose session --resume --session-id 20250620_013617 -goose session --resume -p ./session.jsonl +goose session --resume --session-id 20251108_2 +goose session --resume -p ./session.json # exported session +goose session --resume -p ./session.jsonl # legacy session storage # Start with extensions goose session --with-extension "npx -y @modelcontextprotocol/server-memory" @@ -139,23 +132,27 @@ goose session -n my-session --debug --max-turns 25 List all saved sessions. **Options:** -- **`-v, --verbose`**: Include session file paths in the output - **`-f, --format `**: Specify output format (`text` or `json`). Default is `text` - **`--ascending`**: Sort sessions by date in ascending order (oldest first) +- **`-p, --working-dir `**: Filter sessions by working directory +- **`-l, --limit `**: Limit the number of results **Usage:** ```bash # List all sessions in text format (default) goose session list -# List sessions with file paths -goose session list --verbose - # List sessions in JSON format goose session list --format json # Sort sessions by date in ascending order goose session list --ascending + +# Filter sessions by working directory +goose session list -p ~/projects/myapp + +# List only the 10 most recent sessions +goose session list --limit 10 ``` --- @@ -164,18 +161,16 @@ goose session list --ascending Remove one or more saved sessions. **Options:** -- **`--session-id `**: Remove a specific session by its session ID -- **`-n, --name `**: Remove a specific session by its name -- **`-r, --regex `**: Remove sessions matching a regex pattern +- **`-i, --id `**: Remove a specific session by its session ID +- **`-r, --regex `**: Remove sessions matching a regex pattern **Usage:** ```bash -# Remove a specific session by ID -goose session remove --session-id 20250305_113223 -goose session remove --id 20250305_113223 +# Interactive removal (prompts you to choose sessions) +goose session remove -# Remove a specific session by its name -goose session remove -n my-session +# Remove a specific session by ID +goose session remove -i 20251108_3 # Remove all sessions starting with "project-" goose session remove -r "project-.*" @@ -185,7 +180,7 @@ goose session remove -r ".*migration.*" ``` :::caution -Session removal is permanent and cannot be undone. Goose will show which sessions will be removed and ask for confirmation before deleting. +Session removal is permanent and cannot be undone. goose will show which sessions will be removed and ask for confirmation before deleting. ::: --- @@ -194,9 +189,9 @@ Session removal is permanent and cannot be undone. Goose will show which session Export sessions in different formats for backup, sharing, migration, or documentation purposes. **Options:** -- **`--session-id `**: Export a specific session by session ID +- **`-i, --id `**: Export a specific session by ID - **`-n, --name `**: Export a specific session by name -- **`-p, --path `**: Export a specific session by file path (legacy) +- **`-p, --path `**: Export a specific session by file path - **`-o, --output `**: Save exported content to a file (default: stdout) - **`--format `**: Output format: `markdown`, `json`, `yaml`. Default is `markdown` @@ -217,7 +212,7 @@ goose session export -n my-session --format json -o session-backup.json goose session export -n my-session -o session.md # Export to stdout in different formats -goose session export --session-id 20250305_113223 --format json +goose session export -i 20251108_4 --format json goose session export -n my-session --format yaml # Export session by path (legacy) @@ -243,13 +238,13 @@ Generate a comprehensive diagnostics bundle for troubleshooting issues with a sp **Usage:** ```bash # Generate diagnostics for a specific session by ID -goose session diagnostics --session-id 20250305_113223 +goose session diagnostics --session-id 20251108_5 # Generate diagnostics for a session by name goose session diagnostics --name my-project-session # Save diagnostics to a custom location -goose session diagnostics --session-id 20250305_113223 --output /path/to/my-diagnostics.zip +goose session diagnostics --session-id 20251108_5 --output /path/to/my-diagnostics.zip # Interactive selection (prompts you to choose a session) goose session diagnostics @@ -272,14 +267,14 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/ **Input Options:** - **`-i, --instructions `**: Path to instruction file containing commands. Use `-` for stdin -- **`-t, --text `**: Input text to provide to Goose directly +- **`-t, --text `**: Input text to provide to goose directly - **`--recipe `**: Load a custom recipe in current session **Session Options:** - **`-s, --interactive`**: Continue in interactive mode after processing initial input - **`-n, --name `**: Name for this run session (e.g. `daily-tasks`) - **`-r, --resume`**: Resume from a previous run -- **`-p, --path `**: Path for this run session (e.g. `./playground.jsonl`) +- **`-p, --path `**: Path for this run session (e.g. `./playground.jsonl`). Used for legacy file-based session storage. - **`--no-session`**: Run goose commands without creating or storing a session file **Extension Options:** @@ -300,7 +295,7 @@ Execute commands from an instruction file or stdin. Check out the [full guide](/ # Run from instruction file goose run --instructions plan.md -# Load a recipe with a prompt that Goose executes and then exits +# Load a recipe with a prompt that goose executes and then exits goose run --recipe recipe.yaml # Load a recipe and stay in an interactive session @@ -385,7 +380,7 @@ Automate recipes by running them on a [schedule](/docs/guides/recipes/session-re - `run-now`: Run a scheduled recipe immediately **Options:** -- `--schedule-id `: A unique ID for the scheduled job (e.g. `daily-report`) +- `--id `: A unique ID for the scheduled job (e.g. `daily-report`) - `--cron "* * * * * *"`: Specifies when a job should run using a [cron expression](https://en.wikipedia.org/wiki/Cron#Cron_expression) - `--recipe-source `: Path to the recipe YAML file - `-l, --limit `: Max number of sessions to display when using the `sessions` command @@ -395,19 +390,19 @@ Automate recipes by running them on a [schedule](/docs/guides/recipes/session-re goose schedule # Add a new scheduled recipe which runs every day at 9 AM -goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml +goose schedule add --id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml # List all scheduled jobs goose schedule list -# List the 10 most recent Goose sessions created by a scheduled job -goose schedule sessions --schedule-id daily-report -l 10 +# List the 10 most recent goose sessions created by a scheduled job +goose schedule sessions --id daily-report -l 10 # Run a recipe immediately -goose schedule run-now --schedule-id daily-report +goose schedule run-now --id daily-report # Remove a scheduled job -goose schedule remove --schedule-id daily-report +goose schedule remove --id daily-report ``` --- @@ -423,7 +418,7 @@ goose mcp --- #### acp -Run Goose as an Agent Client Protocol (ACP) agent server over stdio. This enables Goose to work with ACP-compatible clients like Zed. +Run goose as an Agent Client Protocol (ACP) agent server over stdio. This enables goose to work with ACP-compatible clients like Zed. ACP is an emerging protocol specification that standardizes communication between AI agents and client applications, making it easier for clients to integrate with various AI agents. @@ -433,7 +428,7 @@ goose acp ``` :::info -This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using Goose in ACP Clients](/docs/guides/acp-clients) for details. +This command is automatically invoked by ACP-compatible clients and is not typically run directly by users. The client manages the lifecycle of the `goose acp` process. See [Using goose in ACP Clients](/docs/guides/acp-clients) for details. ::: --- @@ -467,11 +462,11 @@ goose projects ### Interface #### web -Start a new session in Goose Web, a lightweight web-based interface launched via the CLI that mirrors the desktop app's chat experience. +Start a new session in goose Web, a lightweight web-based interface launched via the CLI that mirrors the desktop app's chat experience. -Goose Web is particularly useful when: -- You want to access Goose with a graphical interface without installing the desktop app -- You need to use Goose from different devices, including mobile +goose Web is particularly useful when: +- You want to access goose with a graphical interface without installing the desktop app +- You need to use goose from different devices, including mobile - You're working in an environment where installing desktop apps isn't practical :::warning @@ -555,7 +550,7 @@ Once you're in an interactive session (via `goose session` or `goose run --inter ### Themes -The `/t` command controls the syntax highlighting theme for markdown content in Goose CLI responses. This affects the styles used for headers, code blocks, bold/italic text, and other markdown elements in the response output. +The `/t` command controls the syntax highlighting theme for markdown content in goose CLI responses. This affects the styles used for headers, code blocks, bold/italic text, and other markdown elements in the response output. **Commands:** - `/t` - Cycles through themes: `light` → `dark` → `ansi` → `light` @@ -571,7 +566,7 @@ The `/t` command controls the syntax highlighting theme for markdown content in :::info Syntax highlighting styles only affect the font, not the overall terminal interface. The `light` and `dark` themes have subtle differences in font color and weight. -The Goose CLI theme is independent from the Goose Desktop theme. +The goose CLI theme is independent from the goose Desktop theme. ::: **Examples:** @@ -605,10 +600,10 @@ goose session --name use-custom-theme ### Command History Search -The `Ctrl+R` shortcut provides interactive search through your stored CLI [command history](/docs/guides/logs#command-history). This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, Goose searches backwards through your history for matches. +The `Ctrl+R` shortcut provides interactive search through your stored CLI [command history](/docs/guides/logs#command-history). This feature makes it easy to find and reuse recent commands without retyping them. When you type a search term, goose searches backwards through your history for matches. **How it works:** -1. Press `Ctrl+R` in your Goose CLI session +1. Press `Ctrl+R` in your goose CLI session 2. Type a search term 3. Navigate through the results using: - `Ctrl+R` to cycle backwards through earlier matches diff --git a/documentation/docs/guides/logs.md b/documentation/docs/guides/logs.md index 013a6ddf455d..2a8b6fe92952 100644 --- a/documentation/docs/guides/logs.md +++ b/documentation/docs/guides/logs.md @@ -1,25 +1,25 @@ --- -title: Goose Logging System +title: goose Logging System sidebar_label: Logging System sidebar_position: 65 --- -Goose uses a unified storage system for conversations and interactions. All conversations and interactions (both CLI and Desktop) are stored **locally** in the following locations: +goose uses a unified storage system for conversations and interactions. All conversations and interactions (both CLI and Desktop) are stored **locally** in the following locations: | **Type** | **Unix-like (macOS, Linux)** | **Windows** | |---------------------|----------------------------------------|---------------------------------------------| | **Command History** | `~/.config/goose/history.txt` | `%APPDATA%\Block\goose\data\history.txt` | -| **Session Records** | `~/.local/share/goose/sessions/` | `%APPDATA%\Block\goose\data\sessions\` | +| **Session Records** | `~/.local/share/goose/sessions/sessions.db` | `%APPDATA%\Block\goose\data\sessions\sessions.db` | | **System Logs** | `~/.local/state/goose/logs/` | `%APPDATA%\Block\goose\data\logs\` | :::info Privacy -Goose is a local application and all log files are stored locally. These logs are never sent to external servers or third parties, ensuring that all data remains private and under your control. +goose is a local application and all log files are stored locally. These logs are never sent to external servers or third parties, ensuring that all data remains private and under your control. ::: ## Command History -Goose stores command history persistently across chat sessions, allowing Goose to recall previous commands. +goose stores command history persistently across chat sessions, allowing goose to recall previous commands. Command history logs are stored in: @@ -28,31 +28,26 @@ Command history logs are stored in: ## Session Records -Goose maintains session records in `~/.local/share/goose/sessions/` that track the conversation history and interactions for each session. These files use the `.jsonl` format (JSON Lines), where each line is a valid JSON object representing a message or interaction. - -Session files are named with the pattern `[session-id].jsonl` where the session ID matches the identifier used in the corresponding log files. For example, `ccK9OTmS.jsonl` corresponds to log files like `20250211_133920-ccK9OTmS.log`. - -Each session file contains a chronological record of: -- User messages and commands (commands are also stored persistently in `history.txt`) -- Assistant (Goose) responses -- Tool requests and their results -- Timestamps for all interactions -- Role information (user/assistant) -- Message content and formatting -- Tool call details including: - - Tool IDs - - Arguments passed - - Results returned - - Success/failure status - -Each line in a session file is a JSON object with the following key fields: -- `role`: Identifies the source ("user" or "assistant") -- `created`: Timestamp of the interaction -- `content`: Array of interaction elements, which may include: - - Text messages - - Tool requests - - Tool responses - - Error messages +goose maintains session records that track the conversation history and interactions for each session. +Sessions are stored in an SQLite database at: +- **Unix-like**: `~/.local/share/goose/sessions/sessions.db` +- **Windows**: `%APPDATA%\Block\goose\data\sessions\sessions.db` + +:::info Session Storage Migration +Prior to version 1.10.0, goose stored session records in individual `.jsonl` files under `~/.local/share/goose/sessions/`. +When you upgrade to v1.10.0 or later, your existing sessions are automatically imported into the database. Legacy `.jsonl` files remain on disk but are no longer managed by goose. +::: + +This database contains all saved session data including: +- Session metadata (ID, name, working directory, timestamps) +- Conversation messages (user commands, assistant responses, role information) +- Tool calls and results (IDs, arguments, responses, success/failure status) +- Token usage statistics +- Extension data and configuration + +Session IDs are named using `YYYYMMDD_` format, for example: `20250310_2`. goose CLI outputs the session ID at the start of each session. To get session IDs, use [`goose session list` command](/docs/guides/goose-cli-commands#session-list-options) to see all available sessions. + +Also see [Session Management](/docs/guides/sessions/session-management) for details about searching sessions. ## System Logs @@ -78,7 +73,7 @@ The desktop application maintains its own logs: * macOS: `~/Library/Application Support/Goose/logs/main.log` * Windows: `%APPDATA%\Block\goose\logs\main.log` -The Desktop application follows platform conventions for its own operational logs and state data, but uses the standard Goose [session records](#session-records) for actual conversations and interactions. This means your conversation history is consistent regardless of which interface you use to interact with Goose. +The Desktop application follows platform conventions for its own operational logs and state data, but uses the standard goose [session records](#session-records) for actual conversations and interactions. This means your conversation history is consistent regardless of which interface you use to interact with goose. ### CLI Logs @@ -107,7 +102,7 @@ Server logs are stored in: * Unix-like: `~/.local/state/goose/logs/server/` * Windows: `%APPDATA%\Block\goose\data\logs\server\` -The Server logs contain information about the Goose daemon (`goosed`), which is a local server process that runs on your computer. This server component manages communication between the CLI, extensions, and LLMs. +The Server logs contain information about the goose daemon (`goosed`), which is a local server process that runs on your computer. This server component manages communication between the CLI, extensions, and LLMs. Server logs include: * Server initialization details diff --git a/documentation/docs/guides/multi-model/creating-plans.md b/documentation/docs/guides/multi-model/creating-plans.md index bd5f37acac80..a6ced54a5f77 100644 --- a/documentation/docs/guides/multi-model/creating-plans.md +++ b/documentation/docs/guides/multi-model/creating-plans.md @@ -13,23 +13,23 @@ Starting a project without a clear plan is like building a house without a bluep * Wasted time and effort * Projects that grow too big -A good plan keeps everyone on track and helps measure progress. That's why the Goose CLI includes the `/plan` prompt completion command to help break down your projects into clear, manageable steps. +A good plan keeps everyone on track and helps measure progress. That's why the goose CLI includes the `/plan` prompt completion command to help break down your projects into clear, manageable steps. -:::tip Plans in the Goose Desktop -The Goose Desktop doesn't have a `plan` keyword. If you want Goose Desktop to create a plan for you, you need to use a prompt like: +:::tip Plans in the goose Desktop +The goose Desktop doesn't have a `plan` keyword. If you want goose Desktop to create a plan for you, you need to use a prompt like: ``` -"Hey Goose, can you create a plan to convert my CLI project into a locally hosted web page that gives me input fields for each CLI command I can run? Please don't start the actual work" +"Hey goose, can you create a plan to convert my CLI project into a locally hosted web page that gives me input fields for each CLI command I can run? Please don't start the actual work" ``` -Unless you ask Goose to "create a plan", it might just start into the project work. +Unless you ask goose to "create a plan", it might just start into the project work. ::: -The Goose CLI's plan mode is interactive, asking clarifying questions to understand your project before creating a plan. If you can provide thoughtful and informative answers to those questions, Goose can generate a really useful and actionable plan. +The goose CLI's plan mode is interactive, asking clarifying questions to understand your project before creating a plan. If you can provide thoughtful and informative answers to those questions, goose can generate a really useful and actionable plan. ## Set your planner provider and model In some workflows, it can be helpful to use one LLM for planning and a different one for execution. For example, GPT-4.1 tends to excel at strategic planning and breaking down complex tasks into clear, logical steps. On the other hand, Claude Sonnet 3.5 is particularly strong at writing clean, efficient code and following instructions precisely. By using GPT-4.1 to plan and Claude to execute, you can play to the strengths of both models and get better results overall. -The Goose CLI plan mode uses two configuration values: +The goose CLI plan mode uses two configuration values: - `GOOSE_PLANNER_PROVIDER`: Which provider to use for planning - `GOOSE_PLANNER_MODEL`: Which model to use for planning @@ -40,15 +40,15 @@ goose also supports two options for automatic model switching that help balance - **[AutoPilot](/docs/guides/multi-model/autopilot)**: Context-aware switching between multiple models ::: -### Set Goose planner environment variables +### Set goose planner environment variables You might add these lines to your bash shell config file (.bashrc) to add the planner environment variables: ```bash export GOOSE_PLANNER_PROVIDER= export GOOSE_PLANNER_MODEL= ``` -After you save your changes to the config file, you need to re-start your Goose session so that Goose can use the variables. +After you save your changes to the config file, you need to re-start your goose session so that goose can use the variables. -If these aren't set, Goose will use your default provider and model settings. You might want to set different planning models if you find certain models are better at breaking down tasks into clear steps. However, your default model configuration is usually sufficient. +If these aren't set, goose will use your default provider and model settings. You might want to set different planning models if you find certain models are better at breaking down tasks into clear steps. However, your default model configuration is usually sufficient. To verify that the planner provider is set, input the following terminal command: @@ -59,15 +59,15 @@ To verify that the planner provider is set, input the following terminal command In this example, the `info` command returns the current configuration and the path to the configuration file. ```bash -Goose Version: +goose Version: Version: 1.0.18 -Goose Locations: +goose Locations: Config file: /Users/alincoln/.config/goose/config.yaml Sessions dir: /Users/alincoln/.local/share/goose/sessions Logs dir: /Users/alincoln/.local/state/goose/logs -Goose Configuration: +goose Configuration: GOOSE_PROVIDER: anthropic GOOSE_MODEL: claude-3.5-sonnet GOOSE_PLANNER_PROVIDER: openai @@ -78,10 +78,10 @@ Goose Configuration: If either `GOOSE_PLANNER_PROVIDER` or `GOOSE_PLANNER_MODEL` are not set, `GOOSE_PROVIDER` and `GOOSE_MODEL`are used to build your plan. ## Describe your project -While Goose can handle complex project descriptions, it works best with clear, concise ones. Focus on stating your project's purpose and desired outcomes. If these aren't clear, Goose will ask clarifying questions until it fully understands your goals. +While goose can handle complex project descriptions, it works best with clear, concise ones. Focus on stating your project's purpose and desired outcomes. If these aren't clear, goose will ask clarifying questions until it fully understands your goals. ## A simple construction plan example -Goose can produce good plans for relatively simple projects such as the home construction example: +goose can produce good plans for relatively simple projects such as the home construction example: ```bash ( O)> /plan @@ -143,7 +143,7 @@ Given that no extensions are currently available for more specific tools or data * Search for available extensions using the {} ``` -The home construction plan remains high-level because Goose's current models specialize in technology and software development rather than construction. This is why projects like our first example—building a web application—receive more detailed planning and specific guidance. +The home construction plan remains high-level because goose's current models specialize in technology and software development rather than construction. This is why projects like our first example—building a web application—receive more detailed planning and specific guidance. ### Create a separate plan for plan sub-steps Let's return to the home construction example. While the plan includes hiring an architect, this high-level step needs more detail – such as what type of architect to hire and how to navigate the selection process. @@ -151,7 +151,7 @@ Let's return to the home construction example. While the plan includes hiring an ``` - **Architectural Design**: Hire an architect to design the house, ensuring it meets your space requirements and is energy efficient. Consider factors like natural lighting, insulation, and window placement. ``` -If you exit plan mode while reviewing your construction plan, you can always resume it to continue working with Goose. +If you exit plan mode while reviewing your construction plan, you can always resume it to continue working with goose. ``` ( O)> /plan hire an architect @@ -172,12 +172,12 @@ Entering plan mode. You can provide instructions to create a plan and then act o 10. How involved do you want to be in the design process? ``` -After gathering information through clarifying questions, Goose creates a detailed plan for hiring an architect. This sub-plan integrates with the larger home construction project, with steps that reflect and support the overall construction context. +After gathering information through clarifying questions, goose creates a detailed plan for hiring an architect. This sub-plan integrates with the larger home construction project, with steps that reflect and support the overall construction context. ## A development project example -In this example, a developer has written a CLI in Python that interacts with the Contentful CMS to let a user search for strings and replace them with new strings. As a website, the search/replace feature would be more usable and also allow for a larger set of features. The developer is using the Goose CLI to plan the conversion project. +In this example, a developer has written a CLI in Python that interacts with the Contentful CMS to let a user search for strings and replace them with new strings. As a website, the search/replace feature would be more usable and also allow for a larger set of features. The developer is using the goose CLI to plan the conversion project. -If Goose believes the project can be completed in many different ways and using a wide variety of components, it will ask you a clarifying question for each of these decision points. For example, if you start a plan like this: +If goose believes the project can be completed in many different ways and using a wide variety of components, it will ask you a clarifying question for each of these decision points. For example, if you start a plan like this: ```bash ( O)> /plan @@ -186,10 +186,10 @@ Entering plan mode. You can provide instructions to create a plan and then act o ( O)> Convert the CLI built by search_replace_routes.py into a web page ``` -Goose parses your project description, consults with the LLM mode you've configured, and then if it needs more information, starts a round of clarifying questions. +goose parses your project description, consults with the LLM mode you've configured, and then if it needs more information, starts a round of clarifying questions. ## Clarifying questions -Converting a Python CLI into a website seems simple enough but Goose will have questions about things like styling, authentication, features, technology stack, and more. You might see questions like this: +Converting a Python CLI into a website seems simple enough but goose will have questions about things like styling, authentication, features, technology stack, and more. You might see questions like this: ```bash 1. Should the application support any keyboard shortcuts for common actions? @@ -207,14 +207,14 @@ You can answer the questions one at a time or you can batch your answers: :::tip -When Goose requests a project artifact like source code during plan mode, you'll need to paste the content directly into the chat. Simply copying the file contents and prefixing it with a brief description like 'Here's the requested code:' is sufficient. Note that providing just a file path won't work in plan mode. +When goose requests a project artifact like source code during plan mode, you'll need to paste the content directly into the chat. Simply copying the file contents and prefixing it with a brief description like 'Here's the requested code:' is sufficient. Note that providing just a file path won't work in plan mode. ::: -When answering multiple questions, number your responses to match each question. For example, instead of answering with a simple 'no' or 'don't remember', provide context like '2. Do not store my preferences.' This helps Goose track which questions have been answered and prevents repeated questions. +When answering multiple questions, number your responses to match each question. For example, instead of answering with a simple 'no' or 'don't remember', provide context like '2. Do not store my preferences.' This helps goose track which questions have been answered and prevents repeated questions. -In complex projects like converting a CLI to a website, Goose may ask multiple rounds of clarifying questions. Each round typically stems from new information in your previous answers or when additional details are needed about specific aspects of your project. +In complex projects like converting a CLI to a website, goose may ask multiple rounds of clarifying questions. Each round typically stems from new information in your previous answers or when additional details are needed about specific aspects of your project. -If you've answered _all_ of Gooses questions and it has no more questions, Goose will generate the plan. Other times, you might think Goose will never run out of questions. If you want your plan and don't want to answer more questions, you can simply ask for a "generic" plan: +If you've answered _all_ of goose's questions and it has no more questions, goose will generate the plan. Other times, you might think goose will never run out of questions. If you want your plan and don't want to answer more questions, you can simply ask for a "generic" plan: ```bash I still need some critical information to create a comprehensive plan: @@ -228,7 +228,7 @@ I still need some critical information to create a comprehensive plan: Without this information, I can only provide a generic plan that might not accurately capture your requirements. ( O)> please provde a generic plan ``` -While Goose creates a standardized plan format, it customizes the content based on your answers. Goose can generate the code needed to implement the steps of the plan it produces. You should review the plan and any code that it generates before ending plan mode (`/endplan`) and asking Goose to implement the plan. +While goose creates a standardized plan format, it customizes the content based on your answers. goose can generate the code needed to implement the steps of the plan it produces. You should review the plan and any code that it generates before ending plan mode (`/endplan`) and asking goose to implement the plan. Below is a sample plan for this project, with the generated website code omitted for brevity: @@ -299,22 +299,22 @@ This plan provides a comprehensive framework for converting your CLI script to a ## Basic usage -You need to have an active Goose session before you can put the CLI into plan mode. If you are going to dedicate a session to creating a plan, you should give your new session a name as in the following example: +You need to have an active goose session before you can put the CLI into plan mode. If you are going to dedicate a session to creating a plan, you should give your new session a name as in the following example: ```bash -~ goose session -n web-project-plan -r -resuming session | provider: databricks model: databricks-meta-llama - logging to /Users/alincoln/.local/share/goose/sessions/web-plan.jsonl +~ goose session -n web-project-plan +starting session | provider: databricks model: databricks-meta-llama + session id: 20251110_5 working directory: /Users/alincoln -Goose is running! Enter your instructions, or try asking what goose can do. +goose is running! Enter your instructions, or try asking what goose can do. ``` To enter planning mode, type `/plan`. Optionally, you can append your plan description to the prompt completion command. ```bash ( O)> /plan Build a four bedroom house ``` - Plan mode in the CLI is a special interaction mode where Goose helps break down tasks into manageable steps. If you want to close the plan mode and return to the active session, type `/endplan`. + Plan mode in the CLI is a special interaction mode where goose helps break down tasks into manageable steps. If you want to close the plan mode and return to the active session, type `/endplan`. ```bash ( O)> /endplan diff --git a/documentation/docs/guides/recipes/session-recipes.md b/documentation/docs/guides/recipes/session-recipes.md index 8816c0b963af..7a0870a45633 100644 --- a/documentation/docs/guides/recipes/session-recipes.md +++ b/documentation/docs/guides/recipes/session-recipes.md @@ -261,7 +261,7 @@ You can turn your current goose session into a reusable recipe that includes the - Using a recipe with the Goose CLI might involve the following tasks: + Using a recipe with the goose CLI might involve the following tasks: - [Configuring your recipe location](#configure-recipe-location) - [Running a recipe](#run-a-recipe) - [Scheduling a recipe](#schedule-recipe) @@ -295,30 +295,30 @@ You can turn your current goose session into a reusable recipe that includes the │ ○ Toggle Extensions │ ○ Remove Extension // highlight-start - │ ● Goose Settings (Set the Goose Mode, Tool Output, Tool Permissions, Experiment, Goose recipe github repo and more) + │ ● goose settings (Set the goose mode, Tool Output, Tool Permissions, Experiment, goose recipe github repo and more) // highlight-end │ ◇ What would you like to configure? - │ Goose Settings + │ goose settings │ ◆ What setting would you like to configure? - │ ○ Goose Mode + │ ○ goose mode │ ○ Tool Permission │ ○ Tool Output │ ○ Toggle Experiment // highlight-start - │ ● Goose recipe github repo (Goose will pull recipes from this repo if not found locally.) + │ ● goose recipe github repo (goose will pull recipes from this repo if not found locally.) // highlight-end └ ┌ goose-configure │ ◇ What would you like to configure? - │ Goose Settings + │ goose settings │ ◇ What setting would you like to configure? - │ Goose recipe github repo + │ goose recipe github repo │ - ◆ Enter your Goose Recipe GitHub repo (owner/repo): eg: my_org/goose-recipes + ◆ Enter your goose recipe GitHub repo (owner/repo): eg: my_org/goose-recipes // highlight-start │ squareup/goose-recipes (default) // highlight-end @@ -458,7 +458,7 @@ You can turn your current goose session into a reusable recipe that includes the ## Share Recipe -Share your recipe with Goose users using a recipe link or recipe file. +Share your recipe with goose users using a recipe link or recipe file. :::info Privacy & Isolation Each recipient gets their own private session when using your shared recipe. No data is shared between users, and your original session and recipe remain unaffected. @@ -533,7 +533,7 @@ At the bottom of the `Schedule Details` page you can view the list of sessions c ```bash # Add a new scheduled recipe which runs every day at 9 AM - goose schedule add --schedule-id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml + goose schedule add --id daily-report --cron "0 0 9 * * *" --recipe-source ./recipes/daily-report.yaml ``` You can use either a 5, 6, or 7-digit cron expression for full scheduling precision, following the format "seconds minutes hours day-of-month month day-of-week year". diff --git a/documentation/docs/guides/sessions/session-management.md b/documentation/docs/guides/sessions/session-management.md index 1e261d0e12b3..999f770c91ce 100644 --- a/documentation/docs/guides/sessions/session-management.md +++ b/documentation/docs/guides/sessions/session-management.md @@ -13,49 +13,49 @@ A session is a single, continuous interaction between you and goose, providing a ## Start Session :::info First-time setup -In your first session, Goose prompts you to [set up an LLM (Large Language Model) provider](/docs/getting-started/installation#set-llm-provider). +In your first session, goose prompts you to [set up an LLM (Large Language Model) provider](/docs/getting-started/installation#set-llm-provider). ::: - When you open Goose, you'll see the session interface ready for use. Just type—[or speak](/docs/guides/sessions/in-session-actions#voice-dictation "Learn how to enable voice dictation")—your questions, requests, or instructions directly into the input field, and Goose will immediately get to work. + When you open goose, you'll see the session interface ready for use. Just type—[or speak](/docs/guides/sessions/in-session-actions#voice-dictation "Learn how to enable voice dictation")—your questions, requests, or instructions directly into the input field, and goose will immediately get to work. - When you're ready to work on a new task, you can start a new session in the same directory or a different one. This directory is where Goose reads and writes files by default. + When you're ready to work on a new task, you can start a new session in the same directory or a different one. This directory is where goose reads and writes files by default. - To start a session in the same Goose window: + To start a session in the same goose window: 1. Click the button in the top-left to open the sidebar 2. Click `Home` in the sidebar 3. Send your first prompt from the chat box - To start a session in a new Goose window: + To start a session in a new goose window: 1. Click the button in the top-left - 2. In the new Goose window, send your first prompt from the chat box + 2. In the new goose window, send your first prompt from the chat box 1. Click the directory switcher at the bottom of the app 2. Navigate to the new directory or create a new folder - 3. Click `Open` to open a new Goose window for the selected directory + 3. Click `Open` to open a new goose window for the selected directory 4. Send your first prompt from the chat box :::tip - On macOS, you can drag and drop a folder onto the Goose icon in the dock to open a new session in that directory. + On macOS, you can drag and drop a folder onto the goose icon in the dock to open a new session in that directory. ::: - You can also use keyboard shortcuts to start a new session or bring focus to open Goose windows. + You can also use keyboard shortcuts to start a new session or bring focus to open goose windows. | Action | macOS | Windows/Linux | |--------|-------|---------------| | New Session in Current Directory | `Cmd+N` | `Ctrl+N` | | New Session in Different Directory | `Cmd+O` | `Ctrl+O` | - | Focus Goose Window | `Cmd+Option+Shift+G` | `Ctrl+Alt+Shift+G` | + | Focus goose Window | `Cmd+Option+Shift+G` | `Ctrl+Alt+Shift+G` | | Toggle Sidebar | `Cmd+B` | `Ctrl+B` | @@ -65,7 +65,7 @@ In your first session, Goose prompts you to [set up an LLM (Large Language Model goose session ``` - If you want to interact with Goose in a web-based chat interface, start a session with the [`web`](/docs/guides/goose-cli-commands#web) command: + If you want to interact with goose in a web-based chat interface, start a session with the [`web`](/docs/guides/goose-cli-commands#web) command: ```sh goose web --open ``` @@ -90,12 +90,12 @@ In your first session, Goose prompts you to [set up an LLM (Large Language Model 6. A success toast notification will confirm the change :::tip - Session descriptions help you manage multiple Goose windows. When you're in the Goose chat interface, session descriptions appear in the `Window` menu and in the Dock (macOS) or taskbar (Windows) menu, making it easy to identify and switch between different Goose sessions. + Session descriptions help you manage multiple goose windows. When you're in the goose chat interface, session descriptions appear in the `Window` menu and in the Dock (macOS) or taskbar (Windows) menu, making it easy to identify and switch between different goose sessions. ::: - By default, Goose names your session using the current timestamp in the format `YYYYMMDD_HHMMSS`. If you'd like to provide a specific name, this is where you'd do so. For example to name your session `react-migration`, you would run: + By default, goose names your session using the current timestamp in the format `YYYYMMDD_`. If you'd like to provide a specific name, this is where you'd do so. For example to name your session `react-migration`, you would run: ``` goose session -n react-migration @@ -105,7 +105,8 @@ In your first session, Goose prompts you to [set up an LLM (Large Language Model ``` starting session | provider: openai model: gpt-4o - logging to ~/.local/share/goose/sessions/react-migration.json1 + session id: react-migration + working directory: /path/to/your/project ``` @@ -119,7 +120,7 @@ Note that sessions are automatically saved when you exit. To exit a session, type `exit`. Alternatively, you exit the session by holding down `Ctrl+C`. - Your session will be stored locally in `~/.local/share/goose/sessions`. + Your session will be stored in the local SQLite database at `~/.local/share/goose/sessions/sessions.db`. @@ -161,12 +162,25 @@ Search allows you to find specific content within sessions or find specific sess 4. Enter your search term 5. Use keyboard shortcuts and search bar buttons to navigate the results (`Cmd+E` not supported) - This is a metadata-only search. It doesn't search conversation content. Note that searching by file name is supported (e.g. `20250727_130002.jsonl`), but this property isn't displayed in the UI. + This is a metadata-only search. It doesn't search conversation content. Note that searching by session ID (e.g. `20251108_1`) is supported, but this property isn't displayed in the UI. :::tip You can [rename sessions](#name-session) to give them descriptive names that you'll remember later. ::: + #### Search Across All Session Content + + To search conversation content across all your sessions, ask goose directly in any chat session. For example: + + - "Find my earlier conversation about React hooks from last week" + - "Show me sessions where I worked on database migrations" + + 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). + ::: + #### Search Within Historical Session To find specific content within a historical session: @@ -185,6 +199,8 @@ Search allows you to find specific content within sessions or find specific sess + #### Search Within Current Session + Search functionality is provided by your terminal interface. Use the appropriate shortcut for your environment: | Terminal | Operating System | Shortcut | @@ -194,37 +210,53 @@ Search allows you to find specific content within sessions or find specific sess | Windows Terminal | Windows | `Ctrl+F` | | Linux Terminal | Linux | `Ctrl+F` | + To find specific content within your current session: + + 1. Use the shortcut to open the search bar + 2. Enter your search term + 3. Use shortcuts and search bar buttons to navigate the results + :::info Your specific terminal emulator may use a different keyboard shortcut. Check your terminal's documentation or settings for the search command. ::: - The Goose CLI supports [listing session history](/docs/guides/goose-cli-commands#session-list-options) but doesn't provide search functionality. As a workaround, you can use your terminal's search capabilities (including regex support) to search for specific content within sessions or find specific sessions. + #### Search Across All Session Content - Examples for macOS: + To search conversation content across all your sessions, start a goose session and ask directly: + + - "Find my earlier conversation about React hooks from last week" + - "Show me sessions where I worked on database migrations" + + 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). + ::: + + #### Search Session Data Directly + + The [`session list`](/docs/guides/goose-cli-commands#session-list-options) subcommand with supported options can be useful for some search operations. + + You can also query the SQLite database directly: ```bash - # Search session IDs (filenames) - ls ~/.local/share/goose/sessions/ | grep "full or partial session id" - - # List sessions modified in last 7 days - find ~/.local/share/goose/sessions/ -mtime -7 -name "*.jsonl" - - # Show first line (metadata) of each session file - for f in ~/.local/share/goose/sessions/*.jsonl; do - head -n1 "$f" | grep "your search term" && echo "Found in: $(basename "$f" .jsonl)" - done - - # Find search term in session content - rg "your search term" ~/.local/share/goose/sessions/ - - # Search and show session IDs that contain search term - for f in ~/.local/share/goose/sessions/*.jsonl; do - if grep -q "your search term" "$f"; then - echo "Found in session: $(basename "$f" .jsonl)" - fi - done + # Search session descriptions + sqlite3 ~/.local/share/goose/sessions/sessions.db \ + "SELECT id, description FROM sessions WHERE description LIKE '%your search term%';" + + # Search by working directory + sqlite3 ~/.local/share/goose/sessions/sessions.db \ + "SELECT id, description, working_dir FROM sessions WHERE working_dir LIKE '%project-name%';" + + # List recent sessions + sqlite3 ~/.local/share/goose/sessions/sessions.db \ + "SELECT id, description, created_at FROM sessions ORDER BY created_at DESC LIMIT 10;" ``` + :::info Session Storage Migration + Starting with version 1.10.0, goose uses a SQLite database (`sessions.db`) instead of individual `.jsonl` files. Legacy `.jsonl` files remain on disk but are no longer managed by goose. + ::: + @@ -234,7 +266,7 @@ Search allows you to find specific content within sessions or find specific sess 1. Click the button in the top-left to open the sidebar 2. Click `History` in the sidebar - 3. Click the session you'd like to resume. Goose provides [search features](#search-sessions) to help you find the session. + 3. Click the session you'd like to resume. goose provides [search features](#search-sessions) to help you find the session. 4. Choose how to resume: - Click `Resume` to continue in the current window - Click `New Window` to open in a new window @@ -317,7 +349,7 @@ You can resume a CLI session in Desktop. Deleting a session from goose Desktop will also delete it from the CLI. This action cannot be undone. ::: - The session will be immediately removed from your session history and the underlying session file will be deleted from your local storage. + The session will be immediately removed from your session history and the underlying session record will be deleted from local storage. You can remove sessions using CLI commands. For detailed instructions on session removal, see the [CLI Commands documentation](/docs/guides/goose-cli-commands#session-remove-options).