tMemory

Flip pairs, beat the clock, and compare your best runs across terminal and web.

🚀 What is tMemory?

tMemory started as a command-line love letter to the classic Memory card game. It blends React, Ink, and a Supabase-backed API so every flip, combo, and photo-finish can land on a shared leaderboard. The experience now spans a polished CLI, a Next.js-powered leaderboard site at https://tmemory.griffen.codes/, and an API that keeps both in sync.

✨ Key Features

• Core Gameplay — Single-player, head-to-head, and AI showdowns with grid sizes from 2×2 up to custom 12×12 layouts.
• Competitive Edge — Global leaderboards track your best times with optional filters by game mode, rows, and columns so you can “See how you stack up against players from all over the world. Filter by game type and board size to find your competition.”
• Dual Experiences — Jump in instantly via npx tmemory or check the web experience for a quick visual leaderboard at https://tmemory.griffen.codes/.
• Smart Opponent — Face an AI rival that remembers the board and forces you to optimize every flip.
• Custom Boards — Design bespoke layouts directly in the CLI to craft practice drills or community challenges.

🎯 Perfect For

• Speedrunners hunting tighter reaction windows and quicker clears.
• Terminal fans who want a polished, animated CLI game built with Ink.
• Friendly competition circles that need a shared leaderboard without spinning up infrastructure.
• Developers exploring how React can power both terminal interfaces and serverless scoreboards.

⚡ Quick Start

# Play instantly
npx tmemory

# Or install for repeated play
npm install -g tmemory
tmemory

# Play instantly
npx tmemory

# Or install for repeated play
npm install -g tmemory
tmemory

📈 Impact & Proof

• Live leaderboard at https://tmemory.griffen.codes/ pulls scores from the shared Supabase database and stays in sync with every CLI submission.
• Next.js API endpoints at https://tmemory.griffen.codes/api/scores/submit and https://tmemory.griffen.codes/api/scores/leaderboard accept verified runs and serve the top boards on demand.

🧱 Technology Stack

• CLI: React + Ink UI, ink-playing-cards, TypeScript.
• Backend: Next.js App Router handlers with Zod validation, Supabase/PostgreSQL storage, profanity filtering.
• Distribution: Published as tmemory on npm with a compiled CLI entry point in dist/cli.js.

🔗 Links

• GitHub Repository — https://github.com/gfargo/tmemory
• npm Package — https://www.npmjs.com/package/tmemory
• Leaderboard & Web Showcase — https://tmemory.griffen.codes/
• API Source — https://github.com/gfargo/tMemory-www/tree/main/src/app/api/scores
• Ink Playing Cards Component — https://github.com/gfargo/ink-playing-cards

Give the CLI a spin, climb the leaderboard, and let me know where you place—I’m always ready for a rematch.