MODULE 2.1

🧰 Prerequisites and installation

This is the most hands-on module in the trail: you check Python, install the uv, add the CLI graphifyy in the terminal, registers the skill in Claude Code, and gets Obsidian ready. Each command comes in a box copy and run, with the goal and how to verify it.

Topics

~45

Minutes

Practical

Level

0 of 6

🐍 Check Python and install uv

O Graphify is written in Python and asks for the version 3.10 or newer. Before installing anything, check what you already have with python --version. If you see 3.10, 3.11, 3.12, or higher, you're ready. Next, we'll install the uv, the recommended way to install the CLI.

🔰 New here? What is "uv"

O uv is a Python package and tool installer—fast and modern, created by Astral. Think of it as an app store for the Python world: you request a tool, and it makes it available as a command in the terminal. It’s the cleanest way to install Graphify without making a mess of your Python setup.

terminal · illustrative

Objective: confirm that Python is 3.10+ and install the uv.

# 1) checar a versão do Python (precisa ser 3.10+)
python --version

# 2) instalar o uv (instalador oficial da Astral)
curl -LsSf https://astral.sh/uv/install.sh | sh

How to verify: the first command prints something like Python 3.11.x; the installer for uv ends with a success message. Close and reopen the terminal so the command uv start answering.

🔑 Key concepts

Python 3.10+

Minimum version

Quick installer

--version

Check what’s there

PATH

Where the command lives

📦 Install the graphifyy CLI

The package no PyPI is called graphifyy — with two “y”s. It installs the binary graphify (a "y"), which is the command you'll run. One typing detail that prevents the most common error: what you installs has two y’s; the one you runs has one.

🔰 New here? What is a "CLI"

A CLI (Command Line Interface) is a program you use with text commands in the terminal, instead of clicks. PyPI is the official repository for Python packages—the "shelf" where the uv/pip downloads graphifyy.

terminal · illustrative

Objective: leave the command graphify available in the terminal.

# recomendado (com uv)
uv tool install graphifyy

# alternativas, se você não usa uv
pipx install graphifyy
pip install graphifyy

# se o comando "graphify" não for encontrado depois:
uv tool update-shell

How to verify: open a new terminal and type graphify should respond (the full check is in topic 6). If “command not found” persists, run uv tool update-shell and reopen the terminal.

✓ The recommended approach

✓uv tool install graphifyy isolates the tool.
✓Doesn’t mix with the system Python.
✓Updating and removing are simple afterward.

✗ Common mistakes

✗Type graphify (a y) in the install.
✗Forget to reopen the terminal.
✗Confuse the package with the skill.

🔑 Key concepts

graphifyy

Package (2 y)

graphify

Command (1 y)

uv tool

Install in isolation

update-shell

Fix the PATH

🔌 Register the skill (graphify install)

Having the CLI isn’t enough: to use Graphify inside in Claude Code, you need to register the skill. The command graphify install writes a file SKILL.md in the place where Claude Code looks for your skills—and that’s what connects the slash command /graphify.

🔰 New here? What is a “skill” and SKILL.md

A skill is a skill you teach Claude Code: a file SKILL.md that describes what it does and how to invoke it. When this file exists in ~/.claude/skills/, the command /graphify appears in the session.

terminal · illustrative

Objective: activate the command /graphify in Claude Code.

# registra a skill para todos os projetos (escreve ~/.claude/skills/graphify/SKILL.md)
graphify install

# versão por-projeto (grava .claude/skills/graphify/ no repo atual, dá pra commitar)
graphify install --project

How to verify: confirm that the file exists with ls ~/.claude/skills/graphify/SKILL.md. In a new Claude Code session, typing /graphify should show the skill.

↑ Installation has two distinct steps: install the CLI (topic 2) and register the skill (this one). The SKILL.md is the bridge that makes the /graphify exist within Claude Code.

🔑 Key concepts

skill

Skill taught

SKILL.md

Skill file

graphify install

Registers globally

--project

Registers in the repo

