feat: add Supabase plugin

README.md

@@ -30,6 +30,7 @@ Each plugin lives in `plugins/<slug>`. The directory name is the install keyword
 | `linear` | Linear SDK scripting skill for issue, project, team, cycle, and comment workflows. |
 | `mac-notify` | macOS notifications when a Cline run completes. |
 | `nanobanana` | Image generation through OpenRouter and Gemini image models. |
+| `supabase` | Supabase MCP plus project, database, RLS, migrations, and Postgres best-practices skills. |
 | `speak` | Speaks completed Cline replies with ElevenLabs text to speech. |
 | `typescript-lsp` | TypeScript language service `goto_definition` support. |
 | `weather-metrics` | Demo weather tool plus runtime metrics hooks. |

plugins/supabase/README.md

@@ -0,0 +1,23 @@
+# supabase
+
+Supabase project and Postgres guidance for Cline, with the official Supabase remote MCP server and bundled Supabase skills.
+
+## What It Adds
+
+This plugin registers the official Supabase MCP server and bundles Supabase-focused skills for project work, database changes, auth, storage, realtime, edge functions, migrations, RLS, and Postgres performance best practices.
+
+It uses Cline's MCP authorization flow. It does not install the Supabase CLI, run migrations, query projects, or contact Supabase during installation.
+
+## Cline Primitives
+
+- MCP: `supabase` connects to `https://mcp.supabase.com/mcp` for Supabase project, docs, SQL, advisor, logs, migration, and management tools.
+- Skills: `supabase` for general Supabase workflows and `supabase-postgres-best-practices` for Postgres schema, query, connection, RLS, locking, monitoring, and data-access guidance.
+- Bundled guidance for credential masking, read/plan defaults, approval gates for SQL/project mutations, private/untrusted MCP output handling, migration review discipline, and official-doc verification.
+
+## Requirements
+
+Users need access to the relevant Supabase organization/project and may need to complete Supabase MCP OAuth through Cline. CLI workflows require a user-installed Supabase CLI or project-pinned CLI command runner; the plugin does not install the CLI.
+
+## Trust Boundaries
+
+Supabase workflows can expose schema, data rows, auth users, storage metadata, logs, connection strings, API keys, migrations, generated types, and production project configuration. The plugin asks before writes, migrations, broad reads, deployments, auth/storage/RLS changes, and production-impacting operations.

plugins/supabase/index.ts

@@ -0,0 +1,26 @@
+import type { AgentPlugin } from "@cline/sdk"
+
+const SUPABASE_MCP_URL = "https://mcp.supabase.com/mcp"
+
+const plugin: AgentPlugin = {
+	name: "supabase",
+	manifest: {
+		capabilities: ["mcp", "skills"],
+	},
+
+	setup(api) {
+		api.registerMcpServer({
+			name: "supabase",
+			transport: {
+				type: "streamableHttp",
+				url: SUPABASE_MCP_URL,
+				headers: {
+					"X-Source-Name": "cline-plugin",
+					"X-Source-Version": "0.0.0",
+				},
+			},
+		})
+	},
+}
+
+export default plugin

plugins/supabase/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "supabase",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Cline plugin that bundles Supabase MCP and Supabase/Postgres skills.",
+  "cline": {
+    "plugins": [
+      {
+        "paths": [
+          "./index.ts"
+        ],
+        "capabilities": [
+          "mcp",
+          "skills"
+        ]
+      }
+    ]
+  }
+}

plugins/supabase/skills/supabase-postgres-best-practices/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: supabase-postgres-best-practices
+description: Postgres performance optimization and best practices from Supabase. Use this skill when writing, reviewing, or optimizing Postgres queries, schema designs, or database configurations.
+license: MIT
+metadata:
+  author: supabase
+  version: "1.1.1"
+  organization: Supabase
+  date: January 2026
+  abstract: Comprehensive Postgres performance optimization guide for developers using Supabase and Postgres. Contains performance rules across 8 categories, prioritized by impact from critical (query performance, connection management) to incremental (advanced features). Each rule includes detailed explanations, incorrect vs. correct SQL examples, query plan analysis, and specific performance metrics to guide automated optimization and code generation.
+---
+
+# Supabase Postgres Best Practices
+
+Comprehensive performance optimization guide for Postgres, maintained by Supabase. Contains rules across 8 categories, prioritized by impact to guide automated query optimization and schema design.
+
+## When to Apply
+
+Reference these guidelines when:
+- Writing SQL queries or designing schemas
+- Implementing indexes or query optimization
+- Reviewing database performance issues
+- Configuring connection pooling or scaling
+- Optimizing for Postgres-specific features
+- Working with Row-Level Security (RLS)
+
+## Rule Categories by Priority
+
+| Priority | Category | Impact | Prefix |
+|----------|----------|--------|--------|
+| 1 | Query Performance | CRITICAL | `query-` |
+| 2 | Connection Management | CRITICAL | `conn-` |
+| 3 | Security & RLS | CRITICAL | `security-` |
+| 4 | Schema Design | HIGH | `schema-` |
+| 5 | Concurrency & Locking | MEDIUM-HIGH | `lock-` |
+| 6 | Data Access Patterns | MEDIUM | `data-` |
+| 7 | Monitoring & Diagnostics | LOW-MEDIUM | `monitor-` |
+| 8 | Advanced Features | LOW | `advanced-` |
+
+## How to Use
+
+Read individual rule files for detailed explanations and SQL examples:
+
+```
+references/query-missing-indexes.md
+references/query-partial-indexes.md
+references/_sections.md
+```
+
+Each rule file contains:
+- Brief explanation of why it matters
+- Incorrect SQL example with explanation
+- Correct SQL example with explanation
+- Optional EXPLAIN output or metrics
+- Additional context and references
+- Supabase-specific notes (when applicable)
+
+## References
+
+- https://www.postgresql.org/docs/current/
+- https://supabase.com/docs
+- https://wiki.postgresql.org/wiki/Performance_Optimization
+- https://supabase.com/docs/guides/database/overview
+- https://supabase.com/docs/guides/auth/row-level-security

