Repository navigation
docs(workspaces): document asynchronous workspace naming #7890
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. Weβll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -19,7 +19,7 @@ Press **βN** or click "New Workspace". Create from: | |||||||||||||||||||||
|
|
||||||||||||||||||||||
| In the prompt-first workspace flow, **Link pull request** lets you search by title or PR number, or paste the full PR URL to match it directly. The prompt box also keeps a searchable history of your previous prompts; click the history icon to reuse one. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise Superset generates a name from your prompt. Per-project **Naming instructions** (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/". | ||||||||||||||||||||||
| If you type a workspace name yourself, the branch name is derived from it (slugified to kebab-case). Otherwise Superset names it from your prompt in the background; see [Automatic Naming](#automatic-naming). Per-project **Naming instructions** (in project settings) steer generated names, e.g. "prefix branches with fix/ or feat/". | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Each new branch-based workspace gets: | ||||||||||||||||||||||
| - Own git branch | ||||||||||||||||||||||
|
|
@@ -56,6 +56,26 @@ On iPhone, choose **No project** in the composer's project picker, or tap **+** | |||||||||||||||||||||
|
|
||||||||||||||||||||||
| Automations can run in session mode too; see [Automations](/automations). | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| ## Automatic Naming | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| When you create a workspace or session from a prompt without typing a name, Superset names it in the background. Creation and agent startup don't wait for it. Until the name arrives, a new worktree workspace shows **New workspace**, a **Local** workspace shows `local` (or `local 2`, and so on), and a session shows **New session**. Pull request workspaces use the PR title, and workspaces for existing worktrees aren't renamed either. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| The workspace's agent writes the name with its own sign-in, from your prompt and the title and description of any GitHub issue or pull request the prompt links. If the prompt is vague or the attempt fails, Superset tries again after the agent replies, using that reply too, for up to three attempts. Renaming never moves files: the worktree directory and the session folder keep the name they were created with. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| If naming doesn't finish, the workspace keeps working under its placeholder or a title taken from your prompt, and a **Couldn't name "β¦" automatically** warning says so. Agents that can't run headlessly, and prompts sent without an agent, get the prompt title without a warning. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| For a new worktree workspace, Superset also renames the branch it generated, but only while that branch: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| - Is still checked out in the workspace | ||||||||||||||||||||||
| - Has no upstream | ||||||||||||||||||||||
| - Doesn't exist on a remote | ||||||||||||||||||||||
|
Comment on lines
+67
to
+71
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. π Maintainability & Code Quality | π‘ Minor | β‘ Quick win π Supported by static analysisπ Script executed: nl -ba apps/docs/content/docs/workspaces.mdx | sed -n '64,78p'
sed -n '390,440p' packages/host-service/src/workers/tasks/git.ts
sed -n '240,290p' packages/host-service/src/trpc/router/workspace-creation/utils/workspace-naming-job.tsRepository: superset-sh/superset Length of output: 4786 π Script executed: set -eu
rg -n -C 8 'gitAutomaticBranchRenamableTask|automaticBranchRenamable|canRenameBranch|renameAutomaticBranch' packages/host-service/src
printf '\n--- relevant git remote/ref usages ---\n'
rg -n -C 5 'refs/remotes|ls-remote|fetch|remote branch' packages/host-service/src/trpc packages/host-service/src/workers packages/host-service/src/workspaces -g '*.ts' | head -n 240Repository: superset-sh/superset Length of output: 41603 Qualify the remote-branch condition. The automatic check reads only local Suggested fix-- Doesn't exist on a remote
+- Has no same-named local remote-tracking refπ Committable suggestion
Suggested change
π€ Prompt for AI Agents |
||||||||||||||||||||||
|
|
||||||||||||||||||||||
| The new name keeps your branch prefix and gets a short unique suffix, so it doesn't collide with existing branches. Sessions always stay on `main`. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Your edits win. Renaming a workspace or session ends automatic naming, including the branch rename. Changing the branch yourself keeps your branch, though the title can still update. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Pending naming lives in the host service's memory. If the host service restarts before naming finishes, the workspace keeps the name it has at that point; its files, terminals, and running agents are unaffected. | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
|
Comment on lines
+76
to
+78
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. π©Ί Stability & Availability | π‘ Minor | β‘ Quick win π Supported by static analysisπ Script executed: nl -ba apps/docs/content/docs/workspaces.mdx | sed -n '74,80p'
rg -n 'development|dev mode|workspace guide|docs/content/docs/workspaces|host-service' apps/docs/content/docs/workspaces.mdx apps/docs/content/docs
sed -n '100,135p' packages/host-service/src/serve.ts
sed -n '890,920p' packages/host-service/src/daemon/DaemonSupervisor.ts
sed -n '1245,1290p' packages/host-service/src/daemon/DaemonSupervisor.tsRepository: superset-sh/superset Length of output: 5505 Qualify the restart behavior for development mode. When Suggested fix-Pending naming lives in the host service's memory. If the host service restarts before naming finishes, the workspace keeps the name it has at that point; its files, terminals, and running agents are unaffected.
+Pending naming lives in the host service's memory. For production host-service restarts before naming finishes, the workspace keeps the name it has at that point; its files, terminals, and running agents are unaffected. In development, restarting the host service stops the PTY daemon, which ends terminals and running agents.π Committable suggestion
Suggested change
π€ Prompt for AI Agents |
||||||||||||||||||||||
| ## Pin Workspaces | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
| Keep active workspaces at the top of the sidebar: | ||||||||||||||||||||||
|
|
||||||||||||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
π― Functional Correctness | π‘ Minor | β‘ Quick win
π Supported by static analysis
π Script executed:
Repository: superset-sh/superset
Length of output: 10896
π Script executed:
Repository: superset-sh/superset
Length of output: 18527
Qualify the warning's retained-title behavior.
A naming attempt can apply a generated title, remain pending, and later give up after branch-eligibility probes fail. The workspace then keeps the generated title, not a placeholder or prompt-derived title. The warning also describes the title as coming from the prompt, so this paragraph does not cover the user-visible result.
Suggested fix
π Committable suggestion
π€ Prompt for AI Agents