Pick a mission.
Ask to board.
A human says yes.

01

Orientation

BetterHackdays is an open-source Hack Day room: it connects coding agents, matches people into teams, and turns pasted event text into a shared kickoff plan. The RFP Connector is the part of BetterHackdays that opens KnowB's project requests for proposals to outside builders.

Run the connector as an MCP server inside the agent you already use, or call the same functions over REST. Either way you can:

02

Quickstart

You need Python 3.12, Git, and an MCP-capable agent such as Claude Code. Reading RFPs needs no account. Submitting a request needs a GitHub token for your own account, because the token is how the connector knows who you are.

1. Clone and install

   git clone https://github.com/knowb-ai/BetterHackdays.git
   cd BetterHackdays
   python3 -m venv .venv
   .venv/bin/pip install -r requirements.txt
   

2. Connect your agent

   Pick your client. Run the command from the repository root so the paths resolve.

   Claude CodeAny MCP clientREST

   claude mcp add betterhackdays \
     -e PYTHONPATH="$PWD" \
     -e DATABASE_URL="sqlite:///$PWD/betterhackdays.db" \
     -- "$PWD/.venv/bin/python" -m app.mcp_server
   claude mcp list   # betterhackdays: ... ✔ Connected
   

3. Ask in plain language

   Your agent picks the right tool. Try:

   • “List the KnowB RFPs and group them by theme.”
   • “Compare MarkSweep and Subtracktor for a two-person weekend team.”
   • “Would a calendar-aware inbox triage idea qualify for the catalogue?”
   • “Draft an expression of interest for Underminer and show me the preview.”

4. Add your identity, only to send requests

   Give the server a fine-grained GitHub token for your own account in GITHUB_TOKEN. Keep it in your client's local config or a secret manager, never in a repository or a chat message. The connector resolves your login from the token with GitHub; it never accepts a login you type.

03

Explore RFPs

The connector serves two kinds of entry. Website RFPs are the open briefs listed on knowb.run. Live projects are public repositories already in motion that welcome help. Idea suggestions are kept separate, so a brainstorm is never mistaken for a commitment.

Generated from the connector's approved public entries when this site was built. Ask the connector for full briefs, scope, outcomes, and safety boundaries.

The four exploration tools

Building something that should look like it belongs to KnowB? The design tools read an allowlist of public files from the knowb.run repository: the design system, brand guidelines, the Org Book, stylesheets, and the pixel icon dictionary.

04

Refine ideas

The idea catalogue lives in Cloud Builder Stack, and it stays there. The connector fetches it live each time and fails closed: if the catalogue cannot be read, you get an honest source_unavailable, never a stale copy.

1. Fetchfetch_idea_catalogue

   Read suggestions live, filtered by query or section.

2. Qualifyqualify_idea

   A deterministic check against the catalogue, open public projects, and the knowb.run showcase. Duplicates and showcased work come back not_eligible.

3. Proposepropose_idea_catalogue_addition

   Previews by default. With submit, it opens a pull request to Cloud Builder Stack, only after a human-reviewed rationale, a named reviewer, and that repository's review rules all check out.

A proposal is a pull request, never a direct write. Cloud Builder Stack's maintainers merge or decline it.

05

Contributor requests

Request types

How a request travels

1. 1
   Preview. Call preview_contributor_request with a type, an RFP ID, the scope you want, and a short message. Nothing is sent. Read the draft, and fix it if it is wrong.
2. 2
   Submit. Call submit_contributor_request. The connector verifies your GitHub identity from your token and checks your permission on BetterHackdays. If either check fails you get unauthorized, and nothing leaves your machine.
3. 3
   Route. The request is recorded privately and sent to the maintainers at ping@knowb.run. If mail is not configured, you get the complete addressed draft back, plainly marked not sent, to send yourself.
4. 4
   Review. A repository owner reads it and decides. If they approve access, they send the GitHub invitation themselves. Track your own requests with list_contributor_requests.

Write requests the way you would write to a person: what you want to work on, why, and what you have built before. Leave out passwords, tokens, and private data.

06

Permission boundaries

The connector is built to be safe to hand to an agent. These rules are enforced in code and covered by the test suite.

Identity comes from GitHub, not from you

Request bodies and tool arguments never carry identity or role claims. The connector resolves your login from your token with the GitHub API and ignores any login or role that is typed in.

Exact permission, exact repository

Every write checks your live permission on the one repository it targets. Requests need read or higher on BetterHackdays; work elevation needs write or higher.

The bot's scope is checked too

Writes made through the KnowB GitHub App must fit the scopes that app was installed with, and only on an allowlist of public KnowB repositories.

Access grants are owner-only, and preview-only here

grant_repository_access only ever returns a dry run over MCP. Real invitations are sent by the repository owner, by hand.

Failures close, never open

If GitHub, the catalogue, or an installation lookup cannot be reached, the answer is a refusal or source_unavailable, never a guess.

Only public material leaves the connector

RFP briefs are curated summaries. Design resources come from an explicit allowlist of public files. Entries that are not approved for the public never appear on this site.

07

Reference

Both references below are rendered from data/reference.json, which scripts/build_site.py generates from the running code. A test fails if it falls out of date.

MCP tools

29 tools registered by betterhackdays-hack-day.

Explore RFPs

list_project_rfps(visibility: Optional[str] = None)

search_project_rfps(query: str, include_design_resources: bool = False)

read_project_rfp(rfp_id: str)

compare_project_rfps(rfp_ids: list[str])

