Introduction
Flint is a local-first system for thinking, planning, and documentation. It keeps your notes, your references, and your agent workflows in one structured folder. That folder is a Flint.
New to Flint? Start with Quick Start. It takes you from the install to your first Flint. To set up a new machine in full, read Setting Up a Machine.
What a Flint Is
A Flint is one folder with its own id. It has three parts.
The content layer holds your durable thinking. Notes, plans, and decisions live in Mesh/ as Markdown. Images and other files live in Media/.
The capability layer holds shards. Each shard is a cognitive program. It gives agents repeatable instructions, workflows, and templates.
The flint command manages the folder. It creates Flints, installs shards, and makes the files match their declarations.
A Flint is intentionally bounded. It covers one coherent area of work. Your own thinking stays separate from outside material. Copies of external sources live in Sources/. Active repository checkouts live in Workspace/Repos/. The local state of this machine lives in .flint/.
Who Flint Is For
Flint serves three kinds of work.
Software projects need durable notes next to real code. Flint holds architecture notes, migration plans, and investigation logs. It points at codebases without mixing notes with code.
Research and writing need a clean split between input and thinking. Flint keeps raw source material in Sources/. Your interpretation grows in Mesh/.
Agent-assisted work needs a stable starting point. Flint gives each agent the same entrypoint and the same structure. The agent loads shards, resolves sources, and writes durable results back to Mesh/.
The Shape of a Flint
Each new Flint starts with this structure:
(Flint) My Project/
├── flint.toml
├── flint.json
├── .flint/
├── .obsidian/
├── Mesh/
├── Media/
├── Shards/
├── Sources/
└── Workspace/| Area | Purpose |
|---|---|
flint.toml | The intent: what the Flint declares, such as its shards and references |
flint.json | The lock: what the Flint resolved. Only commands write it |
Mesh/ | Your durable thinking: notes, plans, decisions |
Media/ | Images, PDFs, and other files |
Shards/ | Installed cognitive programs for agents |
Sources/ | Read-only copies of external material |
Workspace/ | Active repositories and working surfaces |
.flint/ | The local state of this machine, such as references and sync records |
.obsidian/ | The Obsidian payload and settings. It is absent when Obsidian is off on this machine |
When you start an agent session, Flint also makes .orb/ for the session records. A new Flint has no Modules/ folder and no env files (flint.env, flint.env.local, flint.env.example). flint module install creates Modules/. You create the env files when the Flint needs them. See Modules, Crons, and DMs.
Your First Path
A new person follows six steps.
Install the CLI first. The package gives you the commands flint and nuu:
npm install -g @nuucognition/flint-cliSet up the machine next:
flint setupSetup needs internet access. It asks your Name and the machine display name. It checks your tools and makes your Computer Flint, the home Flint of this machine. It can clone the Guide of NUU Cognition, a Flint that answers Flint questions. It ends in the Computer Flint with your first agent session. Read Setting Up a Machine for the seven steps.
Create a Flint next:
flint create "My Notes"The command makes the folder, the Mesh, and the Git repository. It adds the Flint to the roster of this machine. Read Creating a Flint for presets and options.
Move into the new Flint. The shard commands, flint sync, and flint orbh i act on the Flint of the current folder:
cd "(Flint) My Notes"Add shards next. Browse what you can install:
flint shard browseInstall the shards that fit your work. The shard registry serves many NUU Cognition shards (Flint, Orbh, Knap, Projects, Notepad, Plan, Reports, and more). Install one by its package spec:
flint shard install @nuucognition/projectsWhen the registry has no version of a shard, install it from its Git location:
flint shard install --from-git NUU-Cognition/shard-<slug>Read Shards for the shard model.
Keep the files in step. After you change flint.toml, run:
flint syncSync makes the files match the lock and the declarations. Run flint plan to preview the sync without changes. Read Sync for details.
Work with agents last. Start an interactive agent session in the Flint:
flint orbh iThe agent reads Mesh/(System) Flint Init.md first. It loads the relevant shards. It writes results back to Mesh/. Read Agent Sessions for the session model.
Where to Go Next
If you are new to Flint, read in this order:
You need no NUU account and no org. To share Flints with an org, read Join Your Org. To write your notes in Obsidian, read Using Obsidian. When a command fails, read Doctor and Fix.
If you already understand the basic model and want to do real work:
To look up commands and settings, read CLI Commands and Configuration.