Step 0
Before you start.
Two things on your machine: git, and an AI coding agent that can hold a session in a folder, read and write files, and run terminal commands. Claude Code is the tested reference; any agent meeting those minimums works — the commands are plain language underneath.
Nothing else: no account with FRACTAL, no server, no database. What you build here is yours.
Any operating system works — the memory is plain files. macOS is the tested reference and Linux runs the same lines verbatim; on Windows, use Git Bash (ships with Git for Windows) for the setup lines, and read python3 as py wherever a tool is invoked.
Step 1
First contact.
Clone the public baseline, stand on the newest release…
Open a terminal: on macOS, press ⌘ Space and type “Terminal”; on Windows, open Git Bash from the Start menu; on Linux, your terminal of choice. Then paste the one line from the setup:
The “detached HEAD” notice is the good sign, not an error — it means you are standing exactly on the newest anchored release. The windows on this page are condensed illustrations; version numbers advance with releases.
…open a session…
In the same terminal, in that folder, start your agent — the reference client’s command is one word:
Another agent opens the folder its own way — any client that can read files and run commands in a folder serves.
…type /welcome.
Condensed — the real session says more, in plain words. If /welcome doesn’t autocomplete in your agent, the plain sentence does the same: “I’m new here — welcome me.”
The comfortable road: one line of terminal, then your UI.
Let’s be explicit about the honest split. The terminal is needed exactly once — one copy, one paste, one enter. Everything after that happens in whatever agent interface you’re comfortable in.
One time: paste this in a terminal, press enter, close it
That is the terminal’s entire role in your FRACTAL life. (An agent with desktop access can even run this line for you — paste it into the chat instead.)
Open your comfortable UI
Any agent interface that can connect to your desktop — read files, run commands. Claude Code is the reference example; its desktop app opens like any app.
Connect it to FRACTAL
Open ~/Desktop/fractal as the project folder (in Claude Code’s desktop app: open that folder; in any agent: make it the working folder). The folder is the connection — FRACTAL’s memory is the folder, so an agent standing in it is an agent connected to it.
❋ What’s up next?
Condensed — the real sessions say more. The point of the picture: after the one terminal line, the whole FRACTAL life — first contact, the birth, every working loop — happens inside the interface you already like.
The session explains where you’re standing and offers the two paths: look around, or start your own project. The short form of these steps lives on the home page.
Step 2
The birth.
A project can only be born with facts that belong to its owner: what it is, what to call it, who writes in it, what kinds of work it will hold, where its off-site copy should live. The interview exists to collect exactly those facts — once, in your own words — and to carry them mechanically into the birth: your answers become the project’s founding documents, not notes about them. Nothing is asked twice, nothing is thrown away, nothing is invented on your behalf.
You follow it by typing /begin in the reference copy, where first contact left you. It is a conversation, not a form: one question at a time, and after each answer the session drafts what your words feed and reads it back for your confirmation. At the end it shows you the whole birth plan — the files, the names, the remote — and writes your repository only after your yes.
You are not expected to understand FRACTAL to answer any of this. The questions start simple and deepen as the conversation goes; the session explains each concept at the exact moment it matters, and you find the flow together, naturally. Understanding grows through use — nobody starts by understanding FRACTAL, its founder included.
The five questions, and why each is asked
“What’s your project about?”
That simple. From your answer the conversation deepens on its own — what is it concretely, right now? why does it deserve a memory that outlives any chat? — and what you say becomes the project’s vision and current focus: the two poles every future session reads first to orient.
Behind the question: this writes your Global Context — the central explanation you normally re-type into every new chat. Here it is written once, stays stable, and is read at the start of every session: always in sight, never re-explained again — unless you need to update it. At any depth of the project, simply ask your agent whether the global context still fits, or tell it to change — and it is updated, for every session after. All of FRACTAL’s governing documents work this way: living files your agent maintains with you in plain words. Knowing you can talk about the documents, not just within them, is where the real power sits — and it costs one sentence. And an update is minted on top of the record, never over it: the old version stays in the history together with the reasoning that changed it. Everything a session knows evolves only through such recorded changes — which is why nothing is ever lost, and nothing ever changes invisibly.
“What should it be called?”
The name becomes the prefix every governed artifact carries — one stable identity from day one. The identity name wants letters and digits (the session derives one and confirms it with you); your folder can keep any name you like.
Behind the question: the name is also your way back. It becomes your project’s own opening command — however long you’ve been away, that one word loads the memory and reports where things stand. (Right now, in the reference copy, your project has no name yet — that is exactly why the universal commands /welcome and /begin exist; the birth writes your named command into the newborn, so your first real loop already opens with it.)
“Your name, and the email your git host knows?”
And then: name your AI collaborator. Everything ever written in the project is attributed — you under your real address (one honest footnote the session gives you at this exact moment: commit emails become public with the repo), the AI under a name of your choosing with a synthetic address. Authorship stays meaningful forever; if you defer on the AI’s name, the session proposes one from your project’s own domain.
Behind the question: attribution is the door to how any of this can work: git. Git is the standard way software keeps a complete history of plain-text files — every change recorded with its author, nothing ever overwritten. A host like GitHub keeps a copy of that history on the web. FRACTAL’s memory is exactly such files — which is why it needs writers with names. Create your own git home — a free GitHub account is all the setup this needs.
“What kinds of work will live here?”
From your answer the session proposes two to four territories in your own vocabulary — the top-level domains your knowledge will sort into. The honest rule, stated in the same breath: root names are forever and fewer is better — but everything under a root moves freely later, and adding a root later is cheap. You are naming territories, not committing to a taxonomy. Start minimal.
Behind the question: the territories are how FRACTAL branches — each kind of work becomes a domain, and the work in focus gets its own Local Context: the “where we’re looking right now” beside the stable global one. Underneath sits a knowledge graph — think of it as a network of small cards: every idea, decision, and document gets a card, and cards point to each other. Sessions follow the pointers instead of re-reading everything, which is how a project grows large while every session stays light.
“Where should the off-site copy live?”
A memory should survive your machine. The usual answer is an empty repository on your git host (the session tells you exactly how empty). And birth without a remote is a fine answer — you can bind one later; the host is a swappable convenience, never a dependency.
Behind the question: this is what makes the memory machine-loss-proof, and it rounds the whole picture: every working cycle ends with the close — the handover written, the checkers run green, and everything pushed to the off-site copy (the same git home from question three — no new concept). Lose the laptop, and a fresh clone rebuilds the working system; that claim is drilled, not promised. Other shapes work too: any git host, a self-hosted server, or none yet — the protection begins the day you add one.
What is deliberately not asked: the technical defaults — the rebuild document, the close checklist, the capture door — are written for you and stated, not questioned. One more one-liner only: will this project touch credentials? Names get recorded, values never enter the repo, and “none yet” is the usual answer. Push back on any default and it becomes a real question.
The birth ends with a handoff: your project lives at its own path, and the reference copy governs nothing there — from that moment, only your project’s own sessions act inside it. And one honest line the record insists on: a birthed repository is not yet an instance — the instance is real at its first close. Which is exactly where the next step takes you.
This walkthrough projects the Onboarding Protocol — the ratified interview script; its bibliography entry names the source of record.
Step 3
Driving a session.
Every working session opens with your project’s own command and closes with /close. Between the two you just work — the session reads the memory at the start, and what matters is written back at the end. Mid-work, /fieldnote captures a friction or a win in one line without leaving the task.
And feel free to browse the concepts and blog pages along the way — that’s where the inspiration lives, along with useful interaction and procedure tips.
Step 4
Closing the loop.
Every loop ends the same way: the close. In Claude Code it is the command /close; in the ChatGPT desktop app you simply say close — or, the founder’s usual phrase, “let’s close this session.” Other agents may differ in surface, but the word itself is the trigger: close, said in context, starts the process anywhere. The close is where the memory is actually made: the handover written for the next session, the checkers run green, the work committed and pushed. A session that closed can be picked up cold by any future session — that is the whole point. The chat window itself is disposable after that — some clients even tidy their own artifacts away when you close, and it costs nothing: the memory never lived in the chat.
And what is true of close is true of every command: the slash form belongs to the client, the word belongs to the system. welcome, begin, fieldnote, your project’s own name — each is plain language any capable agent understands*. Which closes this guide the way FRACTAL closes everything: the same small rule, applied at every scale.
* And if an agent ever misreads a word — or you want your own vocabulary — you don’t adapt to the agent; you talk to it: establish the rule once, in plain conversation, and it is recorded in your project’s rule register — honored by every session after, whichever agent drives.
And “picked up cold” means exactly what it says. You can close the chat, throw your laptop into the ocean, go hiking in the rainforest, eat street food in India, survive a plane crash in the Himalayas, get hospitalized, recover, go back home, get bored, find life meaningless, start drinking, get addicted, lose your job, go to rehab, get a new job, fall in love with a stranger from rehab, have three kids, get divorced, have your heart broken, lose your home, join the army, live through World War III, get ambushed with your squad, lose your mate, promise to take care of his dog — and one evening, with the dog on your lap, your new laptop on the dog’s belly, and a cat purring behind you, you remember FRACTAL, set it up again, and continue your project exactly where you left off. Only with an updated FRACTAL, and better AI agents.
Step 5
Growing.
More instances (/look observes them read-only), adopting newer kernel releases by your own decision (the migration standard), adopting standards from the registry, teaching your own commands. Each of these is its own concept — the depth lives on the concepts page.
This page is the guide’s skeleton — each step gains its full walkthrough in the content pass. Until then, the practical companion is GUIDE.md in the baseline, which covers day two onward in detail today.