NoteFlow
FORMAT CHANGE NOTICE: As of version 0.3.0, the note separator changed from
---to<!-- note -->. If you're upgrading from an older version, please update yournotes.mdaccordingly.
NoteFlow is a lightweight, Markdown-based note-taking application with task management capabilities. It runs locally, stores everything in a single notes.md file per folder, and stays out of your way. One Python package, no cloud, no account.
What's new
0.7.6 — Performance, safety & capability
- Faster checkbox toggles — flipping a task no longer re-renders every note or re-runs MathJax; the active-tasks panel updates from the response.
- Shared MarkdownIt + per-note HTML cache — note rendering reuses a single parser and caches HTML until content changes.
- Atomic
notes.mdsaves — write via a temp file + replace so a crash mid-save cannot truncate your notes. - Localhost by default — server binds to
127.0.0.1; use--host 0.0.0.0only if you intentionally want LAN access (there is no authentication). - Hardened uploads — basename-only filenames, automatic collision renames (
photo-1.png), 50 MiB size cap. - External edit awareness — edits to
notes.mdfrom other tools (ornoteflow append) are picked up via mtime polling while the editor is idle. - Richer AI context — recent N notes, note being edited, editor selection, no-notes mode, plus a char budget so huge journals don't blow the context window.
- Abortable search — in-flight search requests cancel when you keep typing.
- First unit tests —
python -m unittest tests.test_core -v.
0.7.0 — Autosave
- Autosave — notes are automatically saved at a configurable interval (1, 3, or 5 minutes). Works for both new and existing notes — the timer starts as soon as you type in the editor. On by default; toggle and configure in the admin panel. A brief "autosaved" indicator flashes next to the Save button after each save.
0.6.0 — Smart editing & cheat sheet
- Smart Enter — pressing Enter in the editor continues list markers (
-,*,+,1.,- [ ]), preserves indentation, and auto-increments numbered lists. A second Enter on an empty marker clears it. - Cheat sheet modal — press
?(orCtrl+?while editing) to see all keyboard shortcuts, Markdown syntax, task tokens, and sigils in one overlay. - Full-width search bar —
/opens a fixed top bar with up/down arrow navigation, Enter to cycle matches, and an "All folders" toggle for cross-folder search. - Keyboard hints bar — subtle always-visible hints below the editor for
/,?, andCtrl+Enter.
0.5.0 — Image management
- Image lightbox — images in notes render at 50 % width; click to expand full-size.
- Image delete — hover an image to reveal a delete button that removes the file from disk and strips the Markdown reference from
notes.md. - Uploaded files panel — a new "files" side tab lists all uploaded assets with thumbnails, size, and in-use / orphan status for easy cleanup.
0.4.0 — Feature parity with noteflow-go
A major release that backports the feature surface from noteflow-go:
- AI assist slideout — chat your notes via any OpenAI-compatible endpoint (OpenAI, Anthropic-direct, Ollama, LM Studio, LiteLLM, OpenRouter, Groq, Together, etc.). Streaming + automatic non-streaming fallback. Per-folder
ai_history.mdlog. - Cross-folder global tasks — register multiple folders; their tasks aggregate to a global page at
/global-tasks. SQLite-backed with stable task IDs and a 30s background sync. - Planning CLI —
noteflow tasks(filter by priority/due/tag/project, save views, toggle by hash),noteflow append(write a note from stdin or args). - Inline task metadata —
!p1!p2!p3priorities,@YYYY-MM-DDdue dates,#tagtags, rendered as colored chips and filterable from the CLI. +file:snippet sigil —+file:path#10-25in a note expands at save time into a fenced code block with the file's content at those lines.- External archiver autodetect — if
monolithorobeliskis on your PATH, NoteFlow uses it for higher-fidelity+http://archives; otherwise falls back to the built-in BeautifulSoup pipeline. - Right-edge tab UI — four slideout panels (fonts / admin / ai / commits) replace the old hover-to-expand admin menu.
- Per-section font scaling — sliders for notes/tasks/links sections with live previews.
- Local + global search — press
/anywhere to focus search; results jump to matching notes. - Git context — branch + short SHA badge in the directory bar, plus a commits panel showing recent
git log. - Code-region-aware task parsing — checkboxes inside fenced or inline code blocks are no longer mis-parsed as real tasks.
- CLI flags —
--help,--version,--port,--host,--no-browser.
Screenshots
Main view — demo notes, tasks with metadata chips, right-edge tabs
Fonts panel — live previews of per-section scaling
AI assist — chat your notes via any OpenAI-compatible endpoint
Commits panel — recent git history for the active folder
Themes
Features
- 📝 One big Markdown file — all notes stream into a single
notes.md, version-controllable with your code - ✅ Active task tracking — checkboxes in any note surface to a dedicated panel
- 🔖 Inline task metadata —
!p1priorities,@YYYY-MM-DDdue dates,#tagtags, rendered as colored chips - 🌐 Cross-folder global tasks — register multiple project folders, see every open task in one place
- 🤖 AI assist — chat your notes via any OpenAI-compatible endpoint; context modes include all / recent N / editing / selection / none
- 💾 Autosave — automatic periodic save while editing (configurable interval, toggleable in admin)
- ⌨️ Smart Enter — list markers, indentation, and numbered-list continuation while you type
- 📖 Cheat sheet — press
?for a quick-reference overlay of shortcuts, syntax, and sigils - 🔍 Search — full-width search bar with match navigation and cross-folder toggle
- 🖼️ Image management — lightbox preview, hover-to-delete, and an uploaded-files panel with orphan detection
- 🔗 Web archiving — prefix any URL with
+to save a self-contained local copy - 📎 File embed sigil —
+file:path#10-25embeds source code at save time - 🚀 CLI —
noteflow append,noteflow taskswith filters / saved views / JSON output - 💾 Zero database for notes — your note history lives in one portable Markdown file (cross-folder task index uses SQLite for speed); atomic saves protect against mid-write crashes
- 🔒 Privacy first — runs entirely local (binds to localhost by default); AI key never sent to the browser; no cloud or account
- 🎨 Multiple themes — dark-orange, dark-blue, light-blue
- 🔢 Math — MathJax inline (
$...$) and block ($$...$$) - 🖥️ Multiple instances — run NoteFlow in any number of folders concurrently
Installation
pip (all platforms)
pip install noteflow
Homebrew (macOS / Linux)
brew tap Xafloc/noteflow
brew install noteflow-py
The formula is named noteflow-py so it can live alongside noteflow-go (brew install xafloc/noteflow-go/noteflow, which installs as noteflow-go). Both binaries can be installed on the same machine without conflict.
Optional: better-fidelity archiving
monolith produces higher-quality +http:// archives on JS-heavy pages. If installed, NoteFlow uses it automatically; otherwise it falls back to the built-in archiver.
brew install monolith # macOS / Linux
# or: cargo install monolith
# or: download binary from https://github.com/Y2Z/monolith/releases
Quick start
# Run in the current folder
noteflow
# Or point at a specific folder
noteflow /path/to/notes
# Pin port / skip browser / expose on LAN (no auth — use carefully)
noteflow --port 8765 --no-browser
noteflow --host 0.0.0.0 --port 8765
noteflow --help
Your browser opens automatically at http://127.0.0.1:8000 (or the next free port). The server binds to localhost only by default. Use --no-browser to suppress the tab, --port 8765 to pin a port, and --host 0.0.0.0 only if you intentionally want LAN access (there is no authentication).
Daily use
Taking notes
Type in the content area, optionally add a title, hit Ctrl+Enter (or Cmd+Enter on Mac) or click Save Note. Notes save to notes.md in the current folder.
Tasks
Any Markdown checkbox becomes a tracked task:
- [ ] Open task
- [x] Completed task
- [ ] !p1 @2026-06-15 #urgent Priority 1, due date, and tag tokens
The inline metadata tokens (!p1 / !p2 / !p3, @YYYY-MM-DD, #tag) render as colored chips and are filterable from the CLI. Checkboxes inside fenced code blocks (```) or inline backticks aren't parsed as real tasks — write task syntax in documentation without polluting your active-tasks list.
Cross-folder global tasks
Click global tasks → below the active-tasks box (or visit /global-tasks) to see every open task across every registered folder. Add a new folder from that page; NoteFlow rescans them every 30 seconds.
Web archiving — the +http:// sigil
Prefix any URL with + and NoteFlow archives the page locally on save:
Saw this technique today: +https://example.com/some-article
The line is replaced with a markdown link to a self-contained HTML archive in assets/sites/. Useful for citation snapshots, reference material that might rot, and reading offline.
Code embedding — the +file: sigil
The save flow lives at +file:noteflow/noteflow.py#883-900
On save, the sigil expands into a fenced code block with the file's lines 883–900 and a language hint detected from the extension. Variants:
+file:path— entire file+file:path#10— just line 10+file:path#10-25— inclusive range
Path resolution is sandboxed to the project folder; ../escape attempts and absolute paths are refused.
AI assist
Click the ai tab on the right edge → Settings. Fill in:
- Endpoint — any OpenAI-compatible
/v1/chat/completionsURL, e.g.:- OpenAI:
https://api.openai.com/v1/chat/completions - Anthropic native:
https://api.anthropic.com/v1/messages(auto-detected) - Ollama local:
http://localhost:11434/v1/chat/completions - LM Studio local:
http://localhost:1234/v1/chat/completions
- OpenAI:
- API key — stored in
~/.config/noteflow-py/noteflow.json(or the macOS equivalent). Never sent to the browser. - Model — e.g.
gpt-4o-mini,claude-sonnet-4-5,llama3.2. - Default context — how much of
notes.mdto include by default (all notes, recent N notes, top N lines, or none).
Per-question context in the chat pane can further narrow to:
| Mode | What the model sees |
|---|---|
| all notes | Entire notes.md (soft-capped by a char budget) |
| recent N notes | Newest N note blocks |
| note being edited | The note currently open in the editor |
| editor selection | Highlighted text in the note editor (or the whole buffer if nothing is selected) |
| top N lines | First N lines of the file (newest content is prepended) |
| no notes context | General knowledge only |
The AI sees this folder's notes as a system prompt, plus your conversation. Click Save to history on any answer to keep it in ai_history.md.
Keyboard shortcuts
Ctrl+Enter/Cmd+Enter— save the current noteEnter— smart continuation: repeats list markers (-,*,+,1.,- [ ]), preserves indentation, auto-increments numbered lists/— open the full-width search bar (up/down to navigate, Enter to cycle)?— open the cheat sheet (Markdown syntax, shortcuts, sigils)Esc— close the active side panel, search bar, or cheat sheet
CLI
noteflow append --title "from cli" "Some body text"
echo "- [ ] !p1 #release ship 0.4.0" | noteflow append
noteflow tasks # human-readable table of open tasks
noteflow tasks --status # one-liner for shell prompts
noteflow tasks --priority 1 # urgent only
noteflow tasks --due today
noteflow tasks --tag release --json
noteflow tasks --toggle <hash> # flip a task by task_hash prefix
noteflow tasks --priority 1 --save-view urgent
noteflow tasks --view urgent # apply a saved filter
See noteflow --help, noteflow tasks --help, and noteflow append --help for the full surface.
File structure
Per folder you point NoteFlow at:
your-folder/
├── notes.md # your notes (the source of truth)
├── ai_history.md # saved AI conversations (per-folder)
└── assets/
├── images/ # drag-and-dropped images
├── files/ # drag-and-dropped files
└── sites/ # +http archives + sidecar .tags metadata
Per user (shared across all folders):
~/.config/noteflow-py/ # Linux; on macOS: ~/Library/Application Support/noteflow-py/
├── noteflow.json # theme, font scales, autosave, AI config (key, endpoint, model)
├── tasks.db # SQLite cache for cross-folder global tasks
└── task_views.json # saved CLI filter combinations
The noteflow-py dir name avoids collision with noteflow-go if both are installed.
Requirements
- Python 3.9+
- Dependencies installed automatically by pip:
fastapi,uvicorn,markdown-it-py,mdit-py-plugins,python-multipart,pydantic,requests,beautifulsoup4,platformdirs,psutil - Optional:
monolithorobeliskon PATH for higher-fidelity web archiving
License
This project is licensed under the GNU General Public License v3.0 — see the LICENSE file for details. In short:
- You can freely use, modify, and distribute this software
- Modifications and derivative works must also be licensed under GPL-3.0
- Source code must be made available when distributing the software
- Changes must be documented
For more, see the full license text.
Metadata
Release files for noteflow 0.7.7
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| noteflow-0.7.7.tar.gz | 2.3 MB | Without provenance | Details for noteflow-0.7.7.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| noteflow-0.7.7-py3-none-any.whl | Python 3 | none | any | Details for noteflow-0.7.7-py3-none-any.whl |
Total release size: 3.0 MB
Release files / noteflow-0.7.7.tar.gz
| Download URL | noteflow-0.7.7.tar.gz |
|---|---|
| Size | 2.3 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5a371e4d68320fa932be7d19f5bab3c8ad3b3ea3025a50224a41533c2b50b4fb
|
|
BLAKE2b-256 checksum How to use checksums |
1e1418b0e85af092b2a68c74cae9c849f63bae402c6473c18004080926723351
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.8
|
Release files / noteflow-0.7.7-py3-none-any.whl
| Download URL | noteflow-0.7.7-py3-none-any.whl |
|---|---|
| Size | 765.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
717e564f9d6dce4e746dadaca4d9cbf402033f03c8d3f9d03dff4aecf5a05e95
|
|
BLAKE2b-256 checksum How to use checksums |
79588f3437cb54aedd4d8d38d571c20454d306a8c22a49befaa3a0a4044b06a1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.11.8
|
Security for noteflow 0.7.7
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.