Project Hudson — Documentation

The guides

Three documents, each with a different job. If you are standing in front of a new Mac mini right now, start with the setup sheet.

Start here

Mac mini 24 GB setup sheet

The hands-on runbook. Open it on the mini and work top to bottom — every command is copy-ready, every number pre-tuned for 24 GB of unified memory, and your ticks are saved in the browser so you can stop and resume.

Open the runbook → 7 phases · 33 steps · progress saved Background

Install guide

The companion why document. What you are building and how the layers fit, the database options, making it always-on, the permission model, security hardening, and a troubleshooting table.

Read the guide → Concepts · decisions · reference Front door

Telegram + Hermes

Signing up for Telegram, creating the bot with BotFather, finding your numeric user ID, and binding it to the gateway — plus how to admit other people safely and what to never switch on.

Wire up the bot → Account · BotFather · allowlist

Which one do I need?

If you are…	Go to
Setting up a brand-new Mac mini	Setup sheet, top to bottom
Deciding Docker vs native Postgres	Install guide → database options
Getting the bot talking to your phone	Telegram setup
Wondering why a Postgres setting is what it is	Setup sheet → Postgres settings
Sizing a local model against 24 GB	Setup sheet → memory budget
Locking the thing down before leaving it unattended	Install guide → security hardening
Debugging a bot that went silent	Troubleshooting tables in either guide

What you are deploying

16specialist subagents

47step-by-step skills

2runtimes: Claude Code + Copilot

24 GBunified memory, budgeted

The team covers the domains a small product outfit actually needs, and the orchestration playbook routes each request to the right one rather than answering everything itself:

go-programmer
web3-engineer
script-kid
infra-engineer
frontend-dev
database-engineer
sre-engineer
ai-ml-engineer
network-engineer
ops-engineer
chaos-engineer
security-engineer
product-researcher
investment
marketing
sales

The same team, twice

Agent definitions live in .claude/agents/ and are mirrored to .github/agents/ by a sync script, so the identical specialists work in Claude Code and GitHub Copilot — VS Code, Copilot CLI, and the cloud agent.

The short version

If you already know the shape of it and just want the commands, this is the spine of the setup sheet. Every one of these steps has a full explanation behind it in the runbook.

on the mac mini

# 1 — base tooling
xcode-select --install
brew install node python@3.11 ripgrep ffmpeg git uv
npm install -g @anthropic-ai/claude-code
claude                       # log in once, then: claude doctor

# 2 — the repo and its memory database
git clone https://github.com/lciamp/project-hudson.git ~/repos/project-hudson
cd ~/repos/project-hudson
scripts/setup-native-postgres.sh

# 3 — never sleep; it is a server now
sudo pmset -a sleep 0 disksleep 0

# 4 — the boss agent out front
curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh   # read it before running it
bash /tmp/hermes-install.sh
hermes gateway setup && hermes gateway start

Reboot before you trust it

Both Hermes and Homebrew register LaunchAgents, which only run inside a logged-in session. On a machine with FileVault on and no auto-login, every reboot leaves the bot silent until someone types the password. The setup sheet lays out the three ways to handle that and what each one costs you.