Set up a computer for coding, and see what it is missing
Take a fresh computer (Linux, macOS or Windows; a current Ubuntu is a good choice) and install Hoprig: its first run (INSTALL.md) includes this part. To run it on its own, or again:
hoprig pc status # what is there, what is missing, what needs attention
hoprig pc setup # shows the same, proposes only what is missing, asks once, installs it
pc setup first shows what the computer has, kit by kit. If everything is there it says so in one line and
stops. Otherwise it lists the exact commands it will run, asks one question, and runs them with their output
as it comes. When a command needs the administrator password, sudo (or Windows) asks for it in your terminal:
Hoprig never sees, keeps or types a password. At the end it says what is ready, what failed (with the exact
command to retry), and what needs a new terminal or a new login. Running it again is safe: what is there is left
alone, never reinstalled or downgraded.
| Option | What it does |
|---|---|
--yes | answer the one question with yes (sign-in questions are still asked when there is a terminal) |
--dry-run | change nothing, only show what would happen |
--kits basics,node,… | choose the kits (default: the kits that miss something) |
--recipe <file or https address> | set up like another computer (see Recipes) |
--rules / --remove-rules | add (or take out again) a good set of working rules for Claude Code: one file, ~/.claude/rules/hoprig-working-rules.md, which Claude Code loads for every project; your own CLAUDE.md is never touched (an import line an earlier version added there is taken out). Nothing of your workspace map is ever written into it; the short text about your workspace is hoprig workspace rules, offered once at a terminal and written into a file of its own only on your yes |
The same is on the dashboard: Computers, open the computer, Setup (next to Overview and Advanced; Setup also shows the workspace folders). It shows the status with a Fix button where a fix exists, and Set up this computer lets you tick kits. The installs run as a job on the Setup page itself: each step with ✓ or ✗, the output as it comes, the result and Check again. The job goes on when you leave the page and shows again when you come back. This works for another computer through the hub too.
The administrator password in the page. When a step needs sudo and sudo wants a password (sudo -n true is
refused; root and passwordless sudo need nothing), the page asks for your computer's password once, for that job:
it is used for these installs and not saved. The server checks it first (a wrong one installs nothing and the page
asks again), runs each admin step as sudo -S -k -p '' -- <command> with the password on sudo's input (never on
a command line; -k leaves no cached sign-in behind), keeps it in memory for that job only, and scrubs it from
every output line. It is never written, logged or sent back. On a plain http:// page that is not this computer
the password would cross the network unencrypted: the page says so and offers Use the terminal instead. The
terminal session is also used for a step that needs you at the computer (macOS's install window, Windows' own
prompts). This replaced the earlier rule that a password never goes through the page: setup belongs on the page
it was started from, and the password goes the way the dashboard's own password already does.
For another computer, the password may be typed on the hub's page only when the leg from the hub to that computer is
encrypted: SSH, an https:// address, or a direct link over wss:// (also with a pinned certificate). Over a plain
leg the page shows no password field: it says the password is asked only on that computer's own page, with a link
to it when its address is known, and both the hub and the computer refuse a password sent that way.
After the kits, pc setup runs the Git and GitHub step (the GitHub sign-in with gh, gh auth setup-git,
git's name and e-mail, and restoring or starting your workspace) and then the workspace step: see
WORKSPACE.md.
Kits
| Kit | Items | How |
|---|---|---|
| Basics | git, curl, unzip, C/C++ build tools (what node modules need to compile) | the system's package manager; macOS: the Xcode command line tools; Windows: the Visual Studio C++ build tools |
| Node.js | Node.js LTS, npm | nvm, for you only (no administrator rights); Alpine: apk add nodejs npm; Windows: winget |
| Python | python3, pip, venv | the package manager; Windows: the Python install manager |
| GitHub | gh, your commit name and e-mail, signing in | GitHub's own package repository; gh auth login (it can also set up git and an SSH key) |
| Terminal extras | tmux, ripgrep, jq | the package manager (no tmux on Windows) |
| Docker (optional, off by default) | Docker | Docker's own install script; you must log out and in again before it works without sudo |
Package managers: apt, dnf (4 and 5), yum, pacman, zypper, apk, Homebrew (offered first on a Mac without it) and
winget. "Old" (!) means past the end of life the project itself publishes (Node.js, Python).
Every command is written next to its source in src/pcsetup/kits.mjs (nodejs.org and nvm, cli.github.com,
docs.docker.com, brew.sh, docs.python.org, the winget package index).
Projects
pc setup first offers the workspace (WORKSPACE.md), then (in a terminal) asks where your projects live (default ~/Workspace/projects; a computer that already uses ~/projects keeps it; remembered) and which
repositories to clone: paste Git addresses or owner/repo, or pick from your own GitHub repositories. For each
clone it looks at what the project needs — the lockfile decides the dependency install (npm, pnpm, yarn, bun,
uv, poetry, pip, bundler, composer, go, cargo), .nvmrc/engines the Node version, and .env.example is
copied to .env when there is none — and asks before running the install. Nothing else of a project ever runs,
and an existing folder is never overwritten. The dashboard's Workspace page lists what is in the projects
folder, each project with its sessions under it (change the folder there, under Projects folder), and New session offers those projects. hoprig pc clone <repo>… does the same for given repositories.
Project workspaces
A project can be one private parent repository with its code in its own repositories, everything
synced through git, the AI memory included (in the workspace: ~/Workspace/projects/<project>/):
<projects folder>/<project>/ the parent repository (private): rules, AI memory, docs, decisions
AGENTS.md the one instruction file for AI tools
CLAUDE.md, GEMINI.md short pointers to AGENTS.md
.claudeignore .aiignore .cursorignore .copilotignore .geminiignore
.claude/settings.json shared Claude Code settings
ai_brain/ learnings.md, active_context.md, daily_logs/, claude-memory/, claude-memory.json
docs/ decisions.md
project.json { name, repos: [{ dir, url, branch? }], memories: { launch folder: memory folder } }
code/.gitignore "*" and "!.gitignore": the parent tracks only this file under code/
code/<project>-<stack>/ each one its own git repository
test-data/ ignored by git
hoprig project new shop [--github [--repo-name <name>] | --remote <git address>] [--template <folder or git address>]
hoprig project add shop web # code/shop-web, its own repository (--github: a private one on GitHub)
hoprig get shop # = hoprig project clone shop; or owner/shop-workspace, or a Git address:
# the parent, every code repository, the memory link, git hooks
# (.githooks), a .env from .env.example, the dependency installs
# (asked). Several names at once; --json
hoprig project setup shop # what a fresh clone sets up, for a project that is here
hoprig project status [shop] # parent and code repositories: branch, changes, ahead/behind
hoprig project sync [shop] [--memory]
hoprig project link shop # link Claude Code's memory folders again
Every command here that changes something takes --dry-run (new, add, clone/get, setup, sync, link):
it changes nothing at all on the computer, not even a lock, a settings file, the workspace map or a git ref, and says
what it would do instead. What it still does is read: the project's folders and git state, gh to look a name up on
GitHub (and project.json of a project that is not here yet), and for sync one git ls-remote per repository (a
dry run does not fetch: the server's new commits are named, and counted only when they are here already).
- The folder is the project's name, whatever its parent repository is called. A parent is often called
shop-workspacebecause the product repository isshop(it then lives incode/shop). The folder is: the name the workspace map gives that address; else thenamein the parent'sproject.json(the clone is made under a temporary name,.hoprig-clone-…, in the same folder and renamed once that file is read); else the repository's name with a trailing-workspacetaken off. Sohoprig get example/shop-workspacemakesshop/. Every result says where its name came from (nameFromin--json:map,project.jsonorrepository); a dry run readsproject.jsonthroughghwithout cloning. - A name in
project.jsonis used only where it is safe: a plain name, not a folder the workspace never looks into (no-aiand the like), and not one your map uses for another repository. Otherwise the folder is the repository's name and the command says why in one sentence ("its project.json names it shop, which your map uses for another repository"); the map's other entry is never changed. A repository name that makes no plain folder name (.x,-rf) is refused before anything is cloned. - Nothing is overwritten or moved. When the folder's name is taken (by a folder, a link, or something that
appears while it clones), or your map uses it for another repository, the clone stays under its temporary name
and the command says so with the
mvto run. A project that is here already under another name (an oldershop-workspace/, orsite/whoseproject.jsonnames itwebsite) is reported with themvthat gives it its name, never moved by itself. Both are "not done, it needs you": the command exits non-zero,--jsonhasok: falsewith themvasfix, the dashboard shows it as needing you, never as done. - The same address is one repository in every spelling:
git@github.com:o/r,ssh://git@github.com/o/randhttps://github.com/o/r, with or without.gitor a trailing/; on GitHub, GitLab, Bitbucket and Codeberg the owner's and the repository's letter case do not count either. A project here under its name is found whatever spelling cloned it; its missing code repositories are cloned and set up like a fresh clone. - A project that is here already is not changed by
get. Nothing inside it is written, linked or installed without asking:getsays what a fresh clone would have set up and is missing there (a.envfrom.env.example, the git hooks, the memory link, the installs) and the one command that does it,hoprig project setup shop. In a terminal (without--yes) it asks for each one instead, and Enter leaves it.hoprig workspace restoretreats a project that is here the same way. - A run that did not finish (killed, or its folder name taken) leaves its clone under the temporary name, one
name per address. The next
hoprig getof that address finishes a complete one instead of cloning again, and moves an unfinished one aside as.hoprig-clone-….aside-<time>(never deleted);hoprig workspace statuslists what is left, each with what to do. Two runs at once for one address (or one project of a group): the second says the project is being fetched by another run. The lock that tells is a file in Hoprig's own state folder (get-locks/), never in the folder a project is cloned into, so a group's repository never sees it;workspace statuslists a lock whose run has ended, and the nextgettakes it over. - A bare name (
hoprig get shop) is looked up in the workspace map first, then on GitHub asshop-workspaceandshopin your account and its organisations (by the name GitHub answers with: a repository found in another letter case, or under its name before a rename, counts once). Where both exist, the project parent (the one with aproject.json) wins; where that cannot be told (also the same parent in two accounts) you are asked once, and without a terminal, with--jsonor with--yesthe command stops with an error that names them all, so you can giveowner/name. project new shop --githubnames the GitHub repositoryshop, orshop-workspacewhen your account has a repositoryshopalready (often the product, made first);--repo-namechooses another name (without--githubit is ignored, and said so). The folder isshopeither way.hoprig project add shop shopmakescode/shopfor a product called like the project.- project.json from a newer Hoprig. A key this version does not know is kept as it is, whatever its name (also
when the file is written again; only
__proto__,constructorandprototypenever are), and shown as a warning inproject statusand its--json; it never stops a clone. The keys it knows are checked strictly as before. - Memory. Claude Code keeps a folder's memory in
~/.claude/projects/<folder as a name>/memory(CLAUDE_CONFIG_DIRis honoured).project newandproject clonemake that folder a link to the folder in the repository named inmemories(.→ai_brain/claude-memory), so the memory travels with git. A memory folder that already has files is merged in first (a file with the same name is kept under a new name, never overwritten) and the old folder is kept as a dated backup. On Windows without links,autoMemoryDirectoryis set in that folder's.claude/settings.local.jsoninstead. - Sync fetches, fast-forwards a branch that is only behind (uncommitted work stays; it stops the pull only
where the new commits touch the same files), and pushes a branch that is only ahead. It
never merges, rebases, forces or stashes by itself: anything that needs a decision is listed with the exact
command.
--memoryfirst commits the memory folders (and only them). - Without project.json a parent is understood from what is there: the repositories in
code/andai_brain/claude-memory.json(kept in step withproject.jsonwhen both exist; never deleted). When cloning such a project from GitHub, the owner's repositories named<project>-…(and<project>itself) are offered as its code repositories, never the parent itself (shop-workspacefitsshop-…), andproject.jsonis written. - Templates. The built-in one is small and neutral.
--template(a folder or a Git address; remembered asprojectTemplate) copies your own structure;{{project}}and{{Project}}in names and text become the name. A template cannot write outside the new folder (no.., no absolute paths, no links out). - Folders named
no-ai,ignoreorai-ignore-dirare never looked into, not even to count changes.
Recipes: make the next computer like this one
hoprig pc recipe save my-setup.json [--with-email]
hoprig pc setup --recipe my-setup.json # or an https address
A recipe holds the kits, the tool versions (as information), the projects folder, and the addresses of your
repositories and project workspaces. Never a key, a token or a password; your e-mail only with --with-email.
A recipe is input from outside, so it is checked strictly: only known kits, only plain https or SSH Git
addresses (no user name or password in them), a projects folder in the home folder. Nothing in a recipe can run
a command.
Status
hoprig pc status [--json] [--offline] checks, without changing anything or needing administrator rights:
the operating system (updates waiting and a pending restart where that can be read), free disk space where your
home and projects are, memory and swap, every kit item with its version, git name and e-mail, the GitHub
sign-in (only the account name is shown), an SSH key (only that a public key exists), Claude Code and its login,
the clock, the working rules, and every repository in the projects folder (branch, uncommitted changes,
ahead/behind — counts only). The exit code is 0 only when nothing needed is missing.
For other parts of Hoprig
import { runPcSetup, pcStatus } from './src/pcsetup/index.mjs';
await runPcSetup({ ui, yes, dryRun, kits, recipe, projects, rules }); // → { ok, changed, missing, code }
await pcStatus({ offline, projects }); // → [{ id, label, status, detail, fix, group, fixKit? }]
What is checked where
Linux (Ubuntu 26.04, Debian 12, Fedora 45) was run for real in fresh containers: setup, a second run doing nothing, cloning and installing a project, a project workspace with two code repositories, a recipe applied on a second computer, and the memory moving between the two. macOS was checked read-only (status and a dry run). Windows was not run: its commands (winget ids, the Visual Studio workload, the Python install manager) are checked against their vendors' pages and by unit tests only.