🤖 AI Agent Starter Kit

A modern full-stack AI-enabled template using Next.js for frontend and Express.js for backend, with Telegram and OpenAI integrations! ✨

🎯 Cursor IDE Integration

This template is specially crafted for the Cursor IDE, offering:

🤖 AI-assisted development with inline code explanations
🔍 Smart environment variable setup assistance
💡 Intelligent error resolution
📝 Context-aware code completion
🛠️ Built-in debugging helpers

Just highlight any error message, code snippet, or variable in Cursor and ask the AI for help!

🎮 Quick Cursor Commands

Cmd/Ctrl + K: Ask AI about highlighted code
Cmd/Ctrl + L: Get code explanations
Cmd/Ctrl + I: Generate code completions
Highlight any error message to get instant fixes

🚀 Getting Started

Prerequisites:

node >= 22 🟢
pnpm >= 9.14.1 📦

Install dependencies:

pnpm install

Fire up the dev servers:

pnpm run dev

📁 Repository Structure

.
├── 📦 client/                 # Next.js frontend
│   ├── 📱 app/               # Next.js app router (pages, layouts)
│   ├── 🧩 components/        # React components
│   │   └── HelloWorld.tsx    # Example component with API integration
│   ├── 💅 styles/           # Global styles and Tailwind config
│   │   ├── globals.css      # Global CSS and Tailwind imports
│   │   └── tailwind.config.ts # Tailwind configuration
│   ├── 🛠️ bin/             # Client scripts
│   │   └── validate-env     # Environment variables validator
│   ├── next.config.js       # Next.js configuration (API rewrites)
│   ├── .env.example         # Example environment variables for client
│   └── tsconfig.json        # TypeScript configuration
│
├── ⚙️ server/               # Express.js backend
│   ├── 📂 src/             # Server source code
│   │   ├── 🛣️ routes/     # API route handlers
│   │   │   └── hello.ts    # Example route with middleware
│   │   └── index.ts        # Server entry point (Express setup)
│   ├── 🛠️ bin/            # Server scripts
│   │   ├── validate-env    # Environment validator
│   │   └── www-dev        # Development server launcher
│   └── tsconfig.json       # TypeScript configuration
│
├── 📦 scripts/             # Project scripts
│   └── dev                 # Concurrent dev servers launcher
│
├── 📝 .env.example         # Root environment variables example for server
├── 🔧 package.json         # Root package with workspace config
└── 📦 pnpm-workspace.yaml  # PNPM workspace configuration

🔐 Environment Variables

💡 Pro Tip: In Cursor IDE, highlight any environment variable name and ask the AI for setup instructions!

Client (.env)

