Project Info

Wayfinder

Inspiration

Opening an unfamiliar repository feels less like reading a map and more like being dropped into a city with a list of street names. The files are all visible, but the practical questions remain: What does this project do? What should I read first? How do I run it? Where does a feature actually live? General chat tools can help, but they make users move context out of GitHub and can answer with a plausible path that does not exist. We wanted the experience of an experienced contributor sitting beside you, pointing at the real repository and saying, "Start here, run this, and this is the evidence."

What it does

Wayfinder appears as a small helper directly on GitHub. Guided mode turns the page into a friendly, project-specific tour. Quick mode gives the highlights without the homework. Ask how to install a finished app and Wayfinder can open GitHub Releases, detect the user's platform, and point to the packaged download instead of a source archive. Ask how to contribute and the same helper builds a clear route through setup, implementation, and verification. It can: summarize a repository and build a clickable reading route show a compact snapshot with stack, package manager, ref, commit, key directories, entry point, and local commands recognize a finished application, open GitHub Releases, detect the user's platform and architecture, and highlight the matching packaged download avoid steering regular users toward source archives, checksums, update metadata, or developer-only setup separate published-project installation from local repository development extract installation, development, test, and build commands from repository evidence label commands as documented, inferred, or conflicting find likely source files from a natural-language question turn a goal such as "I want to change speech generation" into a setup, implementation, and verification route use the active GitHub directory as ranking context classify the active file, route five distinct file actions, resolve explicit local dependencies, and show only target-specific caller and paired-test evidence open every recommended file at the mapped commit and known line range preserve the current trail while the user follows evidence through GitHub keep recent evidence available through temporary network or GitHub failures use GPT-5.6 to synthesize an ordered field brief from several typed tool results The free deterministic route remains fully functional. If the OpenAI key is missing, the model API is unavailable, structured output is invalid, or GPT-5.6 introduces a path or command outside the evidence set, Wayfinder returns the deterministic answer automatically. Paid synthesis is protected by a Cloudflare rate-limit binding and a persistent global budget matching the $100 event credit balance. A SQLite-backed Durable Object serializes spend reservations across all users, reconciles successful calls to actual Luna token usage, and fails closed to the deterministic answer. Cost protection therefore does not turn into a user-facing outage.

How we built it

The Chrome extension uses WXT, TypeScript, Shadow DOM, and Manifest V3. A content script tracks GitHub single-page navigation, renders the isolated helper, maps visible landmarks, calls the Worker, caches results locally, and keeps the complete experience on the active page. A TypeScript Cloudflare Worker provides explicit repository tools: repository mapper guided tour builder installation evidence extractor contextual file finder deterministic intent router multi-tool contribution orchestrator The mapper reads GitHub metadata, the exact viewed branch, tag, or commit, README content, setup landmarks, and a compact source tree. The file finder ranks the full filtered tree, then fetches only the five strongest small text candidates for content and symbol evidence. Current-file questions first distinguish source, test, documentation, configuration, data, and other files, then route summary, dependency, caller, test, and impact actions separately. Relationship results require target-specific evidence; documentation is summarized from its own headings instead of being treated as executable source. The install tool extracts documented commands with line references, limits repository-wide setup evidence to authoritative root and dedicated setup documents, verifies that consumer commands name the actual project, and uses manifests only for clearly labeled inference. GPT-5.6 Luna is connected through the OpenAI Responses API for contribution Trail Plans. The model receives the user's question and the completed typed evidence, uses the lowest reasoning level that passes our evaluation, and must return strict structured output containing a direct answer, explanation, citations, and up to four ordered actions. Responses are not stored. Before the answer reaches the extension, the Worker verifies that every model evidence path and action coordinate occurs in the deterministic result. Focused questions stay on the deterministic route, and successful model calls report token usage, latency, and estimated cost.

Challenges we ran into

