Project Info
Inspiration
We hear a lot about AI and vibe coding. People are building startups with it. But there’s a gap. SENIOR ENGINEERS use VIBE CODING BETTER than JUNIORS. Why? Because they’ve accumulated years of reading code. They can spot issues instantly, debug faster, and anticipate edge cases before they explode in production. Seniors are compounding. Juniors are overwhelmed. They stress over debugging vibe coding with no concrete conception of what their code does. We are NOT just talking about debugging. We are talking about sustainability and scalability of YOUR code so you can vibe code better.
What it does
We are here to fill the Vibe GAP. VibeRight allows learners to become owners of that code without forcing them to manually inspect every line of code. It helps them: review with structure, take ownership, test with intention, catch scalability issues early, ship with confidence. The goal isn’t to slow creativity. It’s to make creativity deliverable.
How we built it
VibeRight has two core components: validating and understanding. 1. Validating — A Multi-Agent Expert System Instead of one general critic, we built specialized agents, each obsessed with one dimension of code quality: Functional agent → Your code runs, tests pass, no hidden debt. API contract agent → Robust APIs. Validation, errors, security boundaries. And bulletproof dependency management. Architecture agent → Clean separation of concerns. No unmaintainable spaghetti. Concurrency agent → No race conditions. No intermittent production failures. Performance agent → Scales efficiently. Algorithmic bottlenecks caught early. Security agent → Injection attacks, unsafe execution, auth vulnerabilities : blocked before prod. Documentation agent → Code others can actually understands. Resilience agent → Graceful failures. Recovers, doesn't crash silently. Quality agent → Readable. Maintainable. Low cognitive load. Dependency agent → Supply chain protected. Vulnerabilities, outdated packages, licensing risks are flagged. Each agent produces structured feedback. Then we cluster, merge, and score the outputs into actionable quality metrics. 2. Understanding — Active Ownership Training Validation isn’t enough. So we built a chat-based learning loop powered by two LLMs: An Interviewer that quizzes you on your own code. An Evaluator that checks whether you actually understand it. The questions go deeper over time . You refine your answers. You correct misconceptions. Step by step, you build durable knowledge in an accessible environment. We’re not just reviewing code. We’re training long-term engineering intuition.
Challenges we ran into
Defining “Good Vibe Code”. How do we define those agents and decide what makes vibe code good without impairing creativity? Unlike LeetCode, there’s no fixed input-output pattern. We wanted to preserve creativity, not constrain it. So how do you enforce quality without standardizing thinking? We had to define expert mental models, not rigid rules. Another challenge is SCALE — how can these agents, even when parallelized, handle huge files and interconnected folders/repos effectively?
Accomplishments we're proud of
We turned an abstract frustration into a working system we actually use. We are proud to see the concept come to life. It’s something we can actually use to become better builders. We focused on real pain points shared by all coders. We debated hard. We disagreed productively. We made structured decisions. And we built something non-obvious.
What we learned
We started trying to "validate code", we ended up learning to capture how experts actually think. Our main takeaway: don't build one smart critic, build 10 specialized ones: each focused on a single thing like security or performance. This catches what a general tool misses, and keeps feedback fast enough to not break your flow. We also learned that how you ask is as important as what you build. The right prompts are basically your system design. We mostly learned a lot about ourselves, and how to divide and conquer when we're tackling building abstract concepts. We found our own pattern for tough problems : find someone who does it well, break down how they think, then automate that. We learned to spend compute where it matters.
What's next
VibeRight expands to all users, feedback and comments on each other's performance and code. Challenges on new concepts. Online vibe hackathons where you can be as creative as you want, without intimidation from bulk programs. We can see this having an impact on education. We believe this changes how we learn to code: less theory, more building, faster feedback loops. New platform to assess student skills. A LeetCode for the AI era. VibeRight becomes a platform for technical interviews preparation + mock interviews that test how you think, and use AI. Students and career-changers get immediate, quality feedback that used to take years of senior mentorship. Catch up fast. Ship faster.
VibeRight