Public design resources

list_design_resources()

search_design_resources(query: str)

read_design_resource(path: str, repo: str = 'knowb-ai/knowb-ai.github.io')

Refine ideas

fetch_idea_catalogue(query: Optional[str] = None, section: Optional[str] = None, limit: Optional[int] = None)

qualify_idea(title: str, summary: str, alignment_evidence: Optional[str] = None, human_reviewed_rationale: Optional[str] = None, reviewed_by: Optional[str] = None)

propose_idea_catalogue_addition(title: str, summary: str, alignment_evidence: Optional[str] = None, human_reviewed_rationale: Optional[str] = None, reviewed_by: Optional[str] = None, section: str = '10. Stronger Actual AI System Ideas', submit: bool = False)

Contributor requests

preview_contributor_request(request_type: str, rfp_id: str, requested_scope: str, message: str)

submit_contributor_request(request_type: str, rfp_id: str, requested_scope: str, message: str)

list_contributor_requests()

Permission guards

authorize_github_mutation(operation: str, target_repo: str, expected_target_repo: Optional[str] = None)

grant_repository_access(target_repo: str, grantee_login: str, permission: str = 'write', requester_login: Optional[str] = None, confirmed: bool = False)

Hack Day room

connect_harness(harness_id: str)

update_profile(harness_id: str, display_label: Optional[str] = None, skills: Optional[list[str]] = None, interests: Optional[list[str]] = None, preferred_role: Optional[str] = None, project_vibe: Optional[str] = None, looking_for: Optional[list[str]] = None, availability: Optional[str] = None)

start_survey(harness_id: str)

answer_survey(harness_id: str, answer: str)

get_survey_state(harness_id: str)

get_match_cards(harness_id: str)

like_profile(from_harness_id: str, to_harness_id: str)

pass_profile(from_harness_id: str, to_harness_id: str)

get_matches(harness_id: str)

ingest_event_text(text: str, source_label: str = 'Pasted event text', source_url: str | None = None)

rank_idea_suggestions(event: Any, profile: Any = None, team: Optional[list[Any]] = None, topics: Optional[list[str]] = None)

generate_process_timeline(event: Any, profile: Any = None, team: Optional[list[Any]] = None, hack_day: Any = None, team_room: Any = None, workspace_repo: Any = None)

generate_prep_checklist(event: Any, profile: Any = None, team: Optional[list[Any]] = None, hack_day: Any = None, team_room: Any = None, workspace_repo: Any = None)

resolve_slug(raw_input: str, hack_days: list[dict[str, Any]], standalone_slugs: Optional[list[dict[str, Any]]] = None, caller_participant_id: Optional[str] = None)

REST API

The REST routes call the same functions as the MCP tools. Routes marked Bearer token read your identity from an Authorization: Bearer header and nothing else.

28 routes served by app.main:app. Interactive docs run at /docs on any local server.

RFPs

Design resources

Ideas

Contributor requests

Hack Day room

08

Configuration

All settings are environment variables. Copy .env.example to .env for local runs. Everything is optional for reading.

09

Deploying this site

This manual is a Zola site in site/, published by GitHub Pages from the BetterHackdays repository to the custom domain hack.knowb.run. It has no tracking and no third-party scripts.

Writing docs

Every section of this page is a Markdown file in site/content/, ordered by weight. To add one, create a file with a title and a weight; it joins the index and search automatically. Components are shortcodes in site/templates/shortcodes/: alert, note, cards, minis, pipeline, route, guarantees, step, and faq.

zola --root site serve                   # live preview at http://127.0.0.1:1111
.venv/bin/python scripts/build_site.py   # refresh the generated reference

Pipeline

1. Checkbuild_site.py --check

   On every pull request, the docs test confirms data/reference.json matches the code.

2. Build.github/workflows/pages.yml

   Installs Zola, checks the reference again, runs the docs tests against the built site, and builds site/public.

3. Servehack.knowb.run

   On a push to main, GitHub Pages serves the build over HTTPS with a certificate it issues for the custom domain.

Custom domain setup

Done once, by a repository admin and the owner of the knowb.run DNS zone.

1. Enable Pages from Actions

   Repository settings, Pages, Source: GitHub Actions. Or:

   gh api -X POST repos/knowb-ai/BetterHackdays/pages -f build_type=workflow
   

2. Add the DNS record

   At the knowb.run DNS host:

   Type	Host	Answer
   CNAME	hack	knowb-ai.github.io

3. Set the custom domain

   Pages deployed by Actions ignore a CNAME file, so set the domain in settings or with:

   gh api -X PUT repos/knowb-ai/BetterHackdays/pages -f cname=hack.knowb.run
   

   site/static/CNAME ships with every build as a record of the intended domain.

4. Enforce HTTPS

   Once GitHub has issued the certificate, usually within an hour of DNS resolving:

   gh api -X PUT repos/knowb-ai/BetterHackdays/pages -F https_enforced=true
   

5. Verify the domain

   Verify knowb.run for the knowb-ai organization under organization settings, Pages, so no other account can claim hack.knowb.run.

Verify a deployment

dig +short hack.knowb.run CNAME             # knowb-ai.github.io.
curl -sI https://hack.knowb.run | head -1   # HTTP/2 200
gh api repos/knowb-ai/BetterHackdays/pages --jq '.cname, .https_enforced, .status'

10

FAQ

11

Contributing

BetterHackdays is developed in the open at knowb-ai/BetterHackdays. Issues and small, reviewable pull requests are welcome.