The hardest problem was not generating an answer. It was deciding which parts of an answer deserved trust. Large repositories need aggressive filtering, but alphabetical truncation can hide the files that explain the architecture. Installation documentation mixes user setup, contributor setup, several package managers, and commands that look executable but are only examples. File names can also be deceptive. During the final dry run, src/pagination.ts looked like the perfect match, but source inspection revealed that it was a deprecated forwarding file. We changed the ranking to reorder candidates after content inspection and prefer the core implementation. We also needed a useful path before model credits arrived. That constraint produced a stronger architecture: deterministic tools are independently valuable, and GPT-5.6 improves interpretation without owning the facts. Accomplishments that we are proud of Every concrete command and file recommendation carries repository evidence. The extension works on public repositories without OpenAI credits. GPT-5.6 output is constrained by a strict schema and an exact-path allow-list. Paid model traffic has both per-client rate limiting and a persistent global budget cap. The same typed contracts drive free mode, model mode, caching, and the interface. Trail Plan combines orientation, sourced setup, implementation discovery, and related tests into one contributor workflow. Consumer install guidance can move from a repository to its Releases page and highlight the correct OS-specific installer in place. The production Worker is live and the Chrome package uses it automatically. The automated suite covers 178 unit and integration cases plus 49 complete browser workflows across URL context, late-rendered and off-screen landmarks, leave-and-return recovery on modern GitHub subpages, compact control clearance, editor focus and host-page shortcut containment, mode persistence, public request validation, ref correctness, latest-release and architecture selection, delayed release assets, per-tab navigation isolation, setup intent and evidence scoping, file-type-aware current-file context, model allowance fallback, global budget accounting, local and edge caching, repository mapping, tours, contribution routing, file ranking, model fallback, responsive layout, and keyboard focus visibility. A repeatable public smoke test passes across TypeScript, Python, Rust, Go, and a truncated JavaScript monorepo. The live public dry run correctly found src/core/pagination.ts in openai/openai-node after excluding its deprecated wrapper.

What we learned

An agent becomes more useful when its tools expose uncertainty instead of hiding it. Confidence labels, ranked alternatives, source lines, and explicit warnings are not secondary interface details. They are part of the reasoning system. We also learned that a model does not need to own retrieval to provide meaningful intelligence. GPT-5.6 can focus on intent and explanation while deterministic code maintains the boundary around repository facts. That division produces a better fallback and a more trustworthy primary experience.

What's next

expand the bounded likely-caller search into a complete symbol-aware call graph add private-repository authentication with an explicit consent flow add symbol-aware impact analysis beyond direct imports and paired tests support saved onboarding routes for teams and contributors add a VS Code surface that consumes the same Worker contracts

Wayfinder is a floating repository guide for public GitHub projects. Its compass helper points to real page landmarks, explains what they reveal, and expands into a complete repository agent without making the user leave GitHub.

Ask how to install a project, where a feature lives, what a file depends on, or how to plan a contribution. Wayfinder answers with commit-pinned paths, source-backed commands, confidence labels, and links that open the exact evidence.

Guided tour	Repository landmark

Why Wayfinder

GitHub exposes every file, but it rarely tells a newcomer what to read first, which setup path applies to them, or where a contribution should begin. Wayfinder turns those scattered clues into a navigable trail.

Experience	Best for	What it does
Guided	New contributors	Moves through visible GitHub landmarks and teaches the repository one step at a time.
Quick	Experienced developers	Opens a compact repository snapshot and focused task shortcuts without moving around the page.
Trail Plan	A concrete change	Combines sourced setup, likely implementation files, related verification, and an ordered reading route.

The deterministic tools remain fully useful without an OpenAI key. When the Worker is configured for GPT-5.6 Luna, contribution plans can receive an additional structured synthesis. Structured model output (evidence paths and brief steps) is strictly validated against the deterministic evidence and the whole synthesis is rejected on any mismatch; free-form prose is additionally screened by heuristics for unsupported paths and command shapes, which blocks common cases but is not a guarantee.

Try it locally

Wayfinder is not yet distributed through the Chrome Web Store. Build and load the production extension from source:

git clone https://github.com/Robertg761/Wayfinder.git
cd Wayfinder
corepack enable
pnpm install
pnpm --filter @wayfinder/extension build

Then:

Open chrome://extensions.
Enable Developer mode.
Select Load unpacked.
Choose apps/extension/.output/chrome-mv3.
Open a public GitHub repository.

Choose Guide me for the landmark tour or Quick map for the compact developer surface. Alt + Shift + W opens and closes Wayfinder from the keyboard.

Production builds call the public Worker at wayfinder-api.hopit-robert.workers.dev. No local Worker or API key is required for the deterministic public-repository experience.

What it can do

