commitly-agent

A small Node CLI that authenticates this machine, watches a working tree, signs each save with Ed25519, and (optionally) runs queued narrative tasks under launchd or systemd. Talks to the dashboard over HTTPS; never writes to your repos unless you explicitly opt in to act-loop.

## at a glance

## three modes

The agent has eleven commands but they fall into three behaviours. Pick one to start; you can mix later.

1 · Read-only

commitly-agent watch tails .git/COMMIT_EDITMSG and POSTs each new commit to the dashboard's sync endpoint. No file writes, no signing, no AI. Useful if you only want the dashboard's analytics on top of your existing workflow.

2 · Signing

commitly-agent observe signs every save. Each file write produces a JSON envelope with a sha256, wall-clock timestamp, device id, and Ed25519 signature; envelopes are spooled to ~/.commitly/attestations.ndjson and flushed to the dashboard in batches. Crash-safe — the spool is replayed on restart.

3 · Acting

commitly-agent act-loop pulls queued narrative tasks from the dashboard, generates an AI-driven edit consistent with your multi-day arc, and (with confirmation) commits it. Run it manually, or use commitly-agent start to register it as a background daemon. Every commit it makes is also signed.

## hello world

From zero to a paired device watching a real repo in three commands.

$ npm i -g commitly-agent
$ commitly-agent login
$ commitly-agent observe ~/code/your-repo

After step 2 you'll have a paired device, an Ed25519 keypair in your OS keychain, and (depending on flow) a Gemini API key for the act family of commands. Step 3 starts emitting signed attestations.

## next

Read Install for system requirements and verification, or jump straight to the command reference.