NEXT_PUBLIC_API_URL: Backend API URL (default: http://localhost:3001) 🌐
NEXT_PUBLIC_TELEGRAM_BOT_NAME: Telegram bot name without the @ symbol, you can get it from BotFather after creating your bot (default: your_bot_username) 🤖

Server (.env)

PORT: Server port (default: 3001) 🚪
NODE_ENV: Environment (development/production) 🌍
TELEGRAM_BOT_TOKEN: 🤖
1. Open Telegram and search for @BotFather
2. Start chat and send /newbot
3. Follow prompts to name your bot
4. Copy the provided token
OPENAI_API_KEY: 🧠
1. Visit https://platform.openai.com/api-keys
2. Click "Create new secret key"
3. Give it a name and copy the key immediately
4. Set usage limits in API settings if needed
NGROK_AUTH_TOKEN: 🔗
1. Create account at https://dashboard.ngrok.com/signup
2. Go to https://dashboard.ngrok.com/get-started/your-authtoken
3. Copy your authtoken
NGROK_DOMAIN: 🔗
1. Go to https://dashboard.ngrok.com/domains
2. Copy your domain (without https://)
COLLABLAND_API_KEY: 🤝
1. Visit https://dev-portal-qa.collab.land/signin
2. Click on "Get Started"
3. Select Telegram login
4. Login with Telegram
5. Verify your e-mail with the OTP sent to your inbox
6. Click on "Request API Access" on the top right corner, and set up the API key name
7. Copy your API key
GAIANET_MODEL: 🤖
1. Visit https://docs.gaianet.ai/user-guide/nodes
2. Choose your model (default: llama)
3. Copy the model name
GAIANET_SERVER_URL: 🌐
1. Visit https://docs.gaianet.ai/user-guide/nodes
2. Get server URL for your chosen model
3. Default: https://llama8b.gaia.domains/v1
GAIANET_EMBEDDING_MODEL: 🧬
1. Visit https://docs.gaianet.ai/user-guide/nodes
2. Choose embedding model (default: nomic-embed)
3. Copy the model name
USE_GAIANET_EMBEDDING: ⚙️
1. Set to TRUE to enable Gaianet embeddings
2. Set to FALSE to disable (default: TRUE)
JOKERACE_CONTRACT_ADDRESS: 🎰
1. Go to https://www.jokerace.io/contest/new
2. Create the contest
3. Copy the contract address
ELIZA_CHARACTER_PATH: 🤖
1. Default: "character.json"
2. Points to a JSON file containing your AI agent's personality configuration
3. Example paths:
  - character.json (default Ace personality)
  - vaitalik.json (Vitalik personality)
  - custom/my-agent.json (your custom personality)
TOKEN_DETAILS_PATH: Points to a JSON/JSONC file containing your token metadata for minting
1. Default: "token_metadata.example.jsonc"
2. Steps:
3. Copy the template: cp token_metadata.example.jsonc token.jsonc
4. Set this env var to point to your file
5. Example: token.jsonc
TWITTER_CLIENT_ID & TWITTER_CLIENT_SECRET: Authentication credentials for Twitter API integration
1. Go to Twitter Developer Portal
2. Create a new project/app if you haven't already
3. Navigate to "Keys and Tokens" section
4. Under "OAuth 2.0 Client ID and Client Secret":
  - Copy "Client ID" → TWITTER_CLIENT_ID
  - Generate "Client Secret" → TWITTER_CLIENT_SECRET
5. Configure OAuth settings:
  - Add callback URL: http://localhost:3001/auth/twitter/callback (development)
  - Add your production callback URL if deploying
6. Format: Alphanumeric strings
7. Example:
```
TWITTER_CLIENT_ID=Abc123XyzClientID
TWITTER_CLIENT_SECRET=Xyz789AbcClientSecret
```
DISCORD_CLIENT_ID & DISCORD_CLIENT_SECRET: Authentication credentials for Discord API integration
1. Go to Discord Developer Portal
2. Click "New Application" or select existing one
3. Navigate to "OAuth2" section in left sidebar
4. Under "Client Information":
  - Copy "Client ID" → DISCORD_CLIENT_ID
  - Copy "Client Secret" → DISCORD_CLIENT_SECRET
5. Configure OAuth settings:
  - Add redirect URL: http://localhost:3001/auth/discord/callback (development)
  - Add your production redirect URL if deploying
  - Select required scopes (typically identify and email)
6. Format: Alphanumeric strings
7. Example:
```
DISCORD_CLIENT_ID=123456789012345678
DISCORD_CLIENT_SECRET=abcdef123456789xyz
```
GITHUB_CLIENT_ID & GITHUB_CLIENT_SECRET: Authentication credentials for GitHub OAuth integration
1. Go to GitHub Developer Settings
2. Click "New OAuth App" or select existing one
3. Under "OAuth Apps" settings:
  - Application name: Your app name
  - Homepage URL: http://localhost:3001 (development)
  - Authorization callback URL: http://localhost:3001/auth/github/callback
4. After creating/selecting the app:
  - Copy "Client ID" → GITHUB_CLIENT_ID
  - Generate new "Client Secret" → GITHUB_CLIENT_SECRET
5. Configure OAuth scopes:
  - Recommended scopes: read:user, user:email
6. Format: Alphanumeric strings
7. Example:
```
GITHUB_CLIENT_ID=1234567890abcdef1234
GITHUB_CLIENT_SECRET=1234567890abcdef1234567890abcdef12345678
```

Note: For production, update the Homepage URL and callback URL to your production domain.

Security Notes:

Never commit these values to version control
Use different credentials for development and production
Rotate secrets periodically
Store production secrets in secure environment variables

🔒 Note: Keep these tokens secure! Never commit them to version control. The template's .gitignore has your back!

🚀 Production Setup

Build both apps:

pnpm run build

Launch production servers:

pnpm start

For production deployment: 🌎

Set NODE_ENV=production
Use proper SSL certificates 🔒
Configure CORS settings in server/src/index.ts 🛡️
Set up error handling and logging 📝
Use process manager like PM2 ⚡

🔧 Advanced Usage

🎯 Adding New Environment Variables

Client:

const ENV_HINTS = {
  NEXT_PUBLIC_API_URL: "Your API URL (usually http://localhost:3001)",
  // Add more hints as needed! ✨
};

Server:

const ENV_HINTS = {
  PORT: "API port (usually 3001)",
  NODE_ENV: "development or production",
  TELEGRAM_BOT_TOKEN: "Get from @BotFather",
  OPENAI_API_KEY: "Get from OpenAI dashboard",
  NGROK_AUTH_TOKEN: "Get from ngrok dashboard",
  // Add more hints as needed! ✨
};

Add TypeScript types in respective env.d.ts files 📝

🛣️ API Routes

Create new route file in server/src/routes/
Import and use in server/src/index.ts
Add corresponding client API call in client/components/

🎨 Frontend Components

Create component in client/components/
Use Tailwind CSS for styling
Follow existing patterns for API integration

⚙️ Backend Middleware

Create middleware in server/src/middleware/
Apply globally or per-route basis

🪙 Minting Tokens

Copy the token metadata template:

cp token_metadata.example.jsonc token.jsonc

Edit token.jsonc with your token details:

{
  "name": "YourToken", // Token name
  "symbol": "TOKEN", // Token symbol (2-6 chars)
  "description": "Your token description",
  "websiteLink": "https://yoursite.com",
  "twitter": "your_twitter_handle",
  "discord": "https://discord.gg/your_server",
  "telegram": "your_bot_telegram_username",
  "nsfw": false,
  "image": "ipfs://your_ipfs_hash", // Upload image to IPFS first
}

Update .env to point to your token file:

TOKEN_DETAILS_PATH=token.jsonc

Start your bot and use the /mint command in Telegram. The bot will:

Read your token config
Mint on Base Sepolia testnet
Return contract details and token page URL

Note: Make sure you have set up your COLLABLAND_API_KEY and TELEGRAM_BOT_TOKEN in .env first.

📚 Sources

Next.js App Router: https://nextjs.org/docs/app 🎯
Express.js: https://expressjs.com/ ⚡
Tailwind CSS: https://tailwindcss.com/docs 💅
TypeScript: https://www.typescriptlang.org/docs/ 📘

📝 Contributing

Commit Message Format

Follow these commit message guidelines to automate changelog generation:

feat: add new feature - New features (generates under 🚀 Features)
fix: resolve bug - Bug fixes (generates under 🐛 Bug Fixes)
docs: update readme - Documentation changes (generates under 📝 Documentation)
chore: update deps - Maintenance (generates under 🧰 Maintenance)

Example:

git commit -m "feat: add OAuth support for Discord"
git commit -m "fix: resolve token validation issue"

Name		Name	Last commit message	Last commit date
Latest commit History 33 Commits
.github		.github
client		client
scripts		scripts
server		server
.cursorrules		.cursorrules
.env.example		.env.example
.eslintignore		.eslintignore
.gitignore		.gitignore
.npmrc		.npmrc
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
HISTORY.md		HISTORY.md
LICENSE		LICENSE
README.md		README.md
character.json		character.json
commands.json		commands.json
package.json		package.json
pnpm-workspace.yaml		pnpm-workspace.yaml
token_metadata.example.jsonc		token_metadata.example.jsonc
vaitalik.json		vaitalik.json

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

🤖 AI Agent Starter Kit

🎯 Cursor IDE Integration

🎮 Quick Cursor Commands

🚀 Getting Started

📁 Repository Structure

🔐 Environment Variables

Client (.env)

Server (.env)

🚀 Production Setup

🔧 Advanced Usage

🎯 Adding New Environment Variables

🛣️ API Routes

🎨 Frontend Components

⚙️ Backend Middleware

🪙 Minting Tokens

📚 Sources

📝 Contributing

Commit Message Format

About

Releases

Packages

Languages

License

0xIntuition/AI-Agent-Starter-Kit

Folders and files

Latest commit

History

Repository files navigation

🤖 AI Agent Starter Kit

🎯 Cursor IDE Integration

🎮 Quick Cursor Commands

🚀 Getting Started

📁 Repository Structure

🔐 Environment Variables

Client (.env)

Server (.env)

🚀 Production Setup

🔧 Advanced Usage

🎯 Adding New Environment Variables

🛣️ API Routes

🎨 Frontend Components

⚙️ Backend Middleware

🪙 Minting Tokens

📚 Sources

📝 Contributing

Commit Message Format

About

Resources

License

Code of conduct

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages