One JSON file, one click, every folder and url and file for a project opens at once. DirNav is a local dashboard that turns a single projects.json manifest into a static page, and routes each click through a custom kickoff:// URI to a PowerShell runner that opens the right things on your machine.
Try the live demo. Browse-only, since Kickoff and Open P00 require the local Windows install.
Windows 10 and 11. MIT licensed.
- π€― A user usually manages 10 to 20 active projects on their computer, ranging from work to personal, learning to hobby, and research to side projects.
- π― The user knows their projects and can roughly compare priorities between them. Even so, it is hard to keep track of all of them.
- π Each project has its own folders, urls, and files that the user needs to open to work on it.
- π Locating and opening all the related folders, urls, and files for a project takes time and attention, and the user might forget some of them, or open the wrong one.
- π« After a long pause on a project, the user might forget where the related folders are, lose time searching for them, and feel friction starting work again.
DirNav is a local dashboard that turns a single projects.json manifest into a static page, and routes each click through a custom kickoff:// URI to a PowerShell runner that opens the right things on your machine. It addresses the five problems above as follows:
- π·οΈ Each project can carry multiple attributes. For example, a personal coding project for stock market analysis can have the attributes
personal,coding, andfinance. Filter projects by attribute to find the one you want to work on quickly. - π© Each project has a priority from 0 to 10, adjustable at any time. The dashboard sorts projects by priority so the most important one surfaces first.
- π
projects.jsonrecords every folder, url, and file of a project, so nothing is forgotten even when things are scattered across different folders or online services. - βοΈ The Kickoff button opens every folder, url, and file of a project in one click. Check or uncheck individual items to open only a subset.
- β‘οΈ We encourage each project to have a
P00progress log. Write an overview, then after each work session note what was done and what to do next. This makes it easy to pick up again after a long pause.
projects.json -> Python generator -> static HTML dashboard
|
| click Kickoff
v
kickoff://open?slug=...&items=...
|
Windows custom URI scheme
v
kickoff.ps1
|
v
folders open as Explorer tabs, urls and files via Start-Process
The interesting piece is the kickoff:// URI scheme. A browser cannot normally launch local programs, for good reason. Registering a custom URI scheme with the OS gives the page exactly one well-defined call site into PowerShell. The dashboard emits kickoff://open?slug=<projectSlug>&items=<index-list>. The runner resolves the slug against projects.json, never executes raw paths from the URL, and only opens entries the manifest already approved.
The page is the UI. The manifest is the trust boundary. PowerShell does the work.
- Single source of truth: every project, folder, url, file, path to project log file (P00, can be md, txt, or excel), attribute, priority, status, and date lives in
projects.json. Edit, recompile, done. - Fuzzy global finder across every folder, url, file, and P00 path in every project.
- Attribute filter chips with per-tag colors. Add an attribute by editing one line in the manifest.
- Status pool with dim flags.
paused,stalled, andcompletedprojects render dimmed automatically. - Grouped grid. Cards group by primary attribute, the highest-priority group on top, ordered by priority within each group. Low-priority and unset cards drop into a parked band at the bottom.
- One-click batch open. The Kickoff button opens every checked folder as an Explorer tab, then the urls, then the files. Uncheck items to open only a subset.
- Open P00 button. Opens the project's P00 markdown in VSCode. Ctrl plus click opens its folder in Explorer instead.
- Validated at compile time. The generator checks attribute-pool membership, unique slugs, date formats, and that every related slug resolves to a real project. A broken
projects.jsonprints an error instead of writing a broken page. Related links are not required to be symmetric, because direction carries meaning; an undeclared one-way link is reported as a warning that does not stop the build.
Requirements: Windows 10 or 11, Python 3.x on PATH, PowerShell (built in), VSCode (only if you want the Open P00 button). No pip install needed, the generator uses standard library only.
All internal paths are resolved at install time. The only file you edit by hand is projects.json (the project entries themselves).
- Clone the repo. Copy
projects.example.jsontoprojects.jsonand edit it to point at your own folders. - Run
[B]_0-Install Protocol.batonce. Registers thekickoff://protocol under your Windows user (HKCU). Re-run if you ever move the repo. Fully restart your browser after the first install so it picks up the new scheme. - Run
[B]_P01-Compile Dashboard.batafter every edit toprojects.json. Validates the manifest, then regenerates02_html/index.html. - Run
[B]_localhost homepage.bat(orpython -m http.server 5599from02_html/) to serve the dashboard, then openhttp://localhost:5599in your browser. Keep the server running while using DirNav.
The first Kickoff click prompts you once to allow PowerShell. That is Windows confirming the custom protocol, not the script asking for elevation.
01_scripts/ P01_generate DirNav page.py, kickoff.ps1, Install-Protocol.ps1
02_html/ generated index.html, style.css, style-forest.css, style-blue.css, style-macaron.css, 03_js/app.js, 04_includes/
projects.example.json sanitized sample manifest
[B]_0-Install Protocol.bat
[B]_P01-Compile Dashboard.bat
[B]_localhost homepage.bat
README.md
LICENSE
- The manifest is the trust boundary. The browser never sends paths to PowerShell. It sends a slug and an index list. The runner re-resolves both against
projects.json. The set of openable things is exactly the set the user has already curated. - The page is the UI. The runner is the worker. They communicate through one well-defined message:
kickoff://open?slug=...&items=.... No other entry point from the browser into the shell. - Tab orchestration uses SendKeys against Explorer. Not elegant, but as of Windows 11 it is the only reliable way to open multiple folders as tabs in the same window.
- Colors are CSS variables in one place. Edit
--attr-<name>instyle.css :rootto recolor a tag. Add--attr-<name>-fontto override the label text color when the background clashes with white (used for the yellowmusictag). - Dashboard theme: in
01_scripts/P01_generate DirNav page.py, setPATH_STYLE_CSSto02_html/style.css(default cyan/magenta),02_html/style-forest.css,02_html/style-blue.css, or02_html/style-macaron.css. Recompile with[B]_P01-Compile Dashboard.bat. Alternate themes importstyle.cssand override only the non-attribute color palette; attribute chip colors stay instyle.css.
- The compiled
02_html/index.htmlis generated. Do not hand-edit it. Editprojects.json, then recompile.
- Windows only. The browser-to-shell URI bridge, the Explorer tab orchestration, and the path conventions are Windows-specific by design. No plan to port to macOS or Linux.
- Single user. No multi-user state, no sync, no auth.
projects.jsonis your file. - A productivity tool, not a product. Use it, fork it, or just steal the
kickoff://pattern for your own thing.
projects.json is a JSON object with five top-level keys: schemaVersion, _relatedPolicy, attributePool, statusPool, and projects.
{
"schemaVersion": 1,
"attributePool": ["coding", "career", "venture", "learning", "music", "personal"],
"statusPool": [ { "value": "active", "label": "Active", "description": "...", "dim": false, "order": 1 } ],
"projects": [ ]
}schemaVersion: integer. Bump when the field set changes so the generator and validator can migrate older files. Currently1._relatedPolicy: documentation, not data. JSON has no comment syntax, so this key carries the rule governingrelatedlinks plusintentionalOneWay, a map of every deliberate one-way link to the reason it points one way. The generator never reads it for rendering and never rejects it, and the compile write-back preserves it, so it is the safe place for a manifest-level note. The advisory symmetry check compares actual asymmetry againstintentionalOneWayand warns about anything undeclared, and about declarations that are no longer asymmetric.attributePool: the controlled, ordered vocabulary of attribute tags. A project'sattributesmay only contain values from this pool. The order here is the order tags appear (e.g. as filter chips) in the navigator. List them in priority order, not alphabetically. Edit this one line to add, rename, or reorder tags.statusPool: the controlled, ordered vocabulary of statuses. Each entry hasvalue,label,description,dim, andorder. A project'sstatusmust equal one of thesevalues.dimtrue means the navigator renders that project dimmed (currentlypaused,stalled,completed).projects: array of project objects, each using the field order below.
Use this order for each project object. All seventeen fields below are required; the validator rejects a project that omits any of them. Use "" for empty strings (note, emoji, unset dates), [] for empty arrays (attributes, folders, urls, codeRepos, writingRepos, files, related), and null for an unset priority.
Two values are filled in for you at compile time. lastWorkDate is still a required key, so a project added by hand must carry it as "" and the compile step will overwrite it. p00SizekB is the exception to the "every field" rule: omit it entirely when adding a project, and the compile step appends it.
Several fields map to a single-letter item reference used by kickoff://<slug>?items=..., noted below where it applies.
projectSlug: short unique identifier. URL-safe, no spaces. Stable, since renaming breaks the kickoff name, thekickoff://link, and any cross-reference.projectName: human-readable name shown in the navigator.attributes: array of tags fromattributePool. The first tag is the project's primary attribute and decides which group the card lands in.priority: integer 0 to 10, ornullif unset. Suggested scale: 0 to 2 stalled or parked, 3 to 5 side projects, 6 to 7 main work, 8 to 10 top priority. Used to sort within a filter, and projects below 2 are grouped separately as parked.status: one ofactive,evolving,waiting,paused,stalled,completed. See below.p00InitiationDate: date this project began being tracked with a P00 file,YYYY-MM-DD.startDate: date the project itself began,YYYY-MM-DD, or""if unset.lastWorkDate: most recent work date,YYYY-MM-DD. Auto-synced at compile time from the P00 file's last-modified timestamp, so write""and let the generator fill it.note: short context note for relationships, status, or caveats.""when empty.emoji: one to three emoji shown before the slug on the card's meta line and before the project name in finder results.""renders nothing at all, with no leading space left behind.folders: array of absolute Windows folder paths. Opened as Explorer tabs by the runner; the first opens a new window and the rest follow as tabs, in array order. Item refd.urls: array of general web urls (portals, dashboards, order or status pages). Rendered with a link icon in the merged "URLs & Repos" card section. A web url on the dashboard opens directly in a new browser tab; anything that is nothttp/httpsis routed through the runner instead. Item refu.codeRepos: array of source-repository urls, typically GitHub. Same card section asurls, distinguished by its own icon. Item refc.writingRepos: array of writing-project urls, typically Overleaf. Same card section again, with its own icon, so a paper is visually distinct from its code. Item refw.files: array of absolute Windows file paths (launchers, spreadsheets, decks, key documents). Each opens in its default application. Item reff.related: array of otherprojectSlugvalues this project relates to. Write the link from the side that belongs to, depends on, or draws from the other, and reciprocate only when both sides genuinely draw from each other. A one-way link is not a defect: a hub that many projects touch, a dependency, and a context constraint are all legitimately one-directional, and forcing symmetry on them makes a hub link to nearly everything and stop carrying information. The rule and every deliberate one-way link live in the_relatedPolicytop-level key. The validator checks that every referenced slug resolves; asymmetry that is not declared there is reported as a warning only.p00: absolute Windows path to the project's P00 markdown file. Item refpopens the file,pdopens its containing folder.p00SizekB: size of the P00 file in kB, written back by the compile step and shown on the card's P00 button. Do not hand-write it; omit the key and let the generator add it.
active: in the current focus, being worked on now. Has an ending goal or milestone.evolving: a long-lived project with no fixed end, worked on intermittently as it grows. Differs fromactive, which is a focused push.waiting: blocked on something external (a person, a decision, a service). Cannot proceed until it resolves.paused: deliberately set aside; not blocked, resumable any time.stalled: unintentionally inactive for a long time, usually due to limited time, attention, or money. Drifted rather than decided.completed: done. No further work expected.
- Use absolute Windows paths.
- Escape backslashes as
\\because this is JSON. - Keep general web urls in
urls, source repositories incodeRepos, writing projects inwritingRepos, local files infiles, and local directories infolders. - No duplicate urls or paths within a project.
{
"projectSlug": "ProjectAlpha",
"projectName": "Project Alpha",
"attributes": ["coding", "learning"],
"priority": 8,
"status": "active",
"p00InitiationDate": "2026-01-15",
"startDate": "2025-09-01",
"lastWorkDate": "2026-06-20",
"note": "Primary coding project; notebooks plus a small dataset.",
"emoji": "π§ͺ",
"folders": [
"C:\\Users\\you\\Projects\\ProjectAlpha",
"C:\\Users\\you\\Projects\\ProjectAlpha\\notebooks",
"C:\\Users\\you\\Projects\\ProjectAlpha\\data"
],
"urls": [
"https://example.com/status-dashboard"
],
"codeRepos": [
"https://github.com/you/project-alpha"
],
"writingRepos": [
"https://www.overleaf.com/project/exampleProjectId"
],
"files": [
"C:\\Users\\you\\Projects\\ProjectAlpha\\Launch.bat"
],
"related": ["ProjectBeta"],
"p00": "C:\\Users\\you\\Projects\\ProjectAlpha\\P00_ProjectAlpha.md"
}The header has the logo, the global finder, the attribute filter chips, a Hide parked toggle, and a Reset button. Each chip is colored from --attr-<name> in style.css. Click a chip to filter by that attribute. Click Reset to clear chips and search, and re-check every per-item checkbox.
Below the header, cards group by primary attribute. The highest-priority group lands on top, cards inside each group are ordered by priority descending. Projects with priority below 2 (or unset) drop into a single Low priority / parked band at the bottom regardless of attribute. Dim-flagged statuses render dimmed.
A card shows:
- Project name in the title row.
- A row of attribute tags, colored per attribute.
- A meta row of
projectSlug | priority | status. - The three dates, with
lastWorkDatebrighter and bolder than the other two. - Two buttons: Kickoff (opens the items currently checked; with everything checked, opens folders as Explorer tabs followed by urls and files) and Open P00 (opens the P00 file in VSCode, Ctrl plus click opens the P00 folder in Explorer).
- Three sections (Folders, URLs, Files), each item with a checkbox (all checked by default) and a clickable label. A single folder or file goes through
kickoff.ps1. A single web url opens directly in a new browser tab. - A
relatedline of clickable slugs that jump to the related card.
MIT. See LICENSE.

