🔮 Kuro

The Next-Gen, Immersive GitHub Intelligence & Workspace Suite.

A futuristic developer command center. Gamified workflows, automated maintenance, and recruiter-focused portfolio optimization wrapped in a high-fidelity liquid-glass design system.

  

---

📍 Navigation

• ✨ Why Kuro?
• 🚀 Key Features
• 🎨 Theme Showcase
• 🛠️ Tech Stack
• ⚡ Quick Start & Installation
• 🔑 Environment Variables
• 🛡️ Authentication & Setup
• 📂 Folder Layout
• 🤝 Contributing
• 📄 License

---

✨ Why Kuro?

Existing developer dashboards feel like boring, sterile tables of numbers. They track lines written and commits pushed, but miss the soul of software engineering.

Kuro is different. It transforms repository management from a dry checklist of administrative tasks into an immersive, game-like experience.

By combining automated AI intelligence with RPG-style quest design and a premium liquid-glass interface, Kuro encourages you to:

• Deeply audit your public code portfolio so recruiters notice your work.
• Maintain high-quality documentation, release notes, and issue triages.
• Discover dead, zombie, and experimental projects in your codebase graveyard and revive them.
• Profile your engineering skills based on actual directory listings, config files, and repository outputs.

---

🚀 Key Features

Kuro compiles complex GitHub REST API data and locally executed heuristic engines into cohesive, premium work modules.

⚔️ Open Source Quest Mode

Turn repository maintenance into a structured RPG. Kuro parses your workspace metadata to curate custom dailies, category missions, and multi-criteria boss fights.

• Automated Verification: Click "Verify Quest" to run real-time checks on README expansion, LICENSE files, GitHub Actions CI configuration, and Dockerfiles.
• Gamified Progression: Earn XP, level up (from Repo Rookie to Maintainer Monk), and unlock strict, verification-only achievement badges.
• Zero Database Dependency: All progress state, streaks, and baselines are preserved locally in encrypted browser storage.

🩺 Portfolio Doctor

An automated recruiter readiness score for your public GitHub presence.

• ** appeals audit**: Grades every repository across recruiter appeal, product feel, technical depth, and open-source maturity.
• Pinnings & Archive recommendations: Detects scaffolds and stale coursework, recommending top projects to pin with pre-written GitHub descriptions.
• Recruiter Pitch & Resume Builder: Drafts high-fidelity elevator pitches and LinkedIn project summaries using actual technologies detected in your package files.

🪦 Repo Graveyard

Scan your account to identify experimental, zombie, or ghost repositories that clutter your profile.

• Developer Roasts: Provides humorous, light-hearted roasts on your half-finished repositories.
• Diagnostic Action Plans: Offers structural checklists to archive, delete, or revive candidate projects.
• Graveyard Report: Compile and export a full REPO_GRAVEYARD_REPORT.md checklist.

🎬 Repo Cinema

Convert raw repositories into engaging technical case studies and narratives.

• Interactive Story Arc: Generates a timeline from initial Problem Spark to Architecture, Challenges, and Future Roadmaps.
• Asset Compilation: One-click drafts for structured portfolio case studies, LinkedIn announcements, screen scripts, and elevator pitches.

📊 Interactive Skill Graph

A customizable SVGs radar chart visualizing your technical strengths.

• Deterministic Heuristics: Analyzes languages, dependencies, config structures, and project structures (e.g. FastAPI/Express folders, Playwright/Vitest configs) to measure competence.
• Strengths & Weaknesses: Identifies code coverage gaps, documentation weaknesses, and recommends concrete next-step projects.

🌌 Liquid Glass UI & Backgrounds

An aesthetic leap forward in developer tooling.

• iridescent WebGL Canvas: A custom Three.js shader background featuring simplex-noise displacement, gyro-responsive parallax, and multi-stop lavender-mint-gold color cycles.
• Houdini CSS Paint API: Utilizes local Houdini paint worklets (liquid-glass.js) to render organic fluid borders and rotating conic shimmers.

🤖 Copilot Workspace & AI Triage

Deep AI integrations that run fully local by default, with serverless hooks for OpenAI and Anthropic compatible providers.

• Issue Triage: Auto-assigns priority, maps categories, and drafts custom maintainer replies.
• PR Dashboard: Aggregates PR reviews, flags stale branches, and builds release note logs.
• README AI: Audits documentation coverage, provides improvement suggestions, and generates full files.

---

🎨 Theme Showcase

Kuro includes a system-wide design framework supporting 10 handcrafted themes with dynamic, smooth transitions. Press Cmd/Ctrl + Shift + T to access the theme switcher.

