superset-vcs-agnostic-agent-workflow-feedback.md

Feedback: Keep Superset VCS-Agnostic and Agent-Driven

This document was generated with AI assistance to expand on a short feedback submission.

TL;DR

Please do not make Superset's core workspace and agent functionality depend on a specific Git workflow.

I want Superset to provide the durable remote runtime, GUI, terminal, session persistence, diff visibility, and agent controls. I want the agent—and the tools I choose—to control repository history and workflow semantics.

In particular:

• A repository in detached HEAD state should still be usable.
• Jujutsu (jj) repositories should not be rejected because Git sees a detached HEAD.
• Stacked changes and stacked PRs should not require Superset itself to understand, own, or deterministically enforce the stack.
• Core terminal and agent functionality should not be blocked because Superset cannot map the repository to its preferred branch/worktree model.
• Git-specific features should degrade gracefully rather than making the entire product unusable.

The current model appears to treat this invariant as foundational:

project
  -> one branch-backed main workspace
  -> one Git worktree per workspace
  -> one attached Git branch per worktree

That is a valid workflow, but it should not be a prerequisite for using Superset.

What I Want Superset to Own

Superset is valuable to me as an execution and interaction layer:

• Run agents on a remote Linux host.
• Control them from a local Mac GUI.
• Preserve sessions across disconnects, sleep, application restarts, and laptop reboots.
• Support clipboard and image transfer from the local GUI to remote agents.
• Show terminals, files, changes, logs, and agent status.
• Let me launch and resume Claude Code, Codex, and other CLI agents.
• Optionally provide Git-aware conveniences when the repository matches Superset's preferred model.

Those capabilities do not inherently require Superset to own branch topology.

What Superset Should Not Require

Superset should not require all of the following before I can launch an agent:

• HEAD must resolve to an attached Git branch.
• Every workspace must correspond to a Git branch.
• Every workspace must be created through git worktree.
• Every PR must be treated as an independent branch against a default base branch.
• Superset must be the system that creates, names, tracks, rebases, or deletes branches.
• The repository must conform to a conventional non-stacked Git workflow.

These assumptions make the GUI the authority over workflow state. I want the agent and my selected VCS tooling to remain authoritative.

Example: Jujutsu

A colocated Jujutsu repository commonly presents Git with a detached HEAD. That is normal and intentional.

Superset currently appears to interpret this as an invalid repository state and refuses to create the main workspace. This means an implementation detail of the Git compatibility layer prevents access to otherwise unrelated features such as:

• terminal sessions;
• remote execution;
• agent launch;
• session persistence;
• clipboard/image handling;
• file browsing.

A detached HEAD should at most disable branch-specific GUI actions. It should not make the project unusable.

A reasonable fallback would be:

Repository opened in VCS-neutral mode.

Available:
- terminals
- agents
- files
- session persistence
- raw repository diff, where possible

Unavailable or limited:
- Superset-managed branch creation
- branch-aware PR actions
- branch deletion
- automatic worktree lifecycle

Example: Stacked Changes

My preferred workflow may look like:

change A
  -> change B
      -> change C

Each change may become a PR targeting its immediate parent rather than the repository's default branch.

I may use:

• Jujutsu;
• Graphite;
• Git Town;
• another stack manager;
• custom agent instructions and ordinary Git commands.

I do not need Superset to become a complete stack manager. I need Superset to avoid blocking or corrupting the workflow.

The agent should be able to:

• create the next change in the stack;
• choose the correct parent;
• rebase or restack descendants;
• retarget PRs;
• update bookmarks or branches;
• submit the stack using the selected tool.

Superset can observe and display this state, but it should not require that all branch relationships be created through deterministic GUI controls.

Agent-Controlled Rather Than GUI-Controlled

The agent should be allowed to decide which repository commands are appropriate based on:

• the repository's own instructions;
• AGENTS.md or equivalent guidance;
• detected VCS tooling;
• user prompts;
• existing stack metadata;
• the current repository state.

For example, the agent might choose among:

jj new
jj rebase
jj bookmark set
gt create
gt restack
git switch
git rebase
git worktree add

Superset should not preclude those choices by requiring a GUI-generated branch/worktree structure before the agent can begin.

Suggested Product Model

Please separate the product into two layers.

1. Core workspace runtime

This should work for any directory:

• local or remote terminal;
• durable PTY/session handling;
• agent launch and resume;
• files and search;
• clipboard and attachment transfer;
• ports and dev servers;
• logs;
• generic change detection;
• user-provided setup commands.

This layer should have no attached-branch requirement.

2. Optional VCS integration

When supported, Superset may add:

• branch and bookmark display;
• worktree or workspace creation;
• PR status;
• ahead/behind information;
• base comparison;
• commit and push controls;
• cleanup assistance.

If VCS detection is incomplete or unsupported, this layer should disable itself without disabling the core runtime.

Minimum Acceptable Fix

A full VCS abstraction would be useful, but the minimum viable improvement is simpler:

1. Permit importing and opening a repository with detached HEAD.
2. Allow a project or workspace to have no branch identity.
3. Permit terminal and agent sessions in that state.
4. Hide or disable operations that genuinely require an attached Git branch.
5. Stop background retry loops that repeatedly treat the same valid repository state as a transient failure.
6. Provide a per-project option such as:

VCS management:
- Superset-managed Git workspaces
- External / agent-managed
- None

In External / agent-managed mode, Superset should not create, switch, rename, delete, rebase, or otherwise own branches or worktrees unless explicitly requested.

Better Long-Term Design

A provider abstraction could support:

• Git branches and worktrees;
• Jujutsu bookmarks and workspaces;
• Sapling;
• external/custom providers;
• VCS-neutral directories.

However, even with native provider support, there should still be an escape hatch where Superset does not own VCS lifecycle.

Native jj support alone would not fully solve the design problem. The broader issue is that agent execution should not be gated behind deterministic GUI assumptions about repository topology.

Acceptance Criteria

I would consider this addressed when all of the following work:

• I can open a colocated jj repository while Git reports detached HEAD.
• I can launch Claude Code or Codex immediately.
• Superset does not create or attach a Git branch behind my back.
• The agent can use jj or another stack tool itself.
• I can maintain stacked changes whose parent relationships are not all main.
• Superset does not overwrite or stale-cache the intended PR base.
• Unsupported VCS-specific UI is disabled rather than blocking the project.
• Session persistence, remote execution, clipboard images, and terminals remain fully functional.
• I can opt out of Superset-managed branch/worktree lifecycle per project.

Why This Matters

Superset's strongest differentiation is not branch creation. It is the durable remote agent runtime and local GUI.

Hard-coding one Git workflow narrows the product to users who accept Superset's repository model. Making the runtime VCS-agnostic would let Superset work with:

• conventional Git users;
• stacked-PR users;
• Jujutsu users;
• teams with custom branch automation;
• repositories where agents already own workflow decisions;
• non-Git project directories.

The desired principle is:

Superset should make agent workflows observable and durable without requiring Superset to control the workflow itself.