hacklab

The terminal-native way to join Hacklab — a social network for AI-native hackers. Scan your local AI token usage, see where you rank, claim your profile with GitHub.

Install & join

One command:

curl -fsSL https://hacklab.so/install | sh

It checks for Node 20+ and runs npx hacklab@latest join. If you have Node already (incl. via a version manager), you can skip the script:

npx hacklab@latest join

The join ritual

scan local AI usage → see your rank → pick a username → sign in with GitHub → claim

1. Scan — reads your local AI token usage from Claude Code, Codex, Cursor, OpenClaw, Hermes, and OpenCode. Nothing leaves your machine yet.
2. Rank — shows the rank that usage would hold (you'd be #15 of N), with no account required.
3. Username — pick your Hacklab handle (checked for availability live).
4. GitHub — sign in to authenticate and link your profile + repos.
5. Claim — your profile goes live at hacklab.so/<username>. Your usage uploads in the background while you get a shareable stats card.
6. Share — a stats thumbnail (belt, level, rank, token breakdown) is rendered locally, copied to your clipboard, and you can post it to X in one keystroke.

Commands

• hacklab join — the join ritual above. Running bare hacklab does this for new users (and sync for returning ones).
• hacklab sync — re-scan local AI usage and sync it to your profile.
• hacklab whoami — show who you're logged in as.
• hacklab drop "message" — post a drop to your feed (-u <url> to attach a link).
• hacklab chat <sub> — the channel and DMs (live, tail, post, history, dms, dm <handle>, flag). Author handles are coloured by belt rank. Add --json to any non-interactive subcommand for machine-readable output an agent can drive.
• hacklab login — re-authenticate with GitHub.
• hacklab exam [--pyro|--hacker] — run your belt exam (token usage + GitHub code).
• hacklab scan — build your full profile (skills, repos, blog).
• hacklab config <key> <value> — set config (cursor-api-key, cursor-email).
• hacklab brag [path] — sync a .hacklab/project.yaml to your profile.
• hacklab org — edit the profile of an organization you've claimed. Pick a field, type the new value, and it saves as you go. Only organizations you've claimed are editable.
• hacklab --version / hacklab --help.

Choosing a backend

By default the CLI talks to production (https://hacklab.so). Pick another with --env (works on any command):

hacklab join --env staging        # https://staging.hacklab.so
hacklab join --env development     # http://localhost:3000

--env maps to a fixed URL; HACKLAB_APP_URL overrides it for a custom target.

Environment

• HACKLAB_APP_URL — explicit app base URL; overrides --env. Defaults to production when unset.
• HACKLAB_SESSION_PATH — custom path for the session file (default ~/.hacklab/session.json).

Local development

From the repo root, run the CLI from source against a local app:

HACKLAB_SESSION_PATH=/tmp/hl-test.json \
pnpm --filter hacklab dev join --env development

pnpm --filter hacklab dev <command> runs src/index.ts via tsx (no build). pnpm --filter hacklab build compiles to dist/.

To reset a test account so its GitHub identity can join fresh:

pnpm --filter @hacklab/db delete-account <handle-or-github-username>