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.json`	Flint root	Identity and state	No
`.flint/references.json`	`.flint/`	Machine-specific workspace paths	No
`.flint/connections.json`	`.flint/`	Machine-specific connection paths	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. This is the source of truth — human-editable, committed to git.

Complete Structure

[flint]
name = "my-project"
type = "flint"
tags = ["active", "dev"]
description = "Main development workspace"

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
increments = { source = "NUU-Cognition/shard-increments" }
notepad = { source = "NUU-Cognition/shard-notepad" }
plan = { source = "NUU-Cognition/shard-plan" }
my-custom = { source = "path:./Shards/(Dev) My Custom", dev = true }

[mods]
claude-code = { source = "NUU-Cognition/flint-mod-claude-code" }

[workspace]
references = [
  { name = "Monorepo", type = "codebase" },
  { name = "design-docs", type = "drive" },
]
repositories = [
  { name = "example-api", url = "https://github.com/user/example-api" },
]

[workspace.sources]
repositories = [
  { name = "design-ref", url = "https://github.com/company/design-system" },
]

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

[connections]
flints = [
  { name = "NUU Vessel" },
]

[flint] Section

Core workspace identity.

[flint]
name = "my-project"
type = "flint"
tags = ["active", "dev"]
description = "Main development workspace"

Field	Required	Values	Description
`name`	Yes	string	Display name, typically matches folder name
`type`	Yes	`flint` or `subflint`	Workspace type
`tags`	No	array of strings	Tags for registry categorization
`description`	No	string	Brief description

The name field is used:

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

[shards] Section

Declare shards to install in this workspace. Each shard is a key-value pair where the key is a local identifier and the value specifies the source.

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
increments = { source = "NUU-Cognition/shard-increments" }
notepad = { source = "NUU-Cognition/shard-notepad" }
plan = { source = "NUU-Cognition/shard-plan" }
orbcode = { source = "NUU-Cognition/shard-orbcode" }
my-custom = { source = "path:./Shards/(Dev) My Custom", dev = true }

Source formats:

"owner/repo" — GitHub repository (e.g., "NUU-Cognition/shard-projects")
"github:owner/repo" — Explicit GitHub prefix
"path:./local/path" — Local filesystem path

Optional fields:

dev = true — Marks as a dev shard (skipped by sync and update)

Available shards:

shard-flint — Base conventions and agent setup
shard-projects — Task and backlog management
shard-increments — Version stream management
shard-notepad — Quick capture and brainstorming
shard-plan — High-level planning
shard-orbcode — Semantic code mapping
shard-reports — Research and analysis
shard-learning-reports — Educational content
shard-flintknapping — Iterative refinement workflows
shard-comments — Inline document comments

[mods] Section

Declare mods (environment modifications) to install.

[mods]
claude-code = { source = "NUU-Cognition/flint-mod-claude-code" }
my-mod = { source = "path:./Mods/(Dev) My Mod", dev = true }

Source formats: Same as shards ("owner/repo", "github:owner/repo", "path:./path").

Optional fields:

dev = true — Marks as a dev mod

Available mods:

flint-mod-claude-code — Claude Code integration with CLAUDE.md generation

[workspace] Section

Declare external resource references and repositories.

[workspace]
references = [
  { name = "Monorepo", type = "codebase" },
  { name = "design-docs", type = "drive" },
  { name = "api", type = "api" },
]
repositories = [
  { name = "example-api", url = "https://github.com/user/example-api" },
]

Reference fields:

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

Reference types: codebase, drive, api, database, service

Repository fields:

Field	Required	Description
`name`	Yes	Repository identifier (creates `Workspace/Repositories/<name>/`)
`url`	Yes	Git URL to clone from

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

[workspace.sources] Section

Declare source repositories — lightweight reference copies that are shallow-cloned with .git stripped.

[workspace.sources]
repositories = [
  { name = "design-ref", url = "https://github.com/company/design-system" },
]

Source repositories are cloned to Workspace/Sources/Repositories/ and managed with flint workspace addreferencerepo, listreferencerepo, updatereferencerepo, and removereferencerepo.

Repository fields:

Field	Required	Description
`name`	Yes	Repository identifier (creates `Workspace/Sources/Repositories/<name>/`)
`url`	Yes	Git URL to clone from

[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.

[connections] Section

Declare connections to other Flints.

[connections]
flints = [
  { name = "NUU Vessel" },
  { name = "NUU Mesh" },
]

Connection fields:

Field	Required	Description
`name`	Yes	Name of the target Flint (must be registered)

Machine-specific paths are stored in .flint/connections.json (gitignored) and Connections/<Name>/con-*.md files.

flint.json

Identity and state file. Located at the Flint root. Committed to git. Do not edit manually.

Structure

{
  "version": "0.2.0",
  "id": "a8f63611-9af9-4bd5-9c73-84d22fdfb201",
  "type": "flint",
  "created": "2026-01-04T10:30:05.856Z",
  "synced": "2026-03-01T15:30:00.000Z",
  "migrations": {
    "migration-id": "2026-02-01T..."
  }
}

Field	Description
`version`	Config format version
`id`	UUID for this Flint (stable identity)
`type`	Flint type (`flint` or `subflint`)
`created`	Creation timestamp
`synced`	Last sync timestamp
`migrations`	Map of applied migration IDs to timestamps

This file is created during flint init and updated by flint sync. The id provides a stable identifier that persists across renames and moves.

.flint/ Directory

Gitignored runtime state. Contains machine-specific data that doesn't travel with the Flint.

.flint/
  references.json      # Machine-specific workspace paths
  connections.json     # Machine-specific connection paths
  index/
    files.json         # Mesh index (file IDs, tags, paths)

references.json

Tracks fulfilled workspace references:

{
  "version": 1,
  "references": [
    {
      "name": "Monorepo",
      "type": "codebase",
      "path": "/Users/me/dev/main",
      "fulfilled": "2026-01-28T10:30:00.000Z"
    }
  ]
}

connections.json

Tracks fulfilled connections:

{
  "version": 1,
  "connections": [
    {
      "name": "NUU Vessel",
      "path": "/Users/me/dev/nuu/(Flint) NUU Vessel",
      "fulfilled": "2026-01-28T10:30:00.000Z"
    }
  ]
}

Global Configuration

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

Structure

mode = "production"

Settings

Setting	Default	Description
`mode`	`production`	Feature mode
`open.apps`	`[]`	Apps to open Flints with (e.g., `["obsidian", "cursor"]`)

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",
      "tags": ["active"],
      "description": "Main Flint development workspace"
    }
  ]
}

Flint Entry Fields

Field	Required	Description
`name`	Yes	Flint name (from `flint.toml`)
`path`	Yes	Absolute path to Flint
`type`	No	Workspace type (`flint` or `subflint`)
`tags`	No	Array of tags for categorization
`description`	No	Brief description

Managing the Registry

# List registered Flints
flint list

# Register current directory
flint register

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

# Scan for Flints to register
flint register --scan ~/projects

# Unregister
flint unregister

# Validate and clean
flint registry validate

# Add/remove tags
flint registry tag "My Project" "important"
flint registry untag "My Project" "old-tag"

Configuration Patterns

Minimal Flint

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

Software Project

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

[shards]
projects = { source = "NUU-Cognition/shard-projects" }
increments = { source = "NUU-Cognition/shard-increments" }
plan = { source = "NUU-Cognition/shard-plan" }
orbcode = { source = "NUU-Cognition/shard-orbcode" }

[mods]
claude-code = { source = "NUU-Cognition/flint-mod-claude-code" }

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

Research/Notes

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

[shards]
notepad = { source = "NUU-Cognition/shard-notepad" }
reports = { source = "NUU-Cognition/shard-reports" }

Subflint

[flint]
name = "Blog"
type = "subflint"

[shards]
notepad = { source = "NUU-Cognition/shard-notepad" }

File Locations Summary

File	Location	Git
`flint.toml`	`<flint>/`	Committed
`flint.json`	`<flint>/`	Committed
`.flint/references.json`	`<flint>/.flint/`	Gitignored
`.flint/connections.json`	`<flint>/.flint/`	Gitignored
`.flint/index/files.json`	`<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