Amp Directory

An experimental Next.js and Convex catalog prototype for browsing, submitting, and upvoting Amp CLI plugins shared through GitHub Gists or repositories.

Problem and solution

Experimental Amp plugins are distributed across individual links and can be hard to compare before installation. Amp Directory explores a searchable catalog with capability filters, trust warnings, install snippets, anonymous upvotes, and GitHub metadata enrichment.

Status

This is an experimental prototype, not a maintained service or a verified plugin registry. There is no supported public deployment, release, moderation queue, authentication system, or stability guarantee. The repository's default deployment URL is not live.

Install and run locally

This project uses Bun and requires a Convex backend. Anonymous local mode is the quickest way to evaluate it without a Convex account:

bun install
CONVEX_AGENT_MODE=anonymous bunx convex dev --once --typecheck disable
CONVEX_AGENT_MODE=anonymous bunx convex run seed:run
bun run dev

The seed command deletes existing plugin and vote records before loading fictional fixtures. Do not run it against data you need to keep.

Trust and privacy boundary

• Plugin descriptions, capabilities, compatibility notes, trust notes, and install commands are submitted or fixture data. They are not reviewed or verified. Inspect a plugin's source and requested capabilities before running any install command.
• Submissions are stored in Convex and include all form fields, including the free-form submitter name. For supported GitHub URLs, the Convex action sends a server-side request to the GitHub REST API for public metadata.
• Upvoting creates a random browser identifier in localStorage and stores that identifier with the plugin ID in Convex. There are no user accounts.
• The optional GITHUB_TOKEN is read only by the Convex action and is not sent to the browser. Deployers are responsible for their Convex and GitHub data handling, retention, access controls, and rate limits.
• The prototype has no submission moderation, abuse controls, or authenticity checks and should not be exposed as a production registry without them.

License

No license has been granted for this repository. Copyright law applies by default, so public visibility does not provide permission to copy, modify, or redistribute the code. A future license decision must be made by the rights holder.

Provenance

The repository history began with a single commit attributed to pc-style. The catalog records in convex/seed.ts are fictional development fixtures, not verified plugins or endorsements. Their source URLs were unresolved when audited on August 16, 2026, and their stars, upvotes, compatibility claims, and trust notes are synthetic. Bundled agent skill files identify Leonxlnx/taste-skill as their source in skills-lock.json. Those files match the audited upstream versions and are covered by the upstream MIT License in THIRD_PARTY_NOTICES.md. That license does not apply to the rest of this repository.

Prototype features

• Browse, search, filter, and sort community plugins
• Upvote plugins (anonymous, no login)
• Submit plugins with live GitHub enrichment (stars + last-updated pulled from the real GitHub REST API)
• Per-plugin detail pages with capability descriptions, install snippets for both project and user scope, and an amber warning when a plugin requests high-trust capabilities

Stack

• Next.js 15 (App Router) + React 19
• Convex for the database, queries, mutations, and a network-capable action that calls the GitHub API
• Phosphor icons, hand-written CSS design system (warm monochrome editorial)
• Bun as the package manager

Data model

Each plugin record stores: name, slug, description (<= 280 chars), author, source URL + source type (gist | github-repo | github-file | other), plugin type (tool | command | subagent | hook | mcp | theme | other), capabilities, free-form tags, install snippet, compatibility/API notes, trust and safety notes, last-updated, stars, submitter, and upvote count.

Capabilities are chosen from: filesystem, shell, network, git, browser, clipboard, screenshot, audio, secrets, llm, telemetry, background. The five high-trust capabilities (shell, network, secrets, browser, background) are flagged with a warning marker throughout the UI.

Other local development options

You need a Convex deployment. Two options:

Option A: Convex Cloud (recommended)

bun install
bunx convex dev      # logs in, provisions a dev deployment, writes .env.local

In a second terminal:

bun run dev          # starts Next.js on http://localhost:3000

Seed sample data:

bunx convex run seed:run

Option B: run everything together

bun run dev:all      # runs `convex dev` and `next dev` concurrently

GitHub API token (optional)

Submitting a plugin performs a real request to the GitHub REST API to read stars and the last-updated timestamp. Public requests work without a token but are rate limited. To raise the limit, set a token on your Convex deployment:

bunx convex env set GITHUB_TOKEN ghp_your_token_here

Deploying to Vercel

1. Push this repo to GitHub and import it into Vercel.
2. Create a Convex production deployment and a deploy key:

   bunx convex deploy   # once, to create the prod deployment

   Then in the Convex dashboard, generate a Production deploy key.
3. In Vercel project settings, add an environment variable:
   • CONVEX_DEPLOY_KEY = the production deploy key
4. The build command is already configured in vercel.json:

   npx convex deploy --cmd 'next build'
   

   This pushes the Convex functions, sets NEXT_PUBLIC_CONVEX_URL for the build, and then runs next build. No further configuration is required.

If NEXT_PUBLIC_CONVEX_URL is ever missing at runtime, the app renders a clear configuration message instead of crashing.

Project layout

convex/
  schema.ts          tables and indexes
  plugins.ts         list / facets / getBySlug / featured / upvote / myVotes
  submit.ts          submitPlugin action (real GitHub fetch) + create mutation
  seed.ts            sample data (bunx convex run seed:run)
  lib/domain.ts      capabilities, types, install-snippet + time helpers
  lib/github.ts      source URL parsing + GitHub REST fetch
src/
  app/               layout, browse page, /p/[slug], /submit
  components/        cards, filters, upvote, copy, detail, submit form
  lib/               filters (URL state) + anonymous voter id