Contributing
This page shows how to find your way around the Seed repository, set it up, run the development stack, run the checks for each part, and make the changes that have special rules.

Seed is one public repository, github.com/seed-hypermedia/seed. This page is for people who want to change anything in it. Read it first: it gets the code running on your machine.

The repository holds the Go daemon, the TypeScript apps and libraries, the app environment that runs Seed Agents, the vault, the deployment tools, and the markdown for these docs (see Editing these docs).

This page covers four things:

    The layout of the repository.

    The development stack, which one command starts.

    The checks to run for each area before a pull request.

    The rules for changes that are hard to undo: storage migrations and protocol changes.

Working on Seed lists the other guides for contributors.

The repository keeps instructions for coding agents in AGENTS.md at the root and in the folders listed below. They are written for people too. Where this page and an AGENTS.md file differ, the AGENTS.md file is right.

The repository

Path

What lives there

Toolchain

backend/

the Seed daemon: storage and indexing (storage/, blob/), the document model and CRDTs (api/documents/, crdt/), networking (hmnet/), gRPC APIs (api/), the embedding model (llm/)

Go, built with Please

proto/

protobuf definitions for every daemon service; generated Go and TypeScript are checked in

Please, ./dev gen

frontend/apps/desktop

the Seed app (Electron)

pnpm

frontend/apps/web

the Seed web app that serves sites, the Seed API and the site services (Remix)

pnpm

frontend/apps/cli

seed-cli, also the home of the hypermedia/ sync script

pnpm workspace, runs under Bun

frontend/apps/notify

the email notification service

pnpm

frontend/apps/explore

the Hypermedia Explorer

pnpm

frontend/apps/mobile

the React Native app, outside the pnpm workspace

npm

frontend/apps/landing, emails, perf-web, performance, performance-dashboard

the landing site, email templates, performance tooling

pnpm

frontend/packages/client

@seed-hypermedia/client, the published SDK

pnpm

frontend/packages/shared, ui, editor, apps-ui

shared models and hooks (@shm/shared), UI components (@shm/ui), the editor (@shm/editor), the packaged agents screens (@seed-hypermedia/apps-ui); see The shared packages

pnpm

apps/

the app environment, the server that runs Seed Agents; see Development

its own Bun workspace

vault/

the key vault service

its own Bun workspace

hypermedia/

this site: concept pages, the Hypermedia Schemas library, the references and guides; see Editing these docs

markdown, scripts/hypermedia/

ops/

the self-hosted node deployment script (seed-deploy)

pinned Bun

tests/

cross-app integration tests

pnpm, Vitest, Playwright

docs/

internal design notes and runbooks; not published

markdown