plugins/supabase/skills/supabase-postgres-best-practices/references/_sections.md

@@ -0,0 +1,39 @@
+# Section Definitions
+
+This file defines the rule categories for Postgres best practices. Rules are automatically assigned to sections based on their filename prefix.
+
+Take the examples below as pure demonstrative. Replace each section with the actual rule categories for Postgres best practices.
+
+---
+
+## 1. Query Performance (query)
+Impact: CRITICAL
+Description: Slow queries, missing indexes, inefficient query plans. The most common source of Postgres performance issues.
+
+## 2. Connection Management (conn)
+Impact: CRITICAL
+Description: Connection pooling, limits, and serverless strategies. Critical for applications with high concurrency or serverless deployments.
+
+## 3. Security & RLS (security)
+Impact: CRITICAL
+Description: Row-Level Security policies, privilege management, and authentication patterns.
+
+## 4. Schema Design (schema)
+Impact: HIGH
+Description: Table design, index strategies, partitioning, and data type selection. Foundation for long-term performance.
+
+## 5. Concurrency & Locking (lock)
+Impact: MEDIUM-HIGH
+Description: Transaction management, isolation levels, deadlock prevention, and lock contention patterns.
+
+## 6. Data Access Patterns (data)
+Impact: MEDIUM
+Description: N+1 query elimination, batch operations, cursor-based pagination, and efficient data fetching.
+
+## 7. Monitoring & Diagnostics (monitor)
+Impact: LOW-MEDIUM
+Description: Using pg_stat_statements, EXPLAIN ANALYZE, metrics collection, and performance diagnostics.
+
+## 8. Advanced Features (advanced)
+Impact: LOW
+Description: Full-text search, JSONB optimization, PostGIS, extensions, and advanced Postgres features.

plugins/supabase/skills/supabase-postgres-best-practices/references/advanced-full-text-search.md

