aios-builder

Scaffold your own personalized AIOS dashboard — an always-on local single-pane view of your content intelligence, business metrics, active projects, and one-click Claude Code skill shortcuts.

npx aios-builder <config-code>

That one line: clones the tested base engine, drops in your aios.config.json, runs a Claude personalization pass (theme + daily-digest skill + terminal buttons), installs dependencies, starts the server, and opens your dashboard.

Requirements

• Node.js >= 18 (built-ins only, zero runtime dependencies).
• git — the base engine is downloaded with git clone. The .git directory is kept so you can git pull future engine updates.
• Claude Code — the claude command must be on your PATH. This is required: the installer runs claude -p (headless) to personalize your theme, generate your daily-digest skill, and wire your terminal quick-action buttons. Install it from https://claude.com/claude-code. (Run with --no-claude to skip personalization and ship the neutral base.)
• Bring your own API keys. AIOS holds nobody's keys. Yours live in ~/.claude/.env (never in the config, never committed). The dashboard degrades gracefully and shows an "add key" state for any panel whose key is missing:
  • YOUTUBE_API_KEY — channel stats + thumbnails (free tier is plenty).
  • APIFY_API_TOKEN — Instagram + LinkedIn followers/engagement (cached 12h).
  • Optional overrides: YOUTUBE_HANDLE, INSTAGRAM_HANDLE, LINKEDIN_URL, PORT, AIOS_CLAUDE_BIN.

Usage

npx aios-builder <config-code> [target-dir] [options]

| Argument | Meaning | | ------------- | ----------------------------------------------------------------------- | | config-code | Code/URL from the AIOS configurator, or a path to a local config. | | target-dir | Where to create the project (default: ./aios). |

| Option | Effect | | --------------- | --------------------------------------------------------------- | | --config=PATH | Use a local aios.config.json instead of fetching a code. | | --dir=PATH | Alias for the target-dir argument. | | --local | Copy the base from a local checkout instead of cloning (dev). | | --no-claude | Skip the Claude pass — ship the neutral AIOS Base unmodified. | | --no-install | Skip npm install (and the node-pty fix). | | --no-start | Don't start the server / open the browser when done. | | --port=N | Override the port (otherwise read from the config). | | --yes, -y | Don't prompt before copying into a non-empty target dir. | | --help, -h | Show help. |

By default the base engine is fetched with git clone --depth 1 https://github.com/duncan-buildroom/aios.git. The .git directory is kept so you can git pull engine updates later.

Local development

To test against a local checkout of the base engine instead of cloning, run the installer from inside the aios-builder monorepo (where a sibling base/ checkout exists) — it is auto-detected. You can also force it with --local:

# from inside the aios-builder repo
node installer/bin/aios-builder.js --config=../aios.config.example.json ./my-aios --local

What it does (step by step)

0. Preflight — verifies Node >= 18 and that Claude Code is installed.
1. Resolve config — decodes your config code (aios1:…) locally into aios.config.json (no network), or reads a local file via --config.
2. Scaffold — git clones the base engine (server.js, public/, layouts, aios.plist.template) into your target dir (or copies a local checkout with --local).
3. Write config — writes aios.config.json beside server.js.
4. Personalize — runs claude -p with AIOS-MASTER-PROMPT.md + your config so Claude themes the dashboard, generates your daily-digest skill, and wires your best ~/.claude/skills as terminal buttons. A failed pass never breaks the dashboard — it just leaves the neutral base in place.
5. Install — npm install, then the node-pty fix (chmod +x node_modules/node-pty/prebuilds/*/spawn-helper) so the embedded terminal can spawn sessions.
6. Launch — starts the server detached and opens http://localhost:<port>.

After it runs, you own everything in the target dir. For always-on at login, install the launchd agent from the shipped aios.plist.template.

Publishing (maintainers)

This package is self-contained: it bundles lib/config-code.mjs (a copy of the canonical monorepo lib/config-code.mjs — keep in sync) and AIOS-MASTER-PROMPT.md, and ships zero runtime dependencies. The files field in package.json limits the tarball to bin/, lib/, the master prompt, and this README.

# from the installer/ directory
node bin/aios-builder.js --help            # sanity check
node --check bin/aios-builder.js           # syntax check
node --check lib/config-code.mjs
node lib/config-code.mjs                  # run the transport self-test
npm pack --dry-run                        # inspect what would be published
npm publish                               # publish to npm (bump version first)

After publishing, anyone can run npx aios-builder <code> — no local checkout required.

Notes

• Loopback only: the dashboard binds 127.0.0.1 + ::1. Nothing is exposed to your network.
• Secrets are never printed or committed by the installer or the Claude pass.
• Update the engine later with git pull in the project; your .env, design.md, generated theme/skill, and config are git-ignored so pulls don't clobber your customization.