Contribute
Help build Homestead
Homestead is MIT-licensed and built in the open by AI agents and people working in parallel. Here's how the work is organised and where you can fit in.
Ways to help
Report what breaks
Run it, try the docs, and file what goes wrong. Good reports are half the fix.
Report a bugReview a language
Chinese and Thai strings wait for a native speaker's sign-off (task Q-02).
See the message filesImprove the docs
This website lives in its own repository. Every docs page has an "Edit this page" link.
Website repositoryPick up a task
Feature work is planned as tasks with clear paths and acceptance criteria.
Open the task board
How the work is organised
Homestead is developed one task at a time. Each task in work/tasks.yaml has a brief in docs/tasks/, a list of paths it may touch, dependencies and acceptance criteria. Right now 17 of 63 tasks are still open. An overseer reviews every branch, runs the checks again and merges into main.
- One task, one branch, one worktree. Branch
task/<ID>-<short-slug>from the latestmain, and touch only the paths your task allows. - Contracts aren't yours to change.
api/openapi.yaml, the database migrations,platforms/platforms.yaml,design/tokens.jsonandwork/tasks.yamlbelong to the overseer. Ask for a change in your handoff under Contract change request, with the exact diff. - Never hand-edit generated files. Run
make genand commit the output; CI fails on drift. - No analytics, telemetry, ads, trackers or remote fonts, and no Google services. Homestead must work in mainland China.
- New user-visible strings go in your feature's ARB namespace in all three locales.
- Accessibility is part of done: labels, focus order, 44 × 44 pt touch targets, contrast from tokens, and
prefers-reduced-motion.
Read CONTRIBUTING.md, AGENTS.md (short, and binding) and docs/13-parallel-workflow.md before your first change.
Set up your tools
The toolchains are pinned in mise.toml: Go 1.26, Node 22, pnpm 9, Flutter 3.24.5 and Java 17 (for the Dart API client generator), plus sqlc, oapi-codegen, staticcheck and govulncheck.
git clone https://github.com/aprajnaparamita/homestead.gitcd homesteadInstall the pinned toolchains with mise, then the JS workspace
make toolsServer on :8080 and the web app on :5173
make devOther useful targets: make mock-api (a Prism mock of the API on :4010, from the OpenAPI examples) and pnpm --dir web dev:mock (the web app against mock data).
Find your way around
| Path | What it holds |
|---|---|
server/ | Go server: REST API, MCP, connectors, feed engine, media, jobs. |
web/ | React 19 + TypeScript web app (Vite, React Router v7, Tailwind CSS v4). |
mobile/ | Flutter app for iOS and Android. |
extension/ | Firefox companion (WXT, Manifest V3). |
helper/ | Homestead Helper: native-messaging host that reads the Firefox cache. |
api/openapi.yaml | The API contract. Clients are generated from it. |
platforms/platforms.yaml | The platform registry. |
design/tokens.json | Design tokens for every client. |
i18n/ | Message files for en, zh_Hans and th. |
agents/ | Agent Skill and config examples for Hermes and OpenClaw. |
docs/ | The specification: product, architecture, API, feed, agents and more. |
work/tasks.yaml | The task board. |
Checks and tests
Before you hand off, from your task branch:
git fetch && git rebase origin/mainmake genmake checkmake scope-check TASK=<ID>make check runs every area: OpenAPI lint and contract checks, gofmt, go vet, staticcheck, govulncheck and race tests for the server and helper, typecheck, lint, tests, build and Storybook for the web app, dart format, flutter analyze and tests for mobile, the extension's checks plus web-ext lint, and a drift check on generated files. Targets for code that hasn't landed yet print not yet: <task>.
Pull requests and commits
- Fill the
## Resultsection of your task brief and use the pull request template: what changed, acceptance criteria and where each is tested, checks run, UI evidence (light and dark, three languages, 160 % text, narrow width), new dependencies, and any contract change request. - Commits follow Conventional Commits with the task ID, for example
feat(server): parse share-sheet text into candidates (S-03). - Reviewers check scope, checks, acceptance criteria, spec fidelity, security, quality, i18n and accessibility. Expect requests for changes; that's the process working.
Code of conduct
Homestead follows the Contributor Covenant: be welcoming, be kind, and keep the project free of harassment for everyone, whatever their background or experience. Report problems to the community leaders as described in the code of conduct.
Security issues never go in public issues. Use private vulnerability reporting.