agent-note-tracker

module
v1.10.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 9, 2026 License: MIT

README

ant — Agent Notebook Tool

Status: work-in-progress (v0.x). The CLI and the on-disk schema are both still moving. Pin a tagged version if you're going to depend on it.

ant is a small local notebook for the why of a project. The design decisions, the alternatives you tried and binned, the awkward pivots, the bit of context that vanishes the moment an issue gets closed.

It's the sibling of ait. Where ait keeps track of the open work — issues, dependencies, what's ready to pick up next — ant keeps the paper trail of how you got here.

$ ant add --kind adr --title "Choose sqlite" --issue ait-AbCdE.2 \
          --body "modernc/sqlite over CGO bindings — pure-Go cross-compiles cleanly"

$ ant recent
[
  {
    "id": "ant-AkRXV",
    "kind": "adr",
    "title": "Choose sqlite",
    "issue_id": "ait-AbCdE.2",
    "created_at": "2026-05-01T18:22:22Z",
    "snippet": "modernc/sqlite over CGO bindings — pure-Go cross-compiles cleanly"
  }
]

Why it exists

ait flush --summary leaves a tiny breadcrumb when you clear issues out. That's fine in the moment, but it's not much help when you come back to a project six months later wondering why on earth you picked this library, or why a refactor went sideways, or why you abandoned an approach that sounds perfectly reasonable in hindsight.

I tried a free-form NOTEBOOK.md for a while. It works, right up until it doesn't — by the time the notebook actually matters it's thousands of lines long, and asking an agent to wade through the lot is just noise.

ant is the lazy fix for that. Adding an entry is a one-liner, and when the agent needs context later it can pull the handful of entries that actually relate to whatever it's working on, rather than re-reading everything you've ever written down.

Install

Build from source — Go 1.25+:

go install github.com/ohnotnow/agent-note-tracker/cmd/ant@latest      # once tagged
# or, in this checkout:
go build -o ant ./cmd/ant

Quick start

ant init                             # creates .ant/ant.db at the git root
ant init --prefix myproj             # override the inferred prefix

ant add --body "rationale"           # capture
ant add --body @path/to/file.md      # capture from file
echo "rationale" | ant add           # capture from stdin
ant add --human --title "Why X"      # write the body in $EDITOR

ant recent                           # 5 most recent, with snippets
ant search "auth refactor"           # multi-term AND across title + body
ant for ait-AbCdE.2                  # entries linked to a specific issue
ant show ant-AkRXV                   # full detail for one entry
ant list --kind adr --human          # filtered table view

ant edit ant-AkRXV --title "New"     # replace fields wholesale
ant edit ant-AkRXV --human           # rewrite the body in $EDITOR
ant append ant-AkRXV --body "later"  # grow an entry with a dated update
ant export ant-AkRXV                 # render one entry as markdown
ant export --kind adr                # render every ADR as markdown
ant export --json                    # JSON instead of markdown

Personal by default

The database lives at .ant/ant.db at the git repo root, and ant init adds .ant/ to .gitignore for you. When it can't — no .git directory yet — its JSON output says so in a note field rather than leaving you to find out at the next git status.

That's on purpose. A lot of what ends up in here is personal working memory: preferences, half-formed grumbles, "fine, just ship it" decisions made at 5pm on a Friday. None of that needs to be a team artefact. When something does earn its place — an actual ADR, a useful post-mortem — promote it with ant export and pipe the markdown wherever it belongs: a PR description, a docs file, a gist.

Conventional kinds

There are four named kinds to start with. The schema doesn't enforce them, so feel free to invent your own as a project grows:

Kind When to use
note (default) Captured thoughts, observations, short rationales. The bulk of entries.
adr Architecture Decision Records — load-bearing choices worth writing down properly.
pivot Changes of direction: "we tried X, here's why we moved on".
foundation The single core vision document for the project. Singleton — one per project.

