Prepare before the hackathon
This public guide is for participants who want to arrive with the basic tools and mental models already in place. It focuses on Claude Code, model settings, context management, GitHub, and local TypeScript app development at a practical introductory level.
This page intentionally leaves out event app URLs, assignment tables, passwords, tokens, private repository names, and privileged infrastructure runbooks.
Internal event docs and working materials live in the Polaris Event repository. That repository is login-gated: you need a GitHub account with event access before the link will open.
Navigation
- First thirty minutes
- Claude Code in Claude Desktop
- Model selection, effort, and context
- Git, GitHub, pull requests, merge, and Actions
- Local and inner development
- Local-first event model
- Optional short videos
The first thirty minutes
The goal is not to master every tool before the event. The goal is to know the workflow well enough that you can ask good questions, avoid unsafe mistakes, and make your first small pull request.
Work inside the assigned application repository, not in personal folders.
Ask Claude Code to read repo instructions before it edits files.
Keep the first change deliberately small and easy to review.
Run the smallest useful check, then open a focused pull request.
Claude Code in Claude Desktop
For this event, start from the Claude Desktop app and use the Code tab. The Code tab gives you Claude Code through a graphical interface with chat, file editing, diff review, an integrated terminal, and live preview panes. You do not need to start from a standalone terminal.
Open the Code tab
- Open Claude Desktop.
- Sign in with the account you will use for the event.
- Select the Code tab.
- Start a local session and choose your assigned app repository folder.
- Keep the diff, terminal, file, and preview panes available while you work.
If the Code tab is missing or a local session will not start, update Claude Desktop and ask a facilitator for a workstation setup check.
Use the integrated terminal
The Desktop app includes a terminal pane that opens in the current session’s
working directory. Use that terminal for commands such as git status,
docker compose up -d db, app setup, tests, and formatters. Keep hackathon
repositories under a dedicated folder and choose only the assigned app
repository as the session workspace.
Choose a mode
Claude Code has modes that control how much it acts on its own.
| Mode | Use it for | Event guidance |
|---|---|---|
| Plan | Understanding the repo, asking questions, proposing files to touch, and checking risk before edits. | Start here by default. Use Plan whenever the task is unclear, risky, or larger than a tiny text change. |
| Auto | Implementing after the scope and plan are clear. | Shift into Auto once you understand what Claude is about to do and want it to run the workflow end to end. |
| Accept Edits | Reviewing proposed file changes before they are accepted. | Use this when you want tighter control over each edit, especially early in the event or in unfamiliar code. |
The recommended flow is: start in Plan, agree on the task and files, then move to Auto for implementation. If you want to stay more hands-on, use Accept Edits instead of Auto.
Use this first prompt
Read README.md, AGENTS.md, and CLAUDE.md first.
Explain how this repo is organized, how I run it, and what commands I should use for tests and formatting.
Do not edit files yet.
That prompt gives Claude the local contract before it starts making assumptions. If the repository does not have every file named in the prompt, Claude should say so and continue with the files that exist.
Model selection, effort, and context
Model selection
Models differ in speed, cost, context size, and reasoning quality. For the beginning of the hackathon, use one shared default so the group spends time building instead of tuning.
Later in the event, you can step down to a faster or cheaper model for very small edits, but do that only after your first PR workflow is working.
Effort
Effort controls how much reasoning Claude spends on a task. Lower effort can be faster, but it may skip planning, search, or edge cases. During the event, predictable quality is more useful than saving a little time on the first few tasks.
Use the effort menu in the Desktop Code tab and set effort to high for implementation, debugging, migrations, pull request review, and anything where missing a detail could create extra work for the team.
Context window
The context window is Claude’s working memory for the current session: prompts, file reads, tool output, diffs, plans, and prior answers. A large context window helps with bigger codebases, but it is not infinite attention.
Watch the context or usage ring near the model picker. When the dial is high, Claude may become less precise, over-rely on old information, or compact important details. Restarting is normal.
Summarize the current task, important decisions, changed files, commands run, and remaining next steps so I can continue in a fresh Claude Code session.
Good times to restart Claude Code:
- after a pull request is merged or abandoned,
- after a large debugging session,
- when switching to a different story or branch,
- when Claude starts mixing old assumptions with the current task.
Git, GitHub, pull requests, merge, and Actions
Claude Code will normally handle most of this workflow for you: checking the diff, creating commits, pushing branches, opening pull requests, and helping interpret Actions failures. It is still important to understand the flow because every code change goes through it, and you are responsible for reviewing what Claude Code proposes before it is merged.
Git keeps a local history of your code changes. GitHub hosts the shared repository. A pull request is the review page where your branch is checked before it becomes part of the main branch.
The normal loop
git status
git switch -c feature/small-story
# edit files
git status
git diff
git add changed-file
git commit -m "Add small story"
git push -u origin feature/small-story
Open a pull request after the branch is pushed. You can use the GitHub website or the GitHub CLI.
gh pr create --fill
gh pr status
What a good pull request contains
- one focused behavior change,
- a short explanation of why it exists,
- the command or manual check you ran,
- any migration or risk reviewers should know about,
- no secrets, private credentials, or unrelated files.
Merge
Merge only after the PR is reviewable and the required checks are green. If the PR is too broad, split it. If a reviewer asks for a change, update the same branch and push again.
GitHub Actions
GitHub Actions are automated checks and release jobs attached to the repository. They usually run tests, formatting, builds, image publishing, or deployment steps. When Actions fail, start with the first real failure in the log, not the last line of the job.
Here is the first real GitHub Actions failure:
<paste log excerpt>
Explain what failed, whether it looks like app code or CI setup, and the smallest fix to try first.
Do not change secrets or platform configuration.
Local and inner development
Your inner development loop is the fast cycle you run before a PR: change code, preview locally, run a small check, and inspect the diff. The point is to speed up feedback on changes while they are still cheap to fix, before a pull request, CI run, or deployment tells you something is wrong. The app repository README is always the source of truth for exact commands.
Recommended prompt:
Read README.md, AGENTS.md, and CLAUDE.md first.
Start the local preview for this app using the repository instructions.
Use the integrated terminal, start only the services needed for local preview, and tell me the local URL to open.
If setup fails, stop and explain the first real error before changing files.
Typical local checks
| Goal | Example command |
|---|---|
| Inspect repo state | git status |
| Install dependencies | npm ci |
| Run TypeScript app | npm run dev |
| Apply database migrations | npm run db:deploy |
| Run tests | Use the exact test command in the app README |
Docker and images
Docker packages services so they can run consistently on different machines.
For the local-first TypeScript app path, the shared Docker task is starting the
PostgreSQL service named db. Use the app README for exact setup, migration,
test, and dev-server commands.
docker compose up -d db
docker compose ps db
docker compose logs db
docker compose down
After the database is running, use the TypeScript app commands from the README. The common shape is:
npm ci
npm run db:deploy
npm run dev
docker compose up --build as the default event
command. The common Compose service is the database service db;
the app itself is normally run with the stack command from the README.
Local preview
After the app is running, open the local URL named by the README and check the specific route or behavior you changed. For UI changes, inspect the page in a browser before opening a PR. For backend changes, run the smallest route, form, or test that proves the behavior.
Local-first event model
The first event round showed that most participant value came from local app work, not from the shared runtime. The next-round default is therefore simpler: run the assigned TypeScript app locally, keep PRs small, and demo from local preview unless facilitators explicitly add a shared publish step.
You run the assigned TypeScript app on your machine.
You make one user-visible improvement.
You run the smallest useful local verification.
You share the diff, local URL, and verification result.
Participants should not need infrastructure credentials, Kubernetes access, cloud-provider access, or a separate infra repository for normal event work.
Participant-owned problems
- local setup and README commands,
- failing tests caused by your change,
- broken app routes, UI, migrations, or validation,
- pull request scope and review feedback.
Facilitator-owned problems
- missing repository access,
- workstation tools that are missing or broken,
- unclear app assignment,
- product scope that needs organizer input,
- any optional shared publishing path added for the session.
Optional short videos
Videos are optional. The text on this page is enough to prepare. These links are useful if you prefer a quick visual introduction before reading the matching section.
| Topic | Video |
|---|---|
| Claude Code | Navigating the Claude desktop app: Chat, Claude Cowork, Claude Code |
| Pull requests | Beginner’s guide to GitHub: Creating a pull request |
| Pull request checks | GitHub for Beginners: Getting started with GitHub Actions |
| Docker | Docker in 100 Seconds |
If a video mentions commands that conflict with an app README or facilitator instruction, follow the app README or facilitator instruction.