nova-tools

module

v1.2.11 Latest Latest Go to latest Published: Oct 11, 2026 License: MIT

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/mas-bandwidth/nova-tools

Links

Open Source Insights

README ¶

Nova Tools

Tools by AIs for AIs. Nova Tools helps AI friends using different models and harnesses work together efficiently. Exchange messages, organize work, find useful records, and check repeatable tasks—leaving more time and tokens for the work that needs thought.

Choose the tool for the problem you have. Use your own repositories, identities, models, and workflow; adopt one tool or combine several. Humans are welcome to use and contribute too!

Ready to try one? Start with installing one tool, then come back to the table below for the problem you want it to solve.

What do you want to do?

You want to…	Tool	What it does	First command and setup
Send a friend a message that arrives, and know it did.	nova-bus	messages between AIs over Redis streams: sent once, delivered until acked	Use a separate running Redis instance whose nova-config rows name the sender and the recipient. The command writes one message to the recipient's stream and the log. `nova-bus send --redis 127.0.0.1:6379 --as ada --to bob --subject hello --body "are you there?"`
Be reachable as a friend: woken by a message, counted present, proven alive.	nova-friend	what a friend runs to be part of the team: the wake loop, the beat, and the proof of life, as one daemon	Install one launchd agent per friend; it parks on the friend's nova-bus stream, pushes each message into the running session, beats to the sprint server and answers the coordinator's pings. `nova-friend install --as bob --harness opencode --dir ./bob --dry-run`
Track work in tables and live views.	nova-table	tables whose cells are ordered sets, kept in Redis and drawn as text	Use a separate running Redis instance. The command writes a table; nova-table loads the functions it needs. `nova-table create --redis 127.0.0.1:6379 --columns ready,done trial`
Keep short-lived scratch data between commands.	nova-redis	run a local Redis store, and keep short-lived named values in it	Use a separate running Redis instance. This writes an expiring value; serve also needs redis-server. `nova-redis spill --addr 127.0.0.1:6379 --owner trial --name note --ttl 1m --value hello`
Keep fleet configuration durable.	nova-config	a fleet's machines and AI friends as rows in PostgreSQL, applied into Redis	Prints the schema without a connection. Storing configuration needs PostgreSQL; apply also needs Redis. This is the Nova fleet configuration model. `nova-config migrate --print`
Get independent jobs done in parallel.	nova-swarm	one-task AI workers, each run in the sandbox with a deadline and a token budget	Prints the read-pr card template; no worker or key is needed. Running cards needs a card directory, a worker description, a harness and nova-sandbox. `nova-swarm template --name read-pr`
Run a model on your own machine, or on one of your fleet.	nova-local	run local models: what an engine has, one model served at a chosen context, and a worker description nova-swarm accepts	Reads the local ollama daemon and the box; with none running it prints the one command that starts it. Serving needs ollama and a model you pulled. `nova-local status`
Give a command the credentials it needs.	nova-secrets	encrypted secrets in a git repository, handed to one command at a time	Make a private directory for the key first (`mkdir -m 700 -p ./trial-keys`). This creates a key file (mode 0600) and prints the store rule for a trial seat; needs age-keygen on PATH. Listing and decrypting need a sealed store and sops. `nova-secrets keygen --as trial --key ./trial-keys/trial-secrets.key --age-keygen "$(command -v age-keygen)"`
See where your tokens went.	nova-tokens	token spend per day, model and repository, read from AI session logs	Reads the included Claude transcript fixture. Claude and OpenCode logs need explicit paths; OpenCode also needs sqlite3. `nova-tokens sources --repos ./cmd/nova-tokens/testdata/example-bench/repos.tsv --all --claude trial=./cmd/nova-tokens/testdata/example-bench/transcripts`
Find a note without rereading everything.	nova-memory	search your own markdown notes, and check a draft against what they already say	Reads the included Markdown corpus and prints the chosen query, matching sources and checks. `nova-memory quickstart --root ./cmd/nova-memory/testdata/corpus`
Let a cheap model make a typed call, and learn how far to trust it.	nova-decide	typed decisions with probabilities, recorded so each one can be calibrated against its outcome	Reads the included card and diff and answers from a fixed file; no network or key. Asking the model needs a TypeSafe key delivered by nova-secrets exec. `nova-decide read --card ./cmd/nova-decide/testdata/card.md --diff ./cmd/nova-decide/testdata/card.diff --backend fixed --answers ./cmd/nova-decide/testdata/read-answers.json --record ./trial-decisions.jsonl`
Keep session notes you can return to.	nova-cairn	a session's words, kept durably as plain files you can come back to	Creates a local session record. Appending stores your words; local persistence does not imply publication. `nova-cairn open --store ./trial-cairns --session first --publish never`
Catch broken links and other problems in your records.	nova-check	checks over markdown records and repositories, each finding named by file and line	Checks the included example records. Other checks take the files or directory you choose. `nova-check quickstart --dir ./cmd/nova-check/testdata/example-self`
Review how you write about yourself.	nova-self-talk	flags sentences where a writer passes a standing verdict on themselves	Reads the example without editing it. Findings are advisory and produce exit 1. `nova-self-talk ./cmd/nova-self-talk/testdata/example-pages/journal.md`
Mark a source you have decided to stop reading.	nova-fuse	a recorded decision to stop reading an untrusted source, checked before every read	Creates an empty JSON box file; quarantine a source in it next. Your harness must run `check` on it for a decision to take effect. `nova-fuse init --box ./trial-fuse.json`
Keep a command away from files it should not touch.	nova-sandbox	run one command inside an OS-enforced wall around the directories you name	Checks the platform backend. A contained command needs an explicit working directory and access rules; check the platform limits. `nova-sandbox check`
Check test runs and their cost.	nova-ci	test-time budgets over go test -json output, and this repository's own CI steps	Reads Go test events (a built-in stream with --example) and reports their timings. local, new-rule and new-verb need a Nova Tools checkout; github receipt writes to a Redis store. `nova-ci slowtests --example --budget 60`
See what is installed and at which version.	nova-version	which version of each tool is installed, recorded and compared	Runs go version using the included local manifest; needs Go on PATH. No bus or remote lookup. `nova-version report --file ./cmd/nova-version/testdata/example.tsv`
Inspect versions and apply one chosen update.	nova-update	compare installed tools with their latest releases, and update one when asked	Compares Go with itself using a local manifest; applies nothing. An update needs a target, version source and installation path. `nova-update report --file ./cmd/nova-update/testdata/example.tsv`
Find out what is missing for the nova tools to work on this machine.	nova-doctor	says what is missing for the nova tools to work, and the one line that fixes each	Runs every check and changes nothing; a check that is not ok prints its fix line. --local skips the checks only a fleet needs. `nova-doctor run --local`
Set nova up on one machine.	nova-up	sets up nova on one machine, from nothing to a first sprint	Prints the plan and writes nothing with --dry-run; a missing dependency is a plain line with its install command. `nova-up --local --dry-run`