Live demo: vibe-right.netlify.app
A lightweight hackathon MVP: upload a project (zip), build a Project Map once, then run a Q/A loop—answer code-understanding questions, get graded with feedback, and see your learner model update. Single-user demo, no auth.
Contents
- Understanding the project
- Quick start
- API keys and environment
- Running the project in the future
- Flow
- Persistence
- API reference
- Tech & constraints
Understanding the project
What it does: You upload a .zip of a codebase. VibeRight builds a one-time project map (key files and structure), then runs a learn flow: it asks you questions about the code, you answer, and it grades you and updates a simple learner model so later questions adapt to what you’ve mastered.
Architecture:
- Next.js 14 (App Router) + TypeScript. No auth; single-user.
- LLM: By default a mock client (no API key). With your own Anthropic API key, the app uses Claude for building the project map, generating questions, and grading answers.
- Data: Locally, everything is file-based (
workspaces/,data/). On deploy (e.g. Netlify), you can add blob storage so projects persist; seelib/blobStorage.tsandlib/storage.ts.
User flow:
- Home – Upload a zip (max 50MB, ~200 files).
- Project – Build project map once; it’s saved in the project workspace.
- Learn – Q/A loop: question → answer → grade + feedback → next topic; session and learner model are persisted.
Key directories:
| Path | Purpose |
|---|---|
app/ | Pages and API routes (home, project, learn, upload, map, question, grade, etc.). |
lib/ | Core logic: schemas.ts (Zod), llm/ (mock + Claude), workspace.ts, storage.ts, buildProjectMapSkill.ts, zip/file handling. |
components/ | Shared UI (e.g. toasts). |
examples/ | sample-src/ and script to build sample.zip for demos. |
Quick start
npm install
npm run dev
Open http://localhost:3000. You can use the app immediately with the mock LLM (no API key). To try with a sample codebase:
npm run create-sample-zip
Then upload examples/sample.zip from the home page.
API keys and environment
The app works without any API keys using a built-in mock LLM. To use your own Claude API for real project maps, questions, and grading:
1. Get an API key
- Go to Anthropic Console.
- Create or copy an API key (starts with
sk-ant-).
2. Create local env file
In the project root (same folder as package.json):
cp .env.example .env.local
(On Windows: copy .env.example .env.local.)
3. Add your key
Edit .env.local and set:
USE_CLAUDE_LLM=true
ANTHROPIC_API_KEY=sk-ant-your-actual-key-here
- Do not commit
.env.localor share your key (it’s in.gitignore). - Optional:
ANTHROPIC_MODEL=claude-3-5-sonnet-20241022(or another model). If unset, the app uses a default.
4. Restart the dev server
npm run dev
The app reads these at runtime: if USE_CLAUDE_LLM is true and ANTHROPIC_API_KEY is set, it uses Claude for map building, question generation, and grading. No code changes needed.
Summary of env vars
| Variable | Required | Description |
|---|---|---|
USE_CLAUDE_LLM | No | Set to true to enable Claude. Omit or set to anything else to use mock LLM. |
ANTHROPIC_API_KEY | Only if using Claude | Your Anthropic API key. |
ANTHROPIC_MODEL | No | Claude model name; optional, has a default. |
Running the project in the future
Commands
| Command | Description |
|---|---|
npm install | Install dependencies (run after clone or when package.json changes). |
npm run dev | Start dev server at http://localhost:3000. |
npm run build | Production build. |
npm run start | Run production server (after npm run build). |
npm run create-sample-zip | Build examples/sample.zip from examples/sample-src for testing. |
npm run dev:netlify | Run with Netlify CLI (npx netlify dev) for local Netlify-style dev. |
Environment
- Local: Copy
.env.exampleto.env.localand add your API key if you want Claude. See API keys and environment. - Deploy (e.g. Netlify): Set the same variables in the host’s environment (e.g. Netlify → Site settings → Environment variables). Never commit real keys.
Where data lives
- Project files:
workspaces/<project_id>/ - Project map:
workspaces/<project_id>/project_map.json - Learner model:
data/learner_model.json - Sessions:
data/sessions_<project_id>.json
workspaces and data are in .gitignore. They are created when you upload a project and build a map.
Coming back to the repo later
git pull(if applicable).npm install.- If you use Claude: ensure
.env.localexists withUSE_CLAUDE_LLM=trueandANTHROPIC_API_KEYset. npm run devand open http://localhost:3000.
For more detail on architecture and conventions, see AGENTS.md.
Flow
- Home (
/) – Upload a.zipof your project (max 50MB, ~200 files). Optional: useexamples/sample.zipafter runningnpm run create-sample-zip. - Project (
/project/[id]) – Overview and Build Project Map (one-time). Map is stored asproject_map.jsonin the project workspace. - Learn (
/project/[id]/learn) – Q/A loop: see a question → type answer → submit → get score + feedback + next recommended topic. Session history and learner model are persisted.
Persistence
- Project files: extracted under
workspaces/<project_id>/. - Project map:
workspaces/<project_id>/project_map.json. - Learner model:
data/learner_model.json(single local user). - Session history:
data/sessions_<project_id>.json.
workspaces and data are in .gitignore; create them by uploading a project and building a map.
API (for reference)
| Method | Path | Description |
|---|---|---|
| POST | /api/upload | Upload zip (form field file) |
| GET | /api/projects | List project IDs |
| GET/POST | /api/project/[id]/map | Get or build project map |
| GET | /api/project/[id]/question | Get next question |
| POST | /api/project/[id]/grade | Submit answer, get grade |
| GET | /api/project/[id]/tree | File tree |
| GET | /api/project/[id]/file?path=... | Read file |
| GET | /api/project/[id]/search?q=... | Text search |
| GET | /api/project/[id]/session | Session history |
Tech & constraints
Tech: Next.js 14 (App Router), TypeScript, Tailwind. Zod for schemas (project_map, question, grade, learner model, session). No auth, no payments, no vector DB; simple text search over files.
Constraints (MVP): Repos up to ~200 files; zip-only upload (no GitHub in this MVP); single-user; data stored on disk (or blob on deploy).
Analysis
View
Metric
- 20
- 1
- 1
Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.
Technology
- AnthropicIn code
- CSSIn code
- FlaskIn code
- JavaScriptIn code
- Next.jsIn code
- PythonIn code
- ReactIn code
- Tailwind CSSIn code
- TypeScriptIn code
- OpenAIClaimed
9 of 10 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.
AI coding agents
- CodexConfig
- CursorConfig · Commits
Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.
Codebase size
Source size
357 KB
Source files
106
Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.
Repository
dennisliang01/VibeRight
128 files · 2.6 MB · @ 7d39c06
Structure
Interface
24 files · 19%Screens, components and styles rendered to the user.
+2 moreAPI & routing
15 files · 12%Request entry points: routes, handlers and controllers.
Application logic
50 files · 39%Domain rules, services and shared utilities.
+3 more
Supporting
Layers are inferred from where files sit in the tree, not from reading the code. A project that names its directories unconventionally will read oddly here — open the file browser to check anything the diagram implies.
Languages
- TypeScript47%
- Python46%
- Markdown6%
- CSS1%
- JavaScript1%
- YAML0%
Share of indexed source by file size. Binary and vendored files are excluded.
Dependencies
package.json
npm · 27- @vercel/blob
- adm-zip
- next
- react
- react-dom
- shiki
- zod
- +20 more
Backend/pyproject.toml
pypi · 9- anthropic
- httpx
- pydantic
- python-dotenv
- pyyaml
- rich
- typer
- +2 more
examples/test_sample/test_sample/requirements.txt
pypi · 2- flask
- requests
Declared in the repository’s manifests at the indexed commit. A declared package is not proof it is used, and runtime dependencies are listed first.
This project’s features have not been analysed yet.
Export this project's context (description, README, evidence, key source files) to chat with an AI agent elsewhere.