homehub
AGENTS.md1.3k starsChanged 6 days agoMITView on GitHub
This file is for anyone changing HomeHub, people and coding agents alike. Read it before you open a pull request. HomeHub is a self-hosted family app: Flask, SQLAlchemy on SQLite, Jinja templates and Tailwind 3, shipped as a Docker image. It runs on a home network for one household, and people upgrade by pulling a new image over their existing data. Most rules below exist to keep those upgrades safe. Then docker compose up -d --build. Never edit compose.yml for…
- Reads credentials
- Installs packages
Trending
More talk lately.thin dataabout the whole repository
Who's talking about surajverma/homehub
- @tom-doerr.bsky.social“https://github.com/surajverma/homehub”Bluesky · Feb 23, 2026 · 1 likes
- AKhozya/homelab“chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.7.0”GitHub · Nov 10, 2026
- AKhozya/homelab“chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.6.0”GitHub · Nov 5, 2026
- AKhozya/homelab“chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.5.0”GitHub · Oct 31, 2026
- AKhozya/homelab“chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.4.1”GitHub · Oct 14, 2026
The biggest 5 of 6 mentions linking to the repository that our crawl found. Each line is their own headline.
See all 6
Talked about on GitHub and Bluesky (6 times).
On GitHub · 5
- Nov 10, 2026chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.7.0 — AKhozya/homelab0 reactions
- Nov 5, 2026chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.6.0 — AKhozya/homelab0 reactions
- Oct 31, 2026chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.5.0 — AKhozya/homelab0 reactions
- Oct 14, 2026chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.4.1 — AKhozya/homelab0 reactions
- Oct 11, 2026chore(deps): update ghcr.io/surajverma/homehub Docker tag to v0.4.0 — AKhozya/homelab0 reactions · 1 comment
On Bluesky · 1
- Feb 23, 2026https://github.com/surajverma/homehub — @tom-doerr.bsky.social1 likes and repost
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository2 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- code-reviewSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 34
Run them with python -m pytest.
- Very specific: line 38
Never run the app or a flask command on the host against a data/ folder that a running container uses: two processes writing one SQLite …
- Distinctive: line 39
If a test already fails on main, it is not yours to fix in an unrelated PR.
- Very specific: line 67
Do not edit config-example.yml or the config sample in the README.
- Distinctive: line 68
Write "Part of #81" in the description, not "Closes #81".
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working on HomeHub
This file is for anyone changing HomeHub, people and coding agents alike. Read it before you open a pull request.
HomeHub is a self-hosted family app: Flask, SQLAlchemy on SQLite, Jinja templates and Tailwind 3, shipped as a Docker image. It runs on a home network for one household, and people upgrade by pulling a new image over their existing data. Most rules below exist to keep those upgrades safe.
Layout
app/holds the application:blueprints/for the pages,api/for the token-protected JSON API under/api/v1(including the MCP endpoint),models.py,migrations.py,security.py,admin.pyandi18n.py.templates/holds the Jinja pages andstatic/js/the page scripts.translations/holds onemessages.poper language and themessages.pottemplate.docs/holds the API guide (api.md), the generatedopenapi.jsonand the calendar feed guide.tests/holds the pytest suite.
Running it
config.ymlis gitignored. Without it,python run.pyruns on the defaults fromconfig-example.yml, and the tests always use their own temporary copy ofconfig-example.yml. Copyconfig-example.ymltoconfig.ymlwhen you want to customise a local instance.- With Docker: copy
config-example.ymltoconfig.ymlbefore the firstdocker compose up -d. Compose mounts that path, and if the file is missing Docker creates a folder namedconfig.ymlin its place. If that happened, stop the container, delete the folder, copy the file and start again. To try local code changes in Docker, build the image from the checkout with a
compose.override.ymlnext tocompose.yml(it is gitignored, and Compose reads it automatically):services: homehub: build: . pull_policy: buildThen
docker compose up -d --build. Never editcompose.ymlfor this (see below)..dockerignorekeepsconfig.yml,data/,uploads/,media/andpdfs/out of the image; keep it that way, so a local build never carries the site password or household files.- Without Docker:
pip install -r requirements-dev.txt,npm install,npm run build:css, thenpython run.py. SetFLASK_DEBUG=1for auto-reload. Media downloads need FFmpeg and PDF compression needs Ghostscript (gs) on your PATH; the Docker image has both. Without Ghostscript, PDF compression quietly keeps an unchanged copy of the file. - The Docker image compiles the translations itself. Outside Docker, run
flask translations compilebefore testing a language other than English, or the pages stay in English.
Tests
- Run them with
python -m pytest. CI runs the same command on every pull request (.github/workflows/tests.yml). - Each test file builds its own app with
create_app({'TESTING': True, 'SQLALCHEMY_DATABASE_URI': 'sqlite://', 'SECRET_KEY': 'test'}), astests/api_support.pydoes. Set bothTESTINGand the in-memory database: withoutTESTING,create_appruns the startup migrations against the realdata/app.dbin your checkout, which moves old calendar trash into the shared Trash, rebuilds tables and marks pending downloads as failed. - That setup creates the current schema and skips the startup migrations, so it cannot test an upgrade. To test a migration, follow
tests/test_migrations.py: build an old-style database file undertmp_pathwithsqlite3, callmigrations.run(path)on it, and check the result. Also check that running it twice is harmless. - Changes to permissions, money calculations, startup migrations or anything security related should come with tests.
- Never run the app or a
flaskcommand on the host against adata/folder that a running container uses: two processes writing one SQLite file can corrupt it. Run commands inside the container (docker exec -it homehub flask ...), or against a copy. - If a test already fails on
main, it is not yours to fix in an unrelated PR. Make sure your change adds no new failures.
Upgrades must not break existing installs
The goal: people upgrade by pulling the new image and starting it. Nothing else, no commands to run, no manual migration. If an upgrade step fails, the app keeps running and the step is retried at the next start.
- There is no Alembic.
app/migrations.pyupgrades existing databases at startup. - A new column on an existing table needs both the model field and an entry in
COLUMNSorLATE_COLUMNSinapp/migrations.py, with a default that makes sense for old rows. Without it, existing installs crash with "no such column". - A new table needs a
CREATE TABLE IF NOT EXISTSinTABLES, or must be safe to create throughdb.create_all(). - Migrations must be additive and safe to run again. Do not rename, drop or change the type of a column. A column the code no longer needs stays in the table; leave a comment on its model field saying it is unused or what it is still kept for (see
Reminder.deleted_at). - One exception: a table may be rebuilt to change what SQLite cannot
ALTER, such asAUTOINCREMENT. Do it only throughuse_autoincrement-style code inapp/migrations.py: one transaction per table; every column, value, default, index and foreign key kept; skipped when already done; and a test intests/test_migrations.pythat upgrades an old database, runs it twice, and makes the rebuild fail part way. - Deleting something a person made (a reminder, an item, a note, an expense...) goes through the shared trash (
app/undo.py,app/trash.py), so it can be undone and restored for 7 days. The API and MCP never delete for good. A new module with deletable records joins the trash, and its table usesAUTOINCREMENT(__table_args__ = TRASHABLEinapp/models.py), so an id is never handed out twice. - A new
config.ymlkey needs a default in code and an entry inconfig-example.yml. An existingconfig.ymlwithout the key must keep working.
Text and translations
- Every piece of text a user sees is translatable. In Python and templates wrap it in
_(), orngettext()for counts. Instatic/jsuset('text', {params}),th()when the result goes into an HTML string,tn(one, other, count)for counts andtc('context', 'text')when one English word needs different translations. - A sentence with a name, number or link in it is one string with a placeholder, never pieces glued together, so each language can put the value where its grammar needs it.
- After adding or changing text, run
flask translations updateto refreshmessages.potand everymessages.po. Leave newmsgstrentries empty unless you are a translator for that language; untranslated text falls back to English. The maintainer fills in the Hindi before each release; the tests only check that existing translations keep their placeholders. - The compiled
.mofiles are build output and are not committed. - What people type into HomeHub (notes, chores, names) is never translated.
Translation pull requests
These follow the rules in issue #81:
- Comment on #81 with your language before starting, so two people do not translate the same one.
- The PR changes only
translations/<code>/LC_MESSAGES/messages.po, adds that language's row to the Supported languages table in the README, and, only for a script that is not Latin, Cyrillic or Greek, adds one line toLANGUAGE_FONTSinapp/i18n.py. - Do not edit
config-example.ymlor the config sample in the README. - Write "Part of #81" in the description, not "Closes #81".
- Keep placeholders such as
%(name)sand{count}exactly as they are, and add no links or HTML.tests/test_i18n.pychecks both. One exception: a plural form may leave out the number (%(num)s,%(num)dor{count}) when the wording already says it, as in "one day left". Every other placeholder must stay. - Partial translations are welcome. Right-to-left languages are not supported yet.
API documentation
docs/openapi.json is generated from the API's operation registry, and a test fails when it is out of date. After any change to /api/v1 operations, run python -m app.api.openapi and commit the regenerated file. Update docs/api.md when the behaviour it describes changes.
Security habits
HomeHub is meant for a trusted network, but a page on another website, a crafted link or one household member can still reach it. Keep these in place:
- Outbound fetches. Any server-side request to a URL a user supplied goes through
is_url_safe_for_fetchinapp/security.py, which refuses anything that is not http(s) or that resolves to a private, loopback or link-local address. It checks only the URL it is given, so a client that follows redirects on its own could still be sent to an internal address. Turn automatic redirects off, or check each new destination withis_url_safe_for_fetchbefore following it. Do not add a fetch that skips these checks. - Cross-site requests. There are no per-form CSRF tokens. Instead, the before-request hook in
app/blueprints/auth.pyrefuses any POST, PUT, PATCH or DELETE that the browser says came from another site (Sec-Fetch-Site, orOriginon older browsers). Keep that check ahead of everything else, and never change data a person chose from a GET request (a GET may still do time-based housekeeping, such as generating recurring items that are due or purging expired trash).tests/test_cross_site.pycovers it. - User content. Plain text goes through
sanitize_textand rich text throughsanitize_htmlbefore it is stored. Jinja autoescaping is on; do not add|safeunless the value was cleaned withsanitize_html. In page scripts, useth()or escape values before putting them into HTML strings. - Links. A standalone URL field (such as a recipe or media link) must hold an http(s) URL (
is_http_url). Refusejavascript:and other schemes when saving, and do not render old stored values that fail the check as clickable links. Links inside rich text are handled bysanitize_html, which also keepsmailto:andtel:links. - Uploads. Filenames go through
secure_filenameand files are served withsend_from_directory, so a name cannot escape its folder. - Permissions. Admin checks go through
is_admin(user)inapp/admin.py; never compare a name toadmin_nameor'Administrator'directly. Editing or deleting an item that belongs to its creator goes throughcan_modify(user, <owner field>)in the same file, not a hand-writtenis_admin(user) or user == owner: the helper refuses a locked session that names the admin to reach an admin-owned record. An empty user never owns anything:can_modifyrefuses a blank name, so a request without a user cannot reach a record saved without a creator. Some actions are shared on purpose and have no owner check, such as ticking a shopping item or marking a chore done; keep them open to everyone, and do not addcan_modifyto them. API tokens only open/api/v1and only what their scopes allow, and an upgrade never widens what an existing token can do: a new ability needs a new token or an explicit grant (seedelete_scopeinapp/api/tokens.py). - Secrets. Passwords, hashes, API tokens and
SECRET_KEYare never logged, flashed, rendered or returned in JSON, and password checks fail closed. The one exception is a new or regenerated API token: the admin page shows it once, in the response that creates it, so it can be copied, because HomeHub keeps only a fingerprint. That response must not be cached (Cache-Control: no-store), and the token must never appear again after it. Undo tokens are secrets too: holding one restores a change without an owner check, so it goes only to the browser or client that made the change, never into a page others can see (the Trash page usesentry_stampandentry_refinstead).
To report a vulnerability, see SECURITY.md.
Server
- The Docker image runs one gunicorn process with threads (
-w 1in theDockerfile). Keep it that way: SQLite, the media download threads and the lock that stops two requests generating the same recurring item all assume a single process.
Releasing
- Fill in the empty Hindi entries in
translations/hi/LC_MESSAGES/messages.po. - Mention in the release notes anything the startup upgrade changes that people would notice.
Front end
- Tailwind 3. Dark mode is switched on by
data-theme="dark"on<html>(darkMode: ['selector', '[data-theme="dark"]']intailwind.config.js), not by adarkclass. New UI needsdark:variants matching the markup around it and must work at phone width. static/output.cssis built bynpm run build:cssand is not committed.
Files that must not be committed
compose.ymlis the published config and points atghcr.io/surajverma/homehub:latest. Do not commit a switch to a local build (such as uncommentingbuild: .) or other local edits to it; local settings go in the gitignoredcompose.override.yml.config.yml,.env,data/,uploads/,media/,pdfs/, compiled.mofiles andstatic/output.cssare local data or build output.
Reviewing a change
.github/skills/code-review/SKILL.md says how to review against the rules in this file. In short, look for:
- a new column without a migration entry, a migration that is not additive, or a migration change tested only through
create_app(which skips migrations in tests); - an owner-only edit or delete without
can_modify, or an admin check that bypassesis_admin; - unsanitised input, a new
|safe, an unchecked outbound fetch or an unchecked link; - money split with plain float division instead of the existing split helper in
app/blueprints/expenses.py, so the parts no longer add up to the total; - edits to recurring items that rewrite past occurrences by accident;
- new user-facing text that is not wrapped for translation, or an API change without a regenerated
docs/openapi.json; Model.query.get(id)in new code, wheredb.session.get(Model, id)is preferred;- any of the files listed above in the diff.
Lead each comment with the concrete failure (what input or state goes wrong, and what happens), put it on the line that causes it, and mark optional suggestions as optional. Skip style nits where the surrounding code already does the same thing.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

