Metadata-Version: 2.4
Name: mindroad
Version: 0.1.0
Summary: Personal, local-first knowledge tracker for self-directed learners.
Author-email: mhmdsamerdev <252254594+mhmdsamer-dev@users.noreply.github.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/mhmdsamerdev/mindroad
Project-URL: Repository, https://github.com/mhmdsamerdev/mindroad
Project-URL: Issues, https://github.com/mhmdsamerdev/mindroad/issues
Keywords: knowledge-tracker,learning,local-first,self-hosted,study
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Web Environment
Classifier: Framework :: FastAPI
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Education
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.29
Requires-Dist: sqlalchemy>=2.0
Requires-Dist: platformdirs>=4.0
Provides-Extra: test
Requires-Dist: pytest>=8; extra == "test"
Requires-Dist: httpx2; extra == "test"
Dynamic: license-file

<img src="https://raw.githubusercontent.com/mhmdsamerdev/mindroad/main/docs/mindroad.png" alt="Mindroad" width="320">

[![CI](https://github.com/mhmdsamerdev/mindroad/actions/workflows/ci.yml/badge.svg)](https://github.com/mhmdsamerdev/mindroad/actions/workflows/ci.yml)

Mindroad is a personal, local-first knowledge tracker for self-directed learners. Everything — subjects, roadmaps, notes, resources, progress — is stored in a single SQLite file on your own machine; there's no account and no cloud sync.

## Install

```
uv tool install mindroad
```

Equivalent, if you don't have `uv`:

```
pipx install mindroad
```

## Usage

```
mindroad
```

This starts the server at `http://127.0.0.1:8420` and opens it in your browser.

Flags:

| Flag | Description |
|---|---|
| `--data-dir PATH` | Directory to store the Mindroad database in (overrides `MINDROAD_DATA_DIR`; default: platform data dir). |
| `--no-browser` | Don't automatically open a browser tab on startup. |
| `--dev` | Developer mode: normal uvicorn logging + auto-reload; skips the banner, first-run message, port self-identification, and auto-open. |
| `-V`, `--version` | Print the Mindroad version and exit. |
| `-h`, `--help` | Show the full help message. |

Running `mindroad` again while it's already running detects the existing instance and just opens it in your browser, rather than erroring.

## Data location

By default, your data lives at the platform-appropriate data directory (via `platformdirs`), e.g. `~/.local/share/mindroad/mindroad.db` on Linux. Override it with the `MINDROAD_DATA_DIR` environment variable, or `--data-dir` (which takes precedence over the environment variable).

## Features

- **Subjects** — flat, standalone topics you're studying, each with a Markdown description, an optional emoji icon, and pin/archive state.
- **Tags** — many-to-many labels on subjects for filtering, colored from a fixed palette.
- **Roadmaps** — an ordered list of milestones per subject, optionally grouped into sections, rendered as a connected path.
- **Milestones** — individual learning objectives within a subject's roadmap, with derived status (not started / in progress / completed).
- **Resources** — up to 3 videos/books/articles/courses linked to each milestone.
- **Notes** — one Markdown note per milestone.
- **Progress tracking** — start/complete/reopen events per milestone, with live-computed rollup progress at the subject level, no cached state.

## License

GPLv3 © 2026
