AI Stack helps developers and teams discover, compare, and share AI technology stacks. Whether you are building a new AI-powered application or optimizing an existing setup, AI Stack is a curated collection of tools, frameworks, and configs that lets you make informed decisions - and carry your own AI config between machines with one command.

• 🔍 Discover AI tools and frameworks organized by stack
• ⚖️ Compare stacks side by side and cut costs for your own usage
• 🚀 Share your own AI stacks with the community
• ➕ Add missing tools inline during stack creation or in batch mode
• 🔄 Sync configs between your repo and the web with the CLI
• 🔐 Authentication via email/password and Google SSO

AI Stack has two surfaces that work together: the web app where you browse and publish, and the CLI that bridges your local filesystem with your stack.

flowchart LR
    dev(["👩‍💻 Your repo"]) -->|aistack collect| stack[("📦 Your Stack<br/>on aistack.to")]
    stack -->|browse & compare| world(["🌍 Community"])
    world -->|fork ideas| stack
    stack -->|aistack create| any(["🖥️ Any machine"])

1. The web app (aistack.to) - where you browse stacks, compare tools, and publish your own setups. Each stack groups multiple projects, and each project holds your actual AI config files (prompts, rules, skills, MCP servers).

2. The CLI (@use-aistack/cli) - a small tool that scans your project for AI config files and uploads them, or clones someone else's configs into your working directory. No manual copy-paste.

Typical flow:

• Sign up on the web app and create a stack.
• Run npx @use-aistack/cli collect inside your repo to upload your .cursorrules, CLAUDE.md, AGENTS.md, skills, and MCP configs to your stack.
• Share the stack link. On another machine, run npx @use-aistack/cli create to write that AI setup into the current directory.

The CLI is published to npm as @use-aistack/cli. Run it on demand with npx - no install required:

npx @use-aistack/cli <command>

collect detects: .cursorrules, CLAUDE.md, AGENTS.md, .cursor/rules/, mcp.json, skill directories, prompts, and global configs (~/.claude/, ~/.cursor/, etc).

Install globally (optional) - if you would rather type aistack than npx @use-aistack/cli every time:

npm i -g @use-aistack/cli
# then: aistack login · aistack collect · aistack create

• Framework: TanStack Start - full-stack React framework
• UI Library: React 19 - latest React with concurrent features
• Styling: Tailwind CSS v4 - utility-first CSS framework
• Icons: Lucide React - beautiful & consistent icons
• Animations: Motion & GSAP - smooth animations
• Components: Radix UI - accessible component primitives

• Backend: Convex - serverless database and backend functions
• Authentication: Better Auth - modern authentication solution
• State Management: TanStack Query - server state management
• Forms: TanStack Forms - type-safe form handling

• Language: TypeScript - type-safe JavaScript
• Build Tool: Vite - fast build tool and dev server
• Package Manager: pnpm - fast, disk-space-efficient package manager
• Linting/Formatting: Biome - all-in-one toolchain
• Testing: Vitest - fast unit testing framework
• Analytics: PostHog - product analytics suite

aistack/              # Main web application
├── convex/           # Convex backend functions & schema
├── public/           # Static assets
├── src/              # React application source
│   ├── components/   # Shared UI primitives and cross-feature components
│   ├── features/     # Feature-scoped modules (landing, stack-editor, etc.)
│   ├── integrations/ # Third-party integrations
│   └── routes/       # File-based routing
└── README.md         # You are here

Frontend architecture notes

• Route files should stay composition-focused (data fetch + section orchestration).
• Landing page is organized under src/features/landing/*.
• Stack editor is organized under src/features/stack-editor/* with section components in sections/*, reducer/selectors/hooks in state/*, and status computation in editor-status.ts.
• Reusable visual wrappers live under src/components/system/*.

• Node.js (v18 or higher)
• pnpm (recommended) or npm
• Git

# 1. Clone the repository
git clone https://github.com/alp82/aistack.git
cd aistack

# 2. Install dependencies
pnpm install

# 3. Set up environment variables
cp .env.example .env.local
# VITE_CONVEX_URL and CONVEX_DEPLOYMENT are required

# 4. Initialize Convex (sets up your deployment + env vars)
pnpm convex dev

# 5. Start the development server
pnpm dev

The application will be available at:

• Frontend: http://localhost:3019
• Convex Dashboard: http://localhost:3210

# Development
pnpm dev          # Start development server
pnpm convex dev   # Start Convex backend server

# Building
pnpm build        # Build for production
pnpm preview      # Preview production build

# Code Quality
pnpm lint         # Run Biome linter
pnpm format       # Format code with Biome
pnpm check        # Run all Biome checks

# Testing
pnpm test         # Run unit tests with Vitest

The project uses Vitest for unit testing. Tests live in src/**/__tests__ directories.

Vitest is configured in vite.config.ts with test.environment = "jsdom" and test.setupFiles = ["./src/test/setup.ts"]. src/test/setup.ts loads @testing-library/jest-dom/vitest matchers for DOM assertions.

# Run all tests
pnpm test

# Run a single test file
pnpm vitest run src/features/stack-editor/state/__tests__/editor-reducer.test.ts

# Watch mode
pnpm test --watch

# Coverage report
pnpm test --coverage

This project uses Shadcn UI components. Add new components with:

pnpm dlx shadcn@latest add [component-name]

Design note: No border-radius (sharp corners throughout), monospace fonts for buttons/labels/technical accents, and lime as the brand color.

• The development server runs on http://localhost:3019; the Convex backend on http://localhost:3210. Both should stay running during development.
• Use Chrome DevTools MCP for debugging and reviewing code updates.
• Dev Admin Access: in development mode, a "Dev Admin Login" button appears on the login page. It signs in as dev-admin@example.com with admin privileges. Requires the Convex env var IS_DEV=true (email verification is also skipped when IS_DEV=true).

Migration scripts live in convex/migrations/. Run them via the Convex Dashboard (Functions tab → pick the function → Run Function) or the CLI:

# Run an internal query (read-only, for previews)
npx convex run migrations/backup:exportStackDescriptions

# Run an internal mutation (makes changes)
npx convex run migrations/populateShortIds:populateAllShortIds

migrations/backup.ts - Backup & Restore

migrations/populateShortIds.ts - ShortId Population

migrations/migrateStackDescriptions.ts - Description Migration

⚠️ Before running migrations on production, always create a backup first.

# 1. Backup existing stack descriptions
npx convex run migrations/backup:exportStackDescriptions > backup-stacks.json

# 2. Check how many records need shortId population
npx convex run migrations/populateShortIds:getMissingCounts

# 3. Populate shortIds for tools, models, and bundles
npx convex run migrations/populateShortIds:populateAllShortIds

# 4. Preview description migration (dry run)
npx convex run migrations/migrateStackDescriptions:dryRunMigration

# 5. Run the actual description migration
npx convex run migrations/migrateStackDescriptions:migrateAllStackDescriptions

Restoring from backup

# Single stack
npx convex run migrations/backup:restoreStackDescription \
  '{"stackId": "k1234...", "description": "<p>Original content...</p>"}'

# Multiple stacks (pass a JSON array)
npx convex run migrations/backup:restoreStackDescriptionsBatch \
  '{"backups": [{"stackId": "k1234...", "description": "..."}]}'

Contributions are welcome.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request against main

Licensed under the MIT License - see the LICENSE file for details.

• TanStack Documentation
• Convex Documentation
• Tailwind CSS
• Better Auth