Dark Themes	Light Themes	Specialty Themes
🔮 Kuro Dark (Default)	☀️ Solar Light	🟢 Terminal Green
🧪 Dracula	🌸 Sakura	🌌 Liquid Glass
🔵 Midnight Blue	🍦 Minimal Mono	⚡ Cyberpunk Neon

---

🛠️ Tech Stack

Kuro's core client is built as a highly optimized Single Page Application (SPA), utilizing native web features for graphics and security.

• Frontend: React 18, Vite, React Router v6, Framer Motion, GSAP.
• API & Data: TanStack Query (React Query) for smart caching, Octokit SDK, Fuse.js for fuzzy local search.
• Canvas & Math: Three.js, CSS Houdini, @dnd-kit (Kanban drag-and-drop).
• Editor & Parsers: Monaco Editor, React Markdown, Rehype Highlight.
• Authentication: Clerk, Web Crypto API (AES-GCM local storage encryption).

---

⚡ Quick Start & Installation

To boot Kuro locally:

1. Clone & Install

git clone https://github.com/starkbbk/kuro.git
cd kuro
npm install

2. Configure Environment Variables

Create a .env.local file in the root directory:

# Clerk Credentials (For Sign-In and GitHub External Connection)
VITE_CLERK_PUBLISHABLE_KEY=your_clerk_publishable_key
CLERK_SECRET_KEY=your_clerk_secret_key

# Developer Fallback (Allows logging in with GitHub PAT instead of Clerk)
VITE_ENABLE_PAT_LOGIN=true

# AI Provider Configuration (mock | real)
VITE_AI_MODE=mock

3. Run Development Server

npm run dev

Open http://localhost:5173 to access the dashboard.

---

🔑 Environment Variables

Kuro reads variables to configure authentication gates, AI engines, and network routing.

Variable	Scope	Required	Description
VITE_CLERK_PUBLISHABLE_KEY	Frontend	Yes	Clerk app public key.
CLERK_SECRET_KEY	Backend	Yes	Clerk app secret key (never prefix with VITE_).
VITE_ENABLE_PAT_LOGIN	Frontend	No	Set true to enable local Personal Access Token login.
VITE_AI_MODE	Frontend	No	mock (deterministic local outputs) or real (backend AI).
AI_PROVIDER	Backend	No	freemodel, openai-compatible, or anthropic.
AI_API_KEY	Backend	No	Serverless completion provider key.
AI_MODEL	Backend	No	Model name (e.g. gpt-4o-mini, claude-3-5-sonnet).
AI_BASE_URL	Backend	No	Custom proxy gateway endpoint (optional).

---

🛡️ Authentication & Setup

Kuro separates application account sign-in from GitHub account connections.

Clerk Social Connection Setup

To support linking your GitHub account through Clerk's secure OAuth flow:

1. Create a project on the Clerk Dashboard.
2. Go to User & Authentication → Social Connections and toggle Google and GitHub.
3. Under the GitHub connection settings:
   • Request scopes: read:user, user:email, repo, notifications.
   • Ensure the callback URL matches the OAuth app registered on your GitHub developer panel.
4. Copy the keys to .env.local and restart the client.

Local Proxy Configuration

All GitHub requests are routed through a local serverless route (/api/github/*) to prevent CORS blocks. In development, Vite mounts the handlers inside api/ directly onto the hot reload server, mirroring Vercel's production behavior.

---

📂 Folder Layout

Kuro organizes features into decoupled routes and modular components.

kuro/
├── api/                          # Serverless auth & AI handlers
│   ├── auth/                     # OAuth proxy routes
│   └── ai/                       # OpenAI/Anthropic/FreeModel endpoints
├── public/                       # Static assets & web worklets
│   ├── favicon.svg               # Modern 'K' logo favicon
│   └── worklets/                 # Houdini paint scripts
├── src/
│   ├── App.jsx                   # Routing, global layout, guards
│   ├── main.jsx                  # Bootloader & worklet registers
│   ├── routes/                   # Layout-level pages
│   ├── components/               # UI Component packages
│   │   ├── github/               # Metrics, heatmap, repo cards
│   │   ├── glass/                # Custom inputs, switches, toasters
│   │   ├── quests/               # Quests, progress, badges
│   │   └── theme/                # Appearance panel, swatches
│   ├── services/                 # AI prompt engines & API facaders
│   ├── store/                    # Zustand stores (Auth, Quest, Agent)
│   └── styles/                   # globals.css & Tailwind theme tokens

---

🤝 Contributing

Contributions to Kuro are welcome!

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

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.