{"id":51176982,"url":"https://github.com/navbytes/nt","last_synced_at":"2026-06-27T04:31:20.857Z","repository":{"id":363113605,"uuid":"1261343434","full_name":"navbytes/nt","owner":"navbytes","description":"A terminal task \u0026 note manager that stores everything as **plain files** — todo.txt tasks + markdown notes — so your editor, `grep`, `git`, and AI coding agents can all read and write it directly. Built to be the durable memory layer for AI sessions: action items an agent creates survive the session in text the next agent can read back.","archived":false,"fork":false,"pushed_at":"2026-06-26T05:08:51.000Z","size":48720,"stargazers_count":6,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-26T05:09:24.856Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/navbytes.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"docs/ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-06T15:01:48.000Z","updated_at":"2026-06-26T04:52:33.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/navbytes/nt","commit_stats":null,"previous_names":["navbytes/nt"],"tags_count":33,"template":false,"template_full_name":null,"purl":"pkg:github/navbytes/nt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbytes%2Fnt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbytes%2Fnt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbytes%2Fnt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbytes%2Fnt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/navbytes","download_url":"https://codeload.github.com/navbytes/nt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/navbytes%2Fnt/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34841990,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-27T02:00:06.362Z","response_time":126,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-06-27T04:31:20.109Z","updated_at":"2026-06-27T04:31:20.851Z","avatar_url":"https://github.com/navbytes.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# nt\n\n### Tasks \u0026 notes as plain text — durable memory your AI agents can't lose.\n\n**Agents forget. Your files don't.** `nt` is a terminal-first task \u0026 note manager that keeps everything as plain files — todo.txt tasks and Markdown notes — so your editor, `grep`, `git`, and your AI coding agents all read and write the same source of truth. One static binary. No database. No cloud.\n\n[![CI](https://github.com/navbytes/nt/actions/workflows/ci.yml/badge.svg)](https://github.com/navbytes/nt/actions/workflows/ci.yml)\n[![Release](https://img.shields.io/github/v/release/navbytes/nt?sort=semver)](https://github.com/navbytes/nt/releases/latest)\n[![Go Report Card](https://goreportcard.com/badge/github.com/navbytes/nt)](https://goreportcard.com/report/github.com/navbytes/nt)\n[![Go version](https://img.shields.io/github/go-mod/go-version/navbytes/nt)](go.mod)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n\n[Quickstart](#-quickstart) · [Why nt](#-why-youll-like-it) · [AI memory](#-durable-memory-for-your-ai-agents) · [The three faces](#-three-faces-one-store) · [vs. alternatives](#-how-it-compares) · [Docs](SPEC.md)\n\n\u003cimg src=\"docs/demo.gif\" alt=\"nt in action — add a task, see what's ready, recall it back, and the TUI\" width=\"900\"\u003e\n\n\u003c/div\u003e\n\n---\n\nMost tools make you choose: a slick app that locks your data in a cloud silo, or a pile of text files with no structure. `nt` refuses the trade-off. Your tasks live in `tasks.txt` (the [todo.txt](https://github.com/todotxt/todo.txt) format). Your notes live as `.md` files with YAML frontmatter and `[[wikilinks]]`. On top of those plain files, `nt` gives you a fast CLI, a gorgeous terminal UI, an embedded web app, and a first-class memory loop for AI coding sessions — without ever changing the files underneath. Point Obsidian at the same folder, `grep` it, `git` it, or let Claude read it back next week. It's all just text you own.\n\n## 🚀 Quickstart\n\n```bash\n# Install the latest release binary — no Go, no checkout (→ ~/.local/bin)\ncurl -fsSL https://raw.githubusercontent.com/navbytes/nt/main/install.sh | bash\n```\n\n```bash\nnt add \"fix token refresh race\" --pri high --due today --tag auth   # capture a task\nnt note \"Chose flock over SQLite\" --folder decisions                # capture a note\nnt                                                                  # open the TUI (just run it)\nnt ready                                                            # what should I do next?\nnt recall --source claude                                          # read back what an AI captured\nnt web                                                              # browse it all in your browser\n```\n\nThat's it — you're up. `nt help` lists every command; [more install options below](#-install).\n\n## ✨ Why you'll like it\n\n- **📄 It's just files.** todo.txt + Markdown in one folder. Open them in any editor, `grep` them, `git init` them. No lock-in, no proprietary database, nothing to export.\n- **🤖 Built for AI memory.** The action items and notes an agent writes today survive as plain text the next agent — or the next *you* — reads back tomorrow. ([see below](#-durable-memory-for-your-ai-agents))\n- **🖥️ Three UIs, one store.** A scriptable **CLI**, a live **terminal UI**, and an embedded **web app** — all over the exact same files, always in sync.\n- **📦 One static binary.** Pure Go, no CGo, no system dependencies, no runtime. `curl | bash` and go. Works fully offline.\n- **🔗 Wikilinks \u0026 backlinks.** `[[link]]` any task or note to any other; \"linked from\" is computed on demand by scanning files — no index to corrupt. Rename a note and every link follows.\n- **🧩 Obsidian-compatible.** Notes are plain `.md` + frontmatter, so you can point an Obsidian vault at the `notes/` folder and use it as your GUI while `nt` owns tasks, the CLI/TUI, and the AI loop.\n- **⛓️ Real task semantics.** Full A–Z priorities, due dates (with optional time-of-day), start/defer dates, projects, tags, recurrence, sub-tasks and dependencies (`blocks:`/`parent:`) with **cycle detection**, time **estimates + start/stop tracking**, and typed provenance (`discovered-from`).\n- **🗓️ A planner, not just a list.** `nt today` / `nt agenda` group your work by date, `nt review` is a weekly triage (overdue · stale · undated · stuck projects), and **daily notes** (`nt journal`) give you a dated log your agents can append to.\n- **🔒 Safe by construction.** Every write goes through one locking, atomic, ULID-keyed engine with transactional **undo/redo** — so a concurrent `nt add` from an AI session is never clobbered. Lossless todo.txt round-trip is enforced by test.\n- **🌿 Git-native.** `nt git-init` sets up `merge=union` so branches don't conflict on every add; `nt doctor` reconciles after a merge.\n\n## 🧠 Durable memory for your AI agents\n\n\u003e Your AI assistant just created three action items — then the session ended and they vanished. Next session it has no idea what it was doing.\n\n`nt` is the place that memory lives. Because the store is plain text, an agent doesn't need a special database or a running service to remember — it just reads and writes files. Three ways to wire it up:\n\n- **PostToolUse hook** — `nt hook` mirrors Claude Code's `TodoWrite` list into your store automatically (idempotent, tagged `src:claude`). Wire it once in `~/.claude/settings.json`.\n- **MCP server** — `nt mcp` exposes typed tools (`nt_ready`, `nt_add`, `nt_recall`, `nt_search`, `nt_note`, `nt_view`, …) over stdio. Register it with one command:\n  ```bash\n  nt mcp install              # add nt to Claude Code / Claude Desktop (absolute path, idempotent)\n  ```\n- **The `/nt` skill + recall loop** — teach the agent to capture as it works and `nt recall` prior context when it resumes.\n\n```bash\n# During a session (the hook does this for you, or call it directly):\nnt add \"fix token refresh race\" --source claude --tag auth\n# A week and three sessions later — read it straight back:\nnt recall --source claude --json\n```\n\n**Why plain files beat a vector DB for this:** the model reads the *real* note, not an embedding's best guess (reliability); you open only what's relevant (token cost); and you can `git diff` and roll back its memory (auditability). It's the [Karpathy \"LLM wiki\" pattern](https://venturebeat.com/data/karpathy-shares-llm-knowledge-base-architecture-that-bypasses-rag-with-an), with tasks and a recall loop on top. Full setup \u0026 walkthrough → **[docs/claude-integration.md](docs/claude-integration.md)**.\n\n## 🪟 Three faces, one store\n\n### Terminal UI — just run `nt`\n\nA Bubble Tea TUI that adapts to your terminal width (compact strip → standard list → wide split with a live detail pane) and **live-refreshes** via fsnotify when a CLI call or an AI session writes the store. Three tabs — **tasks**, **notes**, and a **Logbook** of completed work grouped by date — with multi-select bulk ops, search-as-you-type, mouse support, undo/**redo**, and a read-only lock. A **`:` command palette** runs any action by name, **vim motions take counts** (`5j`, `12G`), notes capture inline (no `$EDITOR` bounce), and the whole UI follows your terminal's **light/dark** theme. Press `?` for the full keymap.\n\n| Notes | Logbook |\n|---|---|\n| ![Notes view](docs/screenshots/07-notes-wide.png) | ![Logbook view](docs/screenshots/08-logbook-wide.png) |\n\n### Web app — `nt web`\n\nA fast single-page app (Svelte + TypeScript) **compiled into the binary** — still one static file, still fully offline, no CDN, no external requests. Browse the folder tree, read Markdown with `[[wikilink]]` navigation, **Mermaid diagrams**, and syntax-highlighted code in light/dark Tokyo Night.\n\nIt's built for moving fast: a **⌘K command palette** to jump anywhere, **keyboard go-to chords** (`g t` Today, `g a` Tasks, `g n` Notes… press `?` for the cheat-sheet), **ranked search** with highlighted snippets, a **`/tasks`** planner with an agenda view, a **`/journal`** of daily notes, a clickable **`/graph`** of your links, **`/tags`** and **`/orphans`** browsers, an **activity** feed, an in-note table of contents + backlinks, and a **mobile-friendly** layout you can install as a PWA. Tasks read at a glance — **colour-coded A/B/C priorities**, **relative due dates** (“Today”, “Tomorrow”, “3d ago”), and a quiet badge on the ones your **AI agent** captured — and they act fast too: the quick-add box shows a **live parse preview** of the todo.txt shorthand as you type (`pay rent due:fri !high @home`), `j`/`k` walk the list, `d` **reschedules in one keystroke** (Today / Tomorrow / Next week), and completing or deleting offers a calm **“— Undo” toast** wired to the store’s transactional undo. Your saved **smart views** (`nt view save`) appear in the sidebar and recall the exact same query the CLI runs. A real **CodeMirror editor** — markdown highlighting, `[[`-wikilink and `/`-slash-command autocomplete, live preview, and backlinks while you write — lets you create and edit notes *and* tasks right in the browser (saves are guarded by a per-process CSRF token and an `If-Match` check so nothing gets clobbered). Binds `127.0.0.1` only — your notes are never on the network.\n\n\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/screenshots/web-tasks-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/screenshots/web-tasks-light.png\"\u003e\n  \u003cimg alt=\"nt web — the Tasks agenda: colour-coded priorities, relative due dates, an AI-agent badge, a quick filter, and saved views\" src=\"docs/screenshots/web-tasks-light.png\" width=\"850\"\u003e\n\u003c/picture\u003e\n\u003cbr\u003e\u003cem\u003eThe Tasks agenda — priority chips, relative due dates, the \u003ccode\u003eclaude\u003c/code\u003e badge on agent-captured work, a quick filter, and your saved views in the sidebar.\u003c/em\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/screenshots/web-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/screenshots/web-light.png\"\u003e\n  \u003cimg alt=\"nt web — note viewer with tags, TOC, backlinks, syntax highlighting, and a Mermaid diagram\" src=\"docs/screenshots/web-light.png\" width=\"850\"\u003e\n\u003c/picture\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n\u003cpicture\u003e\n  \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"docs/screenshots/web-graph-dark.png\"\u003e\n  \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"docs/screenshots/web-graph-light.png\"\u003e\n  \u003cimg alt=\"nt web — the /graph view: notes and wikilinks as an interactive constellation\" src=\"docs/screenshots/web-graph-light.png\" width=\"850\"\u003e\n\u003c/picture\u003e\n\u003cbr\u003e\u003cem\u003eThe \u003ccode\u003e/graph\u003c/code\u003e view — your notes and links as a constellation.\u003c/em\u003e\n\u003c/div\u003e\n\n### CLI — scriptable everything\n\n```bash\nnt add \"write migration\" --blocks task:5 --project api   # task:5 hides until this is done\nnt ready --json                                          # open, unblocked work by urgency (agent entry point)\nnt agenda --days 7                                       # Overdue / Today / Upcoming, grouped\nnt add \"weekly review\" --due monday --recur weekly       # completing spawns the next occurrence\nnt search \"auth\" --tag backend                           # ripgrep + title match, tag-filtered\nnt links jwt-expiry                                      # forward links + backlinks for a note\nnt log --since 2026-01-01 --json                         # the Logbook, machine-readable\n```\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eFull command cheatsheet\u003c/b\u003e\u003c/summary\u003e\n\n```bash\nnt add \"title\" --pri high --due \"fri 5pm\" --est 2h --tag t --project p   # capture a task (a = alias)\nnt note \"title\" --folder work --field status=stable         # capture a note (folders + frontmatter)\nnt journal                  # open today's daily note (j = alias)\nnt                          # TUI            nt list [--status|--tag|--sort urgency|--tree|--all|--json]\nnt view \u003cname\u003e              # saved views    nt view save \u003cname\u003e [list flags]   nt view list / rm \u003cname\u003e\nnt ready / today / agenda   # what's next    nt done \u003cid|task:N\u003e     nt update \u003cid\u003e --status doing\nnt review [--stale N]       # weekly triage  nt start \u003cid\u003e … nt stop \u003cid\u003e   (time tracking → spent:)\nnt search \u003cq\u003e [--tag…]      # find           nt tags                 nt tag \u003cnote…\u003e +ref -inbox\nnt links \u003cid\u003e [--orphans]   # graph          nt recall [--source] [--json]   nt log [--since|--days N]\nnt skip \u003cid\u003e                # recurring: next occurrence      nt mv \u003cnote\u003e \u003cdest\u003e   (rewrites [[links]])\nnt edit \u003cid|task:N\u003e         # safe $EDITOR round-trip        nt rm \u003cnote\u003e [--force]   (→ .trash/)\nnt web [--port N]           # browser app, editing enabled (--detach to run in the background; --status / --stop)\nnt undo / \"redo\"   nt mcp [install]   nt hook\nnt git-init \u0026\u0026 nt doctor    # version-control the store + reconcile merges (+ dependency checks)\nnt path                     # print $NT_DIR  nt archive   nt --version   nt help\n# Optional defaults live in $NT_DIR/config.toml ([defaults]/[web]/[tui]).\n```\n\u003c/details\u003e\n\n## 🆚 How it compares\n\n|  | **nt** | todo.txt CLIs | Taskwarrior | Obsidian | mem0 / MCP memory |\n|---|:---:|:---:|:---:|:---:|:---:|\n| Storage you own (plain files) | ✅ `.txt`+`.md` | ✅ `.txt` | ➖ own DB | ✅ `.md` | ❌ vector DB |\n| Tasks **and** notes, unified | ✅ | tasks only | tasks only | notes only | — |\n| Agent-readable with no service | ✅ (or MCP if you want) | ✅ | ➖ | ➖ plugin | ❌ needs the service |\n| Single static binary, no cloud | ✅ | varies | ✅ | ❌ app | ❌ service |\n| Works with `grep`/`git`/editor | ✅ | ✅ | ➖ | ✅ | ❌ |\n| CLI **+** TUI **+** web in one | ✅ | ❌ | ➖ | GUI | ❌ |\n| Built for AI session memory | ✅ | ❌ | ❌ | ➖ | ✅ |\n\nHonest take: if you want a polished cloud app with shared boards and assignees, use Notion or Linear. `nt` is for people who want their data as text they control.\n\n## 🗂️ How your stuff is stored\n\nOne global store at `$NT_DIR` (default `~/.local/share/nt`):\n\n```\n~/.local/share/nt/\n├── tasks.txt     # todo.txt format, one line per task\n├── done.txt      # archived completed tasks\n├── undo.jsonl    # undo transaction journal\n└── notes/*.md    # Markdown notes with YAML frontmatter\n```\n\nA task line is just todo.txt with a few conventions:\n\n```\n(A) fix auth bug +api @backend due:2026-06-05 [[jwt-expiry]] src:claude id:01JZ8RT3\n```\n\n`(A)`–`(Z)` priority · `+project` · `@tag` · `due:` (optionally `…T17:00`) · `t:` start/defer · `rec:` recurrence · `est:`/`spent:` time · `src:` origin · `id:` ULID · `[[target]]` links to any note or task · `parent:`/`blocks:` are typed task links. Unknown `key:value` tokens from other todo.txt tools are preserved byte-for-byte.\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eNotes ↔ Obsidian (use Obsidian as the GUI, nt as the brain)\u003c/b\u003e\u003c/summary\u003e\n\n`nt` has no notes GUI of its own — and doesn't need one. Notes are plain `.md` + YAML frontmatter + `[[wikilinks]]`, so you can **point an Obsidian vault at the `notes/` folder** and use Obsidian as the GUI while `nt` owns tasks, the CLI/TUI, and the AI-memory loop. `nt` reads back what Obsidian writes: nested subfolders, block-list `tags:`/`aliases:`, notes without an H1 (title falls back to the filename), and link variants (`[[folder/note]]`, `[[note#heading]]`, `[[note|alias]]`) resolved by shortest path-suffix — a bare name colliding across folders is flagged ambiguous rather than guessed.\n\nRename/move is **nt-native**: `nt mv \u003cnote\u003e \u003cnew\u003e` (or `r` in the TUI) renames the file and rewrites every `[[link]]` to it across tasks and notes, so links never dangle. It deliberately does **not** route agents through Obsidian's REST-API MCP (slow, token-heavy, whole-vault exposure) — Obsidian stays an optional human GUI, never a dependency in the agent's path.\n\u003c/details\u003e\n\n## 🛡️ What's guaranteed (the hard parts)\n\n- **Lossless round-trip** — an unmodified `tasks.txt` line is re-emitted byte-for-byte, preserving unknown tokens from other todo.txt tools (enforced by test).\n- **No lost updates** — every write locks, re-reads, mutates, and atomically renames through one ULID-keyed engine, so a concurrent AI-session write is never clobbered (concurrency test included).\n- **Transactional undo/redo** — each change journals before-images keyed by ULID; `nt undo` reverses them and `nt`'s redo re-applies them.\n- **Dependency integrity** — `nt doctor` detects dependency **cycles** (so a `blocks:` deadlock never silently hides tasks) and stale/dangling links, and reconciles duplicate ids after a git merge.\n\n## 🙅 When nt is *not* for you\n\n- You want a managed cloud app with shared boards, assignees, and dashboards → Notion / Linear / Things.\n- You never touch a terminal and want zero file management → a GUI-first app will feel better.\n- You need a native mobile app from an app store → `nt web` is an installable PWA, but it's not a packaged native app.\n\n## 📦 Install\n\n```bash\n# Curl — latest release binary to ~/.local/bin (no Go needed)\ncurl -fsSL https://raw.githubusercontent.com/navbytes/nt/main/install.sh | bash\n\n# Go — install the latest tagged release\ngo install github.com/navbytes/nt@latest\n\n# From source\ngit clone https://github.com/navbytes/nt \u0026\u0026 cd nt \u0026\u0026 make install\n```\n\nSingle static binary for Linux \u0026 macOS (amd64/arm64). Releases are automated by GoReleaser on a `vX.Y.Z` tag ([RELEASING.md](RELEASING.md)). Homebrew is planned (`brew install navbytes/tap/nt`).\n\n**Desktop app** — each release also attaches native **`nt-desktop`** bundles (macOS / Linux / Windows): the same web UI in a native window over your local store, editing included, with **no port opened at all** (the webview talks to the Go server in-process). See [desktop/README.md](desktop/README.md).\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cb\u003eBuild from source / develop\u003c/b\u003e\u003c/summary\u003e\n\n```bash\ngo build -o nt .       # Go 1.25+\n./nt                   # launch the TUI\nmake test              # run the Go test suite\nmake web-build         # rebuild the embedded web app (needs Node 22+)\nvhs docs/demo.tape     # (optional) render an animated demo → docs/demo.gif\n```\nThe web app's built bundle is committed and embedded with `//go:embed`, so `go build` / `go install` need no Node toolchain. See **[SPEC.md](SPEC.md)** for the full design.\n\u003c/details\u003e\n\n## 🤝 Contributing\n\nIssues and PRs welcome. `go test ./...` must pass; run `make test`. The architecture and design rationale live in **[SPEC.md](SPEC.md)**; AI-integration details in **[docs/](docs/)**.\n\n## License\n\n[MIT](LICENSE) © navbytes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavbytes%2Fnt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnavbytes%2Fnt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnavbytes%2Fnt/lists"}