Configuration Reference

Complete guide to Flint configuration files and options.

Configuration Files Overview

File	Location	Purpose	Edit
`flint.toml`	Flint root	Workspace configuration	Yes
`flint.lock`	`.flint/`	Installed state tracking	No
`mesh.config.yaml`	`.flint/`	Mesh indexing metadata	No
`config.toml`	`~/.flint/`	Global user settings	Yes
`registry.json`	`~/.flint/`	Global Flint registry	No

flint.toml

The main configuration file for your Flint workspace. Located at the root of your Flint.

Complete Structure

[flint]
name = "my-project"
type = "flint"

[plugins]
required = [
  "core",
  "living-documents",
  "increments",
  "projects",
]

[mods]
required = [
  "claude-code",
]

[workspace]
references = [
  { name = "monorepo", type = "codebase" },
  { name = "design-docs", type = "drive" },
]

[imports]
required = [
  "NUU Flint/Guide",
]

[flint] Section

Core workspace identity.

[flint]
name = "my-project"
type = "flint"

Field	Required	Values	Description
`name`	Yes	string	Unique identifier, typically matches folder name
`type`	Yes	`flint`	Workspace type

The name field is used:

As the display name in flint list
In import references from other Flints

[plugins] Section

Declare plugins to install in this workspace.

[plugins]
required = [
  "core",
  "living-documents",
  "increments",
  "projects",
  "notepad",
  "plan",
]

Plugins are specified by kebab-case name. Run flint plugin list --available to see all plugins.

Core plugins:

core - Base conventions and agent setup
living-documents - Document lifecycle tracking
increments - Version stream management
projects - Task and backlog management
notepad - Quick capture and brainstorming
plan - High-level planning

[mods] Section

Declare mods (integrations) to install.

[mods]
required = [
  "claude-code",
]

Available mods:

claude-code - Claude Code integration with CLAUDE.md generation

[workspace] Section

Declare external resource references. These are portable declarations of what external resources the workspace connects to.

[workspace]
references = [
  { name = "monorepo", type = "codebase" },
  { name = "design-docs", type = "drive" },
  { name = "api", type = "api" },
]

Field	Required	Description
`name`	Yes	Reference identifier (creates `Workspace/References/rf-<name>.md`)
`type`	Yes	Resource type

Reference types:

codebase - Source code repository
drive - File system directory
api - External API
database - Database connection
service - External service

Machine-specific paths are stored in .flint/workspace.toml (gitignored), not in flint.toml.

[imports] Section

Import exports from other registered Flints.

[imports]
required = [
  "NUU Flint/Guide",
  "NUU Parse/API Docs",
]

Format: "<Flint Name>/<Export Name>"

The source Flint must be registered and have the specified export configured.

flint.lock

Generated lock file tracking installed state. Located at .flint/flint.lock. Do not edit manually.

Structure

version: 1
flintVersion: 1.0.0
created: 2026-01-04T10:30:05.953Z
synced: 2026-01-04T10:30:05.953Z
plugins:
  - name: living-documents
    version: 1.0.0
    installedAt: 2026-01-04T09:00:00.000Z
mods:
  - name: claude-code
    version: 1.0.0
    installedAt: 2026-01-04T10:30:05.953Z

Field	Description
`version`	Lock file format version
`flintVersion`	Flint CLI version that created/synced
`created`	When the lock file was created
`synced`	Last sync timestamp
`plugins`	Array of installed plugins
`mods`	Array of installed mods

Plugin/Mod Entry

- name: living-documents
  version: 1.0.0
  installedAt: 2026-01-04T09:00:00.000Z

Field	Description
`name`	Kebab-case identifier
`version`	Installed version
`installedAt`	Installation timestamp

The lock file is regenerated by flint sync.

mesh.config.yaml

Mesh indexing configuration. Located at .flint/mesh.config.yaml. Do not edit manually.

Structure

version: 1
id: a8f63611-9af9-4bd5-9c73-84d22fdfb201
type: flint
created: 2026-01-04T10:30:05.856Z

Field	Description
`version`	Config format version
`id`	UUID for this mesh
`type`	Mesh type (`flint`)
`created`	Creation timestamp

This file is created during flint init and should not be modified.

Global Configuration

User-wide settings stored at ~/.flint/config.toml.

Structure

mode = "production"

Settings

Setting	Default	Description
`mode`	`production`	Feature mode

Feature Mode

Controls which features are available:

Mode	Description
`production`	Stable features only (default)
`experimental`	Include experimental features
`dev`	All features including development

Manage with the flint mode command (see below).

flint config Command

View and modify global configuration.

# View all config
flint config

# Get a specific value
flint config get mode

# Set a value
flint config set mode production

flint mode Command

Manage feature mode with better UX than direct config editing.

# Show current mode
flint mode

# Set mode
flint mode production
flint mode experimental
flint mode dev

# List all features and availability
flint mode --list

# Reset to default
flint mode --reset

Global Registry

Registry of all Flints on this machine. Located at ~/.flint/registry.json. Managed by CLI commands.

Structure

{
  "version": 1,
  "flints": [
    {
      "name": "NUU Flint",
      "path": "/Users/nathan/dev/nuu/nuu-flints/(Flint) NUU Flint",
      "type": "flint",
      "source": "local",
      "exports": ["Guide"]
    }
  ]
}

Flint Entry Fields

Field	Required	Description
`name`	Yes	Flint name (from `flint.toml`)
`path`	Yes	Absolute path to Flint
`type`	No	Workspace type
`source`	No	Currently always `local`
`exports`	No	Array of export names

Managing the Registry

# List registered Flints
flint list

# Register current directory
flint register

# Register specific path
flint register /path/to/flint

# Unregister
flint unregister

Configuration Patterns

Minimal Flint

[flint]
name = "notes"
type = "flint"

Software Project

[flint]
name = "my-app"
type = "flint"

[plugins]
required = [
  "core",
  "living-documents",
  "increments",
  "projects",
  "plan",
]

[mods]
required = [
  "claude-code",
]

[workspace]
references = [
  { name = "repo", type = "codebase" },
]

Research/Notes

[flint]
name = "research"
type = "flint"

[plugins]
required = [
  "core",
  "living-documents",
  "notepad",
]

File Locations Summary

File	Location	Git
`flint.toml`	`<flint>/`	Committed
`.flint/flint.lock`	`<flint>/.flint/`	Gitignored
`.flint/mesh.config.yaml`	`<flint>/.flint/`	Gitignored
`.flint/workspace.toml`	`<flint>/.flint/`	Gitignored
`~/.flint/config.toml`	Home directory	N/A
`~/.flint/registry.json`	Home directory	N/A

Reference - CLI Commands - Full command reference
Guide - Quick Start - Getting started guide

On this page