Setting up the same way of working

This project was built with an AI coding assistant working from a written spec, with the code hosted on GitHub and this site published straight from the repository. None of that requires anything exotic. Here is the practical path to setting up the same toolchain, whatever you plan to build.

Claude Code

Claude Code is Anthropic's coding agent: a tool that reads and edits files, runs commands, and works through multi-step programming tasks in conversation with you, grounded in your actual codebase rather than a copy-pasted snippet. It is what wrote most of the code and this page, working from the project's README and plan.

The most common way to install it is via npm:

npm install -g @anthropic-ai/claude-code

Then, from inside a project directory:

claude

This opens an interactive session in your terminal, with the assistant able to see and modify the files in that directory (subject to permissions it asks you for along the way). You need a Claude account to use it. A useful first command inside a new project is /init, which has the assistant read through the codebase and generate a CLAUDE.md file summarising conventions and context for future sessions.

Claude Code is not limited to the terminal. The same agent is available as an extension inside VS Code and JetBrains IDEs, as a desktop application, and on the web at claude.ai/code — so the same way of working is available whether you prefer a terminal, an IDE panel, or a browser tab.

Working across devices

A practical benefit of running Claude Code sessions is that they are not necessarily tied to the one machine where you started them: a session can be followed and picked back up from elsewhere, and the web interface at claude.ai/code provides a cloud-based way to start or continue a coding session without a local terminal at all. If you plan to work this way regularly — starting something on a desktop machine and checking on it from a laptop or phone later — it is worth exploring what claude.ai/code currently offers directly, since the exact interface and capabilities are the kind of thing that improves over time and is best checked at the source rather than assumed from a description here.

A GitHub account

GitHub hosts the repository, tracks its history, and — as used here — serves this website directly from it. Signing up is free, and free accounts include unlimited private repositories. If you are affiliated with a university, GitHub Education is worth applying for: it extends free access to a number of otherwise-paid developer tools.

To turn a local project into a GitHub-hosted repository for the first time:

git init
git add <files>
git commit -m "Initial commit"
git remote add origin https://github.com/<you>/<repo>.git
git push -u origin main

(Create the empty repository on GitHub's website first, under your account, so origin has somewhere to push to.)

Authenticating with GitHub

There are three working ways to authenticate. SSH is the recommended default if you expect to push regularly; the other two are reasonable if you would rather not manage a key pair.

SSH. Generate a key pair (ed25519 is the current recommended key type), add the public key to your GitHub account, then point the remote at the SSH URL instead of the HTTPS one:

ssh-keygen -t ed25519 -C "your@email"
# add the printed public key at:
# github.com → Settings → SSH and GPG keys → New SSH key
git remote set-url origin git@github.com:<you>/<repo>.git
ssh -T git@github.com

The first time you connect over SSH to a host you have never used before, you will see a prompt along the lines of "The authenticity of host 'github.com' can't be established", followed by a fingerprint, and asked whether to continue connecting. Do not answer that reflexively. Check the fingerprint it shows you against GitHub's own published list of SSH key fingerprints at docs.github.com — GitHub's SSH key fingerprints before accepting it. This is what stops your very first connection to a host from being silently intercepted, and it costs one extra look at a web page. Once accepted, the host is remembered and you will not see the prompt again for that machine.

GitHub CLI. The GitHub CLI (gh, a separate install — for example brew install gh on macOS) can handle authentication for you interactively:

gh auth login

Follow its prompts once, and subsequent git push/git pull commands over HTTPS use the credentials it stored.

Personal access token. Under github.com → Settings → Developer settings → Personal access tokens, generate a token scoped to repo access, and paste it in place of a password the next time Git prompts you for one over an HTTPS remote.

Turning on GitHub Pages from the docs/ folder

This site is served directly from the docs/ folder of the project's main branch, with no separate build step. To enable that on your own repository:

1. Open your repository on GitHub and go to Settings.
2. In the left sidebar, select Pages.
3. Under Build and deployment, set Source to Deploy from a branch.
4. Under Branch, choose main and the folder /docs, then save.

GitHub then builds and publishes the site, typically within a minute or two, at https://<you>.github.io/<repo>/. Because this approach serves plain files with no Jekyll build, a .nojekyll file is included in docs/ to stop GitHub Pages from trying to process the site with Jekyll and skipping files it thinks are special.

Putting it together

None of these three pieces depends on the others technically, but they compose well: a written spec in the repository gives an AI coding assistant something concrete to work from and be checked against (see the spec-first design page), GitHub gives that spec and the resulting code a durable, shared home, and GitHub Pages turns part of that same repository into a public explanation of the work with no separate publishing step. This site is that last piece, published from the same docs/ folder you are reading right now.