Agents forget. Your files don't. nt is a terminal-first task & 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.
Quickstart · Why nt · AI memory · The three faces · vs. alternatives · Docs
Most 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 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.
# Install the latest release binary — no Go, no checkout (→ ~/.local/bin)
curl -fsSL https://raw.githubusercontent.com/navbytes/nt/main/install.sh | bashnt add "fix token refresh race" --pri high --due today --tag auth # capture a task
nt note "Chose flock over SQLite" --kind decision # capture a note
nt # open the TUI (just run it)
nt ready # what should I do next?
nt index # the KB catalog an AI reads back
nt web # browse it all in your browserThat's it — you're up. nt help lists every command; more install options below.
- 📄 It's just files. todo.txt + Markdown in one folder. Open them in any editor,
grepthem,git initthem. No lock-in, no proprietary database, nothing to export. - 🤖 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)
- 🖥️ 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.
- 📦 One static binary. Pure Go, no CGo, no system dependencies, no runtime.
curl | bashand go. Works fully offline. - 🔗 Wikilinks & 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. - 🧩 Obsidian-compatible. Notes are plain
.md+ frontmatter, so you can point an Obsidian vault at thenotes/folder and use it as your GUI whilentowns tasks, the CLI/TUI, and the AI loop. - ⛓️ 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). - 🗓️ A planner, not just a list.
nt agendagroups your work by date,nt reviewis a weekly triage (overdue · stale · undated · stuck projects · faded notes past their half-life), and daily notes (nt journal) give you a dated log your agents can append to. - 🔒 Safe by construction. Every write goes through one locking, atomic, ULID-keyed engine with transactional undo/redo — so a concurrent
nt addfrom an AI session is never clobbered. Lossless todo.txt round-trip is enforced by test. - 🌿 Git-native.
nt git-initsets upmerge=unionso branches don't conflict on every add;nt doctorreconciles after a merge.nt syncwraps the whole loop (commit → pull → reconcile → push) for a team sharing one store over a git remote — no hosted service.
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.
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:
- PostToolUse hooks —
nt hookmirrors Claude Code'sTodoWritelist into your store automatically (idempotent, taggedsrc:claude), and on a failed Bash command surfaces any matching recorded lesson back to Claude (block+reason). Wire both matchers once in~/.claude/settings.json— see docs/claude-integration.md. - MCP server —
nt mcpexposes 22 typed tools (nt_index,nt_recall,nt_add,nt_note,nt_note_edit,nt_get,nt_status,nt_search,nt_update,nt_doctor,nt_distill,nt_mindmap, …) with strict unknown-parameter rejection, over stdio. Register it with one command:nt mcp install # add nt to Claude Code / Claude Desktop (absolute path, idempotent) nt mcp install --client opencode # …or OpenCode (~/.config/opencode/opencode.json) nt opencode install # …or the FULL OpenCode integration: MCP + memory plugin + # skill + /learn + /recall + /distill + AGENTS.md + seeded rules/memory nt pi install # …or the FULL Pi integration: an extension that bridges nt's # tools (Pi has no MCP) + skill + /learn + /recall + /distill + AGENTS.md
- Claude Code plugin marketplace — this repo is a self-hosted marketplace (
.claude-plugin/):/plugin marketplace add navbytes/ntthen/plugin install nt@navbytes-ntinstalls the skill + registers the MCP server in one step, no separatent mcp installneeded. - Context7 — nt's docs are indexed for the Context7 MCP (
context7.jsonat repo root), so any Context7-connected agent can pull them in withuse context7/ resolvingnavbytes/nt, no extra setup here. - The
/ntskill + read-back loop — teach the agent to capture as it works and load prior context (nt index, then fetch on demand) when it resumes. - Learn from past mistakes — record a footgun or dead-end as a lesson (
nt note … --lesson), thennt recall "<what you're about to do>"surfaces relevant notes with lessons flagged ⚑ first — paraphrase-aware (stemming + an extensible synonym vocabulary), with a precision floor for multi-concept queries and a per-hit confidence tier (read the tier — a weak hit is a signal to doubt, and an empty result usually means nothing is recorded), plus a soft same-project boost (NT_WORKSTREAM/--project;nonedisables). See docs/claude-integration.md. - Parallel agents, one store — set
NT_WORKSTREAMper agent to isolate in-flight tasks (list/ready/log/review/indexscope to it;"*"widens) while notes stay shared;undo/redorefuse another workstream's change unless--force. - Curate, don't hoard —
nt doctorflags near-duplicates, orphans, and an oversized pinned tier;nt supersede/nt archiveretire stale notes;nt gcsweeps superseded stubs and stranded task-detail notes to.trash/(dry-run by default). - Memory that ages honestly — give a volatile fact a
--half-life 90dand it fades in recall and the index as it goes un-reconfirmed (down-ranked and flagged~faded, never hidden);nt touchsays "still true" and resets the clock, andnt reviewlists the most-faded notes for triage.--if-exists returnsteers agents to edit the topic's canonical note instead of creating a duplicate,nt decidekeeps a dated## Decisionshistory of why a note changed (so a superseded approach isn't re-proposed), andnt historyreads the full per-edit story back from git. Inspired by how Kimi K3's delta-attention memory learns — design in docs/spec-memory-dynamics.md.
Beyond Claude Code, any MCP-speaking agent can drive the same store — including OpenCode, whose rules / knowledge-base / memory layers map cleanly onto nt. Full mapping & phased plan → docs/opencode-integration.md. Pi has no built-in MCP, so nt pi install ships an in-process extension that bridges nt's tools in and injects rules + memory live → integrations/pi/README.md. The ranked backlog for where the integration layer goes next (researched by a multi-agent team against market alternatives) → docs/memory-integration-roadmap.md.
# During a session (the hook does this for you, or call it directly):
nt add "fix token refresh race" --source claude --tag auth
nt note "Single-flight the token refresh" --lesson --description "two parallel refresh calls double-spend the refresh token" --source claude # record a gotcha
# A week and three sessions later — read it straight back:
nt index --json # tiered catalog: pinned rules/memory/ref + recent stubs + folder counts (--all = every stub); then nt show <id>
nt recall "adding concurrent token refresh" # surfaces the lesson before you hit it againWhy plain files beat a vector DB for this: the model reads the real note, not an embedding's best guess (reliability); it loads a cheap index and opens only what's relevant (token cost); and you can git diff and roll back its memory (auditability). It's the Karpathy "LLM wiki" pattern — index-first progressive disclosure, with tasks on top. Full setup & walkthrough → docs/claude-integration.md.
A 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 — notes, tasks, 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.
| Notes | Logbook |
|---|---|
 |
 |