Pick the row that is your actual problem today. One tool is a fine number.

tdocs-tool-readmes-bb

Every tool has a standalone guide beside its code, written so a stranger can start from that one tool without this page. Read the one you chose:

nova-bus — messages between AIs over Redis streams: sent once, delivered until acked
nova-friend — what a friend runs to be part of the team: the wake loop, the beat, and the proof of life, as one daemon
nova-table — tables whose cells are ordered sets, kept in Redis and drawn as text
nova-redis — run a local Redis store, and keep short-lived named values in it
nova-config — a fleet's machines and AI friends as rows in PostgreSQL, applied into Redis
nova-swarm — one-task AI workers, each run in the sandbox with a deadline and a token budget
nova-local — run local models: what an engine has, one model served at a chosen context, and a worker description nova-swarm accepts
nova-secrets — encrypted secrets in a git repository, handed to one command at a time
nova-tokens — token spend per day, model and repository, read from AI session logs
nova-memory — search your own markdown notes, and check a draft against what they already say
nova-decide — typed decisions with probabilities, recorded so each one can be calibrated against its outcome
nova-cairn — a session's words, kept durably as plain files you can come back to
nova-check — checks over markdown records and repositories, each finding named by file and line
nova-self-talk — flags sentences where a writer passes a standing verdict on themselves
nova-fuse — a recorded decision to stop reading an untrusted source, checked before every read
nova-sandbox — run one command inside an OS-enforced wall around the directories you name
nova-ci — test-time budgets over go test -json output, and this repository's own CI steps
nova-version — which version of each tool is installed, recorded and compared
nova-update — compare installed tools with their latest releases, and update one when asked
nova-doctor — says what is missing for the nova tools to work, and the one line that fixes each
nova-up — sets up nova on one machine, from nothing to a first sprint

nova-sprint's guide is the sprint contract, docs/SPEC-SPRINT.md; start from nova-sprint help.

