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, track-lsp exposes interactive editor navigation, and track web serves a local workspace.

In Neovim, :Track markdown opens the saved current Markdown file in the read-only external viewer, starting or reusing the local workspace without importing a note. Its containing folder supplies relative Markdown links and local images; save and repeat the command to refresh.

Documentation: https://ttak0422.github.io/track/ — syntax, CLI reference, web workspace, tasks, queries, and visualization.

Layout

cmd/track/main.go        # thin CLI entry point
cmd/track-lsp/           # LSP server 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, ...)
web/                     # web workspace frontend
desktop/                 # macOS AppKit/WKWebView shell
nix/apps/                # `nix run .#test-nvim` launcher
flake.nix                # Go CLI + Vim plugin packaging

For the macOS app, see desktop build and verification. The former SwiftUI shell is retired; make desktop-app builds the current app.

Agent skills

Skills that let a coding agent drive this CLI live in ttak0422/track-lab as the note plugin.

What stays here is the contract they build on: normal commands print one compact JSON object and errors are {"error":...} with exit code 1. The deliberate exceptions are version (plain text), web (a listening URL on stderr, then no JSON while the server runs), export without --out (Markdown), and gen peek (Markdown); export --out is JSON. Help prints prose usage, while the tool-neutral workflow reference is docs/spec/agent-workflows.md.

Data safety

Note bodies are plain .md files, but their metadata (title, tags, created date, Babel results) lives in sidecar files under .track/notes/. The .track/ directory is authoritative and cannot be fully rebuilt from the note bodies, so back it up and keep it in version control, just as you would .git. The SQLite index is a disposable cache outside the vault. track reindex --full resets the cache schema in place and rebuilds it from note files and sidecar metadata, without unlinking databases held open by other Track processes. See docs/spec/storage.md for details.

For recovery copies, track backup --out /independent-backup/vault.tar.gz archives canonical vault files with a versioned checksum manifest. Keep the output on independent storage; finish synchronization and pause editing before the backup.

Platform support

The Nix flake supports Linux (x86_64-linux, aarch64-linux) and macOS on Apple Silicon (aarch64-darwin). Intel macOS (x86_64-darwin) is no longer supported.

Development

nix develop              # Go on PATH
go test ./...            # run the engine + CLI tests
go build ./cmd/track ./cmd/track-lsp  # build the Go binaries

nix build .#track-cli    # build the Go CLI and LSP binaries
nix build .#track        # build the Neovim plugin (references the CLI)
nix run .#test-nvim      # launch Neovim; the vault defaults to $HOME/track (TRACK_VAULT/config.yml override)

make site                # build the static help site from docs/help

The Nix-built Neovim plugin embeds the store paths of the matching track and track-lsp binaries, so Nix users do not need to add them to $PATH manually.

Design decisions live in docs/adr/, specifications in docs/spec/.

License

MIT