A 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.
It'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.
The Tasks agenda — priority chips, relative due dates, the
claude badge on agent-captured work, a quick filter, and your saved views in the sidebar.
The
/graph view — your notes and links as a constellation.
nt add "write migration" --blocks task:5 --project api # task:5 hides until this is done
nt ready --json # open, unblocked work by urgency (agent entry point)
nt agenda --days 7 # Overdue / Today / Upcoming, grouped
nt add "weekly review" --due monday --recur weekly # completing spawns the next occurrence
nt search "auth" --tag backend # ripgrep + title match, tag-filtered
nt links jwt-expiry # forward links + backlinks for a note
nt log --since 2026-01-01 --json # the Logbook, machine-readableFull command cheatsheet
nt add "title" --pri high --due "fri 5pm" --est 2h --tag t --project p # capture a task (a = alias)
nt add "title" --blocked-by <id> # dependency edge (--blocks none clears)
nt note "title" --folder work --field status=stable # capture a note (folders + frontmatter)
nt note "title" --kind lesson|decision|ref|rule|memory --description "…" # taxonomy + the one-line summary index shows
nt journal # open today's daily note (j = alias)
nt # TUI nt list [--status|--tag|--sort urgency|--tree|--all|--json]
nt view <name> # saved views nt view save <name> [list flags] nt view list / rm <name>
nt ready / today / agenda # what's next nt done <id|task:N> nt update <id> --status doing
nt review [--stale N] # weekly triage nt start <id> … nt stop <id> (time tracking → spent:)
nt search <q> [--tag…] # find
nt recall "<context>" [--lessons-only] # lessons flagged ⚑ first, paraphrase-aware (bare --lessons-only = the whole lesson book)
nt tags # tag vocab nt tag <note…> +ref -inbox
nt links <id> [--orphans] # graph nt log [--since|--days N]
nt index [--all|--tag|--folder|--json] # tiered on large stores; --all = flat, scoped views are complete
nt skip <id> # recurring: next occurrence nt mv <note> <dest> (rewrites [[links]])
nt edit <id|task:N> # safe $EDITOR round-trip nt rm <note> [--force] (→ .trash/)
nt web [--port N] # browser app, editing enabled (--detach to run in the background; --status / --stop)
nt supersede <old> --by <new> nt gc [--yes] # curation: retire, then reclaim (dry-run default)
nt export --tag rule # compile the standing rules layer into CLAUDE.md/AGENTS.md
nt import backup.json | vault/ # export's inverse: round-trip a JSON backup or bulk-load an Obsidian vault
nt undo / redo # workstream-safe: refuses another agent's change unless --force
nt mcp [install] nt hook
nt git-init && nt doctor # version-control the store + reconcile merges (+ dependency checks)
nt sync [--no-push] # team memory over git: commit, pull, doctor-reconcile, push
nt path # print $NT_DIR nt archive nt --version nt help
# Optional defaults live in $NT_DIR/config.toml ([defaults]/[web]/[tui]).| nt | todo.txt CLIs | Taskwarrior | Obsidian | mem0 / MCP memory | |
|---|---|---|---|---|---|
| Storage you own (plain files) | ✅ .txt+.md |
✅ .txt |
➖ own DB | ✅ .md |
❌ vector DB |
| Tasks and notes, unified | ✅ | tasks only | tasks only | notes only | — |
| Agent-readable with no service | ✅ (or MCP if you want) | ✅ | ➖ | ➖ plugin | ❌ needs the service |
| Single static binary, no cloud | ✅ | varies | ✅ | ❌ app | ❌ service |
Works with grep/git/editor |
✅ | ✅ | ➖ | ✅ | ❌ |
| CLI + TUI + web in one | ✅ | ❌ | ➖ | GUI | ❌ |
| Built for AI session memory | ✅ | ❌ | ❌ | ➖ | ✅ |
Honest 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.
One global store at $NT_DIR (default ~/.local/share/nt):
~/.local/share/nt/
├── tasks.txt # todo.txt format, one line per task
├── done.txt # archived completed tasks
├── undo.jsonl # undo transaction journal
└── notes/*.md # Markdown notes with YAML frontmatter
A task line is just todo.txt with a few conventions:
(A) fix auth bug +api @backend due:2026-06-05 [[jwt-expiry]] src:claude id:01JZ8RT3
(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.
Notes ↔ Obsidian (use Obsidian as the GUI, nt as the brain)
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.
Rename/move is nt-native: nt mv <note> <new> (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.
- Lossless round-trip — an unmodified
tasks.txtline is re-emitted byte-for-byte, preserving unknown tokens from other todo.txt tools (enforced by test). - 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).
- Transactional undo/redo — each change journals before-images keyed by ULID;
nt undoreverses them andnt's redo re-applies them. - Dependency integrity —
nt doctordetects dependency cycles (so ablocks:deadlock never silently hides tasks) and stale/dangling links, and reconciles duplicate ids after a git merge.
- You want a managed cloud app with shared boards, assignees, and dashboards → Notion / Linear / Things.
- You never touch a terminal and want zero file management → a GUI-first app will feel better.
- You need a native mobile app from an app store →
nt webis an installable PWA, but it's not a packaged native app.
# Curl — latest release binary to ~/.local/bin (no Go needed)
curl -fsSL https://raw.githubusercontent.com/navbytes/nt/main/install.sh | bash
# Homebrew (macOS/Linux)
brew install navbytes/tap/nt
# mise (not yet in the official registry — installs straight from GitHub releases)
mise use -g github:navbytes/nt
# Go — install the latest tagged release
go install github.com/navbytes/nt@latest
# From source
git clone https://github.com/navbytes/nt && cd nt && make installSingle static binary for Linux, macOS & Windows (amd64/arm64). Releases are automated by GoReleaser on a vX.Y.Z tag (RELEASING.md).
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.
Build from source / develop
go build -o nt . # Go 1.25+
./nt # launch the TUI
make test # run the Go test suite
make web-build # rebuild the embedded web app (needs Node 22+)
vhs docs/demo.tape # (optional) render an animated demo → docs/demo.gifThe web app's built bundle is committed and embedded with //go:embed, so go build / go install need no Node toolchain. See SPEC.md for the full design.
Issues and PRs welcome. go test ./... must pass; run make test. The architecture and design rationale live in SPEC.md; AI-integration details in docs/.
MIT © navbytes