🔮 Install and open Obsidian

O Obsidian is where the generated map will live and be explored. Download it at obsidian.md, install and open it—it’s free and runs on desktop (Windows, macOS, Linux). There’s no terminal command here: just click, download, and install it like any other app. You don’t need to create anything yet; just have it ready for when the markdown arrives (module 2.4).

🔰 New here? What are "Obsidian" and "vault"

O Obsidian is a note-taking app in markdown with links between pages (PKM — personal knowledge management). A vault is simply a folder of notes it opens—nothing more than files .md in a folder. Graphify will generate exactly these files.

✓ Take action now

✓Download to obsidian.md and install.
✓Open the app at least once.
✓Make sure it's the free desktop version.

○ Not needed yet

○Create a vault (Graphify generates it later).
○Don’t install plugins or pay anything.
○Set up cloud sync.

🔑 Key concepts

Obsidian

Markdown app

vault

Notes folder

desktop

Free, local

obsidian.md

Where to download

🔑 API keys: when you need them (and when you don't)

This is the question that trips up the most people. The short rule: when running via /graphify inside Claude Code, you doesn't need a key — the session itself provides the model. Only the headless (plain terminal, for documents) requires the ANTHROPIC_API_KEY. And extraction of code doesn't use any key — it's built from the AST, without an LLM.

🔰 New here? "API key," "headless," and "AST"

A API key is a password that authorizes a program to call the model and charge your account. Headless is running without an interface, directly in the terminal. AST (abstract syntax tree) is the structural reading of code — Graphify uses the tree-sitter library for this, so code becomes a graph without call an LLM.

↑ Two of the three paths don't ask for a key. You only need to export the ANTHROPIC_API_KEY when you run Graphify headlessly on documents.

terminal · illustrative

Objective: only for the headless case — provide the key to the terminal. Replace <sua-chave> through yours.

# só no modo headless sobre documentos (NÃO precisa dentro do /graphify)
export ANTHROPIC_API_KEY=<sua-chave>

How to verify: with the variable exported, Graphify headless stops complaining about a missing key and processes the documents. Inside Claude Code, you can skip this entire step.

🔑 Key concepts

/graphify

No key

headless

Asks for the key

AST

Code without an LLM

ANTHROPIC_API_KEY

The variable

✅ Verify that everything works

Before moving on to module 2.2, do the sanity check: two commands confirm that the CLI responds and that the skill is registered. Catching a problem now takes seconds; discovering it in the middle of an extraction costs much more.

terminal · illustrative

Objective: confirm the CLI + skill before extracting any graph.

# a CLI responde e lista os subcomandos?
graphify --help

# a skill foi registrada no lugar certo?
ls ~/.claude/skills/graphify/SKILL.md

How to verify: the first command prints the list of subcommands; the second prints the path to SKILL.md (and not "file not found"). If both respond, the environment is ready.

✅ Environment checklist

✓python --version shows 3.10+.
✓graphify --help lists the subcommands.
✓~/.claude/skills/graphify/SKILL.md exists.
✓Obsidian installed and opened at least once.

🔑 Key concepts

--help

Lists subcommands

ls SKILL.md

Confirm the skill

sanity check

Check first

checklist

4 ready-to-go points

✋ Self-recovery (optional, non-blocking): you are going to run /graphify within Claude Code. You need to export the ANTHROPIC_API_KEY?

📌 Module summary

✓

Right foundation: Python 3.10+ verified with python --version e o uv installed.

✓

CLI installed: uv tool install graphifyy (two y's) makes the command graphify in the terminal.

✓

Skill registered: graphify install writes the SKILL.md and connect the /graphify.

✓

Obsidian ready: downloaded from obsidian.md and open, waiting for the vault.

✓

Key: only in headless mode: inside Claude Code, you don’t need one; code processed via AST never needs one.

Next module

2.2 · Choose and prepare the source — decide between code and documents, download the corpus, and organize the folder Graphify will read.

← Back to Track 2 Next: 2.2 Choose and prepare the source →