🚀 ShellGen - AI-First Project Shell Generator

Formerly part of ClearGen. Now a standalone tool for generating project shells.

Generate consistent, empty project structures designed for AI-assisted development. Each project includes an MCP.json file that tells AI tools exactly where to put code.

Status: ✅ FULLY WORKING (v2.0.1)

✨ What It Does

ShellGen generates empty project shells (not full templates) that:

• ✅ Run immediately after generation with a starter page
• 🤖 Include docs/mcp.json for AI understanding
• 📁 Have proper folder structure for the project type
• 🎯 Are optimized for Claude, Cursor, ChatGPT, and other AI tools

🎯 Quick Start

# Install globally
npm install -g shellgen

# Generate a new project
shellgen init my-app --type ai-chatbot --features typescript,testing

# Or run directly from this repo
node dist/cli/index.js init my-app --type dashboard

# Navigate and run
cd my-app
npm install
npm run dev

🛠️ Available Shell Types

• 🤖 ai-chatbot - Chat interface with streaming responses
• 🛍️ ecommerce - Online store with products and cart
• 📊 dashboard - Analytics with charts and widgets
• 🔌 api-server - RESTful backend with routes
• 🏠 landing-page - Marketing site with sections
• 🚀 fullstack - Complete frontend + backend

📦 Features

• typescript - TypeScript configuration
• testing - Testing framework (Vitest)
• tailwind - Tailwind CSS styling
• authentication - Auth structure
• database - Database models
• docker - Docker configuration
• ci-cd - GitHub Actions

🎨 Visual Interface

# Start the GUI
shellgen gui

# Or from this repo
node dist/cli/index.js gui

# Open browser to http://localhost:3000

🤖 How It Works with AI

1. Generate Shell: Creates empty folder structure
2. MCP.json: Includes AI context file with:
   • Folder purposes and descriptions
   • Code placement patterns
   • Dependencies and features
   • Project conventions
3. Starter Page: Working demo page that runs immediately
4. AI Development: Open in AI tool and it knows where everything goes

📁 Example Generated Structure

my-app/
├── src/
│   ├── components/     # React components
│   ├── api/            # API endpoints
│   ├── lib/            # Utilities
│   └── styles/         # CSS files
├── docs/
│   └── mcp.json       # AI context file (tells AI where to put code)
├── package.json       # With correct dependencies
├── index.html         # Entry point
├── App.tsx            # Starter page showing project info
└── vite.config.ts     # Dev server config

🚀 AI Development Workflow

1. Generate a shell:

   shellgen init my-chat-app --type ai-chatbot --features typescript

2. Run immediately to see it works:

   cd my-chat-app
   npm install
   npm run dev  # Opens starter page at localhost:3000

3. Open in your AI tool:

   cursor my-chat-app
   # or open in Claude, VS Code + Copilot, etc.

4. Tell the AI:

   "Read docs/mcp.json and help me build a chat interface with streaming responses"

5. The AI knows:

   • Put chat components in src/components/chat/
   • Put API endpoints in src/api/chat/
   • Use the streaming utilities in src/lib/streaming/

🔧 Development

# Clone the repo
git clone https://github.com/jpoindexter/shellgen.git
cd shellgen

# Install dependencies
npm install

# Build
npm run build

# Test locally
node dist/cli/index.js init test-app --type dashboard --features typescript,tailwind
cd test-app && npm install && npm run dev

📋 Commands

CLI Commands

• init [name] - Generate a new project shell
• list - Show available shell types
• history [path] - Show generation history
• gui - Launch visual interface

Options

• --type <type> - Shell type (ai-chatbot, ecommerce, dashboard, etc.)
• --features <features> - Comma-separated features
• --output <path> - Output directory

📚 Documentation

• Shell Types Guide
• MCP Integration
• API Reference
• Troubleshooting

📝 License

MIT - Free and open source

---

Built for the AI development era. Generate consistent structures that AI understands.

ShellGen is the project generator. Looking for the AI-optimized Next.js boilerplate? Check out ClearGen.