scaffold-agent (generator repo)
Scope
This workspace is the npm package that writes new project directories. It is not a Scaffold-ETH / Next app inside packages/—those only exist after someone runs the CLI. Treat src/ as the source of truth for behavior; dist/cli.js is build output.
Before editing
- Read
AGENTS.md (root) for the full code map, security rules, and Shroud notes.
- After any change under
src/, run npm run build before validating node dist/cli.js or npx scaffold-agent.
Files that always warrant a rebuild when touched:
| Path |
Role |
src/cli.ts |
Entry, env write, 1Claw setup, dump-config path |
src/cli-argv.ts |
parseArgs, flag definitions, -y defaults |
src/cli-wizard.ts |
gatherWizardInputs, swarm / config validation |
src/agent-project-config.ts |
agent.json load/merge, swarm plan, dump JSON builder |
src/actions/scaffold.ts |
Monorepo layout, justfile, large embedded templates |
src/scaffold-templates/*.ts |
Reusable generated UI/network/wallet/swarm snippets |
src/actions/project-scripts.mjs templates |
fund-deployer, swarm-agents, etc. |
Local CLI
npm install && npm run build
node dist/cli.js --help
node dist/cli.js my-dir # interactive
Strict parsing: unknown flags error.
Config file (agent.json)
--from-config <file> — Merge JSON into flags; CLI overrides file for any flag passed on the command line.
- Shape: top-level or
options object for CLI-like keys; project / name, swarm, agents (id → preset string), extra (written to generated agent.config.extra.json when present).
- Loader / merge / dump logic:
src/agent-project-config.ts.
Dump config
--dump-config — Print merged agent.json-shaped JSON to stdout (no scaffold, no banner).
--dump-config-out <path> — Write the same JSON to a file (implies dump if used alone).
- Fills unset fields with the same defaults as
-y; omits secret flags from output (passwords, API keys) so the file is safe to share.
Swarm
--swarm <n> (1–64): multiple generated agent wallets; first remains AGENT_ADDRESS / AGENT_PRIVATE_KEY; extras in encrypted SWARM_AGENT_KEYS_JSON. Public roster: packages/*/public/agents.json.
- Generated UI:
lib/agent-swarm.tsx, header picker, /swarm page, balances/identity use selected agent.
- Post-scaffold:
just swarm agents=N (see generated justfile).
Non-interactive (-y)
Use -y for CI/agents. --env-password (≥ 6 chars) is required when --secrets is oneclaw or encrypted, unless --secrets none. Shroud edge cases: see AGENTS.md and reference.md.
Editing templates
src/actions/scaffold.ts holds very large template strings—prefer small diffs, preserve escaping, match existing style. For UI pieces, prefer src/scaffold-templates/ when a module already exists there.
Security
- Never commit real keys or deployer private keys.
ONECLAW_AGENT_ID is a UUID, not an Ethereum 0x… address (Shroud rejects addresses there).
Terminology
More detail
- reference.md — Flag table and links.
AGENTS.md — Authoritative repo instructions for humans and agents.
1---2name: scaffold-agent3description: >-4 Maintains and extends the scaffold-agent npm CLI that generates onchain AI agent5 monorepos (Foundry/Hardhat + Next.js/Vite/Python), including -y flags, agent.json6 --from-config, --dump-config, --swarm, Shroud/1claw, and embedded Next/Vite templates.7 Use when editing this repository, changing CLI behavior or templates, running or8 documenting npx scaffold-agent, or answering questions about generated repos vs this9 generator codebase.10metadata:11 source: https://skillmd.com/skills/1clawai/scaffold-agent12---1314# scaffold-agent (generator repo)1516## Scope1718This workspace is the **npm package** that **writes** new project directories. It is **not** a Scaffold-ETH / Next app inside `packages/`—those only exist **after** someone runs the CLI. Treat **`src/`** as the source of truth for behavior; **`dist/cli.js`** is build output.1920## Before editing21221. Read **`AGENTS.md`** (root) for the full code map, security rules, and Shroud notes.232. After any change under **`src/`**, run **`npm run build`** before validating **`node dist/cli.js`** or **`npx scaffold-agent`**.2425Files that always warrant a rebuild when touched:2627| Path | Role |28|------|------|29| `src/cli.ts` | Entry, env write, 1Claw setup, dump-config path |30| `src/cli-argv.ts` | `parseArgs`, flag definitions, `-y` defaults |31| `src/cli-wizard.ts` | `gatherWizardInputs`, swarm / config validation |32| `src/agent-project-config.ts` | `agent.json` load/merge, swarm plan, dump JSON builder |33| `src/actions/scaffold.ts` | Monorepo layout, justfile, large embedded templates |34| `src/scaffold-templates/*.ts` | Reusable generated UI/network/wallet/swarm snippets |35| `src/actions/project-scripts.mjs` templates | `fund-deployer`, `swarm-agents`, etc. |3637## Local CLI3839```bash40npm install && npm run build41node dist/cli.js --help42node dist/cli.js my-dir # interactive43```4445Strict parsing: unknown flags **error**.4647## Config file (`agent.json`)4849- **`--from-config <file>`** — Merge JSON into flags; **CLI overrides file** for any flag passed on the command line.50- Shape: top-level or **`options`** object for CLI-like keys; **`project`** / **`name`**, **`swarm`**, **`agents`** (id → preset string), **`extra`** (written to generated **`agent.config.extra.json`** when present).51- Loader / merge / dump logic: **`src/agent-project-config.ts`**.5253## Dump config5455- **`--dump-config`** — Print merged **`agent.json`**-shaped JSON to stdout (no scaffold, no banner).56- **`--dump-config-out <path>`** — Write the same JSON to a file (implies dump if used alone).57- Fills unset fields with the same defaults as **`-y`**; **omits** secret flags from output (passwords, API keys) so the file is safe to share.5859## Swarm6061- **`--swarm <n>`** (1–64): multiple generated agent wallets; first remains **`AGENT_ADDRESS`** / **`AGENT_PRIVATE_KEY`**; extras in encrypted **`SWARM_AGENT_KEYS_JSON`**. Public roster: **`packages/*/public/agents.json`**.62- Generated UI: **`lib/agent-swarm.tsx`**, header picker, **`/swarm`** page, balances/identity use selected agent.63- Post-scaffold: **`just swarm agents=N`** (see generated justfile).6465## Non-interactive (`-y`)6667Use **`-y`** for CI/agents. **`--env-password`** (≥ 6 chars) is required when **`--secrets`** is **`oneclaw`** or **`encrypted`**, unless **`--secrets none`**. Shroud edge cases: see **`AGENTS.md`** and [reference.md](reference.md).6869## Editing templates7071**`src/actions/scaffold.ts`** holds very large template strings—prefer **small diffs**, preserve escaping, match existing style. For UI pieces, prefer **`src/scaffold-templates/`** when a module already exists there.7273## Security7475- Never commit real keys or deployer private keys.76- **`ONECLAW_AGENT_ID`** is a **UUID**, not an Ethereum **`0x…`** address (Shroud rejects addresses there).7778## Terminology7980- **1claw** — [1claw.co](https://1claw.co), vault + Shroud. **OpenClaw** ([openclaw.ai](https://openclaw.ai)) is a different product.8182## More detail8384- **[reference.md](reference.md)** — Flag table and links.85- **`AGENTS.md`** — Authoritative repo instructions for humans and agents.