diff --git a/README.md b/README.md index 2725e4d8f28..2686657804b 100644 --- a/README.md +++ b/README.md @@ -1,145 +1,239 @@ -
-supersetlogo +Superset -

Superset

-

- Run 10+ parallel coding agents on your machine -

+### The Terminal for Coding Agents + +[About](#why-superset) · [Features](#features) · [Download](#getting-started) · [Docs](https://docs.superset.sh) · [Contributing](#contributing) + +[![GitHub stars](https://img.shields.io/github/stars/superset-sh/superset?style=flat&logo=github)](https://github.com/superset-sh/superset/stargazers) +[![GitHub release](https://img.shields.io/github/v/release/superset-sh/superset?style=flat&logo=github)](https://github.com/superset-sh/superset/releases) +[![License](https://img.shields.io/github/license/superset-sh/superset?style=flat)](LICENSE.md) +[![Twitter](https://img.shields.io/badge/@superset__sh-555?logo=x)](https://x.com/superset_sh) +[![Discord](https://img.shields.io/badge/Discord-555?logo=discord)](https://discord.gg/cZeD9WYcV7) + +
+ +[**Download for macOS**](https://github.com/superset-sh/superset/releases/latest)  •  [Documentation](https://docs.superset.sh)  •  [Changelog](https://github.com/superset-sh/superset/releases)  •  [Discord](https://discord.gg/cZeD9WYcV7) + +
-[![Superset Twitter](https://img.shields.io/badge/@superset_sh-555?logo=x)](https://x.com/superset_sh) -[![Superset Twitter](https://img.shields.io/badge/Discord-555?logo=discord)]([https://x.com/superset_sh](https://discord.gg/cZeD9WYcV7))
-## A Terminal Built for Coding Agents -Run 10+ CLI coding agents like Claude Code, Codex, etc. in parallel on your machine. -Spin up new coding tasks while waiting for your current agent to finish. Quickly switch between tasks as they need your attention. +## Why Superset? + +Superset is a turbocharged terminal that allows you to run any CLI coding agents along with the tools to 10x your development workflow. + +- **Run multiple agents simultaneously** without context switching overhead +- **Isolate each task** in its own git worktree so agents don't interfere with each other +- **Monitor all your agents** from one place and get notified when they need attention +- **Review changes quickly** with built-in diff viewer and editor + +Wait less, ship more. + +## Features + +| Feature | Description | +|:--------|:------------| +| **Parallel Execution** | Run 10+ coding agents simultaneously on your machine | +| **Worktree Isolation** | Each task gets its own branch and working directory | +| **Agent Monitoring** | Track agent status and get notified when changes are ready | +| **Built-in Diff Viewer** | Inspect and edit agent changes without leaving the app | +| **Workspace Presets** | Automate env setup, dependency installation, and more | +| **Universal Compatibility** | Works with any CLI agent that runs in a terminal | +| **Quick Context Switching** | Jump between tasks as they need your attention | +| **IDE Integration** | Open any workspace in your favorite editor with one click | + +## Supported Agents + +Superset works with any CLI-based coding agent, including: -https://github.com/user-attachments/assets/d85ec84f-34de-4e17-9d44-5ccbd225566f +| Agent | Status | +|:------|:-------| +| [Claude Code](https://github.com/anthropics/claude-code) | Fully supported | +| [OpenAI Codex CLI](https://github.com/openai/codex) | Fully supported | +| [OpenCode](https://github.com/opencode-ai/opencode) | Fully supported | +| Any CLI agent | Will work | + +If it runs in a terminal, it runs on Superset + +## Requirements + +| Requirement | Details | +|:------------|:--------| +| **OS** | macOS (Windows/Linux untested) | +| **Runtime** | [Bun](https://bun.sh/) v1.0+ | +| **Version Control** | Git 2.20+ | +| **GitHub CLI** | [gh](https://cli.github.com/) | ## Getting Started -Prerequisites: -1. Install [Bun](https://bun.sh/) (package manager and Node runtime) -2. Clone the repo from GitHub -``` +### Quick Start (Pre-built) + +**[Download Superset for macOS](https://github.com/superset-sh/superset/releases/latest)** + +### Build from Source + +
+Click to expand build instructions + +**1. Clone the repository** + +```bash git clone https://github.com/superset-sh/superset.git +cd superset ``` -3. Set up environment variables (choose one): - **Option A: Full setup** - ```bash - cp .env.example .env - ``` - Then edit `.env` and fill in the values +**2. Set up environment variables** (choose one): - **Option B: Skip env validation** - ```bash - export SKIP_ENV_VALIDATION=1 - ``` - This skips environment validation, useful for quickly running the app without external services. +Option A: Full setup +```bash +cp .env.example .env +# Edit .env and fill in the values +``` -Install dependencies: +Option B: Skip env validation (for quick local testing) ```bash -bun install +export SKIP_ENV_VALIDATION=1 ``` -Run in dev mode: + +**3. Install dependencies and run** + ```bash +bun install bun run dev ``` -Build desktop app: + +**4. Build the desktop app** + ```bash bun run build -open apps/desktop/release +open apps/desktop/release ``` -> [!NOTE] -> While Electron is cross-platform, Superset Desktop has only been built and tested on **macOS**. Other platforms are currently untested and may not work as expected. +
-### Usage +## Keyboard Shortcuts -For each parallel tasks, Superset uses git worktrees to clone a new branch on your machine. Automate copying env variables, installing dependencies, etc. through a config file (`.superset/config.json`). -Each workspace gets their own organized terminal system. You can create default presets. +All shortcuts are customizable via **Settings > Keyboard Shortcuts** (`⌘/`). See [full documentation](https://docs.superset.sh/keyboard-shortcuts). -Screenshot 2025-12-24 at 9 33 35 PM +### Workspace Navigation -Superset monitors your running agents, notify you when changes are ready, and help coordinate between multiple agents. There's a diff view with editor built in so you can quickly inspect and edit agents' changes. +| Shortcut | Action | +|:---------|:-------| +| `⌘1-9` | Switch to workspace 1-9 | +| `⌘⌥↑/↓` | Previous/next workspace | +| `⌘N` | New workspace | +| `⌘⇧N` | Quick create workspace | +| `⌘⇧O` | Open project | -Screenshot 2025-12-24 at 9 33 51 PM +### Terminal -Superset is designed to be a superset of your existing tools. It works for any CLI agents that runs in the terminal. You can open your superset workspace in any apps like IDE, filesystem, terminal, etc. +| Shortcut | Action | +|:---------|:-------| +| `⌘T` | New tab | +| `⌘W` | Close pane/terminal | +| `⌘D` | Split right | +| `⌘⇧D` | Split down | +| `⌘K` | Clear terminal | +| `⌘F` | Find in terminal | +| `⌘⌥←/→` | Previous/next tab | +| `Ctrl+1-9` | Open preset 1-9 | -Screenshot 2025-12-24 at 9 34 04 PM +### Layout -### Tech Stack +| Shortcut | Action | +|:---------|:-------| +| `⌘B` | Toggle workspaces sidebar | +| `⌘L` | Toggle changes panel | +| `⌘O` | Open in external app | +| `⌘⇧C` | Copy path | -[![Electron](https://img.shields.io/badge/Electron-191970?logo=Electron&logoColor=white)](https://www.electronjs.org/) -[![React](https://img.shields.io/badge/React-%2320232a.svg?logo=react&logoColor=%2361DAFB)](https://reactjs.org/) -[![TailwindCSS](https://img.shields.io/badge/Tailwindcss-%2338B2AC.svg?logo=tailwind-css&logoColor=white)](https://tailwindcss.com/) -[![Bun](https://img.shields.io/badge/Bun-000000?logo=bun&logoColor=white)](https://bun.sh/) -[![Turborepo](https://img.shields.io/badge/Turborepo-EF4444?logo=turborepo&logoColor=white)](https://turbo.build/) -[![Vite](https://img.shields.io/badge/Vite-%23646CFF.svg?logo=vite&logoColor=white)](https://vitejs.dev/) -[![Biome](https://img.shields.io/badge/Biome-339AF0?logo=biome&logoColor=white)](https://biomejs.dev/) -[![Drizzle ORM](https://img.shields.io/badge/Drizzle%20ORM-FFE873?logo=drizzle&logoColor=black)](https://orm.drizzle.team/) -[![Neon](https://img.shields.io/badge/Neon-00E9CA?logo=neon&logoColor=white)](https://neon.tech/) -[![tRPC](https://img.shields.io/badge/tRPC-2596BE?logo=trpc&logoColor=white)](https://trpc.io/) +## Configuration +Configure workspace setup and teardown in `.superset/config.json`. See [full documentation](https://docs.superset.sh/setup-teardown-scripts). + +```json +{ + "setup": ["./.superset/setup.sh"], + "teardown": ["./.superset/teardown.sh"] +} +``` + +| Option | Type | Description | +|:-------|:-----|:------------| +| `setup` | `string[]` | Commands to run when creating a workspace | +| `teardown` | `string[]` | Commands to run when deleting a workspace | + +### Example setup script + +```bash +#!/bin/bash +# .superset/setup.sh + +# Copy environment variables +cp ../.env .env + +# Install dependencies +bun install + +# Run any other setup tasks +echo "Workspace ready!" +``` + +Scripts have access to environment variables: +- `SUPERSET_WORKSPACE_NAME` — Name of the workspace +- `SUPERSET_ROOT_PATH` — Path to the main repository + +## Tech Stack + +

+ Electron + React + TailwindCSS + Bun + Turborepo + Vite + Biome + Drizzle ORM + Neon + tRPC +

## Contributing -If you have a suggestion that would make this better, please fork the repo and -create a pull request. You can also -[open issues](https://github.com/superset-sh/superset/issues). +We welcome contributions! If you have a suggestion that would make Superset better: -See the [CONTRIBUTING.md](CONTRIBUTING.md) for instructions and code of conduct. +1. Fork the repository +2. Create your feature branch (`git checkout -b feature/amazing-feature`) +3. Commit your changes (`git commit -m 'Add amazing feature'`) +4. Push to the branch (`git push origin feature/amazing-feature`) +5. Open a Pull Request + +You can also [open issues](https://github.com/superset-sh/superset/issues) for bugs or feature requests. + +See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed instructions and code of conduct. -## Cookbook +## Community + +Join the Superset community to get help, share feedback, and connect with other users: -See tips and motivation under `docs`: [docs/cookbook/README.md](docs/cookbook/README.md). +- **[Discord](https://discord.gg/cZeD9WYcV7)** — Chat with the team and community +- **[Twitter](https://x.com/superset_sh)** — Follow for updates and announcements +- **[GitHub Issues](https://github.com/superset-sh/superset/issues)** — Report bugs and request features +- **[GitHub Discussions](https://github.com/superset-sh/superset/discussions)** — Ask questions and share ideas -## Follow Us -- [![Avi Twitter](https://img.shields.io/badge/Avi-@avimakesrobots-555?logo=x)](https://x.com/avimakesrobots) -- [![Kiet Twitter](https://img.shields.io/badge/Kiet-@flyakiet-555?logo=x)](https://x.com/flyakiet) -- [![Satya Twitter](https://img.shields.io/badge/Satya-@saddle_paddle-555?logo=x)](https://x.com/saddle_paddle) +### Team + +[![Avi Twitter](https://img.shields.io/badge/Avi-@avimakesrobots-555?logo=x)](https://x.com/avimakesrobots) +[![Kiet Twitter](https://img.shields.io/badge/Kiet-@flyakiet-555?logo=x)](https://x.com/flyakiet) +[![Satya Twitter](https://img.shields.io/badge/Satya-@saddle__paddle-555?logo=x)](https://x.com/saddle_paddle) ## License Distributed under the Apache 2.0 License. See [LICENSE.md](LICENSE.md) for more information. - - - -[superset-twitter]: https://x.com/supersetdev -[kiet-twitter]: https://x.com/flyakiet -[satya-twitter]: https://x.com/saddle_paddle -[avi-twitter]: https://x.com/avimakesrobots -[contributors-shield]: https://img.shields.io/github/contributors/superset-sh/studio.svg?style=for-the-badge -[contributors-url]: https://github.com/superset-sh/superset/graphs/contributors -[forks-shield]: https://img.shields.io/github/forks/superset-sh/studio.svg?style=for-the-badge -[forks-url]: https://github.com/superset-sh/superset/network/members -[stars-shield]: https://img.shields.io/github/stars/superset-sh/studio.svg?style=for-the-badge -[stars-url]: https://github.com/superset-sh/superset/stargazers -[issues-shield]: https://img.shields.io/github/issues/superset-sh/studio.svg?style=for-the-badge -[issues-url]: https://github.com/superset-sh/superset/issues -[license-shield]: https://img.shields.io/github/license/superset-sh/studio.svg?style=for-the-badge -[license-url]: ./LICENSE.txt -[linkedin-shield]: https://img.shields.io/badge/-LinkedIn-black.svg?logo=linkedin&colorB=555 -[linkedin-url]: https://www.linkedin.com/company/superset-sh -[twitter-shield]: https://img.shields.io/badge/-Twitter-black?logo=x&colorB=555 -[twitter-url]: https://x.com/supersetdev -[discord-shield]: https://img.shields.io/badge/-Discord-black?logo=discord&colorB=555 -[discord-url]: https://discord.gg/hERDfFZCsH -[React.js]: https://img.shields.io/badge/react-%2320232a.svg?logo=react&logoColor=%2361DAFB -[React-url]: https://reactjs.org/ -[TailwindCSS]: https://img.shields.io/badge/tailwindcss-%2338B2AC.svg?logo=tailwind-css&logoColor=white -[Tailwind-url]: https://tailwindcss.com/ -[Electron.js]: https://img.shields.io/badge/Electron-191970?logo=Electron&logoColor=white -[Electron-url]: https://www.electronjs.org/ -[Vite.js]: https://img.shields.io/badge/vite-%23646CFF.svg?logo=vite&logoColor=white -[Vite-url]: https://vitejs.dev/ -[product-screenshot]: assets/brand.png diff --git a/SEO_AUDIT_PLAN.md b/SEO_AUDIT_PLAN.md deleted file mode 100644 index 40bd58b9338..00000000000 --- a/SEO_AUDIT_PLAN.md +++ /dev/null @@ -1,892 +0,0 @@ -# Superset SEO Audit & Improvement Plan - -**Audit Date:** January 26, 2026 -**Sites Audited:** superset.sh (marketing + blog), docs.superset.sh - ---- - -## Executive Summary - -The Superset websites have a solid foundation with Next.js 16 and proper content structure, but are missing several critical SEO elements that significantly impact search visibility. The most urgent issues are: - -1. **No robots.txt** on either site - search engines have no crawl guidance -2. **No sitemap.xml** on either site - pages aren't efficiently discovered -3. **Docs OG/Twitter images resolve to localhost** - broken social previews and share cards -4. **LLM/MDX endpoints are indexable** - duplicate content + wasted crawl budget -5. **Missing canonical URLs** - risk of duplicate content issues -6. **No structured data (JSON-LD)** - missing rich snippets in search results -7. **Incomplete Open Graph/Twitter Cards** - poor social sharing experience (blog index + non-home pages) - ---- - -## Critical Issues (Fix Immediately) - -### 1. Missing robots.txt (Both Sites) - -**Impact:** Search engines have no guidance on crawl behavior, crawl budget may be wasted. - -**Files to create:** - -#### Marketing Site -``` -apps/marketing/src/app/robots.ts -``` -```typescript -import type { MetadataRoute } from "next"; - -export default function robots(): MetadataRoute.Robots { - return { - rules: [ - { - userAgent: "*", - allow: "/", - disallow: ["/api/", "/_next/"], - }, - ], - sitemap: "https://superset.sh/sitemap.xml", - }; -} -``` - -#### Docs Site -``` -apps/docs/src/app/robots.ts -``` -```typescript -import type { MetadataRoute } from "next"; - -export default function robots(): MetadataRoute.Robots { - return { - rules: [ - { - userAgent: "*", - allow: "/", - disallow: ["/api/", "/_next/", "/llms.mdx/", "/*.mdx"], - }, - ], - sitemap: "https://docs.superset.sh/sitemap.xml", - }; -} -``` - ---- - -### 2. Missing sitemap.xml (Both Sites) - -**Impact:** Search engines discover new pages slowly, blog posts may not be indexed promptly. - -#### Marketing Site -``` -apps/marketing/src/app/sitemap.ts -``` -```typescript -import type { MetadataRoute } from "next"; -import { getBlogPosts } from "@/lib/blog"; - -export default async function sitemap(): Promise { - const baseUrl = "https://superset.sh"; - - // Static pages - const staticPages: MetadataRoute.Sitemap = [ - { - url: baseUrl, - lastModified: new Date(), - changeFrequency: "weekly", - priority: 1.0, - }, - { - url: `${baseUrl}/blog`, - lastModified: new Date(), - changeFrequency: "daily", - priority: 0.9, - }, - { - url: `${baseUrl}/privacy`, - lastModified: new Date("2025-01-15"), - changeFrequency: "yearly", - priority: 0.3, - }, - { - url: `${baseUrl}/terms`, - lastModified: new Date("2025-01-15"), - changeFrequency: "yearly", - priority: 0.3, - }, - { - url: `${baseUrl}/ports`, - lastModified: new Date(), - changeFrequency: "monthly", - priority: 0.5, - }, - ]; - - // Dynamic blog posts - const posts = await getBlogPosts(); - const blogPages: MetadataRoute.Sitemap = posts.map((post) => ({ - url: `${baseUrl}/blog/${post.slug}`, - lastModified: new Date(post.date), - changeFrequency: "monthly" as const, - priority: 0.8, - })); - - return [...staticPages, ...blogPages]; -} -``` - -#### Docs Site -``` -apps/docs/src/app/sitemap.ts -``` -```typescript -import type { MetadataRoute } from "next"; -import { source } from "@/lib/source"; - -export default function sitemap(): MetadataRoute.Sitemap { - const baseUrl = "https://docs.superset.sh"; - - const pages = source.getPages(); - - return pages.map((page) => ({ - url: `${baseUrl}${page.url}`, - lastModified: new Date(), - changeFrequency: "weekly" as const, - priority: page.url === "/quick-start" ? 1.0 : 0.8, - })); -} -``` - ---- - -### 3. Missing Canonical URLs - -**Impact:** Potential duplicate content issues, PageRank dilution. - -#### Marketing Site - Update layout.tsx -``` -apps/marketing/src/app/layout.tsx -``` -Add `metadataBase`: -```typescript -export const metadata: Metadata = { - metadataBase: new URL("https://superset.sh"), - // ... existing metadata - alternates: { - canonical: "/", - }, -}; -``` - -#### Docs Site - Update layout.tsx -``` -apps/docs/src/app/layout.tsx -``` -Add `metadataBase`: -```typescript -export const metadata: Metadata = { - metadataBase: new URL("https://docs.superset.sh"), - // ... existing metadata -}; -``` - ---- - -### 4. Docs OG/Twitter Images Resolve to localhost - -**Impact:** Broken social previews and incorrect OG image URLs in production (currently resolving to `http://localhost:3000/...`). - -**Root cause:** `metadataBase` is not set for docs, and OG image URLs are generated as relative paths. - -**Fix:** Set `metadataBase` and ensure OG/Twitter images use relative URLs that resolve against it. - -``` -apps/docs/src/app/layout.tsx -``` -```typescript -export const metadata: Metadata = { - metadataBase: new URL("https://docs.superset.sh"), - // ... existing metadata -}; -``` - -``` -apps/docs/src/app/(docs)/[[...slug]]/page.tsx -``` -```typescript -export async function generateMetadata( - props: PageProps<"/[[...slug]]">, -): Promise { - const params = await props.params; - const page = source.getPage(params.slug); - if (!page) notFound(); - - const pageImage = getPageImage(page).url; - - return { - title: page.data.title, - description: page.data.description, - openGraph: { - images: [pageImage], - }, - twitter: { - card: "summary_large_image", - images: [pageImage], - }, - }; -} -``` - ---- - -### 5. LLM/MDX Endpoints Are Indexable (Duplicate Content) - -**Impact:** Duplicate content (`/quick-start.mdx`, `/llms.mdx/...`) can be indexed alongside the canonical docs URLs. - -**Fix:** Add `X-Robots-Tag: noindex, nofollow` and disallow these paths in `robots.txt`. - -``` -apps/docs/src/app/llms.mdx/[[...slug]]/route.ts -``` -```typescript -return new Response(await getLLMText(page), { - headers: { - "Content-Type": "text/markdown", - "X-Robots-Tag": "noindex, nofollow", - }, -}); -``` - -``` -apps/docs/src/app/robots.ts -``` -```typescript -export default function robots(): MetadataRoute.Robots { - return { - rules: [ - { - userAgent: "*", - allow: "/", - disallow: ["/api/", "/_next/", "/llms.mdx/", "/*.mdx"], - }, - ], - sitemap: "https://docs.superset.sh/sitemap.xml", - }; -} -``` - ---- - -### 6. Missing Structured Data (JSON-LD) - -**Impact:** No rich snippets in search results, missing knowledge graph signals. - -#### Homepage - Organization Schema -``` -apps/marketing/src/app/components/JsonLd/JsonLd.tsx -``` -```typescript -export function OrganizationJsonLd() { - const schema = { - "@context": "https://schema.org", - "@type": "Organization", - name: "Superset", - url: "https://superset.sh", - logo: "https://superset.sh/logo.png", - description: "Run 10+ parallel coding agents on your machine", - sameAs: [ - "https://github.com/AviSupersetSH/superset", - "https://twitter.com/AviSupersetSH", - "https://discord.gg/superset", - ], - foundingDate: "2024", - founders: [ - { - "@type": "Person", - name: "Avi Peltz", - }, - ], - }; - - return ( -