Introduction

Flint is a local-first workspace framework for structured thinking. It provides a simple but powerful way to organize your notes, connect them to external resources, and collaborate with AI agents.

At its heart, Flint is a folder structure with conventions. But these conventions create something greater: a cognitive workspace where your ideas live as interconnected markdown files, navigable by both humans and AI.

Who Is Flint For?

Developers managing complex projects. If you're building software and need to keep track of architecture decisions, implementation notes, and project plans alongside your code, Flint gives you a structured home for that thinking.

Researchers organizing knowledge. If your work involves connecting ideas across sources, building understanding over time, and producing written outputs, Flint provides the framework to capture and evolve your thinking.

AI-assisted workflows. If you collaborate with AI agents (Claude, ChatGPT, or local models), Flint gives them the context they need to be genuinely helpful. Your agent can read the init file, understand the workspace structure, and get to work without lengthy explanations.

Anyone who wants their notes to be more than a pile of files. Flint turns scattered documents into a connected knowledge graph with clear organization.

The Local-First Philosophy

Your data stays on your machine. A Flint is just a folder - plain markdown files in a sensible structure. There is no cloud service, no proprietary database, no vendor lock-in.

This means:

• You own your data. Move it, back it up, version it with git, sync it however you want.
• It works offline. No internet required. Your workspace is always available.
• It's future-proof. Markdown files will be readable in 50 years. Proprietary formats won't.
• It's inspectable. You can open any file in any text editor and see exactly what's there.

Core Concepts

Mesh: Your Thinking Space

The Mesh/ folder is where your notes live. Every markdown file in Mesh is automatically indexed and becomes part of your knowledge graph. When you write [Other Note](/other-note), you create a link. When you write ![Embedded Content](/embedded-content), you create a transclusion.

Mesh is the center of your workspace. Everything else either feeds into it (context, resources) or flows out of it (exports, outputs).

Plugins: Agent Capabilities

The Plugins/ folder extends what you and AI agents can do. Plugins are markdown-based prompt packages - they provide context, skills, templates, and workflows that agents can follow.

For example, the Increments plugin helps you track versioned work. The Living Documents plugin manages document lifecycle. The Projects plugin provides task tracking patterns.

Plugins are safe and inspectable. They don't run arbitrary code - they provide structured prompts that agents interpret.

Mods: Environment Integration

Mods configure how Flint integrates with your environment. The git mod initializes a git repository and manages .gitignore. The claude-code mod generates CLAUDE.md for Claude Code integration.

Mods run on install and sync, setting up configuration files that help Flint work seamlessly with your existing tools.

Workspace: External Resources

The Workspace/ folder connects your thinking to external reality. When you're documenting an API or planning a feature, Workspace bridges the gap between your notes and the actual codebase.

Declare workspace references in flint.toml, fulfill them with local paths, and the reference documents travel with your Flint to explain what each resource is.

The Folder Structure

(Flint) my-project/
├── flint.toml           # Configuration file
├── .flint/              # Runtime data (gitignored)
├── Mesh/                # Your notes and documents
│   └── (System) Flint Init.md
├── Imports/             # Content from other Flints
├── Exports/             # Compiled outputs for sharing
├── Workspace/           # External resource links
├── Media/               # Images, PDFs, assets
└── Plugins/             # Automation capabilities

Each folder has a specific purpose:

Obsidian Integration

Flint workspaces work seamlessly with Obsidian. Open any Flint folder as an Obsidian vault, and you get:

• Graph view of your note connections
• Backlinks panel showing what links to each note
• Quick switcher for fast navigation
• Link completion as you type `[bash

Then create your first workspace:

```bash
flint init my-project

This creates the folder structure, initializes configuration, and registers the Flint. From there:

1. Open the folder in Obsidian or your preferred editor
2. Read the init file at Mesh/(System) Flint Init.md
3. Create notes in Mesh/ - they're automatically indexed
4. Run flint sync to index files and sync plugins

See [Guide - Quick Start for a complete walkthrough.

Key Commands

What Makes Flint Different

Bounded, not infinite. A Flint has clear edges. One folder, one domain of thought. When it gets too big, split it. This makes workspaces comprehensible to both humans and agents.

Modules with purposes. Each folder has a specific role. You know where things go. No more wondering if this document belongs in docs/, notes/, or resources/.

Declarative configuration. Everything is declared in TOML and markdown. You describe what you want, not how to achieve it. Configuration is readable and portable.

Agent-native design. The init file convention, plugin system, and structured context are designed for AI collaboration from the ground up.

Just files. No database, no proprietary format. Your Flint is a folder of markdown files that you can read, edit, and move with any tool.

Next Steps

• Guide - Quick Start - Create your first Flint
• Guide - Core Concepts - Understand the mental model
• Guide - Tutorial Project Planning - See Flint in action for software projects
• Guide - Tutorial Research Notes - See Flint for research and writing
• Module - Mesh - Deep dive into the core module
• Module - Plugins & Mods - Understand the plugin system