Fract

A universal dashboard engine that turns any file structure into a living, visual workspace.

One system — infinite shapes. Use it for project management, personal GTD, CRM, spec-driven development, or anything else. Methodology-agnostic, storage-agnostic, fully customizable.

• Filesystem-driven — Folders are entities, markdown files are items, config.json defines the schema
• Zero dependencies — Pure Node.js, vanilla JS client, no build tools required
• AI-first — Plain-text storage that both humans and AI agents can read and write
• Modular UI — Board, table, cards, list, editor, metrics — or create your own views
• Multi-methodology — Shape Up, Scrum, Kanban, GTD, SDD, CRM — or define your own

Quick Start

# Install globally
npm install -g fractd

# Start the dashboard in any project
fractd

# Or run directly with npx
npx fractd

Init a New Project

fractd init "My Project"

You'll be prompted to choose:

1. Base folder name — where your data lives (e.g. spec, board, gtd)
2. Methodology preset — shape-up, scrum, kanban, gtd, sdd, crm
3. AI agent docs — generate CLAUDE.md / AGENTS.md for AI context

This creates your base folder with per-entity config.json files, PROJECT.md, and fract.json.

How It Works

Fract discovers your project structure automatically. No central config needed — just folders with config.json files:

my-project/
  fract.json              # { "root": "board" }
  workspace.json
  board/                   # your base folder (any name)
    fract.json             # project-level settings
    PROJECT.md
    tasks/
      config.json          # defines "task" entity: fields, UI, etc.
      TASK-001.md
      TASK-002.md
    epics/
      config.json          # defines "epic" entity with children: ["task"]
      epic-01/
        README.md
        tasks/
          config.json
          TASK-003.md
    notes/
      config.json
      NOTE-001.md

Each config.json defines an entity:

{
  "entity": "task",
  "singular": "Task",
  "plural": "Tasks",
  "prefix": "TASK",
  "file": "PREFIX-NNN.md",
  "fields": {
    "status": {
      "type": "enum",
      "values": [
        { "key": "todo", "label": "Todo", "color": "#8B8B93" },
        { "key": "in-progress", "label": "In Progress", "color": "#D4A72C" },
        { "key": "done", "label": "Done", "color": "#2EA043" }
      ],
      "default": "todo"
    },
    "assigned": { "type": "list", "label": "Assigned" },
    "points": { "type": "number", "label": "Points" }
  },
  "completedStatuses": ["done"],
  "children": ["subtask"],
  "categories": {
    "colors": { "frontend": "#5B6EF5", "backend": "#F97316" }
  },
  "ui": {
    "layouts": ["board", "table", "list"],
    "defaultLayout": "board",
    "icon": "check-square"
  }
}

Items are markdown files with YAML frontmatter:

---
id: TASK-001
title: "Implement auth flow"
status: in-progress
assigned: [alice, bob]
points: 8
created: 2026-03-23
---

## Implementation Notes

OAuth2 with PKCE flow. See @SPEC-001 for details.

CLI Commands

| Command | Description | |---------|-------------| | fractd | Start the dashboard server | | fractd init [name] | Scaffold a new workspace | | fractd create <entity> "title" | Create an entity | | fractd update <entity> <id> --field value | Update an entity | | fractd delete <entity> <id> | Delete an entity | | fractd list <entity> | List entities with filters | | fractd status | Show project status | | fractd sync | Detect & configure new entities/files | | fractd migrate | Migrate v2 project to v3 format | | fractd preset list | List available methodology presets | | fractd config | Setup preferences & AI skill | | fractd agentdocs | Generate CLAUDE.md / AGENTS.md |

Options: --project <path>, --port <number>, --preset <name>

Dashboard Views

All views are config-driven and rendered from your entity definitions:

• Board — Kanban columns grouped by status, drag-and-drop to update
• Table — Sortable data table with configurable columns
• Cards — Card grid with progress bars, expandable children
• List — Hierarchical list with inline expansion
• Editor — EditorJS block editor for notes and documents (with image support)
• Metrics — Progress by parent, status breakdown, health dashboard

Custom Views

Create custom view modules in your project's modules/ directory:

board/modules/
  gantt/
    gantt.js    # registerModule('gantt', renderGantt)
    gantt.css

