Session Management
A session is a single, continuous interaction between you and Goose, providing a space to ask questions and prompt action. This guide covers how to manage the session lifecycle.
Start Session
In your first session, Goose prompts you to set up an LLM (Large Language Model) provider.
- Goose Desktop
- Goose CLI
When you open Goose, you'll see the session interface ready for use. Just type—or speak—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.
- Same Directory
- Different Directory
To start a session in the same Goose window:
- Click the button in the top-left to open the sidebar
- Click
Home
in the sidebar - Send your first prompt from the chat box
To start a session in a new Goose window:
- Click the button in the top-left
- In the new Goose window, send your first prompt from the chat box
- Click the directory switcher at the bottom of the app
- Navigate to the new directory or create a new folder
- Click
Open
to open a new Goose window for the selected directory - Send your first prompt from the chat box
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.
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 |
Name Session
- Goose Desktop
- Goose CLI
Within the Desktop app, sessions are automatically named based on the context of your initial prompt.
You can rename sessions after they're created:
- Click the button in the top-left to open the sidebar
- Click
History
in the sidebar - Hover over the session you'd like to rename
- Click the button that appears on the session card
- Enter the new session name
- Click
Save
Session names can also help you manage multiple Goose windows. When you're in the Goose chat interface, session names 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:
goose session -n react-migration
You'll know your session has started when your terminal looks similar to the following:
starting session | provider: openai model: gpt-4o
logging to ~/.local/share/goose/sessions/react-migration.json1
Exit Session
Note that sessions are automatically saved when you exit.
- Goose Desktop
- Goose CLI
To exit a session, simply close the application.
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
.
Search Sessions
Search allows you to find specific content within sessions or find specific sessions.
- Goose Desktop
- Goose CLI
You can use keyboard shortcuts and search bar buttons to search sessions in Goose Desktop.
Action | macOS | Windows/Linux |
---|---|---|
Open Search | Cmd+F | Ctrl+F |
Next Match | Cmd+G or ↓ | Ctrl+G or ↓ |
Previous Match | Shift+Cmd+G or ↑ | Shift+Ctrl+G or ↑ |
Use Selection for Find | Cmd+E | n/a |
Toggle Case-Sensitivity | Aa | Aa |
Close Search | Esc or X | Esc or X |
The following scenarios are supported:
Search Within Current Session
To find specific content within your current session:
- Use
Cmd+F
to open the search bar - Enter your search term
- Use shortcuts and search bar buttons to navigate the results
Search For Session By Name or Path
To search all your sessions by name or working directory path:
- Click the button in the top-left to open the sidebar
- Click
History
in the sidebar - Use
Cmd+F
to open the search bar - Enter your search term
- 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.
You can rename sessions to give them descriptive names that you'll remember later.
Search Within Historical Session
To find specific content within a historical session:
- Click the button in the top-left to open the sidebar
- Click
History
in the sidebar - Click a specific session tile from the list to view its content
- Use
Cmd+F
to open the search bar - Enter your search term
- Use keyboard shortcuts and search bar buttons to navigate the results
Using regular expressions or search operators in search text isn't supported.
Search functionality is provided by your terminal interface. Use the appropriate shortcut for your environment:
Terminal | Operating System | Shortcut |
---|---|---|
iTerm2 | macOS | Cmd+F |
Terminal.app | macOS | Cmd+F |
Windows Terminal | Windows | Ctrl+F |
Linux Terminal | Linux | Ctrl+F |
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 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.
Examples for macOS:
# 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
Resume Session
- Goose Desktop
- Goose CLI
- Click the button in the top-left to open the sidebar
- Click
History
in the sidebar - Click the session you'd like to resume. Goose provides search features to help you find the session.
- Choose how to resume:
- Click
Resume
to continue in the current window - Click
New Window
to open in a new window
- Click
You can also quickly resume one of your three most recent sessions by clicking it in the Recent chats
section on the Home
page.
To resume your latest session, you can run the following command:
goose session -r
To resume a specific session, run the following command:
goose session -r --name <name>
For example, to resume the session named react-migration
, you would run:
goose session -r --name react-migration
While you can resume sessions using the commands above, we recommend creating new sessions for new tasks to reduce the chance of doom spiraling.
Resume Session Across Interfaces
You can resume a CLI session in Desktop.
- Goose Desktop
- Goose CLI
All saved sessions are listed in the Desktop app, even CLI sessions. To resume a CLI session within the Desktop:
- Click the button in the top-left to open the sidebar
- Click
History
in the sidebar - Click the session you'd like to resume
- Choose how to resume:
- Click
Resume
to continue in the current window - Click
New Window
to open in a new window
- Click
Currently, you cannot resume a Desktop session within the CLI.
Resume Project-Based Sessions
- Goose Desktop
- Goose CLI
Project-based sessions are only available through the CLI.
You can use the project
and projects
commands to start or resume sessions from a project, which is a tracked working directory with session metadata. For a complete guide to using Projects, see Managing Projects Guide.
Remove Sessions
- Goose Desktop
- Goose CLI
Removing sessions is only available through the CLI.
You can remove sessions using CLI commands. For detailed instructions on session removal, see the CLI Commands documentation.
Export Sessions
Export sessions to Markdown to share with your team, create documentation, archive conversations, or review them in a readable format.
- Goose Desktop
- Goose CLI
Session export is currently only available through the CLI.
Export sessions using the export
subcommand:
# Interactive export - prompts you to select a session
goose session export
For more details on export options, available flags, and output formats, see the CLI commands documentation.