Code, repos, and codebases

When you ran your first Claude conversation in Level 2, you opened it in a folder. Claude looked at the files in there and answered questions about them. That folder was, in all likelihood, a codebase.

The code is the human-readable instructions that make a piece of software work. A codebase is all of that code, organized in a folder. A repository (or repo) is a codebase plus a complete history of every change ever made to it.

In practice, people use repo and codebase almost interchangeably. “Open the repo” and “open the codebase” mean the same thing.

What it looks like

Open a typical repo and you’ll see a folder tree something like:

my-app/
├── README.md          ← what this project is, how to run it
├── package.json       ← list of libraries this project uses
├── src/               ← the actual source code
│   ├── index.js
│   ├── components/
│   └── pages/
├── public/            ← images, fonts, static stuff
├── tests/             ← code that tests other code
└── .git/              ← the history (hidden by default)

This is roughly what every web project on Earth looks like. The names of folders vary. The shape doesn’t.

The .git/ folder is the magic one — that’s where the history lives. We’ll get into it properly in Level 8.

See it for yourself

That tree isn’t a special diagram — it’s just what you’d see if you opened a repo in the terminal. There’s a small project called taskly waiting in the practice terminal. List what’s at the top of it:

ls

A README.md, a package.json, a src/ folder — the same shape as the tree above. Look inside the source folder:

ls src

Now have the terminal show you every file in the project, however deep it’s tucked away:

find . -type f

find walks the whole tree and lists each file it lands on. That short list is the codebase — every instruction that makes taskly run, sitting in plain files in plain folders. The wall of jargon clears the moment you realize it’s just files you can list.

The thing that trips people up

A repo isn’t just the current state of the files. It’s every version of those files, going back to whenever the project started.

Imagine a Google Doc where you could rewind to any second of any day, see who made every change, and undo any one of them without undoing the others. That’s a repo.

Every time a developer commits a change, the repo remembers it forever. Five years later you can still see exactly what changed on a specific Tuesday in 2021. That’s why teams put code in a repo and not in Dropbox — the history is the point.

The tool that makes this work is called Git. We’ll learn to use it the Claude way in Level 8. For now, just hold this: when someone says “the repo,” they mean the code plus the time machine attached to it.

GitHub, GitLab, Bitbucket

A repo lives in a folder on your computer. But teams need to share repos, so the folder gets mirrored to a hosting service on the internet.

• GitHub — by far the most popular. Owned by Microsoft. Almost every open-source project lives here.
• GitLab — similar, often used by companies that want to self-host.
• Bitbucket — third-place. Often used by teams already on Atlassian tools.

When someone says “send me the GitHub link,” they mean: send me the URL of your repo on GitHub. The code is on your machine and theirs and on GitHub, all kept in sync.

What’s next

Open a repo and you’ll see a wall of file types you might not recognize: .tsx, .py, .go, package.json, requirements.txt. The next lesson decodes them — what’s a language, what’s a framework, and what’s a package?