THUFIR

Your Repository's Mentat

"It is by will alone I set my mind in motion."

Account Setup

Get Your Token

Account Setup

Choose Your Sietch

"Every sietch has its own ways. Choose wisely."

Environment

Prepare Your Tools

The Mentat requires certain instruments

1

Claude Code

First, get a Claude Code subscription ($20/mo). Once you have it, run these two commands — the first installs the Claude Code CLI, and the second opens your browser to log in with your Anthropic account:

This installs the Claude Code CLI globally so you can run it from any project folder.

npm install -g @anthropic-ai/claude
claude auth login

npm install -g @anthropic-ai/claude
claude auth login

Requires Node.js (v18+) — npm is included when you install Node.

After installing Node.js on Windows, close and reopen your terminal before running npm.

2

GitHub CLI

Your AI colleague uses GitHub to manage code. Install the GitHub CLI, then log in — it will open your browser to authenticate with GitHub:

GitHub CLI lets your AI colleague create repositories and manage code on your behalf.

brew install gh
gh auth login

winget install GitHub.cli
gh auth login

If brew is not recognized, install Homebrew first: brew.sh

Don't have a GitHub account? Create one here — it's free.

3

Create Your Project

Create a new folder for your project and initialize it as a git repository. Replace my-project with whatever you'd like to name it:

This creates an empty folder with git version control — the home for your AI project.

mkdir my-project && cd my-project
git init

mkdir my-project; cd my-project
git init

4

Typeless (Optional)

Download and install Typeless for speech-to-text.

Speech-to-text lets you talk to your AI colleague instead of typing. Great for brain dumps.

Once installed, click into your terminal where Claude Code is running, tap the Fn key (bottom-left of your keyboard) once, and start speaking. Typeless captures up to 9 minutes of speech and sends it directly to the agent as text. Tap Fn again to stop.

This is especially useful for brain dumps — describing your project, glossary, or taxonomy in your own words. The agent will make sense of it and structure it for you.

Environment

Connect to Your Sources

Access the spice reserves

1

Request Databricks Access

Your AI colleague needs permission to read your team's data tables.

Go to the Microsoft Access Portal and request the packages you need:

At the top of the panel, select All Packages
Search for the domain package you need — one package covers all tables in that domain:
- [TDP] Databricks dmn_public_analytics — pipeline & workflow data
- [TDP] Databricks dmn_core_analytics — quality scores, finances, team hours
- [TDP] Databricks dmn_workers — qualifications
- [TDP] Databricks tier_eu_svc_sft_temporal_backend — item metadata
Select your role: VIEWER if you're staff (internal), OUTSTAFF if you're external/contractor. You do NOT need Analyst.

Access is not automatic — someone from the analytics team or your manager needs to approve it. You'll get a Slack notification. Follow up directly if it takes too long.

2

Get Your Personal Access Token

This token authenticates your AI colleague's queries against Databricks.

Log in to Databricks, then:

Click your profile icon in the top-right corner
Select Settings
Click Developer in the left menu
Under Access Tokens, click Manage
Click Generate New Token
Name it (e.g., "workshop demo"), set lifetime to 90 days, click Generate

Copy the token immediately — you won't be able to see it again. Save it somewhere safe. You'll paste it into your project's .env file in the next step.

3

Save Your Credentials

The .env file keeps your secrets local — they never get committed to git.

In your project folder, create a file called .env and paste these three lines, replacing the placeholder with your actual token:

DATABRICKS_HOST=adb-2350007385231210.10.azuredatabricks.net
DATABRICKS_TOKEN=<paste your token here>
SQL_WAREHOUSE_ID=05bd6e6a717c8be7

This file is automatically gitignored — your token will never be committed or shared.

4

Verify Your Connection

This confirms your AI colleague can reach the data warehouse and list what's available.

Open Claude Code in your project and run:

claude "Check my Databricks connection and list available schemas"

Environment

Activate Your Mentat

Initialize your repository's intelligence

1

Run the Installer

This downloads the Thufir configuration and sets up your project's AI memory.

Make sure you're inside your project folder (from Step 3), then run this command. npx downloads and runs the installer without a permanent install. It will ask for your token — paste the one from the "Get Your Token" page:

npx thufir init

