From 6bdb2836a6c7a89a53f7aaa86abd593f25b8422b Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Mon, 7 Jul 2025 01:55:56 -0400 Subject: [PATCH 1/5] Docs: goose projects --- .../docs/guides/goose-cli-commands.md | 4 + .../docs/guides/managing-goose-sessions.md | 4 +- documentation/docs/guides/projects.md | 105 ++++++++++++++++++ 3 files changed, 111 insertions(+), 2 deletions(-) create mode 100644 documentation/docs/guides/projects.md diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 323b69fb962d..318e3da1d4de 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -423,6 +423,8 @@ 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. +**For a complete guide to Goose Projects, including workflows and best practices, see [Projects Guide](/docs/guides/projects).** + **Alias**: `p` **Usage:** @@ -444,6 +446,8 @@ Goose stores your project history in `~/.local/share/goose/projects.json`. Choose one of your projects to start working on. +**See [Projects Guide](/docs/guides/projects) for detailed usage examples and workflows.** + **Alias**: `ps` **Usage:** diff --git a/documentation/docs/guides/managing-goose-sessions.md b/documentation/docs/guides/managing-goose-sessions.md index 69d62e1f4467..5d463f062073 100644 --- a/documentation/docs/guides/managing-goose-sessions.md +++ b/documentation/docs/guides/managing-goose-sessions.md @@ -43,7 +43,7 @@ A session is a single, continuous interaction between you and Goose, providing a ``` :::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. + 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 [Projects Guide](/docs/guides/projects). ::: @@ -118,7 +118,7 @@ Note that sessions are automatically saved when you exit. ::: :::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. + 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 [Projects Guide](/docs/guides/projects). ::: diff --git a/documentation/docs/guides/projects.md b/documentation/docs/guides/projects.md new file mode 100644 index 000000000000..58c03743833c --- /dev/null +++ b/documentation/docs/guides/projects.md @@ -0,0 +1,105 @@ +--- +sidebar_position: 2 +title: Projects +sidebar_label: Projects +--- + +Goose Projects automatically track your working directories and associated sessions, making it easy to resume work across multiple codebases with full context preservation. + +## What Are Goose Projects? + +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, storing your path, last access time, recent instruction, and session ID for context continuity. + +## Key Benefits + +- **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 + +:::tip Time Savings +Projects eliminate the typical 2-5 minutes lost when switching between codebases, especially valuable for developers working on multiple projects daily. +::: + +## How to Use Projects + +**Resume your most recent project:** +```bash +goose project # or goose p +``` + +**Browse all your projects:** +```bash +goose projects # or goose ps +``` + +When resuming a project, you can continue the previous session or start fresh in that directory. + +## Real-World 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. + + + +## CLI Reference + +For complete command syntax and options, see the [CLI Commands Guide](/docs/guides/goose-cli-commands#project). From 64d56a06ba105214041340b923964fbe840877df Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Mon, 7 Jul 2025 02:04:52 -0400 Subject: [PATCH 2/5] quick edits --- documentation/docs/guides/projects.md | 16 ++++++++++------ 1 file changed, 10 insertions(+), 6 deletions(-) diff --git a/documentation/docs/guides/projects.md b/documentation/docs/guides/projects.md index 58c03743833c..67644ee749b7 100644 --- a/documentation/docs/guides/projects.md +++ b/documentation/docs/guides/projects.md @@ -6,11 +6,17 @@ sidebar_label: Projects Goose Projects automatically track your working directories and associated sessions, making it easy to resume work across multiple codebases with full context preservation. -## What Are Goose Projects? -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, storing your path, last access time, recent instruction, and session ID for context continuity. +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: -## Key Benefits +- **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`. + +## Benefits - **Eliminate context switching friction** - Jump between projects instantly without manual navigation - **Preserve work context** - Resume exactly where you left off with full conversation history @@ -34,7 +40,7 @@ goose projects # or goose ps When resuming a project, you can continue the previous session or start fresh in that directory. -## Real-World Workflow Example +## Example Use Case Let's follow Sarah, a developer working on multiple projects throughout her day: @@ -98,8 +104,6 @@ Goose displays: Sarah can see her recent projects with timestamps and context, making it easy to choose where to continue working. - - ## CLI Reference For complete command syntax and options, see the [CLI Commands Guide](/docs/guides/goose-cli-commands#project). From d271ffa30539f5ff1913a6a7bdbae79e71b88f75 Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Mon, 7 Jul 2025 02:09:05 -0400 Subject: [PATCH 3/5] more edits --- documentation/docs/guides/projects.md | 37 +++++++++++++++------------ 1 file changed, 20 insertions(+), 17 deletions(-) diff --git a/documentation/docs/guides/projects.md b/documentation/docs/guides/projects.md index 67644ee749b7..1e2e495f92e4 100644 --- a/documentation/docs/guides/projects.md +++ b/documentation/docs/guides/projects.md @@ -16,31 +16,26 @@ A **project** in Goose is a record of a working directory where you've used Goos Projects are stored in `~/.local/share/goose/projects.json`. -## Benefits - -- **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 - -:::tip Time Savings -Projects eliminate the typical 2-5 minutes lost when switching between codebases, especially valuable for developers working on multiple projects daily. -::: - -## How to Use Projects +## Basic Usage **Resume your most recent project:** + ```bash -goose project # or goose p +goose project ``` **Browse all your projects:** + ```bash -goose projects # or goose ps +goose projects ``` - +:::tip When resuming a project, you can continue the previous session or start fresh in that directory. +::: -## Example Use Case +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: @@ -104,6 +99,14 @@ Goose displays: Sarah can see her recent projects with timestamps and context, making it easy to choose where to continue working. -## CLI Reference +## 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 -For complete command syntax and options, see the [CLI Commands Guide](/docs/guides/goose-cli-commands#project). From 082b9de0def2dc0c0293349b31770bdc2fd62a69 Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Mon, 7 Jul 2025 02:40:37 -0400 Subject: [PATCH 4/5] more detail for managing projects --- .../docs/guides/goose-cli-commands.md | 33 ++----------------- .../docs/guides/managing-goose-sessions.md | 12 +++---- .../{projects.md => managing-projects.md} | 8 +++-- 3 files changed, 11 insertions(+), 42 deletions(-) rename documentation/docs/guides/{projects.md => managing-projects.md} (95%) diff --git a/documentation/docs/guides/goose-cli-commands.md b/documentation/docs/guides/goose-cli-commands.md index 318e3da1d4de..9a0f5b277bc9 100644 --- a/documentation/docs/guides/goose-cli-commands.md +++ b/documentation/docs/guides/goose-cli-commands.md @@ -421,10 +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. - -**For a complete guide to Goose Projects, including workflows and best practices, see [Projects Guide](/docs/guides/projects).** - **Alias**: `p` **Usage:** @@ -432,22 +428,13 @@ 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 Choose one of your projects to start working on. -**See [Projects Guide](/docs/guides/projects) for detailed usage examples and workflows.** - **Alias**: `ps` **Usage:** @@ -455,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 5d463f062073..18c4522a4ec4 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. For a complete guide to using Projects, see [Projects Guide](/docs/guides/projects). - ::: @@ -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. For a complete guide to using Projects, see [Projects Guide](/docs/guides/projects). - ::: @@ -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/projects.md b/documentation/docs/guides/managing-projects.md similarity index 95% rename from documentation/docs/guides/projects.md rename to documentation/docs/guides/managing-projects.md index 1e2e495f92e4..83302951a9b9 100644 --- a/documentation/docs/guides/projects.md +++ b/documentation/docs/guides/managing-projects.md @@ -1,12 +1,11 @@ --- sidebar_position: 2 -title: Projects +title: Managing Projects sidebar_label: 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 @@ -16,6 +15,10 @@ A **project** in Goose is a record of a working directory where you've used Goos 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:** @@ -105,7 +108,6 @@ Sarah can see her recent projects with timestamps and context, making it easy to 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 From 9d712e6ce0a2900fae3b5d8b9a592003792f65b2 Mon Sep 17 00:00:00 2001 From: Rizel Scarlett Date: Mon, 7 Jul 2025 02:43:33 -0400 Subject: [PATCH 5/5] fixing sidebar label --- documentation/docs/guides/managing-projects.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/guides/managing-projects.md b/documentation/docs/guides/managing-projects.md index 83302951a9b9..8136cdd2bc73 100644 --- a/documentation/docs/guides/managing-projects.md +++ b/documentation/docs/guides/managing-projects.md @@ -1,7 +1,7 @@ --- sidebar_position: 2 title: Managing Projects -sidebar_label: 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.