If a note turns out to matter more than you thought, promote it later with ant edit --kind adr <id>.

Project foundation

The foundation kind is special. It's the one entry that captures the essence of a project — what it is, what it isn't, the load-bearing ideas an agent (or future-you) needs to read before making judgement calls about design, wording, and trade-offs.

A project has at most one. ant add --kind foundation refuses if one already exists; revise it with ant edit instead.

$ ant add --kind foundation --title "ant — vision" --body @ANT_PLAN.md

$ ant foundation
{
  "id": "ant-AkRXV",
  "kind": "foundation",
  "title": "ant — vision",
  "body": "...the full text, untruncated..."
}

ant foundation returns the full body (no snippet) — this is the one read path where truncation would defeat the goal. If no foundation has been recorded, it exits non-zero with a hint.

The DB is gitignored, so foundation revisions are lossy. If you want a history of how the vision evolved, render it to markdown periodically (ant export <id>) and commit that file alongside the code.

Linking to issue trackers

--issue is a free-form string. ant won't validate or resolve it, so use ait ids if you're using ait, or Jira / Linear / GitHub ids otherwise. ant for <id> returns entries with an exact match — nothing fancier.

Linking entries to each other

Two kinds of connection, both shown by ant show:

  • Mentions are worked out from the bodies on every read. Cite an entry's id in a body and show lists it under mentions (with its title, so a mistyped id stands out), and the cited entry lists the citing one under mentioned_by. Ids with the project prefix that match no entry appear under not_in_notebook; they are often ait issues, since projects tend to share one prefix. Nothing is stored, so they can't go stale, and ant init --prefix rewrites cited ids along with the entries themselves.

  • Supersedes is declared by the writer when a newer entry overturns all or part of an older one:

    ant add --supersedes ant-Ed6UZ --supersedes-reason "only the grouping rule" --body @new.md
    ant edit ant-mjBCN --supersedes ant-Ed6UZ     # add one later (no prior show needed)
    ant edit ant-mjBCN --unsupersede ant-Ed6UZ    # remove a wrong one
    

    The older entry's show output then leads with superseded_by, and its rows in list, recent, search and for carry a superseded_by marker, so a reader knows to check the newer entry before trusting it.

Command reference

Command Purpose
ant init [--prefix p] Create .ant/, run migrations, set the prefix, add gitignore entry
ant config Show prefix, schema version, resolved DB path
ant add (alias: ant create) Capture a new entry (body via --body, --body @file, stdin, or --human for $EDITOR); --supersedes <id> marks an older entry as overturned
ant show <id> Full record for one entry, plus superseded_by / supersedes and mentions (see above)
ant edit <id> Update body / title / kind / issue (empty --title/--issue clears; --human opens the body in $EDITOR; --supersedes/--unsupersede manage links; see guards below)
ant append <id> Add content to an existing entry, separated by a markdown --- rule
ant delete <id> Remove an entry (refuses without --force, see below)
ant list List entries; --long, --human, filters: --kind, --issue, --since
ant recent [--limit N] N most recent entries with body snippets
ant search <query> Case-insensitive AND-of-terms across title + body
ant for <issue-id> Entries linked to a specific issue id (exact match)
ant foundation Print the project's foundation entry, if one has been recorded
ant export [<id>] Render entries as markdown; --json for JSON
ant version Print the build version (and check GitHub for newer releases)
ant self-update Update to the latest release; --check reports without installing, --yes skips the prompt
ant completion {bash,zsh} Print a shell completion script

Output

JSON by default, because that's what agents and pipelines want. If you're the one reading the output, ant list --human gives you a tabular view, --long includes the full bodies, and ant export produces markdown.

Guards against blind writes