If npx is not recognized, you need to install Node.js first (same prerequisite as Claude Code).

2

Validate Claude

Confirms Claude Code is installed and accessible from your terminal.

Confirm Claude Code is installed and working. You should see a version number like 1.x.x:

claude --version

If you see "command not found," go back to Slide 3 Step 1 and re-run the npm install command. On Windows, try closing and reopening your terminal first.

3

Say Hello

Starts an interactive session — your AI colleague is ready to talk.

Start Claude Code and talk to your new AI colleague. That's it — you're ready for the workshop:

claude

Your Mentat Is Ready

The pre-work is complete. Your tools are sharp.
The spice will flow when the council convenes.

Workshop begins in

--:--:--

"The sleeper must awaken."

Workshop

Teach Your Mentat

Give your colleague deep knowledge of your data systems

What This Prompt Does

This prompt gives your Mentat foundational knowledge about how data is organized — the four layers from raw sources to polished data marts, naming conventions your team uses, and how to build new views.

Learns the four data layers (source, staging, marts, reporting)
Understands your team's naming conventions
Knows how to structure a new data mart
Saves this knowledge for all future sessions

Prompt

Loading prompt...

Workshop

Connect to Your Data

Establish the pipeline between your Mentat and your warehouse

What This Prompt Does

This prompt connects your Mentat to the data warehouse so it can run real queries. It configures credentials, catalogs, schemas, and teaches the agent how to execute SQL against Databricks.

Connects to your Databricks workspace
Discovers available catalogs and schemas
Learns how to execute and debug SQL queries
Verifies the connection works end-to-end

Prompt

Loading prompt...

Workshop

Name Your World

The first step to understanding is naming things precisely

What This Prompt Does

This prompt puts your Mentat in listening mode. It will ask you to describe your project in your own words — what you do, who works on it, what matters — then structure everything into a glossary.

Listens to your project description (voice or text)
Extracts key terms, roles, and concepts
Builds a structured glossary file
Maps your language to the actual data tables

Prompt

Loading prompt...

◆

Your Turn — Talk to Your Mentat

After pasting the prompt, the agent will wait for you to describe your project. Use Typeless (tap Fn) or type. Talk about:

What your project does and who works on it
The roles people play — use YOUR names, not generic ones
How work flows through your pipeline — what stages exist
What distinctions matter (e.g., junior vs senior, new vs experienced)
What kinds of questions you want to ask about your data

You don't need to mention table names, column names, or any technical details. The agent already knows the data sources — it will connect your language to the right tables.

Okay so I'm working on the Anthropic Virtual Companies project — we call it AVC for short. This is a Toloka project where we have people creating test cases. The people who do this work, we call them wrappers. Not experts, not workers — wrappers. That's our term and it's important because at Toloka the word expert is incredibly broad, it can mean anyone on the platform. When we say wrapper, everyone on our team knows exactly who we're talking about.

Now there are two kinds of wrappers and this distinction is really important for us. There are novice wrappers and graduated wrappers. A novice wrapper is someone who hasn't delivered a test case yet — they have zero prior accepted deliveries. They might be in training, they might be working on their first test case, but they haven't crossed the finish line yet. A graduated wrapper is someone who has delivered at least one test case that was accepted. That's it — once you deliver one, you're graduated. We also track active graduated wrappers, which means they graduated and they've been active in the last two weeks.

There's also the concept of a bootcamp, which is our training program. In bootcamp, a QA mentor works with novice wrappers to help them get to their first delivery. The bootcamp is really about getting people from novice to graduated.

Our pipeline goes through several stages. At the highest level it's acquisition, then onboarding, then production work, then delivery. Acquisition is where we recruit people — and we have different types of acquisition pipelines. Onboarding is training where they learn how to do the work. Production work is where they actually create test cases. And delivery is the output — the finished test cases.

Within the production work stage, test cases go through their own flow. A test case gets created, then someone wraps it, then it goes to QA review, and if it passes QA it gets accepted. If it fails QA it goes back for rework. The key moment for us is when a test case reaches an accepted state — that's what we consider a delivery.

The kinds of data we care about on this project are: who the wrappers are and what level they're at, what qualifications people have, how items move through the pipeline, our project spending, quality scores, and how people transition between stages. These are the things I want to be able to ask questions about.

