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: Maintains and extends the scaffold-agent npm CLI that generates onchain AI agent monorepos (Foundry/Hardhat + Next.js/Vite/Python), including -y flags, agent.json --from-config, --dump-config, --swarm, Shroud/1claw, and embedded Next/Vite templates. Use when editing this repository, changing CLI behavior or templates, running or documenting npx scaffold-agent, or answering questions about generated repos vs this generator codebase.4---56# scaffold-agent (generator repo)78## Scope910This 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.1112## Before editing13141. Read **`AGENTS.md`** (root) for the full code map, security rules, and Shroud notes.152. After any change under **`src/`**, run **`npm run build`** before validating **`node dist/cli.js`** or **`npx scaffold-agent`**.1617Files that always warrant a rebuild when touched:1819| Path | Role |20|------|------|21| `src/cli.ts` | Entry, env write, 1Claw setup, dump-config path |22| `src/cli-argv.ts` | `parseArgs`, flag definitions, `-y` defaults |23| `src/cli-wizard.ts` | `gatherWizardInputs`, swarm / config validation |24| `src/agent-project-config.ts` | `agent.json` load/merge, swarm plan, dump JSON builder |25| `src/actions/scaffold.ts` | Monorepo layout, justfile, large embedded templates |26| `src/scaffold-templates/*.ts` | Reusable generated UI/network/wallet/swarm snippets |27| `src/actions/project-scripts.mjs` templates | `fund-deployer`, `swarm-agents`, etc. |2829## Local CLI3031```bash32npm install && npm run build33node dist/cli.js --help34node dist/cli.js my-dir # interactive35```3637Strict parsing: unknown flags **error**.3839## Config file (`agent.json`)4041- **`--from-config <file>`** — Merge JSON into flags; **CLI overrides file** for any flag passed on the command line.42- 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).43- Loader / merge / dump logic: **`src/agent-project-config.ts`**.4445## Dump config4647- **`--dump-config`** — Print merged **`agent.json`**-shaped JSON to stdout (no scaffold, no banner).48- **`--dump-config-out <path>`** — Write the same JSON to a file (implies dump if used alone).49- Fills unset fields with the same defaults as **`-y`**; **omits** secret flags from output (passwords, API keys) so the file is safe to share.5051## Swarm5253- **`--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`**.54- Generated UI: **`lib/agent-swarm.tsx`**, header picker, **`/swarm`** page, balances/identity use selected agent.55- Post-scaffold: **`just swarm agents=N`** (see generated justfile).5657## Non-interactive (`-y`)5859Use **`-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).6061## Editing templates6263**`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.6465## Security6667- Never commit real keys or deployer private keys.68- **`ONECLAW_AGENT_ID`** is a **UUID**, not an Ethereum **`0x…`** address (Shroud rejects addresses there).6970## Terminology7172- **1claw** — [1claw.co](https://1claw.co), vault + Shroud. **OpenClaw** ([openclaw.ai](https://openclaw.ai)) is a different product.7374## More detail7576- **[reference.md](reference.md)** — Flag table and links.77- **`AGENTS.md`** — Authoritative repo instructions for humans and agents.
1clawAI