Reference in your entity config: "layouts": ["board", "gantt"]

Features

Entity References

Reference other entities inline with @ID syntax:

Depends on @TASK-001. See also @sdd:SPEC-002 for cross-project ref.

References render as clickable badges. Backlinks are computed automatically — every entity shows what references it.

The editor has @ autocomplete: type @ and search by ID or title.

Categories

Organize items into subfolder categories. Files in tasks/frontend/TASK-001.md automatically get _category: "frontend".

Define colors in config:

"categories": {
  "colors": { "frontend": "#5B6EF5", "backend": "#F97316", "infra": "#10B981" }
}

Categories appear in the sidebar, support drag-and-drop, and can be changed from the detail panel.

Images

Upload images via the EditorJS image block. Files are stored in <root>/assets/ and served from /api/images/.

Supports Obsidian-style references: ![[screenshot.png]]

Multi-Source Workspaces

Aggregate data from multiple repositories via workspace.json:

{
  "sources": [
    { "name": "main", "path": ".", "color": "#5B6EF5" },
    { "name": "docs", "type": "remote", "url": "https://github.com/org/docs.git" }
  ]
}

Theming

CSS variables control the entire look. Override in fract.css:

:root {
  --bg: #FFFFFF;
  --surface: #F8F9FA;
  --text: #212529;
  --accent: #0969DA;
  --radius-sm: 6px;
  --radius: 12px;
  --radius-lg: 16px;
}

Built-in themes available via Settings (gear icon).

Presets

| Preset | Entities | Use Case | |--------|----------|----------| | shape-up | cycles, bets, scopes, tasks, pitches, notes | Product development | | scrum | sprints, stories, tasks, epics, bugs, notes | Agile teams | | kanban | tasks, notes | Simple task management | | gtd | contexts, projects, actions, inbox, references | Personal productivity | | sdd | specs, modules, tasks, decisions, notes | Spec-driven development | | crm | companies, contacts, deals, activities | Sales & relationships |

Create your own preset: fractd preset create my-methodology

API

Dynamic REST API generated from your entity config:

| Method | Endpoint | Description | |--------|----------|-------------| | GET | /api/config | Full config (entities, hierarchy, UI) | | GET | /api/{plural} | List entities (with query filters) | | GET | /api/{plural}/{id} | Get entity with content | | POST | /api/{plural} | Create entity | | PATCH | /api/{plural}/{id} | Update entity fields | | DELETE | /api/{plural}/{id} | Delete entity | | GET | /api/resolve/{id} | Resolve entity reference | | POST | /api/categorize | Move item to category | | POST | /api/images/upload | Upload image | | GET | /api/images/{name} | Serve image | | GET | /api/status | Project status | | GET | /api/metrics | Computed metrics | | GET | /api/events | SSE stream for live updates |

PWA Mode (Optional)

You can install Fract as a Progressive Web App for a standalone window experience instead of opening in a browser tab.

1. Start the server: fractd
2. Open the dashboard URL in your browser (Chromium-based: Chrome, Brave, Edge)
3. Install as app: browser menu → "Install page as app..."
4. Create a launcher script (e.g. ~/.local/bin/fractd-open):

#!/bin/sh
exec /path/to/your/browser --profile-directory=Default --app-id=YOUR_APP_ID

5. Set the BROWSER environment variable in your shell profile:

export BROWSER=$HOME/.local/bin/fractd-open

From now on, running fractd in any project will open the PWA window instead of a browser tab.

The app-id is generated by the browser when you install the PWA. You can find it in the .desktop file created in ~/.local/share/applications/ (Linux) or by inspecting chrome://apps in your browser.

AI Agent Integration

Fract is designed to work with AI coding agents. The entire project state is plain markdown files that agents can read and modify directly.

# Generate context files for AI agents
fractd agentdocs

# Creates CLAUDE.md (Claude Code) and/or AGENTS.md (Cursor, Copilot)

Agents can:

• Read PROJECT.md for project context
• Create/update entities by writing markdown files with frontmatter
• Use the REST API for structured operations
• Reference entities with @ID syntax in content
• Run fractdd sync to auto-configure new files they create

License

MIT