Contributing

Contributing

Vyre is plain JavaScript on Node 22.5 or newer, with no build step for the core and almost no dependencies. This page is what you need before your first change: where things live, the rules a change is held to, and how to check it. The rules come from Section 14 of the spec; where the spec and the code disagree, one of them is a bug.

Get the code running#

git clone https://github.com/vyre-ai/vyre
cd vyre
npm test

Try a change against a throwaway home, never your real ~/.vyre. Export VYRE_HOME, so every command after it uses the same home:

export VYRE_HOME=$(mktemp -d)
bin/vyre up --json
bin/vyre call system.echo '{"text":"hi"}'
bin/vyre down
unset VYRE_HOME

{
  "text": "hi"
}

--json keeps vyre up on a Mac from asking where your box runs. A temp VYRE_HOME also means Vyre raises no dialogs (Touch ID, keychain, browser tabs) unless you set VYRE_ALLOW_DIALOGS=1. See Testing.

Where things live#

The full tree is Section 3 of the spec, and the layers are explained in Architecture.

The rules every change follows#

• Tests beside the code, with node --test. A bug fix comes with the test that would have caught it. Tests never touch your real ~/.vyre or real transcripts; they get a temp VYRE_HOME.
• Real data before merge. Anything that talks to Claude Code or a network is exercised for real once before it merges, not only against a fake.
• The changelog is updated with every change (see below).
• Conventional commits (feat:, fix:, refactor:, docs:, test:), one concern each, committed by path (git commit -m "..." -- <paths>) so parallel sessions never sweep up each other's files.
• No secrets and no personal data in code, tests, fixtures or commits. test/hygiene.test.js fails when shipped code names a real person or business or holds something shaped like a key. Examples use the sample world: the user alex, Juniper Studio, Northwind Bakery, the agents juno and kit, and example.com.
• Principles hold. Public Claude Code surfaces only, local first, one process per machine, everything a module, light by default. A change that breaks one needs a spec change first. See Section 2 of the spec.
• Every feature merges with its doc page. A feature is not done until the page that describes it says what it does. See Writing the docs.

The changelog#

CHANGELOG.md at the root, newest first. Every change to code lands there in the same commit, under ## Unreleased, in plain sentences that say what changed and why. A new dependency says why it is worth having. The docs site shows it as the Changelog.

Decision records#

Write an ADR in docs/adr/ for any decision a future contributor would ask about: a trade-off, a boundary, a thing you chose not to do. Number it next in sequence, and follow the shape of the existing ones: front matter like any page, a title ADR NNNN: <decision>, a status line (proposed or accepted, the date, the workstream, the spec sections it touches), then the problem, the decision, and its consequences. Add it to docs/nav.json. The list is in Architecture.

Run the tests#

npm test                      # the whole suite, with the temp-folder leak guard around it
node --test core/vault/*.test.js   # one area
npm run perf-check            # the idle budgets: a real vyred sampled for 60 s
npm run docs:check            # the docs contract

CI runs npm test and npm run perf-check on Ubuntu and macOS, on Node 22 and 24, for every push and pull request. How the suite is organised, the helpers, and the fakes are in Testing.

Where to go next#

• Testing
• Writing the docs
• Writing a module
• Development rules: every rule for writing code here, why it exists and the check behind it