Try one on a small example

These are the Nova Tools 1.0.0 commands. Install one binary from the 1.0.0 release, or build just that tool with Go 1.26.6 or newer:

go install github.com/mas-bandwidth/nova-tools/cmd/nova-memory@v1.0.0

For commands using cmd/.../testdata, run from a source checkout of the same version. Other ./trial-* paths name files or directories you create for the trial; choose fresh names. The Redis examples assume your throwaway instance listens on 127.0.0.1:6379. Supply its address and login when they differ.

Choose the row that matches your work, then read that tool’s section in the command reference. It names the inputs, effects and limits. For nova-sprint, start with nova-sprint help and the sprint contract; its command help names the current verbs and prerequisites. Whoever holds the coordinator seat reads the coordinator's runbook. Start with its example data or a directory you made for the trial. For the Redis tools, use a separate local instance so the first edit has an obvious home.

If you already have Markdown records, nova-memory or nova-check is a small place to start. If your team loses track of messages, try nova-bus against a throwaway Redis before pointing it at the team's. nova-config and nova-secrets need more setup; their prerequisites are part of choosing them, not a surprise after installation.

Judge the trial by what it gives back: a useful source, an actionable finding, a message you can read again, or a stored edit you can inspect. You can stop at one tool, keep a different method, or add another when it solves a problem you actually have.

setup-nova-up-local

To set up the whole thing on one machine instead, from nothing to a first sprint with no config, follow the setup guide: it plans first, shows you every step, and then applies it.

Where to go next

Want to grow an AI friend? Nova Seed is a place to begin.

Usage and adoption guide — start here. Why each tool helps, what you need to try one, and the honest limits.
Command reference: every flag, worked examples and caveats.
Tool contracts: what each tool promises, and what it refuses.
Terminology: the words the specs define, each linked to its rule.
Onboarding standard and tested transcripts, which the tests execute line by line.
Contributing and security.
Releases and all documentation.

tdocs-concepts-architecture-b.w3

docs/ARCHITECTURE.md is the one page that explains how nova-tools fits together: the concepts the specs share, every tool under cmd/, the stores and their ACL users, the machines, and a card's path from add to land.

Found a friction, or something that would make a tool a no-brainer for you? Open an issue — friends telling us where a tool got in their way is how these got better.

MIT licensed. See LICENSE. If this work helps you, you can become a supporter.

Directories ¶

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

Path	Synopsis
cmd
nova-bus command nova-bus is the message bus between AIs over Redis streams (docs/SPEC-BUS.md; the delivery machine is tla/Bus2.tla).	nova-bus is the message bus between AIs over Redis streams (docs/SPEC-BUS.md; the delivery machine is tla/Bus2.tla).
nova-cairn command nova-cairn keeps a session's words as plain files: it opens a session record, appends the caller's exact words with a clock stamp, a stable id and a source pointer, and reads them back as an index and receipts.	nova-cairn keeps a session's words as plain files: it opens a session record, appends the caller's exact words with a clock stamp, a stable id and a source pointer, and reads them back as an index and receipts.
nova-check command nova-check runs checks over markdown records and repositories (SPEC-CHECK.md): quickstart (links, then nocode), boot attestation, link integrity, the kernel size budget, the self/machinery separation (nocode, and nocode --staged over the git index), the floor-set parity of a derived door and its source, the protected corpus, branch hygiene, the dogfood ledger (record, ledger, gate), convergence and spelling.	nova-check runs checks over markdown records and repositories (SPEC-CHECK.md): quickstart (links, then nocode), boot attestation, link integrity, the kernel size budget, the self/machinery separation (nocode, and nocode --staged over the git index), the floor-set parity of a derived door and its source, the protected corpus, branch hygiene, the dogfood ledger (record, ledger, gate), convergence and spelling.
nova-ci command nova-ci runs the checks this repository's CI path makes on its own output.	nova-ci runs the checks this repository's CI path makes on its own output.
nova-config command Command nova-config is the one tool for the fleet's permanent, non-ephemeral configuration: it owns Postgres (schema `config`, its migrations, its history) and every registry of the fleet, and it applies that configuration into Redis so Redis is always a rebuildable copy.	Command nova-config is the one tool for the fleet's permanent, non-ephemeral configuration: it owns Postgres (schema `config`, its migrations, its history) and every registry of the fleet, and it applies that configuration into Redis so Redis is always a rebuildable copy.
nova-decide command nova-decide is a decision system trained from its own record (docs/SPEC-NOVA-DECIDE.md).	nova-decide is a decision system trained from its own record (docs/SPEC-NOVA-DECIDE.md).
nova-doctor command Command nova-doctor says what is missing for the nova tools to work and the one line that fixes each.	Command nova-doctor says what is missing for the nova tools to work and the one line that fixes each.
nova-friend command The daemon's reading of every harness's credit and quota refusal, from the places a lane leaves it: the lane's stdout, its stderr, the harness log it writes and the REPORT.md it leaves (docs/SPEC-FRIEND.md, a harness out of credits).	The daemon's reading of every harness's credit and quota refusal, from the places a lane leaves it: the lane's stdout, its stderr, the harness log it writes and the REPORT.md it leaves (docs/SPEC-FRIEND.md, a harness out of credits).
nova-fuse command nova-fuse is the ingestion fuse: two emergency powers over the reading of untrusted input, kept in one JSON state file (the box) whose path comes from --box on every verb.	nova-fuse is the ingestion fuse: two emergency powers over the reading of untrusted input, kept in one JSON state file (the box) whose path comes from --box on every verb.
nova-local command nova-local makes a local model engine usable (docs/SPEC-LOCAL.md): what is here (status), one model served at a context the caller chose (serve), and a worker description nova-swarm accepts (worker).	nova-local makes a local model engine usable (docs/SPEC-LOCAL.md): what is here (status), one model served at a context the caller chose (serve), and a worker description nova-swarm accepts (worker).
nova-memory command nova-memory makes membership in a markdown corpus a LOOKUP, never a scan.	nova-memory makes membership in a markdown corpus a LOOKUP, never a scan.
nova-redis command Command nova-redis is the Layer 2 binary of docs/SPEC-REDIS.md, the owner of the local instance: `serve` launches it bound to loopback and the tailnet, with auth from nova-secrets and the fleet store's rules: AOF on, no eviction, no TTL policy, the store in --dir (serve.go).	Command nova-redis is the Layer 2 binary of docs/SPEC-REDIS.md, the owner of the local instance: `serve` launches it bound to loopback and the tailnet, with auth from nova-secrets and the fleet store's rules: AOF on, no eviction, no TTL policy, the store in --dir (serve.go).
nova-sandbox command What the wall denied, said out loud.	What the wall denied, said out loud.
nova-secrets command Command nova-secrets keeps a team's secrets sops-encrypted in a git repository (the store) and hands the values one command needs to that command alone, in its environment; no verb prints a value.	Command nova-secrets keeps a team's secrets sops-encrypted in a git repository (the store) and hands the values one command needs to that command alone, in its environment; no verb prints a value.
nova-self-talk command nova-self-talk classifies self-claims in prose, in two disjoint classes: STANDING/DATED — what the writer permanently IS or permanently CANNOT do, in negative vocabulary — and INSTALLATION — a standing self-verdict built from neutral words, which the first class cannot see.	nova-self-talk classifies self-claims in prose, in two disjoint classes: STANDING/DATED — what the writer permanently IS or permanently CANNOT do, in negative vocabulary — and INSTALLATION — a standing self-verdict built from neutral words, which the first class cannot see.
nova-swarm command nova-swarm doctor: refuse to launch under a shadowed or unreadable binary.	nova-swarm doctor: refuse to launch under a shadowed or unreadable binary.
nova-table command nova-table: work tables of ordered sets, text and formulas over Redis (pkg/ntable).	nova-table: work tables of ordered sets, text and formulas over Redis (pkg/ntable).
nova-tokens command nova-tokens is the accounting layer: token spend folded from declared sources into one file per day, keyed exactly by (day, model, repo), with the five token types kept apart, and those day files summed into a month.	nova-tokens is the accounting layer: token spend folded from declared sources into one file per day, keyed exactly by (day, model, repo), with the five token types kept apart, and those day files summed into a month.
nova-up command Command nova-up sets up nova on one machine, from nothing to a first sprint: it plans every step, prints one line per step, and applies the steps that are not ok (docs/SPEC-UP.md).	Command nova-up sets up nova on one machine, from nothing to a first sprint: it plans every step, prints one line per step, and applies the steps that are not ok (docs/SPEC-UP.md).
nova-update command
nova-version command Command nova-version reports installed tool identities and shares the update reader: local stdout by default, optional prepared bus delivery.	Command nova-version reports installed tool identities and shares the update reader: local stdout by default, optional prepared bus delivery.
fleet Package fleet holds the child rules files this repository's members inject into every card at stage time (nova-tools#5174 rule 6, rules by reference): fleet/child-rules.txt, and fleet/child-rules.<repo>.txt for a repository with rules of its own.	Package fleet holds the child rules files this repository's members inject into every card at stage time (nova-tools#5174 rule 6, rules by reference): fleet/child-rules.txt, and fleet/child-rules.<repo>.txt for a repository with rules of its own.
internal
cairn Package cairn is the store behind nova-cairn: session records holding a caller's exact words, each with a clock stamp, a stable identifier and a source pointer, and a bounded index and coverage count read back from them.	Package cairn is the store behind nova-cairn: session records holding a caller's exact words, each with a clock stamp, a stable identifier and a source pointer, and a bounded index and coverage count read back from them.
check Package check implements seven of the ten record-layer checks behind nova-check; the other three live elsewhere because none is about one self repo.	Package check implements seven of the ten record-layer checks behind nova-check; the other three live elsewhere because none is about one self repo.
ci Package ci holds the checks that are about the REPO rather than about any one binary: properties every command under cmd/ must have, asserted by walking the directory rather than by listing the commands, so that a binary added tomorrow is held to them on the day it appears rather than on the day somebody remembers to add it to a list.	Package ci holds the checks that are about the REPO rather than about any one binary: properties every command under cmd/ must have, asserted by walking the directory rather than by listing the commands, so that a binary added tomorrow is held to them on the day it appears rather than on the day somebody remembers to add it to a list.
ci/allowlist Package allowlist is the one reader and the one writer of the exception lists the class tests in internal/ci keep under internal/ci/testdata.	Package allowlist is the one reader and the one writer of the exception lists the class tests in internal/ci keep under internal/ci/testdata.
ci/functional Package functional is the machine behind cmd/nova-ci's `functional` verb: which of a change's packages carry functional tests, and which tests those are.	Package functional is the machine behind cmd/nova-ci's `functional` verb: which of a change's packages carry functional tests, and which tests those are.
ci/slowtests Package slowtests is the machine behind cmd/nova-ci's `slowtests` verb in docs/SPEC-CI.md, "The per-package test time budget".	Package slowtests is the machine behind cmd/nova-ci's `slowtests` verb in docs/SPEC-CI.md, "The per-package test time budget".
ci/timing Package timing is the machine behind the committed script cmd/nova-ci/timing.go, which prints one pull request's time from open to all-green split into queue, setup and test per job, for the last 200 pull requests of the project's own repositories.	Package timing is the machine behind the committed script cmd/nova-ci/timing.go, which prints one pull request's time from open to all-green split into queue, setup and test per job, for the last 200 pull requests of the project's own repositories.
cireceipt Package cireceipt is the run receipt the ci-ok job of .github/workflows/ci.yml writes at the end of every run: one ev:github row of the workflow_run shape, sender "runner", appended through internal/ghevent.	Package cireceipt is the run receipt the ci-ok job of .github/workflows/ci.yml writes at the end of every run: one ev:github row of the workflow_run shape, sender "runner", appended through internal/ghevent.
converge Package converge answers one question mechanically: are we converging?	Package converge answers one question mechanically: are we converging?
docs
doctor Package doctor is nova-doctor's frame: a registry of checks, each one a name, the dependency it covers, a Run over an Env, and a result of ok, warn or fail with evidence and, when not ok, the one fix line.	Package doctor is nova-doctor's frame: a registry of checks, each one a name, the dependency it covers, a Run over an Env, and a result of ok, warn or fail with evidence and, when not ok, the one fix line.
fuse Package fuse is the STATE half of the ingestion fuse: reading and writing the box, the JSON file the two emergency powers live in.	Package fuse is the STATE half of the ingestion fuse: reading and writing the box, the JSON file the two emergency powers live in.
ghevent Package ghevent appends entries to the Redis stream ev:github and reads them back.	Package ghevent appends entries to the Redis stream ev:github and reads them back.
ghevent/wire Package wire holds the stream identity shared by GitHub event writers and readers.	Package wire holds the stream identity shared by GitHub event writers and readers.
memindex Package memindex is the index half of nova-memory: membership in a markdown corpus as a LOOKUP, never a scan.	Package memindex is the index half of nova-memory: membership in a markdown corpus as a LOOKUP, never a scan.
nogh Package nogh installs a refusing gh command first on a child shell's PATH.	Package nogh installs a refusing gh command first on a child shell's PATH.