Every time I started a new AI chat session, it read my entire codebase.
50 files. Thousands of tokens. On every single message. Whether I was asking about authentication, database schema, or a single UI component — the AI read everything.
I'm 16 and building AI-powered products. Token costs add up fast. Context windows fill up. The AI loses track of older files. Responses slow down.
So I built something to fix it.
When you work with AI on large projects, you face a choice:
There's no middle ground — or at least there wasn't.
FolioDux is a lightweight, open-source file-mapping standard for AI-assisted development.
The idea is simple: instead of giving your AI every file, you give it a compact index that tells it where everything is and what it does. The AI reads the index first, identifies the relevant files, and reads only those.
One file. Two rules. Any AI.
It works with Claude, ChatGPT, Gemini, Cursor, Copilot — any tool that accepts a system prompt.
You add one file — FOLIODUX.md
— to your project root.
STACK: React19+TypeScript+Vite · Express+SQLite · JWT
---
## TASKS
auth/login/register → AuthView.tsx, authService.ts, server.ts
create/edit task → TaskForm.tsx, taskService.ts, server.ts, types.ts
list/filter tasks → TaskList.tsx, taskService.ts
database → db.ts, server.ts
---
## INDEX
App.tsx | fe | root: routing, auth state, layout wrapper
AuthView.tsx | fe | login + register forms, error display
taskService.ts | svc | CRUD tasks, local cache, optimistic updates
server.ts | be | Express: all routes — auth, tasks, projects, user
db.ts | be | SQLite setup, schema creation, migrations on boot
types.ts | typ | Task, Project, User, Status(todo|in-progress|done)
---
## GROUPS
Frontend: App.tsx · AuthView.tsx · TaskList.tsx · TaskForm.tsx
Services: authService.ts · taskService.ts
Backend: server.ts · db.ts
---
## NOTES
- All routes except /api/auth/* require Authorization: Bearer {JWT}
- Task status values: todo | in-progress | done only
Then you add two rules to your AI system prompt:
RULE 1 — NAVIGATE BEFORE RESPONDING
At the start of every response, before reading any other file:
1. Read FOLIODUX.md in full.
2. Check TASKS — if the request matches a keyword, read ONLY those files.
3. If no match in TASKS, scan INDEX keywords to identify relevant files.
4. Read ONLY the identified files. Never read the full codebase unless asked.
RULE 2 — UPDATE AFTER CREATING
After creating any new file, add one line to FOLIODUX.md INDEX:
{filename} | {type} | {keywords — no articles, no filler verbs, max 8 words}
Update TASKS and GROUPS if needed.
That's it. Your AI now navigates the project like a developer who already knows the codebase.
Without FolioDux:
You ask "fix the login bug". Your AI reads all 50 files. Uses 4,000 tokens before even starting to think about your question. Maybe hits the context limit halfway through.
With FolioDux:
Your AI reads FOLIODUX.md
, finds auth/login → AuthView.tsx, authService.ts, server.ts
, reads 3 files. Uses ~300 tokens. Answers faster and more accurately.
curl -O https://raw.githubusercontent.com/matteo-turri/foliodux/main/foliodux-init.mjs
node foliodux-init.mjs
The CLI script scans your project, detects the tech stack from package.json
, classifies every file by type, extracts descriptions from comments and exports, and generates FOLIODUX.md
in seconds.
Zero external dependencies. Node.js 18+ only.
The only part the script can't fill automatically. Open FOLIODUX.md
and map your most common requests to the files they need:
## TASKS
auth/login/register → AuthView.tsx, authService.ts, server.ts
create/edit product → ProductForm.tsx, productService.ts, server.ts, types.ts
payment/checkout → CheckoutView.tsx, paymentService.ts, server.ts
Copy the two rules above into your AI tool's system prompt. Templates for Claude Projects, ChatGPT, Cursor, and generic tools are available in the repo.
FolioDux uses a compressed keyword syntax designed to be readable by both humans and AI while using as few tokens as possible.
Description rules:
+
for "and", |
for "or", →
for "calls"| ❌ Verbose | ✅ FolioDux | |---|---| | This is the main server file that handles all the API routes | Express: all routes — auth, tasks, projects, user | | A service that manages authentication and user sessions | login, register, logout, JWT session storage |
Type codes:
| Code | Meaning |
|---|---|
fe |
|
| Frontend component | |
be |
|
| Backend / API | |
svc |
|
| Service / logic | |
cfg |
|
| Config / build | |
typ |
|
| Types / interfaces | |
doc |
|
| Documentation | |
tst |
|
| Test | |
dpl |
|
| Deploy / infra |
One file. No config, no database, no server. Just a Markdown file in your project root.
Tool-agnostic. Works with any AI that accepts a system prompt.
Token-first. Every design decision optimizes for token efficiency.
Self-updating. Rule 2 makes the AI maintain the index automatically as the project grows.
Human-readable. Valid Markdown. Open, edit, and version-control it like any other file.
The full project — including the CLI script, prompt templates for Claude/ChatGPT/Cursor, and a complete example — is on GitHub:
→ github.com/matteo-turri/foliodux
Open source. MIT license. Stars and feedback welcome.
Built this to solve my own problem while working on my projects. I'm 16 and based in Milan — if you try FolioDux, let me know what you think in the comments.