map repository, tree, branch, tag, commit, directory, and file context
preserve the requested ref and pin every answer to the resolved commit SHA
summarize the project, stack, package manager, entry point, and key directories
separate end-user installation from local contributor setup
extract commands from authoritative repository-level setup evidence, verify consumer commands name the project, and label documented or inferred steps
find likely implementation files with reasons, signals, confidence, and direct links
classify the active file and answer summary, dependency, caller, test, and impact questions separately
build a Trail Plan from a concrete contribution goal
keep saved trails and recent evidence available across GitHub navigation or a temporary network failure
guide users to the newest compatible GitHub Release without guessing their operating system or processor

Evidence before prose

Wayfinder treats trust as a product feature:

Repository identities, refs, paths, sizes, and timestamps are validated at the Worker boundary.
Commands carry a repository source and inferred commands are labeled.
File relationships require target-specific evidence; possible matches do not become headline claims.
Model responses use strict structured output and an exact evidence allow-list.
Missing credentials, exhausted allowance, invalid model output, or upstream failure returns the deterministic answer instead of breaking the task.

See Architecture for the complete trust boundary and Privacy for data flow and retention.

Architecture

GitHub page
  └─ Chrome extension (WXT + Shadow DOM)
       ├─ visible landmark guide
       ├─ local commit-aware cache
       └─ public Worker request
            ├─ GitHub repository mapper
            ├─ deterministic tour, install, find, and file-context tools
            ├─ contribution orchestrator
            └─ optional GPT-5.6 Luna synthesis

Workspace	Responsibility
`apps/extension`	Manifest V3 extension, page helper, navigation, caching, and evidence UI
`apps/api`	Cloudflare Worker, GitHub retrieval, deterministic tools, model guardrails, and budget controls
`packages/contracts`	Shared request, response, repository-map, and answer contracts
`tests/browser`	Full extension workflows against deterministic GitHub fixtures
`scripts/verify-public.mjs`	Repeatable semantic matrix against real public repositories

Local development

Requirements: Node.js 22 or newer and pnpm 10.

pnpm install
cp apps/api/.dev.vars.example apps/api/.dev.vars

Both credentials are optional for public-repository development:

GITHUB_TOKEN=
OPENAI_API_KEY=
OPENAI_REASONING_EFFORT=low

Start the Worker and extension in separate terminals:

pnpm dev:api
pnpm dev:extension

Development extension builds use http://localhost:8787. Set WXT_WAYFINDER_API_URL to test another Worker origin.

Worker routes

Route	Purpose
`GET /health`	Deployment, model, limiter, and budget status
`POST /map`	Repository metadata, tree, README, setup, and commit mapping
`POST /tour`	Deterministic page-landmark tour
`POST /guide/install`	Consumer or contributor setup evidence
`POST /find`	Context-aware repository file discovery
`POST /agent`	Intent routing, file context, Trail Plan, and optional Luna synthesis

Verification

pnpm typecheck
pnpm test
pnpm test:browser
pnpm build
pnpm --filter @wayfinder/extension zip

The browser suite launches Chromium with the unpacked extension and covers reloads, GitHub SPA navigation, narrow and dark layouts, keyboard behavior, reduced motion, setup intent, release selection, evidence navigation, cache isolation, and failure recovery.

After deploying the Worker, run the real-repository matrix:

pnpm smoke:public node python rust go monorepo

The matrix currently covers openai/openai-node, pallets/flask, BurntSushi/ripgrep, cli/cli, and vercel/next.js. Results and pinned coordinates are recorded in Verification matrix.

The optional live Luna evaluation requires OPENAI_API_KEY:

pnpm eval:luna

Project documentation

Contributing

Issues and pull requests are welcome. Start with CONTRIBUTING.md, preserve the evidence rules, and include a focused regression whenever ranking or repository-task behavior changes.

License

Wayfinder is available under the MIT License.

Analysis

Compare with all teams

View

Metric

Robertg761
51

Figures cover GitHub contributors during the hackathon window. A co-authored commit counts in full for each author, so per-member totals add up to more than the whole-team figures.

Technology

Found in codeClaimed only

TypeScriptIn code
OpenAIClaimed

1 of 2 appear in the indexed code. 1 claimed on Devpost could not be matched to code, which may simply mean the tool leaves no trace in the repository.

AI coding agents

Claude CodeConfig · Commits

Detected from committed agent config files and commit authorship. Absence of a signal is not proof an agent was unused.

Codebase size

Source size

766 KB

Source files

Counts recognized source files only; vendored directories, binaries and lockfiles are excluded, so this is smaller than the repository on disk.