I know we should exclude internal staff from our counts — they're not real wrappers. And I know that qualification and graduation are very different things — qualification means someone has permission to work on something, while graduation means they've actually delivered something. That distinction matters a lot for us.

You already explored the source tables in the previous step — use what you learned there to figure out which tables map to the concepts I just described. I don't need to tell you table names — that's your job to connect my business language to the data you've already documented.

Workshop

Build Your First View

Turn your glossary into queryable data

What This Prompt Does

This prompt tells your Mentat to collaborate with you on designing a data mart view. It will use brainstorming to ask clarifying questions, then build and test the SQL automatically.

Starts a collaborative design session
Asks what rows, columns, and categories you want
Generates and tests the SQL view
Documents the view in your project

Prompt

Loading prompt...

◆

Your Turn — Describe What You Want to See

After pasting the prompt, use Typeless (hold Fn) or type to tell the agent what data you want. Describe:

What the rows should represent (one row per person? per delivery? per day?)
What columns you want to see
Any categorizations that matter (e.g., novice vs experienced)
What question this view should answer

The agent will use /brainstorm to ask you clarifying questions, design the view, then build and test the SQL automatically.

Okay so what I want to build is a view that shows me all the wrappers who have delivered test cases on our project. For each wrapper, I want to see each test case they delivered and when it was delivered. One row per delivery — so one row per wrapper per delivered test case.

The columns I want are: who the wrapper is, which test case it was, and the delivery date.

Here's the critical part — I want to mark each delivery as either novice or graduate. At the time they delivered that particular test case, had they delivered one before? If this was their very first delivery, they were a novice at that point. If they had any prior deliveries, they were a graduate. So the same person might have their first row marked as novice and all subsequent rows as graduate.

Don't include internal Toloka staff — they're not real wrappers. And only count real production deliveries, not onboarding stuff.

Call it something like avc_wrapper_deliveries. You already know where the data lives from the source tables you explored — figure out the right tables and joins yourself.

Workshop

Teach It to Remember

Make your Mentat's knowledge permanent

What This Prompt Does

Right now, your Mentat knows everything because you just built the project together. But if you open a new Claude session tomorrow, that new agent won't know any of it. This prompt tells your Mentat to update its own configuration files so that every future session automatically knows how to query your data.

Updates AGENTS.md with data querying instructions
Updates CLAUDE.md with pointers to your glossary and docs
Makes your Mentat's knowledge survive across sessions
Any new claude session will immediately know how to help

Prompt

Loading prompt...

Workshop

The Spice Flows

Ask your Mentat anything about your project

Open a new Claude session in your project folder. Because you updated the agent files in the previous step, this fresh session already knows everything — your glossary, your data, your views. Just ask.

◆

Your Turn — Ask About Your Project

Start a new Claude session (claude) and use Typeless or type to ask questions about your data:

"How many test cases did we deliver in the last 30 days, and by how many people?"
"Show me all active wrappers and their delivery counts"
"What's our weekly delivery trend over the past month?"
"Break down deliveries by wrapper experience level"

You can ask anything about your project for which you built the data mart in the prior steps. The agent will read your glossary, find the right view or table, run the SQL, and show you the results.

This is a brand new Claude session — the agent has never seen your project before. It works because the agent files you updated in the previous step tell it exactly where to look.

Workshop

Debug the Spice

When the numbers don't add up

Sometimes the data comes back but something feels off — too many results, missing people, wrong totals. When that happens, tell the agent to use /systematic-debugging. It will investigate methodically instead of guessing.

◆

Your Turn — Debug What Looks Wrong

In your Claude session, type /systematic-debugging and then explain what seems off. Use Typeless or type naturally:

"These numbers don't look right — I'm seeing way more deliveries than expected. I think there might be duplicates."
"The wrapper count seems too low. I know we have at least 15 active people but the query only shows 8."
"The date range looks wrong — I asked for last 30 days but some of these entries are from months ago."

Explain what you understand to be true about your project that doesn't match what the agent returned. You don't need to diagnose the technical problem — just describe what seems wrong and why.

The agent will systematically investigate: checking filters, looking for duplicates, verifying date ranges, and comparing its results against your expectations. It handles the technical diagnosis.

Continue exploring at home — your Mentat remembers everything. Push your work before you close: git push