Superset is a specialized, turbocharged terminal application designed to optimize the workflow for developers utilizing CLI (Command Line Interface) coding agents. Its primary purpose is to address inefficiencies associated with running, managing, and monitoring multiple AI coding agents concurrently, as well as handling context switching and task isolation.

The core methodology of Superset revolves around several key features:

1. Parallel Execution: Superset enables the simultaneous execution of numerous CLI coding agents. This is achieved by providing an environment where each agent operates within its own isolated context, preventing resource conflicts and ensuring independent progress.

2. Worktree Isolation: A central technical innovation is the use of Git worktree isolation for each task or "workspace." When a new task is initiated, Superset leverages git worktree to create a separate, linked working directory. This means each task operates on its own Git branch and within its own isolated file system context, preventing agents from interfering with each other's code changes, dependencies, or environment configurations within the main repository. This effectively creates an independent development environment for each agent-driven task.

3. Agent Monitoring and Notification: The platform provides integrated tools to track the status of active agents and workspaces. It notifies the user when agents require attention or when changes are ready for review, streamlining the human-agent interaction loop.

4. Built-in Diff Viewer and Editor: To facilitate rapid code review and modification of agent-generated changes, Superset integrates a diff viewer and editor directly within the application, eliminating the need to switch to external tools.

5. Workspace Presets and Configuration: Superset offers robust configuration capabilities for automating workspace setup and teardown. This is managed via a .superset/config.json file located at the root of a project. This JSON configuration defines setup and teardown arrays, each containing a list of shell commands (strings) to be executed.
   • The setup array specifies commands (e.g., ["./.superset/setup.sh"]) to run automatically when a new workspace is created. This allows for automated environment setup, dependency installation (bun install), and other initialization tasks.
   • The teardown array specifies commands (e.g., ["./.superset/teardown.sh"]) to run when a workspace is deleted, facilitating cleanup.

These scripts have access to environment variables such as SUPERSET_WORKSPACE_NAME and SUPERSET_ROOT_PATH, enabling dynamic and context-aware script execution.

6. Universal Compatibility: Superset is designed to work with any CLI-based coding agent, including popular ones like Claude, OpenAI Codex CLI, Cursor Agent, Gemini CLI, GitHub Copilot, and OpenCode, as long as they can run in a standard terminal environment.

7. Quick Context Switching and IDE Integration: The application provides efficient keyboard shortcuts for navigating between active workspaces (⌘1-9, ⌘⌥↑/↓) and managing terminal panes (⌘T, ⌘W, ⌘D, ⌘⇧D). It also allows users to open any workspace directly in their preferred external Integrated Development Environment (IDE) with a single action (⌘O).

Technical Requirements and Setup:
Superset is primarily supported on macOS, requiring Bun v1.0+ as its JavaScript runtime, Git 2.20+ for version control (crucial for worktree isolation), GitHub CLI (gh), and Caddy (for a development server, specifically for Electric SQL streams, configured via Caddyfile.example). Users can either download a pre-built macOS application or build from source by cloning the repository, setting up environment variables (either fully or skipping validation with $SKIP_ENV_VALIDATION=1$), configuring Caddy, installing dependencies via bun install, and running bun run dev for development or bun run build for a desktop release.

Superset aims to provide a comprehensive, integrated environment that streamlines the development workflow when collaborating with multiple AI coding agents, enhancing productivity by minimizing overheads related to context switching, environment management, and code review.