Both guards exist because an agent once wiped an entry body by piping an empty heredoc into an edit, and another sent a diff where the whole text was expected.

  • ant edit --body "" (or --body - with nothing on stdin, or @file on an empty file) is refused rather than blanking the body.
  • A new body less than half the length of the existing one is refused with a shrink error unless you pass --force. Growing a body is never questioned, and bodies under 200 characters are exempt. ant append is the right tool when you want to add rather than replace.
  • When CLAUDE_CODE_SESSION_ID is set (Claude Code sets it for every command an agent runs), ant show records the session and time against the entry. ant edit --body/--title/--human then refuses with an unread error unless that session ran show on the entry within the last hour. The error says which it was: never shown, shown by another session, or shown too long ago. A plain terminal has no session id, so humans are never checked. The override is deliberately long:
ant edit <id> --body @rewrite.md --dangerously-skip-read-check

The hour is a constant (ShownWindow in internal/ant/guards.go), chosen so that a session whose context has been compacted since it last looked cannot keep editing on a stale memory of the entry. ait has the same guards with the same flag and error codes.

ant delete sneakyness

ant delete <id> won't actually delete anything by itself. That's on purpose — it's far too easy to nuke the wrong entry from a shell loop. Run it without --force and it just prints a warning to stderr saying what it would have deleted, exits non-zero, and leaves the DB alone:

$ ant delete ant-AkRXV
would delete ant-AkRXV — "Choose sqlite" (adr, 2026-05-01T18:22:22Z)
this is irreversible; refusing to act without confirmation.

Pass --force to actually remove the row:

$ ant delete ant-AkRXV --force
{ "id": "ant-AkRXV", ... }

The deleted record gets echoed to stdout on the way out, so at least there's something in your scrollback if you immediately regret it. There's no soft-delete by design: entries are either there or they're not, and recovery means your shell history or your backups.

--db <path>

ant --db /path/to/other.db <command>

Handy for scratch databases, testing, or hopping between worktrees. The special path :memory: opens an in-memory SQLite instance, which is what the test suite uses.

Build

go build -o ant ./cmd/ant

# with a stamped version
go build -ldflags "-X github.com/ohnotnow/agent-note-tracker/internal/ant.Version=v0.1.0" -o ant .

A stamped (non-dev) build will, on ant version, do a best-effort GitHub check against the latest tagged release and let you know if a newer one is available. The check has a 5-second timeout and fails silently — offline use is unaffected.

Self-update

ant self-update            # show release notes, prompt y/N, replace the binary
ant self-update --check    # exit 0 if current, 1 if newer is available, 2 on lookup failure
ant self-update --yes      # skip the prompt

self-update downloads the matching binary for your OS and architecture from the latest GitHub release, verifies it against the published SHA256SUMS, and atomically replaces the running executable. Release notes appear inside the confirmation prompt so there's nothing to chase down separately.

A few cases short-circuit before any download:

  • Dev builds refuse — there's no version to compare against, and overwriting a hand-built binary with a release one is rarely what you want.
  • Homebrew and go install installs print a hint pointing you at the right tool (brew upgrade ant, go install …@latest) instead of sidestepping your package manager.
  • Unwriteable install dirs report immediately with a "re-run with sudo, or visit /releases/latest" message rather than failing partway.

Layout

cmd/ant/main.go                 CLI entrypoint, --db extraction
internal/ant/app.go             App struct, command dispatch
internal/ant/store.go           DB connection
internal/ant/migrate.go         Forward-only schema migrations
internal/ant/entries.go         Insert/Get/List/Update/Delete entry
internal/ant/prefix.go          Project prefix CRUD + Rekey
internal/ant/keys.go            sqids public_id generation
internal/ant/paths.go           Project root detection, path resolution
internal/ant/gitignore.go       Idempotent .gitignore handling
internal/ant/format.go          Markdown rendering
internal/ant/cmd_*.go           One file per command handler
internal/ant/version.go         Version + ldflags hook
internal/ant/completion.go      bash/zsh completion scripts
claude/SKILL.md                 Claude Code skill documentation

License

MIT — see LICENSE.

Directories

Path Synopsis
cmd
ant command
internal
ant

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL