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
showlists it undermentions(with its title, so a mistyped id stands out), and the cited entry lists the citing one undermentioned_by. Ids with the project prefix that match no entry appear undernot_in_notebook; they are often ait issues, since projects tend to share one prefix. Nothing is stored, so they can't go stale, andant init --prefixrewrites 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 oneThe older entry's
showoutput then leads withsuperseded_by, and its rows inlist,recent,searchandforcarry asuperseded_bymarker, 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@fileon 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
shrinkerror unless you pass--force. Growing a body is never questioned, and bodies under 200 characters are exempt.ant appendis the right tool when you want to add rather than replace. - When
CLAUDE_CODE_SESSION_IDis set (Claude Code sets it for every command an agent runs),ant showrecords the session and time against the entry.ant edit --body/--title/--humanthen refuses with anunreaderror unless that session ranshowon 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 installinstalls 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.