Home · Blog

Guide

A notes app your AI agents can read and write

If you use an AI agent on your Mac, like Claude Code, Codex or your own scripts, it can use your Gravity notes too. The gravity command-line tool lets an agent search your notes for context, add a note when it finishes a task, or tidy your to-dos, with the same rules the app follows.

I'm Tristan, and I make Gravity on my own. I built this after someone told me they had pointed their agent straight at Gravity's database file to read their notes. That works until the file's layout changes, and it can't safely write anything. The command-line tool is the supported way in.

Install it

You need the Gravity Mac app, opened at least once. Then, in Terminal:

brew install tristanmanchester/tap/gravity-cli
gravity doctor

doctor checks that the tool can reach your notes. The first time, macOS may ask whether Terminal (or whichever app runs your agent) can access data from other apps. Say yes, or the tool can't open your notes.

The quickest way to set up an agent is in the Mac app: open Settings, choose Advanced, and click Copy Prompt under Command Line Tool. Paste that into your agent. It installs the tool, checks access, and reads gravity agent, a short guide written for agents.

What it can do

Everything you can do to a note in the app:

  • gravity list shows your stream, newest first. gravity search finds notes the way the app does, including tags like todo:.
  • gravity get prints a note's text. gravity add, append and edit write.
  • gravity rescue, archive, trash and restore move notes around, exactly like the buttons in the app.
  • gravity tags, stats and sync status answer questions about your notes as a whole.
  • gravity export and gravity import use the same file format as the app's own backup.

Here's what it looks like with a few notes:

$ gravity list
c8fc4198      now  todo:  renew the car insurance before the 14th
640bf3db      now         ask about hydrocortisone cream for Sam
ff641e0c      now  idea:  a weekly digest of rescued notes
18631840      now  todo:  book the ferry for half term
5bb476c9      now  read:  The Mom Test by Rob Fitzpatrick

$ gravity add --tag todo "call the dentist about Thursday"
created 824d763a-2834-447b-acea-c9e3d7f9d86e
tag: todo
words: 6

Agents add --json to every command and get structured output they can rely on:

$ gravity search "cream" --json --fields id,firstLine
{"notes":[{"id":"640bf3db-…","firstLine":"ask about hydrocortisone cream for Sam"}],"meta":{"count":1,…}}

How it keeps your notes safe

  • It writes the way the app does. Every change follows the same rules as the Mac and iPhone apps, so a note an agent edits looks exactly like one you edited yourself.
  • Nothing permanent without asking. Deleting a note forever needs an explicit --yes, and you can preview it with --dry-run first. Everything else, like trashing or archiving, can be undone in the app.
  • Edits don't overwrite your changes. An agent can pass the version it read, and if you've changed the note since, the edit is refused with your current text so the agent can merge.
  • Your iCloud account stays with the app. The tool never talks to iCloud. It marks changed notes, and the Mac app syncs them to your other devices, usually within a second if it's running, or next time you open it.
  • It stays on your Mac. Nothing is sent anywhere except a version check you run yourself.

Some ways to use it

  • Before starting on a project, an agent runs gravity search for anything you've jotted down about it and reads those notes first.
  • At the end of a research session, it saves the links worth keeping with gravity add --tag read, and they're on your phone by the time you're on the train.
  • Once a week, it lists your todo: notes and archives the ones you've marked done.

The app is still where you write. The command-line tool means the notes you capture quickly are there for the tools you work with, too.