apps/ and vault/ copy the frontend packages they use through file: dependencies. So a change to frontend/packages/* reaches them only after bun install. Their development servers do this for you. The map pages under The Seed software, such as Daemon, Desktop and Web, explain how the programs talk to each other.

Setting up

mise.toml fixes the version of every tool, and direnv turns them on in your shell.

    Install mise and direnv, and hook direnv into your shell.

    Clone the repository and allow the environment, with the commands below.

The first direnv allow takes a few minutes. It installs the tools, sets up the llama-go submodule, downloads the embedding model that the daemon uses for search, and builds the llama.cpp libraries.

git clone https://github.com/seed-hypermedia/seed cd seed direnv allow pnpm install

Install Docker too if you want the full stack. The web search backends that agents use run as containers.

./dev only runs in a shell where direnv is active. From a script or a coding agent, run commands as direnv exec . <command>.

Running things

./dev with no arguments lists every command. These are the ones you will use:

Command

What it does

./dev up

the whole stack on mainnet in one mprocs window, one pane per process (see mprocs.yaml)

./dev up-testnet

the same stack on the dev testnet (see mprocs.testnet.yaml)

./dev run-desktop

build the daemon, then run the desktop app on the dev testnet; the app starts its own daemon

./dev run-desktop-mainnet

the same, on mainnet

./dev run-backend

build and run seed-daemon alone; flags after -- go to the daemon

./dev build-backend, ./dev build-desktop, ./dev build-web

production builds

./dev test-desktop

the desktop test suite

./dev install-cli

build seed-cli and link it into ~/.local/bin

./dev hm-sync [dir]

edit a markdown folder, hypermedia/ by default, in the desktop dev app

./dev gen [targets]

check generated code and regenerate what is stale

./dev frontend-validate

format the whole workspace, then check formatting the way CI does

./dev up starts these panes:

Pane

Process

Address

backends

SearXNG and crawl4ai containers for agent web search

:8899, :11235

agents

the Seed Agents server with hot reload

:3051

web

the web app, talking to the desktop app's daemon

:3000

explore

the Hypermedia Explorer

:5173

notify

the notification server

:3060

vault

the vault

:3030

desktop

the Electron app on mainnet with its daemon

daemon HTTP :58001

host

the hosting service; it runs only when a SeedHost checkout sits beside this repository

:5555

hm-sync

the round trip between hypermedia/ and the desktop app


In mprocs, r restarts the selected process, s stops it, x starts it and q quits everything. Quitting also runs docker compose down for the search containers. The development daemon and the desktop app use ports 58000 to 58004. The full port table is on The Seed software.

Scripts in the root package.json start one app each: pnpm web, pnpm desktop, pnpm notify, pnpm explore and pnpm mobile. pnpm web:standalone runs a web app with its own daemon.

Checks before a pull request

Run the checks for every area you changed. CI runs the same ones. One file with wrong formatting, anywhere, fails the Lint job.

Area

Commands

Whole TypeScript workspace

pnpm typecheck

Formatting, everywhere

pnpm format:write, then pnpm format:check from the root; this covers the pnpm workspace, apps/ and vault/

Web, shared, desktop unit tests

pnpm test runs all three; singly pnpm web:test, pnpm shared:test, pnpm desktop:test:unit

SDK, UI, editor, notify, explore

pnpm --filter @seed-hypermedia/client test, pnpm --filter @shm/ui test, pnpm --filter @shm/editor test, and the same for @shm/notify and @shm/explore

CLI

pnpm --filter @seed-hypermedia/cli test (a fixture suite against a real daemon) and pnpm --filter @seed-hypermedia/cli test:unit

Desktop end to end

pnpm desktop:test, which packages the app and drives it with Playwright

Integration

pnpm test:integration from the root

Mobile

pnpm mobile:test, pnpm mobile:typecheck

App environment

bun check and bun test in apps/; bun run protocol:check when you change the protocol between the server and its clients

Vault

bun check and bun test in vault/

Dependencies

pnpm audit --audit-level=high --ignore-registry-errors, the command the Security Audit workflow runs

Go

go test ./backend/... and golangci-lint run --new-from-merge-base origin/main ./backend/...

Docs

node scripts/hypermedia/check.mjs; see Editing these docs

Three notes on these checks:

    In apps/ and vault/, bun check runs the type checker and fixes the formatting. Commit whatever it changes.

    The Go tests need the submodule and the model that direnv allow fetched. CI runs them with go test -tags cpu --count 1 ./backend/....

    For a bug fix in the backend, first add a test that fails, when you can. Use testify/require in Go tests.

To run CI on your machine before you push, use agent-ci. Local CI with agent-ci has the setup and the command for each area.

Changes with special rules

Storage schema and migrations

The daemon's SQLite schema is in backend/storage/schema.sql, which is the source of truth. The migrations are in backend/storage/storage_migrations.go. Read the note at the top of that file before you add one. These are the rules it sets:

    The version of a migration is a timestamp from date +%Y-%m-%d.%H%M%S. The list is kept with the newest first.

    The run function of a migration runs in an immediate write transaction. Write it so that running it twice does no harm, as far as you can.

    A migration runs only when its version is higher than the version of the data directory. So never run a feature branch that has a migration against a data directory you care about. Back the directory up first. If you switch back to main afterwards, the daemon fails on the unknown version.

    After you change the schema or the migrations, run ./dev gen //backend/....

    Avoid a migration that forces a full reindex or computes the embeddings again, unless you must. Servers without a GPU take a long time to do that. Prefer a new column and a background task that fills it in small steps.

If you are not sure, ask the backend team before you add a migration. Tag the maintainers of the Go daemon on pull requests that change backend/.

Protobuf and generated code

Edit the .proto files under proto/, then run ./dev gen //proto/... from the root. Do not run buf or protoc yourself, and do not format the generated code. A proto change reaches both Go and TypeScript callers, so run the backend checks and the frontend checks above. gRPC describes the services for people who call them.

Protocol changes

A protocol change is a change to something that every implementation must agree on:

A feature that you can build in an application alone is not a protocol change. The team's advice is to build it that way first.

This is the team's process for a protocol change:

    Write a proposal note that describes the problem and the change.

    Write down the arguments for and against it in the open. Include the options you rejected.

    Decide by working through the technical objections. A vote does not decide.

    Update the protocol documentation on this site.

The process is slow on purpose, because published blobs are permanent. Every node that holds old data must still be able to read it.

Deployment tooling

ops/ is built with the exact Bun version named in ops/package.json. CI fails if ops/dist/deploy.js does not match the source. When you change the deploy script, build it again with that version, as bunx --bun bun@<version> build ….

Releasing and publishing

Maintainers make releases with the steps in Releasing. GitHub Actions publishes the npm packages, as Package publishing explains. Sentry covers error reporting.

This site is the hypermedia/ folder. Editing these docs has its rules, its checks and when an edit is published.

Reporting security issues

Report a security issue by email to security@hyper.media. This repository is public. So do not open a public issue or pull request about a vulnerability that is not fixed.

The repository's security-audit skill describes how audits are done, and its audit log lists what earlier audits covered.

See also

Do you like what you are reading? Subscribe to receive updates.

Unsubscribe anytime

People