The workspace and the AI brain
One folder tree, the same on every computer. Coding happens inside projects/.
~/Workspace/
├── ai_brain/ shared AI knowledge for all projects: the rules every coding tool gets, skills,
│ memory, notes, scripts; its own private git repository
├── projects/<project>/ the project's parent: AGENTS.md, ai_brain/ (that project's memory, learnings,
│ │ current context), docs, decisions, project.json
│ └── code/<repo>/ each code repository, its own git repository
├── credentials/ keys and passwords for local work: never in git; AI tools may use them but never print them
├── development/ toolchains and SDKs installed for you (node, flutter, android, …)
├── git/ your own git material (mirrors, shared hooks)
├── database/postgresql/ local database data
└── backups/
Names are case-exact. The place is one setting: workspaceDir in Hoprig's config.json (default ~/Workspace);
the environment variable HOPRIG_WORKSPACE_DIR wins over both. A project's parent is described in
PC-SETUP.md.
hoprig workspace status [--json] # every folder: there or not, what it is for; the map against this computer;
# clones hoprig get left under a temporary name, with what to do
hoprig workspace setup [--dry-run] [--yes] # create only what is missing
hoprig workspace link [--dry-run] [--yes] # let every coding tool that is on read its rules, skills and memory from the brain
hoprig workspace map [--dry-run] # write the map of every git repository (ai_brain/workspace.json)
hoprig workspace map --upgrade [--yes] # the map to version 2, needed for groups (asks once)
hoprig workspace group add <dir> [--repo <address>] [--holds name:group,name] # a folder of projects of your own
hoprig workspace group remove <dir> # out of the map, when no project of the map is in it (nothing deleted)
hoprig workspace restore <brain address> # a fresh computer: the brain, then everything its map names
hoprig workspace sync [--memory] [--push] [--with <computer>] # every repository in step
hoprig workspace set --dir <folder> --projects <folder> # where things are, for future work (nothing moves)
hoprig workspace forget <entry> # a project (<place>/<name> in a group), project/code/<name> or a folder out of the map
hoprig workspace git # git's name and e-mail, the GitHub sign-in, your workspace on GitHub
hoprig workspace auto [--map|--commit|--sync|--push on|off] [--every <hours>] # the upkeep's switches
hoprig workspace mylink add|remove|list [<path>] # a link in the workspace that is your own (Hoprig follows it)
hoprig workspace rules [--write] [--yes] # the short text about this workspace for coding sessions: shown; written on a yes
Every one of them takes --json; the ones that change something take --dry-run, which shows exactly what would
happen. hoprig setup and hoprig pc setup offer the workspace as one step: on a new computer (no AI brain yet)
they say in one sentence what it creates and ask once (default yes); where the brain is there already, they only
report. Before that comes the Git and GitHub step (below). hoprig doctor shows the workspace under Projects:
the tree, whether the brain is on a git server and in step (as of the last fetch; the doctor does not fetch), and
whether the map matches this computer.
A fresh computer in three commands
curl -fsSL https://raw.githubusercontent.com/allswebtech/hoprig/main/install.sh | sh # Hoprig, git, gh, …
hoprig workspace git # name and e-mail, the GitHub sign-in (any other git server: skip)
hoprig workspace restore example/ai_brain # or any git address of your brain
The installer's own setup already asks the second and third question in a terminal; the commands are for doing it
later or again. Then hoprig workspace link makes every coding tool that is on (Claude Code, and OpenCode when it is
on) use the brain's rules, skills and memory.
The map: every repository in one file
<workspace>/ai_brain/workspace.json lists what makes up the workspace, by address, never by content. It lives in
the AI brain because the brain is the one repository every computer has.
{
"version": 1,
"config": { "projectsDir": "code" },
"brain": { "url": "https://github.com/example/ai_brain.git" },
"projects": [
{ "name": "shop", "url": "https://github.com/example/shop.git",
"memories": { ".": "ai_brain/claude-memory" },
"repos": [ { "dir": "code/shop-api", "url": "https://github.com/example/shop-api.git" },
{ "dir": "code/shop-web", "url": "git@gitlab.example.com:example/shop-web.git", "branch": "main" },
{ "dir": "code/sketches", "url": null } ] }
],
"others": [
{ "dir": "development/flutter/flutter", "url": "https://github.com/flutter/flutter.git", "branch": "stable", "sync": false },
{ "dir": "git/tool", "url": "https://github.com/example/tool.git", "branch": "main" }
],
"skip": [ "old-project" ]
}
- The map is the union of your workspace across your computers, not a picture of one disk.
hoprig workspace mapadds and updates what is on this computer (addresses, branches, tool flags, memory links, code repositories); what the map has and this computer does not stays as it is and is listed as "in the map, not on this computer" (never as removed). A computer without a brain remote, or with a projects folder the map cannot describe, never blanks what the map says. Onlyforgettakes something out. The one exception: a project that IS on this computer and whose ownproject.jsonno longer names one of its code repositories (whose folder is not here either): itsproject.jsonis the truth for it, so that repository is "taken out of <project> by its project.json". A linked worktree (git worktree add, a second checkout of another repository) is never added to the map; an entry whose folder here is one is kept as not on this computer (also when the project'sproject.jsondoes not name it: the exception above is only for a folder that is not here at all), and restore and sync leave that folder alone. Apart from that one exception nothing leaves the map by itself:forgetremoves a stale entry.mapshows what changed (added, taken out, a changed address), never commits, and prints thegit addandgit committo run in the brain.project new,project cloneandproject addkeep it up to date by themselves when there is a brain. - A project's own
project.jsonstays the truth for its code repositories. The map repeats them so that one file is enough to rebuild everything, andmapadds a code repository found on disk to aproject.jsonthat lacks it (commit that in the project). - Addresses are kept without a user name or password (
https://user:token@host/…becomeshttps://host/…), and an address that still looks like it holds a secret is refused. Only https and SSH git addresses are accepted. - A repository with no remote is listed with
"url": null("not on a git server yet") and reported; nothing is guessed. Folders namedno-ai,ignore,ai-ignore-dir,credentials,node_modulesand dot-folders are never looked into.othersare git repositories elsewhere in the workspace (up to three folders deep), never inai_brain/or the projects folder. - Tools:
"sync": false. A git repository that is a toolchain or SDK (by default everything underdevelopment/, such as a Flutter or nvm checkout) is restored on a fresh computer on its mapped branch, because that is how such a tool is installed, butsync(also--withand the automation) never fetches or moves it: that would be an upgrade nobody asked for.mapsays so ("tools: restored on a fresh computer, never synced"),synccounts them as "tools, left alone", andstatusshows them in their own group. Change it by editing the field:"sync": truemakes a tool synced like the rest,"sync": falseon any entry (a project, a code repository, another repository) makes it a tool;mapkeeps what you set. - The workspace's own settings, so a fresh computer becomes the same place:
config.projectsDir(the projects folder relative to the workspace, written only when it is notprojects; a projects folder outside the workspace is not written: the map never holds a machine path) and each project'smemories(which folder's Claude Code memory lives where, as in itsproject.json). Restore puts the projects there unless this computer chose a projects folder before, and links each project's memory asproject.jsonsays, or as the map says when the project has noproject.json. Nothing fromcredentials/, no host names, no tokens. forgettakes a project, a code repository (<project>/code/<name>, asmaplists it) or another folder out of the map and adds it toskip, somapdoes not add it back and restore does not clone it from aproject.json.- A map read from a repository is checked strictly (unknown keys, names and folders that would lead out of the workspace, bad addresses or branch names): a map that fails is not used, and nothing is changed.
Groups: folders of projects of your own
The default tree has one projects folder. A group is a folder of the workspace you add for more projects beside it, for example one for client work. It is written to the map, so every computer of yours gets the same folders. A group needs a map of version 2 (below); a new workspace has none until you add one.
hoprig workspace group add client-work # a plain group
hoprig workspace group add kits --repo https://github.com/example/kits.git --holds packs:group,builds
hoprig workspace group remove client-work # only while no project of the map is in it
hoprig workspace group ignore kits # the ignore lines kits lacks, written on a yes
- A plain group (
client-work/): every folder in it is a project of the usual shape (a parent repository withproject.jsonandcode/<repo>), exactly as in the projects folder. - A group that is a repository (
kits/,--repo): it has its own files (anAGENTS.md, anai_brain/with its memory, its tools) and keeps its projects in the folders it holds, never at its top. A held folder says whether each of its projects is a repository of its own (builds:kits/builds/<project>) or comes with the group's repository (packs:group: the group trackskits/packs/<project>'s small files, only itscode/<repo>folders are repositories). - The group's repository ignores what it holds. One
git addinkits/must never take a project, so its.gitignoreneeds/builds/*/and/packs/*/code/.group add --repoandgroup ignore <dir>show the lines it lacks and write them on your yes (--yeswithout a question);workspace statuswarns while git would still take a project or another repository inside it, and sync never counts a project as a change of the group. - Hoprig stays inside a project's own folder: a link that leads out is not followed unless you named it as
yours. Every place Hoprig acts (a clone, a fetch, a push, a commit, a file written or copied, a memory link, a
dependency install, a hooks setting) must, with every link resolved, lie inside the real folder of its entry (the
project's, the group's, the member's, the code repository's), and that folder must lie where the map puts it, with
no link on the way. A repository is data from a git server: when it brings
builds -> /somewhere/else,code -> ..or.env.example -> ~/.ssh/..., nothing is done there; a file is never written through a link. There is no difference between a link a repository brought and one you made by hand, except the links you name as yours on this computer:hoprig workspace mylink add <path>(a project folder you keep on another disk), kept in Hoprig's own settings, never in the map, never synced.workspace statusnames every other link it met with that command, and the project page shows a code folder that is not followed. The check is made at each act, so what it cannot see is a folder that a program already running on this computer swaps for a link in the instant between the check and the act, or a bind mount (it looks like a folder): the rule guards against what a repository brings, not against a program that already runs as you. - Names. A project of the projects folder is
<name>; one in a group is<place>/<name>(client-work/shop,kits/packs/blog). A name is unique in its place, so two places may each have ablog: every command, the page and Tia take the bare name when only one place has it, and refuse it naming both forms when two do; the projects folder's own is thenprojects/<name>. The map'sskiplist uses the same names, soforget kits/packs/blognever hidesclient-work/blog. One repository is in one place only: the map refuses the same address in two places when a command writes it, and the scan does not add a folder whose address the map has in another place. A duplicate that arrives through a merge on the git server is used, andworkspace statusnames both entries with theforgetto run. A project of the projects folder may have the name of a group's folder: they are two folders. - Memory. A session started in a project of a group uses that project's own memory when it has one
(
ai_brain/claude-memory), else the group's; a session started in the group's own folder uses the group's. Restore,hoprig getandhoprig project link <place>/<name>make those links (hoprig project link <group>the group's own); for a project or a group that was here before, restore andgetsay a missing link with that command instead of making it. - Everything that listed the projects folder lists every place:
workspace status,map,sync, restore (a group's repository is cloned before its projects), the Workspace page (one section per place), the new-session list,project status|sync|link, and Tia's project list.project newstays in the projects folder unless--in <group>is given;hoprig get <place>/<name>(or--in <group>for a project the map does not have yet) puts a project into its group.group adddrops nothing from the map: a repository an earlier map listed as "other" inside the new group's folder becomes the project (or the group's own repository) it fits as, every other one stays another repository, and it says which for each. A repository in a group's folder that is no project (a tool folder of the group, a folder of folders in a plain group) is another repository. - Folders are written one way. The map holds
client-work, neverclient-work/or./client-work, and no part of a folder starts with-; reserved names are compared without letter case (Credentialsiscredentials). What you type is tidied first (group add a//b/addsa/b).
The map with groups (version 2):
{
"version": 2,
"brain": { "url": "https://github.com/example/ai_brain.git" },
"groups": [
{ "dir": "client-work" },
{ "dir": "kits", "url": "https://github.com/example/kits.git", "memories": { ".": "ai_brain/claude-memory" },
"holds": [ { "dir": "packs", "parent": "group" }, { "dir": "builds" } ] }
],
"projects": [
{ "name": "shop", "url": "https://github.com/example/shop-workspace.git", "repos": [ … ] },
{ "name": "shop", "in": "client-work", "url": "https://github.com/example/acme-shop.git", "repos": [] },
{ "name": "blog", "in": "kits/packs", "url": null, "repos": [ { "dir": "code/blog-theme", "url": "…" } ] },
{ "name": "blog", "in": "kits/builds", "url": "https://github.com/example/blog-build.git", "repos": [] }
],
"others": [ … ],
"skip": [ "kits/builds/old" ]
}
The strict check covers every new key, one rule each: a group's folder and a project's in are folders inside the
workspace (no .., no full path, none of the folders the map never looks into, none of the workspace's own
folders), in names a declared group or held folder, a project that comes with its group has no address of its
own, a name is in its place once, no other repository is where a group, its held folder or a project of it is,
and only a group that is a repository keeps memory or holds folders. The upkeep never stops on the map: what keeps
it from being written is skipped with its reason, which workspace status shows.
Version 1 and 2. A map of version 1 is read as it is and stays version 1: the upkeep never upgrades it.
hoprig workspace map --upgrade does, once, when you run it. A computer whose Hoprig knows only version 1 refuses a
map of version 2 and changes nothing in it, but its map then stands still until Hoprig is updated there, so update
Hoprig on every computer first. The upgrade says how many computers reported a Hoprig that reads version 2 and which
reported an older one, and always that a computer that never reported cannot be seen from here; it asks once, with
"no" as the default. It keeps the content as it is and drops entries whose folder here is a linked worktree (a
second checkout an older map took for a repository).
A naming rule per place, and the look-up on the hosting site
The map is the union of what your computers have seen. A project that is only on the hosting site can be fetched by
one word when its place says how its repositories are named. A place whose projects are repositories of their own
(a plain group, or a held folder without :group) may carry a rule:
{ "dir": "builds", "find": { "parent": "{project}-{product}-project", "code": "{project}-{product}-*",
"folder": "{product}-{project}", "make": ["code", "apps"], "skip": ["old"] } }
- A placeholder (
{project},{product}: a word of lower-case letters and digits in braces, never a name every object has such as{constructor}) stands for one word of a name, never one with a hyphen;parentuses one or two of them and a fixed part,folderandcodeuse all of the parent's (else every repository of the account that fitscodecould become one project's code),codemay end in*(the rest of the name). The check refuses a pattern whose parts cannot be told apart ({a}{b},{a}.{b}).makelists the folders made in a fetched project (defaultcode; plain names, neverai_brain, each once whatever its letter case); a code repository whose*part holds a word ofskipis left out. hoprig workspace find --in kits/builds [--json]lists what the signed-in account and its organisations have that fits and the map has not: each project with its code repositories and its folder (shop-alpha-project→kits/builds/alpha-shop), and what does not fit exactly (another count of hyphens, no fixed ending, an excluded word, a code repository without a parent) as "does not fit", never guessed.--addwrites the projects into the map and clones nothing;--place-it <repository> <folder>records one that does not fit under the folder you name.hoprig get shop --in kits/builds(orhoprig get kits/builds/alpha-shop) looks the project up, shows the parent, its code repositories and the folder, and after one yes fetches it; its entry is written into the map only once the clone succeeded (a failed one sayshoprig get kits/builds/alpha-shopto try again). Two fits for one word are one question at a terminal; with--json, without a terminal or with--dry-runthey are an error naming both.get alex/shop-alpha-project --in kits/builds, a git address or the bare repository name follow the rule the same way (its folder, its code repositories), or are refused plainly when the name does not fit.--inis checked before anything is looked up.- In such a place one repository is in the map once (
--place-itrefuses an address the map has), a folder that differs from one of the map's only in letter case is refused, and a repository renamed on the hosting site is matched by what the site answers for its old name: it is not added again. - A parent without
project.jsonin such a place is another tool's project, and Hoprig writes nothing into it: noproject.json, no ignore line, no renamed file, no hooks setting, no.env. What it needs to know is in the map's entry.getand restore clone the parent and its code repositories, make the folders ofmakeand link its memory (in Claude Code's own folder); a parent that does not ignorecode/is said, not changed. A project another tool made in such a place is seen by the next scan and written into the map. In a plain group without a rule a get still writes aproject.jsonafter asking.
A group's own command
A group that is a repository may name one command of its own:
{ "dir": "kits", "url": "https://github.com/example/kits.git", "tool": { "name": "kit", "run": "kit.sh", "needs": ["git", "jq"], "needsOn": { "mac": ["pod"] } } }
hoprig workspace tool # each group's command: made, or waiting for your yes, and what it lacks here
hoprig workspace tool allow kits # shows the name and the file, then makes the command after your yes
hoprig workspace tool remove kits # takes it away again (only a command Hoprig made)
A map comes from a git server, so a command in it is never made by itself: only after your yes on this computer
does Hoprig write a small kit beside its own hoprig command. The yes is kept in Hoprig's own settings with what
you were shown: the group's address, the name and the file. kit does not start the file itself: it starts
hoprig workspace tool run kits -- <your arguments>, which checks at every start that the group is here with that
address, that the map still says that name and file, and that the file is a regular file really inside the group's
folder that the group's own repository tracks (never a file of another repository cloned into its folder, nor one it
does not track or ignores), and only then becomes the file (the same arguments, exit code and signals). Anything else: it does not
start, and says why in one sentence and how to allow it again. A name that is hop, hoprig or a command already
on your PATH is refused, and nothing at that name that Hoprig did not make (a dangling link too) is replaced; when
the folder is not on your PATH you get the line to add. No shell start file is edited, and Hoprig never runs the
command itself. Restore, the upkeep and workspace status say the truth about each command: made, waiting for your
yes, or why it would not start; status also names the programs of needs this computer lacks, and the kit that
installs one where Hoprig has it.
Your workspace, for coding sessions
hoprig workspace rules shows a short text about this workspace: its folders that are here, your groups that are
on this computer, a group's command only when you allowed it here, and the commands to ask where things are. The map
comes from a git server, so nothing of it goes into a file a coding tool reads as instructions without your yes:
hoprig workspace rules --write shows the text, asks (or --yes), and writes it into one file of Hoprig's own,
~/.claude/rules/hoprig-workspace.md, which says in its first line that Hoprig made it and replaces it as a whole.
Names that are not plain (letters, digits, ., _, -, at most 64 characters) are left out and named. The upkeep,
a restore and the group and tool commands never write it, your working rules file is never touched by it, and
workspace status says when the file is older than what the map says now. The first hoprig pc setup at a
terminal offers it as one question.
Restore: everything the map names
hoprig workspace restore <address> clones the brain into <workspace>/ai_brain, reads the map, shows the whole
plan (every repository and where it goes), asks once, then clones each project's parent and its code repositories
(and any code repository its project.json names that the map does not have yet), the other repositories, makes
the missing folders of the tree, and finishes each project it cloned like project clone: memory folders linked,
git hooks, .env.example copied, the dependency installs offered. A project that was here already is not changed:
what it misses is said, with hoprig project setup <name>. --dry-run writes nothing in the workspace; to read the
map of a brain that is not here yet it clones the brain into a temporary folder of the system and removes it.
- Each project goes into the folder the map names, whatever its repository is called (
shopforexample/shop-workspace; see PC-SETUP.md for the rulehoprig getuses). - Run it again and it only gets what is missing. What is there is never overwritten or moved: the same repository
counts as done; a folder that is something else is reported and left alone. A project that is here under another
name (the map says
shop, the disk hasshop-workspacewith the same address) is not cloned a second time: restore andworkspace statusshow themvthat gives it the map's name. A folder that is itself a project of the map under its own name (two entries may share one address) is in its place, never offered as another's copy. An address counts as the same in every spelling (ssh or https,.gitor not; on the usual hosting sites the letter case of owner and repository too). - A repository that cannot be cloned (no access, deleted) is listed with git's own reason, and the rest goes on.
- A brain folder that is another repository stops it before anything changes. The one exception is the starting
brain
workspace setupmade and nobody changed (only its own files and first commit, no remote): it is kept aside asai_brain.unused-<time>, so restoring after setup works. - In the dashboard (no terminal) git may not ask for a password and ssh may not ask about a host key: such a repository fails with the reason instead of waiting.
Sync: every repository in step
hoprig workspace sync goes through every repository of the map, the brain first, with the same engine as
project sync, leaving tools alone: fetch; fast-forward a branch that is only behind; push a branch that is only ahead only
with --push. Uncommitted work stays where it is and does not stop a fast-forward, unless the new commits touch
the same files: then git refuses and nothing is changed. It never merges, rebases, forces or stashes. Whatever needs
a decision (both sides moved, something to pull into files with uncommitted changes, no upstream, a push that failed, a repository not on this computer) is
listed with the exact command. --memory first commits the memory folders (the brain's claude-memory/ and each
project's), and only them. --dry-run changes nothing, not even a remote-tracking ref: it does not fetch, it asks the server for each branch's commit (git ls-remote) and says what it would pull and push (new commits that are not on this computer yet are named, not counted). --with does the same with the other computer.
The upkeep the dashboard does by itself
While the dashboard runs (hoprig serve, or the background service), right after it starts and then every few
hours. Five switches, the automation setting workspace (the same in the dashboard and in
hoprig workspace auto):
| Switch | Default | What it does |
|---|---|---|
map | on | The map keeps building itself. It looks at the workspace as map does (the union rule) and writes workspace.json only when something would change: a new project or code repository, a new address. Nothing changed: no write and no message. It never makes the first map (that is your hoprig workspace map), and it leaves project.json files alone. |
commitMap | off | A change of the map is saved in the brain's history: workspace.json is added and committed alone ("Update the workspace map"), with the brain's own git name and e-mail. Never while the brain has other staged changes: then the map is written, not committed, and you are told why. |
sync | off | Every repository of the map is fetched and fast-forwarded, as workspace sync does (tools left alone). |
push | off | Uploads what is purely ahead: sync's pushes, and the map's commit (only when the brain is ahead and not behind its git server). |
everyHours | 6 | How often (1 to 168). |
hoprig workspace auto # show the switches
hoprig workspace auto --commit on --push on --every 3 # set them: --map --commit --sync --push on|off, --every <hours>
Each real change is one line in the activity log ("The map gained shop/code/shop-admin"). A notification comes
only when something needs you (a repository with no address, the brain's staged changes in the way, the brain and
its git server both moved), and the same list is not told twice. hoprig workspace status (and the dashboard)
says when the map on disk is not saved in the brain's history yet, with the command that saves it.
Between your computers, without a git server
hoprig workspace sync --with <computer> gets the commits straight from another computer of yours, over SSH, for
a repository that has no git server or a server this computer cannot reach. Only a computer added by SSH (hoprig machines) is used, at the address stored there; its own Hoprig says where its workspace and projects are.
It is pull only, on purpose: git fetch over SSH runs git-upload-pack there, which never writes on the other
computer. Pushing into its repository would change a branch that may be checked out there. What is fetched lands
under refs/hoprig-peer/<computer>/<branch> (not a branch, not a remote), and the branch here is fast-forwarded
only when it is only behind (uncommitted work stays, as in sync). The other computer gets this one's commits the same way, by running
sync --with itself.
Git and GitHub
One step of hoprig setup and hoprig pc setup, and hoprig workspace git on its own. The dashboard's Setup
does the same in the page, without a terminal: a small form for the name and e-mail; Sign in shows the
one-time code from gh auth login --web with a copy button and a link to github.com/login/device, you confirm it
there and gh finishes by itself (then gh auth setup-git); Keep on GitHub puts the brain into a new private
repository as a job. No GitHub password or token goes through the dashboard:
- The GitHub sign-in:
gh auth loginin the terminal (you confirm a code in the browser), thengh auth setup-git, so plain git uses that sign-in too. Only the account name is ever kept or shown. - git's name and e-mail when they are missing. Once signed in, GitHub's no-reply address is suggested (it keeps your own address out of commits); nothing is made up.
- Is there a workspace of yours on GitHub already? Repositories of your account and your organisations whose
name has "brain" in it are offered (one with a
workspace.jsonfirst): restore it. Or start a new one: the brain goes into a new private repository (never public), the map is committed in it and pushed. Or later. A brain with another name:hoprig workspace restore <its address>.
Other git servers (GitLab, your own SSH server) work for map, restore and sync through plain git with your own sign-in (SSH key or credential helper). Only this sign-in help and creating a repository are GitHub's.
Changing where things are
hoprig workspace set --dir <folder> --projects <folder> changes where the workspace and the projects folder are
for everything from now on. Nothing is moved: the mv that would move the files is shown, to run yourself.
The command in every shell
Node.js installed with nvm is only on PATH in an interactive shell, so ssh <computer> hoprig doctor used to say
"command not found". hoprig setup (the installer runs it) writes two small scripts, ~/.local/bin/hoprig and
~/.local/bin/hop, that start Hoprig with the full path of its Node.js, and puts ~/.local/bin on PATH in
~/.profile (and ~/.bash_profile when there is one), at the top of ~/.bashrc (before the line that stops a
non-interactive shell), in ~/.zshenv, and for fish in ~/.config/fish/conf.d/hoprig.fish. Each line is added
once. A new Node.js version: run hoprig setup again (the doctor says when the scripts point to one that is gone).
A file of npm's own in ~/.local/bin is left alone.
What setup creates, and what it never touches
- Only what is missing: the workspace folder and each folder of the tree.
credentials/gets owner-only permissions and a short README. The projects folder for a new install is<workspace>/projects. ai_brain/is made only when there is none (or it is an empty folder):BRAIN.md(what the folder is),learnings.md,active_context.md,daily_logs/,claude-memory/home/,skills/,scripts/,claude/CLAUDE.md(Hoprig's working rules as the starting global rules),.gitignore, thengit initand a first commit when git knows your name and e-mail.- Never: a folder or file that exists is not moved, renamed, overwritten or "fixed" (a credentials folder others
can open is reported, with the
chmodto run). An existingai_brainthat is already a git repository with its own structure is adopted as it is. A projects folder chosen before (or~/projectsfrom an earlier install) stays where it is. Claude Code's folder (~/.claude) is never touched by setup.
Linking the coding tools into the brain
workspace link is a separate, explicit step. It first lists exactly what it will do:
| Claude Code's | links to |
|---|---|
~/.claude/CLAUDE.md (the rules for every project) | ai_brain/claude/CLAUDE.md |
~/.claude/skills/ | ai_brain/skills/ |
~/.claude/projects/<home folder as a name>/memory/ | ai_brain/claude-memory/home/ |
(~/.claude is $CLAUDE_CONFIG_DIR when that is set.) A real folder's files are merged into the brain (a name
that is taken gets .from-<time> added; nothing is overwritten) and the folder is kept as a dated backup. A rules
file moves into the brain only when the brain has none; when both exist with different text, nothing is changed
and you are told to keep one. A link that points somewhere else is left alone. Windows: folders become junctions;
a file link needs the right to make links, and without it the file is put back and the step reports the error.
OpenCode: the same brain
When OpenCode is on (hoprig tools on opencode, or installing it), workspace link covers it too, so all
coding tools read the same rules, skills and memory:
| Coding tool | what is linked or named | in the brain |
|---|---|---|
| OpenCode | ~/.agents/skills/ | ai_brain/skills/ |
| OpenCode | ~/.config/opencode/AGENTS.md | ai_brain/claude/CLAUDE.md |
| OpenCode | "instructions" in ~/.config/opencode/opencode.json: Claude Code's rules/*.md and each project's ai_brain/claude-memory/MEMORY.md | (added to the list; the file's other settings stay, the old file is kept as a backup) |
It keeps no memory of its own, so the shared rules file gets a short Memory section at its end (once,
between two marker lines, after your own text) that tells it where each project's memory is and to keep it.
OpenCode does not read CLAUDE.md in a project, only AGENTS.md: the projects Hoprig sets up have both.
The AI brain page shows, per coding tool, whether it is linked, with one Link button.
The AI brain in the dashboard
The AI brain page (under More) shows what the AI knows on a computer (also another computer, through the hub), read-only. The workspace folders themselves are on a computer's page, Setup. The AI brain page shows:
- the global rules (
CLAUDE.mdand Claude Code'srules/folder), and the brain's own copy; - the brain's
BRAIN.md,learnings.md,active_context.md,PENDING.md, the daily logs (newest first); - skills: name and one-line description of each (Claude Code's skills folder, and the brain's when it is another);
- memory: for everywhere (the home folder's) and for each project (its parent's
ai_brain/claude-memory), one entry per file with its name, description and type, and when it changed; - each project's
AGENTS.md,decisions.md,ai_brain/learnings.mdandai_brain/active_context.md.
The page asks for one item by the id the index gave it, never by a path. Never shown: anything outside these
places (no .., no absolute path, no link that leads out), folders named no-ai, ignore or ai-ignore-dir
(not even counted), credentials folders, dot-files, .env files, key files, and anything that is not plain
text (.md, .txt). Text that looks like a secret is masked before it leaves the computer; an item is cut at
200 KB.
Routes (behind the login; another computer's through the hub): GET /api/workspace, POST /api/workspace/setup,
GET /api/brain, GET /api/brain/item?id=<id>, GET|POST /api/workspace/map, POST /api/workspace/restore,
POST /api/workspace/sync, GET /api/workspace/job, POST /api/workspace/settings, POST /api/workspace/forget,
GET /api/workspace/git, POST /api/workspace/git/identity, GET|POST /api/workspace/git/signin,
POST /api/workspace/git/signin/cancel, POST /api/workspace/git/brain (the list with what each takes is at the top of
src/workspace/feature.mjs).
What is checked where
Tests on temporary folders with local bare repositories as the git server: status, setup, adopting an existing
tree, linking with merge and backup, every refusal of the brain view, the map (a token stripped, private folders
unseen, a repository without a remote), restore (twice, with an unreachable repository, after setup), sync
(behind, ahead, both moved, uncommitted), --with between two temporary homes, and the Git and GitHub step with a
stand-in for gh. Groups: a workspace with the projects folder, a plain group and a group repository holding two
folders (scan, write, read, status, sync, memory links, restore on a second home, git add -A in the group taking no
project), one test per rule of the strict check, the upgrade from version 1, and the previous release's reader
meeting a version-2 map and changing nothing. Where Hoprig acts (test/workspace/inside*.test.mjs): the review's
cases, a property over 300 random trees with links in random places and over random workspaces with real git
(restore, get, sync with --push, the upkeep, project setup: nothing outside an entry's folder changes), and a test
that finds every raw act outside inside.mjs. End to end in two fresh Ubuntu 24.04 containers (tools/e2e-workspace.sh): install from a
tarball, a workspace built and mapped on one, restored on the other from the brain's address, a change synced, the
command found over ssh. The real GitHub sign-in needs a person and was not run. Windows was not run.