diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 323b69fb962..9a0f5b277bc 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -421,8 +421,6 @@ goose schedule remove --id daily-report Start working on your last project or create a new one. -A project is a record of a working directory and recent session metadata. Note that any directory where you run `goose project` becomes a tracked project, so you might want to run the command from the directory where you want to work. - **Alias**: `p` **Usage:** @@ -430,14 +428,7 @@ A project is a record of a working directory and recent session metadata. Note t goose project ``` -The command provides three options: -1. **Resume project with session**: Continue the last session in the project -2. **Resume project with fresh session**: Start a new session in the project -3. **Start new project in current directory**: Create a new project in the current directory - -:::note -Goose stores your project history in `~/.local/share/goose/projects.json`. -::: +For a complete guide, see [Managing Projects Guide](/docs/guides/managing-projects). --- ### projects @@ -451,23 +442,7 @@ Choose one of your projects to start working on. goose projects ``` -Example output: -```bash -┌ Goose Project Manager -│ -◆ Select a project: -│ ● .../Users/svera (2025-05-21 18:42:05) -│ ○ .../Development/goose (2025-05-21 18:38:26) -│ ○ .../Documents/goose-recipes (2025-05-21q 18:29:15) -│ ○ .../Desktop/temp (2025-05-21 15:13:48)q -│ ○ .../doc_projects/shared (2025-05-21 14:32:22) -│ ○ Cancel -└ -``` - -After selecting a project, you'll be asked to either: -- **Resume previous session**: Continue the last session in the selected project -- **Start new session**: Start a new session in the selected project +For detailed usage examples and workflows, see [Managing Projects Guide](/docs/guides/managing-projects). --- ### web diff --git a/documentation/docs/guides/managing-goose-sessions.md b/documentation/docs/guides/managing-goose-sessions.md index 69d62e1f446..18c4522a4ec 100644 --- a/documentation/docs/guides/managing-goose-sessions.md +++ b/documentation/docs/guides/managing-goose-sessions.md @@ -41,10 +41,6 @@ A session is a single, continuous interaction between you and Goose, providing a ```sh goose web --open ``` - - :::tip - You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata. - ::: @@ -116,10 +112,6 @@ Note that sessions are automatically saved when you exit. :::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). ::: - - :::tip - You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#projects) commands to start or resume sessions from a project, which is a tracked working directory with session metadata. - ::: @@ -234,6 +226,10 @@ You can resume a CLI session in Desktop and vice versa. +## Project-Based Sessions + +You can also use the [`project`](/docs/guides/goose-cli-commands#project) and [`projects`](/docs/guides/goose-cli-commands#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](/docs/guides/managing-projects). + ## Remove Sessions 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). diff --git a/documentation/docs/guides/managing-projects.md b/documentation/docs/guides/managing-projects.md new file mode 100644 index 00000000000..8136cdd2bc7 --- /dev/null +++ b/documentation/docs/guides/managing-projects.md @@ -0,0 +1,114 @@ +--- +sidebar_position: 2 +title: Managing Projects +sidebar_label: Managing Projects +--- + +Goose Projects automatically track your working directories and associated sessions, making it easy to resume work across multiple codebases with full context preservation. + +A **project** in Goose is a record of a working directory where you've used Goose. Every time you run Goose, it automatically tracks the current directory as a project, storing: + +- **Path**: The absolute path to the project directory +- **Last accessed**: When you last worked on this project +- **Last instruction**: The most recent command you gave to Goose +- **Session ID**: The associated session for context continuity + +Projects are stored in `~/.local/share/goose/projects.json`. + +:::info CLI Only Feature +Projects are currently available only through the Goose CLI. Desktop support is planned for future releases. +::: + +## Basic Usage + +**Resume your most recent project:** + +```bash +goose project +``` + +**Browse all your projects:** + +```bash +goose projects +``` +:::tip +When resuming a project, you can continue the previous session or start fresh in that directory. +::: + +For complete command syntax and options, see the [CLI Commands Guide](/docs/guides/goose-cli-commands#project). + +## Workflow Example + +Let's follow Sarah, a developer working on multiple projects throughout her day: + +### Morning: API Development +```bash +cd ~/projects/ecommerce-api +goose session --name "api-auth-work" +``` +*Sarah asks Goose to help implement JWT token refresh logic* + +### Mid-Morning: Mobile App Bug Fix +```bash +cd ~/projects/mobile-app +goose session +``` +*Sarah gets help debugging an iOS crash in the login screen* + +### Afternoon: Admin Dashboard +```bash +cd ~/projects/admin-dashboard +goose session --name "dashboard-ui" +``` +*Sarah works on creating user management interface components* + +### Next Day: Quick Resume +```bash +# From any directory, quickly resume the most recent project +goose project +``` + +Goose shows: +``` +┌ Goose Project Manager +│ +◆ Choose an option: +│ ○ Resume project with session: .../admin-dashboard +│ Continue with the previous session +│ ○ Resume project with fresh session: .../admin-dashboard +│ Change to the project directory but start a new session +│ ○ Start new project in current directory: /Users/sarah +│ Stay in the current directory and start a new session +└ +``` + +### Later: Browse All Projects +```bash +goose projects +``` + +Goose displays: +``` +┌ Goose Project Manager +│ +◆ Select a project: +│ ○ 1 .../admin-dashboard (2025-01-07 09:15:30) [create user management interface] +│ ○ 2 .../mobile-app (2025-01-06 11:45:20) [login screen crashing on iOS] +│ ○ 3 .../ecommerce-api (2025-01-06 09:30:15) [JWT token refresh logic] +│ ○ Cancel +└ +``` + +Sarah can see her recent projects with timestamps and context, making it easy to choose where to continue working. + +## Benefits + +:::tip Time Savings +Projects eliminate the typical 2-5 minutes lost when switching between codebases, especially valuable for developers working on multiple projects daily. +::: + +- **Eliminate context switching friction** - Jump between projects instantly without manual navigation +- **Preserve work context** - Resume exactly where you left off with full conversation history +- **Seamless session integration** - Maintain continuity across different codebases +