@@ -0,0 +1,55 @@
+---
+title: Use tsvector for Full-Text Search
+impact: MEDIUM
+impactDescription: 100x faster than LIKE, with ranking support
+tags: full-text-search, tsvector, gin, search
+---
+
+## Use tsvector for Full-Text Search
+
+LIKE with wildcards can't use indexes. Full-text search with tsvector is orders of magnitude faster.
+
+Incorrect (LIKE pattern matching):
+
+```sql
+-- Cannot use index, scans all rows
+select * from articles where content like '%postgresql%';
+
+-- Case-insensitive makes it worse
+select * from articles where lower(content) like '%postgresql%';
+```
+
+Correct (full-text search with tsvector):
+
+```sql
+-- Add tsvector column and index
+alter table articles add column search_vector tsvector
+  generated always as (to_tsvector('english', coalesce(title,'') || ' ' || coalesce(content,''))) stored;
+
+create index articles_search_idx on articles using gin (search_vector);
+
+-- Fast full-text search
+select * from articles
+where search_vector @@ to_tsquery('english', 'postgresql & performance');
+
+-- With ranking
+select *, ts_rank(search_vector, query) as rank
+from articles, to_tsquery('english', 'postgresql') query
+where search_vector @@ query
+order by rank desc;
+```
+
+Search multiple terms:
+
+```sql
+-- AND: both terms required
+to_tsquery('postgresql & performance')
+
+-- OR: either term
+to_tsquery('postgresql | mysql')
+
+-- Prefix matching
+to_tsquery('post:*')
+```
+
+Reference: [Full Text Search](https://supabase.com/docs/guides/database/full-text-search)

plugins/supabase/skills/supabase-postgres-best-practices/references/advanced-jsonb-indexing.md

@@ -0,0 +1,49 @@
+---
+title: Index JSONB Columns for Efficient Querying
+impact: MEDIUM
+impactDescription: 10-100x faster JSONB queries with proper indexing
+tags: jsonb, gin, indexes, json
+---
+
+## Index JSONB Columns for Efficient Querying
+
+JSONB queries without indexes scan the entire table. Use GIN indexes for containment queries.
+
+Incorrect (no index on JSONB):
+
+```sql
+create table products (
+  id bigint primary key,
+  attributes jsonb
+);
+
+-- Full table scan for every query
+select * from products where attributes @> '{"color": "red"}';
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+Correct (GIN index for JSONB):
+
+```sql
+-- GIN index for containment operators (@>, ?, ?&, ?|)
+create index products_attrs_gin on products using gin (attributes);
+
+-- Now containment queries use the index
+select * from products where attributes @> '{"color": "red"}';
+
+-- For specific key lookups, use expression index
+create index products_brand_idx on products ((attributes->>'brand'));
+select * from products where attributes->>'brand' = 'Nike';
+```
+
+Choose the right operator class:
+
+```sql
+-- jsonb_ops (default): supports all operators, larger index
+create index idx1 on products using gin (attributes);
+
+-- jsonb_path_ops: only @> operator, but 2-3x smaller index
+create index idx2 on products using gin (attributes jsonb_path_ops);
+```
+
+Reference: [JSONB Indexes](https://www.postgresql.org/docs/current/datatype-json.html#JSON-INDEXING)

plugins/supabase/skills/supabase-postgres-best-practices/references/conn-idle-timeout.md

@@ -0,0 +1,46 @@
+---
+title: Configure Idle Connection Timeouts
+impact: HIGH
+impactDescription: Reclaim 30-50% of connection slots from idle clients
+tags: connections, timeout, idle, resource-management
+---
+
+## Configure Idle Connection Timeouts
+
+Idle connections waste resources. Configure timeouts to automatically reclaim them.
+
+Incorrect (connections held indefinitely):
+
+```sql
+-- No timeout configured
+show idle_in_transaction_session_timeout;  -- 0 (disabled)
+
+-- Connections stay open forever, even when idle
+select pid, state, state_change, query
+from pg_stat_activity
+where state = 'idle in transaction';
+-- Shows transactions idle for hours, holding locks
+```
+
+Correct (automatic cleanup of idle connections):
+
+```sql
+-- Terminate connections idle in transaction after 30 seconds
+alter system set idle_in_transaction_session_timeout = '30s';
+
+-- Terminate completely idle connections after 10 minutes
+alter system set idle_session_timeout = '10min';
+
+-- Reload configuration
+select pg_reload_conf();
+```
+
+For pooled connections, configure at the pooler level:
+
+```ini
+# pgbouncer.ini
+server_idle_timeout = 60
+client_idle_timeout = 300
+```
+
+Reference: [Connection Timeouts](https://www.postgresql.org/docs/current/runtime-config-client.html#GUC-IDLE-IN-TRANSACTION-SESSION-TIMEOUT)

plugins/supabase/skills/supabase-postgres-best-practices/references/conn-limits.md

@@ -0,0 +1,44 @@
+---
+title: Set Appropriate Connection Limits
+impact: CRITICAL
+impactDescription: Prevent database crashes and memory exhaustion
+tags: connections, max-connections, limits, stability
+---
+
+## Set Appropriate Connection Limits
+
+Too many connections exhaust memory and degrade performance. Set limits based on available resources.
+
+Incorrect (unlimited or excessive connections):
+
+```sql
+-- Default max_connections = 100, but often increased blindly
+show max_connections;  -- 500 (way too high for 4GB RAM)
+
+-- Each connection uses 1-3MB RAM
+-- 500 connections * 2MB = 1GB just for connections!
+-- Out of memory errors under load
+```
+
+Correct (calculate based on resources):
+
+```sql
+-- Formula: max_connections = (RAM in MB / 5MB per connection) - reserved
+-- For 4GB RAM: (4096 / 5) - 10 = ~800 theoretical max
+-- But practically, 100-200 is better for query performance
+
+-- Recommended settings for 4GB RAM
+alter system set max_connections = 100;
+
+-- Also set work_mem appropriately
+-- work_mem * max_connections should not exceed 25% of RAM
+alter system set work_mem = '8MB';  -- 8MB * 100 = 800MB max
+```
+
+Monitor connection usage:
+
+```sql
+select count(*), state from pg_stat_activity group by state;
+```
+
+Reference: [Database Connections](https://supabase.com/docs/guides/platform/performance#connection-management)