Read code without learning to code. An AI-powered code reader built for non-programmers.
Cursor and VS Code are Swiss army knives for developers. CodeABC is a magnifying glass for everyone else -- it lets you read code like reading an article, and annotate code like annotating a document.
More and more non-programmers need to deal with code: grad students running Python data analysis scripts, product managers reviewing what developers built, founders evaluating outsourced code quality. But every existing tool assumes you already know how to code.
AI can already explain code perfectly. What's missing is a product that wraps this capability in a UX designed for people who don't code.
Drop in a project folder or paste a GitHub link. CodeABC scans the files and generates a plain-language "project manual":
- What is this? One-sentence summary anyone can understand
- File guide Every file explained in plain language, sorted by importance
- Reading map A deterministic "start here, then read this" path appears before the AI call
- How to run it Step-by-step instructions, no jargon
- Quick tips "If you just want to change X, go to file Y"
Click any file to view it with AI-generated annotations. Hover over any line to see a plain-language explanation of what it does. No programming jargon -- uses everyday analogies to explain concepts.
- Fine-grained: annotations cover every 1-3 lines, not just blocks
- Context-aware: explains why a number is 0.05 or a timeout is 3600
- Cached: annotations are stored locally so repeat visits are instant
Every file view lists the programming terms that actually appear in that file -- async, decorator, closure, middleware, regex, and dozens more. Hover a term to see a plain-language explanation that leans on everyday analogies. It is computed deterministically (no LLM, no API key), so it is instant and always available.
Describe a change in plain words -- "把茅台换成比亚迪", "change the timeout from 3600 to 600" -- and CodeABC returns a suggested rewrite of the selected snippet, touching only what you asked for. It never writes to your files; the result is yours to review and copy.
Select any snippet in a file (or just leave it unselected for the whole file) and ask a question in plain language -- "what does this do?", "why is this number here?". CodeABC answers in the same patient, jargon-light voice, grounded only in the code you pointed at. Answers are cached, so asking the same thing again is free.
The whole interface switches between Chinese and English with one toggle in the header. Your choice is remembered, and the first visit follows your browser language. (LLM-generated content like the manual and annotations follows the prompt language; the UI chrome is fully translated.)
CodeABC skips build outputs, package caches, minified bundles, generated frontend chunks, and paths ignored by the repository's .gitignore before sending files to the LLM. It also leaves out secret-shaped files such as real .env files, credential JSON files, API key notes, and private keys while still allowing safe examples like .env.example. That keeps the project manual focused on source code instead of dist/, node_modules, local scratch files, one-line JavaScript bundles, or private credentials.
Before an LLM response is ready, CodeABC builds a deterministic reading map from README files, likely entry points, package manifests, core source directories, and tests. It gives newcomers a useful first route even when no API key is configured.
CodeABC builds a small import graph from the scanned files and ranks them by fan-in: how many other files import each one. The most-imported files are usually where the real logic lives (shared utilities, data models, core services), so they surface next to the reading map as "core modules", each tagged with the number of files that depend on it. It resolves Python imports (including relative and package imports) and JavaScript/TypeScript imports (relative paths with extension and index resolution), and ignores third-party and standard-library imports since they never point at a scanned file. Like the reading map, it runs without an LLM call, so it works with no API key configured.
A blunt but useful question when you're sizing up code you didn't write — work you outsourced, say: does it actually have tests? CodeABC pairs each source file with the test files that exercise it, both by import and by the usual test_scanner.py / scanner.test.ts naming, then shows the share of files that are covered. More usefully, it ranks the untested files by how many other files depend on them: an untested file that half the project imports is exactly where a quiet regression spreads furthest, so it sits at the top of the "worth covering first" list with a plain-language note on why. A green progress bar gives the at-a-glance number; the list tells you where to look. Like the other maps it is deterministic and needs no API key.
| Layer | Choice | Why |
|---|---|---|
| Frontend | React 19 + Vite + TailwindCSS 4 | Fast dev, no SSR needed for this app |
| Code highlighting | Shiki | VS Code-quality syntax highlighting, zero runtime JS |
| Tooltips | @floating-ui/react | Lightweight positioning for hover annotations |
| State | Zustand | Minimal, performant state management |
| Backend | FastAPI + uvicorn | Async Python, great for streaming LLM responses |
| LLM | litellm | Multi-provider support (OpenAI, Claude, DeepSeek, Kimi, etc.) |
| Cache | SQLite | Simple, no Redis needed for MVP |
One command, no setup:
python run.pyOn Windows you can just double-click start.bat; on macOS/Linux, run ./start.sh. The first run builds the web interface and installs dependencies — after that it just starts. Everything is served from one place, and it opens in your browser for you once the server is ready — at http://127.0.0.1:8000, or the next free port if 8000 is already taken. Press Ctrl+C to stop.
You need Python 3.10+, plus Node.js 18+ for that first build. Installing uv is optional and makes startup faster.
Then click the gear icon in the top-right and paste an API key (or use the free tier — see API Key). An OpenRouter key (sk-or-...) is the easiest: one key reaches every provider, and CodeABC recognises it automatically and picks a fast, inexpensive model for you. OpenAI, Anthropic, and DeepSeek keys work too. To force a specific model, set CODEABC_MODEL (e.g. openrouter/anthropic/claude-haiku-4.5).
To run the backend and the Vite dev server separately with hot reload:
# backend (terminal 1)
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
export OPENAI_API_KEY=<OPENAI_API_KEY> # or ANTHROPIC_API_KEY / OPENROUTER_API_KEY / ...
uvicorn backend.app:app --reload
# frontend (terminal 2)
cd frontend
npm install
npm run devThe dev UI runs at http://localhost:5173 and calls the backend on port 8000.
The same UI ships as a native desktop window via Tauri — a small Rust shell around the web frontend, no Electron-sized bundle. It's self-contained: the app bundles the FastAPI backend as a sidecar and starts it automatically, so there's nothing to run by hand. You'll need the Rust toolchain installed to build it.
# 1. package the backend into the sidecar binary (clean venv with just the
# project's deps + pyinstaller; a fat env produces a huge binary)
pip install -e . pyinstaller
python scripts/build_desktop_sidecar.py
# 2. build the desktop app (bundles that sidecar)
cd frontend
npm install
npm run tauri:build # installer in src-tauri/target/release/bundle/The release app spawns the backend on 127.0.0.1:8000 at launch and stops it on exit. For development, run the backend yourself (uvicorn backend.app:app --reload) and use the hot-reloading window — npm run tauri:dev doesn't start the sidecar:
npm run tauri:dev- Local folder: Drag a project folder into the upload zone, or click to select
- GitHub repo: Paste a GitHub URL like
https://github.com/user/repoand click "Analyze" - Browse the generated project overview
- Click any file to see it with hover annotations
CodeABC supports two modes:
- Free mode (default): Limited to 20 requests per day
- BYOK mode: Click the gear icon in the top-right corner to enter your own API key for unlimited use. The key is stored only in your browser's localStorage.
CodeABC/
├── backend/ # Python FastAPI server
│ ├── app.py # Entry point, CORS, lifespan
│ ├── models.py # Pydantic data models
│ ├── routers/
│ │ ├── project.py # Upload / GitHub clone / file endpoints
│ │ └── analyze.py # Overview + annotation generation
│ ├── services/
│ │ ├── scanner.py # Project file scanner with smart filtering
│ │ ├── importgraph.py # Import-graph fan-in ranking (core-module detection)
│ │ ├── github_clone.py # Shallow clone with size limits
│ │ ├── llm.py # litellm wrapper (stream + non-stream)
│ │ └── cache.py # SQLite cache layer
│ └── prompts/
│ ├── overview.py # Project overview prompt
│ └── annotate.py # Line-by-line annotation prompt
├── frontend/ # React + Vite + TailwindCSS
│ └── src/
│ ├── pages/ # Home, Overview, FileView
│ ├── components/ # UploadZone, CodeViewer, AnnotationTooltip, ApiKeyModal
│ ├── stores/ # Zustand state management
│ └── lib/ # API client
├── pyproject.toml
└── README.md
- Project overview generation
- Hover annotations (Python priority)
- Terminology dictionary (hover keywords for definitions)
- Natural language editing ("change the stock from Maotai to BYD")
- Q&A mode (select code and ask questions)
- Multi-language UI (English interface)
- Test-coverage map (which files have tests; untested core files ranked by risk)
- Git-history insight (change hotspots, co-change coupling, and code ownership / knowledge silos)
- Tech-debt map (collect the codebase's own TODO/FIXME/HACK/XXX markers, ranked by file)
- Env-var surface (the environment variables a project reads, split into required vs optional)
- Entry-point detection (where execution starts:
__main__scripts, declared console commands, conventional entry files) - Logic-complexity ranking (which Python files carry the most tangled branching, from the AST — a different axis than centrality or churn)
- One-command launcher (
run.py/start.bat— builds, serves, and opens the app) - Single-process serving (the backend serves the built UI; one URL, no separate dev server)
- Native desktop app (Tauri —
npm run tauri:buildwraps the same UI in a native window)
Issues and PRs welcome. This project is in early development.
MIT