Chapter 0 is the ordered path through this documentation, and it assumes you already have a terminal open and know what to type into it. This page does not assume that. It is the same destination by a different road: you install four pieces of software, and then Claude Code reads the repository and sets it up while telling you what it is doing.
At the end you will have the pipeline running on a fictional person, which is exactly where Chapter 0 leaves you at the end of its Stage 1. From that point the two roads merge and everything else is the same.
One thing costs money, and nothing works without it
Claude Code requires a paid Claude plan. Pro, Max, Team, Enterprise or a Console account all work. The free tier on claude.ai does not include it.
Sort this out before you spend an hour on the rest, because there is no way around it. Everything else on this page is a free download.
What was tested, and what was not
The Mac path on this page was run on a Mac. The Windows path was not run on a Windows machine. Its commands come from Microsoft's and Anthropic's own current documentation, and everything after the first step happens inside Ubuntu, which is the operating system this project's test suite runs on for every change. That is a good reason to trust it. It is not the same thing as having watched it work.
Pick your machine
On a Mac
You need macOS 13 or newer. There is nothing to install in this step. Go to step 2.
On Windows
You are going to install Ubuntu inside Windows and do everything after this inside it. That deserves a paragraph of explanation, because it is the only place where the two roads differ at all.
Every command in this project is written for Mac and Linux, and the project's automated tests run on Ubuntu on every single change. Ubuntu is therefore the version that is actually proven to work. Windows spells several things differently, so a Windows-native setup would need a different command on almost every line of this page and of the eleven chapters after it. Installing Ubuntu once removes that problem permanently. From step 2 onward your screen matches a Mac user's exactly.
You need Windows 11, or Windows 10 build 19041 or newer.
Open PowerShell as an administrator: press Start, type PowerShell,
right-click the result and choose Run as administrator. Then run this:
> wsl --install
Restart the machine when it finishes. After the restart, open Ubuntu from the Start menu. It asks you to create a username and password, and these are new ones for Linux rather than your Windows login.
The password looks like it is not typing
Linux prints nothing while you type a password. Not dots, not stars, nothing. The cursor sits still and it looks broken. Type it anyway and press Enter. This catches almost everyone once.
Write that password down somewhere. You need it again for the sudo
command in step 4.
From here on, wherever this page says "your terminal", it means this Ubuntu window, or the terminal inside VS Code once you connect the two in step 2. It never means PowerShell again.
Install VS Code
VS Code is a free editor from Microsoft. You are installing it because the friendliest version of Claude Code lives inside it as an extension, with a panel you can type into like a chat. You will not be writing any code in it yourself.
Download it from code.visualstudio.com and run the installer. You need version 1.94.0 or newer, and any current download is well past that.
On Windows, leave the Add to PATH option checked during installation. It is checked by default, so this only matters if you go looking for options to change.
Windows only: connect VS Code to Ubuntu
You installed VS Code on the Windows side, and your work is going to live on the Ubuntu side. One Microsoft extension bridges the two.
Open the Extensions view with Ctrl+Shift+X, search for WSL,
and install the one published by Microsoft. Its identifier is
ms-vscode-remote.remote-wsl.
Then press F1, type WSL: Connect to WSL, and press Enter. A new
VS Code window opens. Look at the bottom-left corner: it now shows a WSL indicator.
Check this before going further
On Windows, every remaining step on this page happens in the VS Code window whose bottom-left corner says WSL. If you do them in the plain Windows window instead, most of them appear to work and then fail later, in ways that are hard to trace back to here.
Install Claude Code
Claude Code is the thing that will do the actual setup work in step 6. The VS Code extension is a complete version of it, so there is nothing to install in a terminal here.
Open the Extensions view: Cmd+Shift+X on a Mac, Ctrl+Shift+X
on Windows. Search for Claude Code. Check that the publisher reads
Anthropic before you install it. Extension marketplaces let anyone
publish, and the name alone is not proof of anything.
On Windows, install it while the bottom-left corner shows WSL. VS Code keeps separate extension lists for the Windows side and the Ubuntu side, and you want this one on the Ubuntu side where your project will be. If VS Code offers to install it in WSL, accept.
Open the panel by clicking the Spark icon in the left sidebar, or Claude Code in the bottom-right status bar. A sign-in screen appears the first time. Click Sign in and finish in your browser. No API key is involved, and you should not be asked to paste one.
If the panel is not there
Press Cmd+Shift+P or Ctrl+Shift+P, type
Developer: Reload Window, and press Enter. That fixes it almost every
time.
Install Python
Python is the language the engine is written in. You need version 3.11 or newer. The project's tests run on 3.11, 3.12, 3.13 and 3.14, so any of those four is a known quantity rather than a hope.
You need a terminal for this step and the next one. Use the one built into VS Code rather than hunting for a separate app: open the Terminal menu and choose New Terminal. It opens along the bottom of the window, already in the right place.
On a Mac
Download the macOS installer from python.org/downloads and run it. The current release is 3.14.7. Then confirm it took:
$ python3 --version
You also need Git, which is how you download the code in step 5. macOS does not ship it
until you ask for it. Run git --version. If a dialog appears offering to
install the command line developer tools, click Install and wait. That
dialog is the expected behaviour, not an error.
On Windows, in the Ubuntu terminal
Ubuntu already has Python. It needs two companion packages, plus Git:
$ sudo apt update $ sudo apt install -y python3-venv python3-pip git
sudo asks for the password you created in step 1, and shows nothing as you
type it, same as before. Then check the version:
$ python3 --version
If that prints 3.11 or higher, you are done with this step. If it prints something older, do not go hunting for a fix: say so to Claude Code in step 6 and let it sort out a newer version for you.
Get the code
The repository is private. Whoever sent you here has to grant your GitHub account
access before this works. If the command below fails with
Repository not found, that is almost always the access rather than a typo
in the address.
$ cd ~ $ git clone https://github.com/Cre8Chaos/job-search-engine.git $ cd job-search-engine
If you were given the repository under a different owner or name, use that address instead.
If Git asks you for a password
GitHub stopped accepting account passwords for this years ago. What it wants is a personal access token, which you create in your GitHub account under Settings, then Developer settings. Paste the token in where it asks for the password.
One last thing, and it matters more than it looks. Open this folder in VS Code: use
File, then Open Folder, and pick the
job-search-engine folder itself rather than the folder containing it.
Why the open folder matters
Claude Code can only see the folder VS Code has open. The nine slash commands this project defines are instructions stored inside this repository, so they exist only when this repository is the open folder. If you type a slash command later and nothing happens, this is the first thing to check, before assuming anything is broken.
Hand it to Claude
Open the Claude Code panel and paste this in as your first message. Every line in it is there for a reason, so paste the whole thing rather than a shortened version.
Set this repository up for me. I have never used a terminal before, so explain each step in plain English as you go and do not assume I know what anything means. Work through the Quick Start in README.md, in order: 1. Check my Python version first. If it is older than 3.11, stop and tell me. Do not try to work around it. 2. Create the virtual environment and install the requirements. 3. Install the headless browser that Playwright needs. 4. Copy the three example config files. Do not change any values in them. 5. Run the test suite and tell me the actual numbers you got, not the numbers the README predicts. 6. Run the pipeline once with scripts/daily_run.sh. 7. Show me the digest it wrote, and walk me through what I am looking at. Rules for you: - Run the commands yourself. Do not just print them for me to copy. - If a step fails, stop and show me exactly what you saw. Do not try three workarounds and carry on. - Do not edit anything in config/ beyond the copy in step 4. Those are my decisions to make, not yours. - Do not commit anything to git.
Claude Code asks permission before it runs each command. That is the design working, not an obstacle to get past. Read what it is about to run, then approve it. If you would rather not read every one, you can tell it to stop asking, but the first time through is a good time to watch.
The slowest part is the browser download in step 3, which is a few hundred megabytes. The engine needs it to turn your tailored resume into a PDF, and four of the tests drive a real browser on purpose.
Why step 5 says "the actual numbers you got"
The README's own test counts were ten short on the day they were published, because two later commits added tests. Numbers in prose go stale quietly. Asking Claude for what it measured rather than what the document predicts is the habit this whole project is built on, and it is worth picking up on day one.
Did it work?
Claude saying it is finished is not the same as it being finished. Three things have to be true, and you can check all of them yourself in about two minutes.
- The test suite passed. Not "mostly passed". If anything failed, ask Claude what failed and why, and do not move on.
- The pipeline finished cleanly.
scripts/daily_run.shran to the end without an error. -
A digest exists and you have read it. Look in
data/digests/for a file dated today, open it, and read it end to end. Then open one file indata/jobs/. This is the shape of the thing you will read every morning, so five minutes now is time well spent.
If any of those three is not true
Do not carry on to the next section. docs/operations.md in the repository
is organised by symptom, and Claude Code can read it with you. Say what you actually
saw rather than "it did not work", and it will get further faster.
What Claude cannot decide for you
Everything you have just watched is about a fictional person: Alex Rivera, of Portland, Oregon. The example configuration exists so you can prove the machine runs before you have to make a single decision about yourself. None of it is your job search yet.
Three files carry that, and nothing can default them for you:
| File | What it holds |
|---|---|
config/profile.yaml | What you are targeting, where you will work, what a good offer looks like |
config/resume.md | Your master resume, the source of truth every tailored version is cut from |
config/resume-ai.md | The second master, for roles where the AI and automation side leads |
This part is you, not the engine
Claude Code can set the machine up. It cannot decide what job you want, what you will accept, or what is true about your own career. Handing it those decisions produces a confident, plausible, fictional job search.
This is Stage 2 of Chapter 0, and Chapter 3 walks it as an interview rather than a form. It takes about an hour and it is the part that cannot be skipped.
Once those three files are yours, you rejoin the main road. Everything from Stage 3 onward in Chapter 0 reads the same whether you got here by this page or by typing the commands yourself.
When it goes wrong
These are the failures that come up first, and what each one actually means.
| What you see | What it means |
|---|---|
| The Claude Code panel is missing entirely | Reload the window: Cmd+Shift+P or Ctrl+Shift+P, then Developer: Reload Window |
Not logged in in the panel |
The sign-in did not stick. Sign in again, and confirm your Claude plan is a paid one |
Repository not found from git clone |
Access, not spelling. Your GitHub account has not been granted the private repository yet |
| Git asks for a username and password | The password it wants is a personal access token from your GitHub settings, not your account password |
python3: command not found on a Mac |
The installer did not finish, or this terminal was open before it did. Close the terminal, open a new one, try again |
| A slash command does nothing | VS Code has the wrong folder open. It has to be the job-search-engine folder itself |
| On Windows, commands fail in confusing ways | Check the bottom-left corner of VS Code says WSL. If it does not, you are on the Windows side rather than the Ubuntu side |
| Something else entirely | Paste the exact error into the Claude Code panel and ask what it means. docs/operations.md is organised by symptom |
Describe what you saw, not how it felt
"It did not work" gives Claude nothing to work with. The exact last ten lines of output gives it almost everything. This is true of asking a person, too.