I know setup docs are usually the part where things go sideways. This one is different. Every step is written assuming you haven't done this before, because most people haven't, and that's completely fine.
Three things need to be on your computer before anything else works. Here's what each one is and where to get it.
Claude Code is where you'll do everything. It's an app from Anthropic that gives you a code editor, a terminal (the panel where you type commands), and Claude as a built-in assistant. If you don't have it yet, download it from claude.ai/download.
Python is the language the tracker is written in. You probably already have it if you've used Claude Code for anything before. To check, open Claude Code, look for the terminal panel at the bottom of the screen (if it's not open, press Ctrl+` on Windows or Cmd+` on Mac (that's the backtick key, the one to the left of the 1)), and type:
If it shows something like Python 3.11.4, you're good. If it says "not found" or throws an error, go to python.org/downloads and install the latest version.
An Airtable account. Free tier works. You'll also need a Personal Access Token (it's a key Airtable generates for you). The companion guide below covers this in about 5 minutes if you haven't done it yet.
data.records:read, data.records:write, schema.bases:read, schema.bases:write, and workspacesAndBases:read (only needed for the automatic setup --create path in Step 5; the manual path doesn't need it).You need a copy of the tracker on your computer. The way to do that is called "cloning" (which just means downloading a copy of everything from GitHub onto your machine).
In the terminal, paste this and press Enter (swap in the actual repo URL when you have it):
That creates a folder called lilyp.ai-relationship-tracker wherever you ran the command. Now move into it:
cd means: "change directory." It's just how you navigate into a folder from the terminal. Think of it as double-clicking a folder, but in text form.The tracker uses a few Python packages (pre-built tools that do things like talk to Airtable and call Claude). This one command installs all of them at once:
You'll see a bunch of text scroll by. That's normal, it's just downloading things. Wait until it finishes and returns you to a blank line with a cursor.
-r requirements.txt just means "install everything listed in this file."The tracker needs two private keys to work: one to talk to Claude (from Anthropic) and one to talk to Airtable. You'll paste both into a plain text file called secrets.env.
Open the file config/secrets.env in Claude Code (you can click it in the file browser on the left, or open it from the terminal with open config/secrets.env). It looks like this:
Replace each placeholder with the real value. Here's where to find them:
ANTHROPIC_API_KEY: go to console.anthropic.com, sign in, click "API Keys" in the left sidebar, and create a new key. Copy the whole thing (it starts with sk-ant-).
AIRTABLE_PAT: your Airtable Personal Access Token. If you haven't gotten it yet, the companion guide above walks you through it, including the scopes you need.
TRACKER_BASE_ID: leave this one blank for now. Step 5 covers how it gets filled in, either automatically or by hand depending which path you take.
.gitignore, which means if you ever push this project to GitHub, your keys won't be included. They stay private on your computer.There are two ways to do this step, and both end up in the same place: a base with Contacts, Interactions, and Events tables, ready to go. Try Option A first. If it errors out, Option B takes a few extra minutes and worked more reliably when I tested this.
Option A: automatic
This one command creates your entire Airtable base: all three tables, all the fields, and the Follow-Up Queue view. You don't set anything up by hand, and it writes the base ID into secrets.env for you.
When it finishes, open Airtable in your browser. You should see a new base called "Relationship Tracker" with everything already set up.
workspacesAndBases:read. See If something breaks below, or just move on to Option B.Option B: manual
Create the base yourself, then have Claude build the tables inside it.
1. Go to airtable.com and create a new base. Name it whatever you want, "Relationship Tracker" is fine.
2. Open the base and copy its URL from your browser's address bar.
3. In Claude Code, paste the URL and ask Claude to set up the Contacts, Interactions, and Events tables using config.py as the spec. Something like: "Here's my Airtable base: [paste URL]. Set up the tables and fields from config.py."
4. Claude can pull the base ID from that URL. Add it to secrets.env:
You're set up. Try it with someone you've actually met recently. Replace the text in quotes with a quick description of them:
The more detail you give, the better the record. Even a few sentences is enough. Claude parses it, creates the structured contact record in Airtable, and schedules your follow-up automatically.
Check your Airtable base and you should see the contact appear within a few seconds.
python3 instead of python everywhere. On some systems they're the same thing installed under a different name. If that works, replace python with python3 in all the commands.pwd (print working directory). It should show the lilyp.ai-relationship-tracker folder. If not, cd back to it and try the pip install again.pip install pip-system-certs, then try the command again.AIRTABLE_PAT is probably wrong or missing. Open config/secrets.env, double-check the token is pasted in full with no spaces around the = sign, and make sure there are no quotes around it.workspacesAndBases:read scope, which the automatic setup needs to create a new base in your workspace. Go back to airtable.com/create/tokens, edit the token, and add that scope. Or skip it entirely: Option B in Step 5 builds the base manually and doesn't need it.ANTHROPIC_API_KEY in your secrets.env. The key starts with sk-ant-. If it's expired or you've hit a limit, generate a new one at console.anthropic.com.