track

[!CAUTION] Please note that this is currently in an experimental phase. Destructive changes may be apply.

A journal + Zettelkasten note tool: a Go CLI/LSP engine with a SQLite index, plus a thin Neovim frontend.

The Go engine is the source of truth — it parses notes, maintains the index, and resolves links. The CLI exposes scriptable commands, and track-lsp exposes interactive editor navigation. The engine lives in reusable internal/track/* packages so a future LSP server can reuse it directly.

Concepts

• Notes are markdown files named note/{id}.md in a vault directory. Regular note ids are sortable time-derived ids: Unix seconds * 1000 + same-second sequence.

• Metadata: note metadata is stored outside the markdown file, under .track/notes/{id}.yaml. The sidecar title is the authoritative note title and link keyword; body H1 headings are ordinary Markdown content. The file is versioned so future metadata shape changes can be handled explicitly:

  # リンク
  
  本文 ...
  

  version: 1
  title: リンク
  tags: [zettel]
  created: 2026-05-24
  

  generated-by-ai is reserved as a provenance tag for AI-agent-generated drafts. It is still included in normal search; track treats it as a light ranking/display signal rather than a quality label.

• Links are explicit, written [[title]], with optional Obsidian-style [[target|display]] aliases. A heading anchor jumps inside a note: [[note#foo]], [[note##bar]], … where the number of # is the Markdown heading level and the first matching heading wins. Resolved links are highlighted and followable; links to notes that don't exist yet are flagged with a warning diagnostic. Completion offers titles as you type inside [[, then headings once you type #. Exact-match resolution works for Japanese without word boundaries. See docs/spec/links.md.

• Journal: each day maps to a stable yyyyMMdd note, so opening "today" is idempotent. Journal notes are stored as journal/<yyyyMMdd>.md.

Layout

cmd/track/main.go        # thin CLI entry point
internal/cli/            # argument routing -> engine -> JSON
internal/track/          # engine (config, note metadata, store, index, link, lsp)
lua/track/               # Neovim frontend (config, client, lsp, follow, ...)
nix/apps/                # `nix run .#test-nvim` launcher
flake.nix                # Go CLI + Vim plugin packaging

CLI

All commands except version print a single line of JSON; errors are {"error":...} with exit code 1. The vault is read from the platform user config file (config.yml under the track config directory) and defaults to $HOME/track when unset (ADR 0015); precedence is TRACK_VAULT > config vault_dir > $HOME/track. Environment variables are intended for tests and one-off overrides. The rebuildable index db defaults to the user cache directory under track/. The Neovim frontend sets TRACK_CACHE_DIR to vim.fn.stdpath("cache") .. "/track".

vault_dir: ~/track

Typical config locations are ~/.config/track/config.yml on XDG-style systems and ~/Library/Application Support/track/config.yml on macOS.