create-openfigs

Scaffold one OpenFigs employee in one line.

npm create openfigs@latest my-agent

OpenFigs is a small, file-based skeleton for building one back-office AI employee — an agent that owns a recurring job, learns from its work, and reports to a human through Figs. This is its installer.

What it does

npm create openfigs@latest [dir]
# or
npx create-openfigs [dir] [--yes] [--here] [--from <source>] [--no-init]

1. Fetches the current OpenFigs skeleton into dir (defaults to my-agent; prompts if omitted) — straight from figs-so/openfigs at runtime, so you always get the latest.
2. Regenerates the runtime symlink — CLAUDE.md → AGENTS.md (and .claude/skills → .agents/skills) — so Claude Code, Codex, and opencode all read one source of truth. (This is why a scaffolder beats a plain ZIP download: the link is rebuilt deterministically, never shipped as a broken text file.)
3. Stamps the agent's name into the skeleton's placeholders.
4. Runs figs init --yes (account-free) — so the agent has a local identity + activity journal and is ready to work with no account. (--yes confirms Figs is a fit — choosing npm create openfigs is that decision. Identity is minted here, per clone — never shipped in the skeleton, so two agents never collide. Skip with --no-init.)
5. git inits the repo with a first commit — a scaffolded agent is a real repo (the skeleton commits config.json / agent.json / CONTRACT.md; the journal + credentials stay gitignored). Skipped if the target lands inside an existing repo (e.g. --here in a monorepo).

Then:

cd my-agent
# read AGENTS.md, fill your charter in .figs/agent.json (role, mandate, department)
# work — figs records you locally from day one (no account needed)
# when your team should see it:
npx @figs-so/cli@latest login    # opens your browser — sign up & approve
npx @figs-so/cli@latest link     # join a workspace
npx @figs-so/cli@latest push     # appear on the org chart

One repo = one employee. Want a team? Run this once per job and point them at the same Figs workspace — the org chart groups them by each agent's department. Never copy a scaffolded folder to make another (a copy carries the original's identity); scaffold fresh so each mints its own.

Options

| Flag | What | |---|---| | --from <source> | skeleton source: github:owner/repo[#ref] or a local path (default: github:figs-so/openfigs; or set OPENFIGS_SOURCE) | | --here | scaffold into the current directory | | --no-init | skip running figs init (you'll run it yourself) | | -y, --yes | non-interactive (no prompts) | | -h, --help | usage |

Prefer the raw skeleton with no init/prompts? npx degit figs-so/openfigs my-agent.

How the skeleton is fetched (always current)

The skeleton is not bundled here — it's fetched from the canonical openfigs repo at runtime (zero-dependency: Node fetch + the GitHub tarball + tar). So new agents always get the latest skeleton, and this package only needs a release when the scaffolder logic itself changes — never just because openfigs changed.

Point it elsewhere with --from (a fork, a pinned #tag, or a local checkout):

npx create-openfigs my-agent --from github:me/openfigs-fork#v1.2.0
npx create-openfigs my-agent --from ../openfigs          # local path (offline / dev)

Developing locally (with the openfigs repo as a sibling directory):

npm test     # smoke-test against ../openfigs (no network): scaffold + assert the live symlink

Licensing

• This repo — the scaffolder: MIT. Use it, fork it, point it at your own skeleton with --from.
• The hosted app at app.figs.so is a commercial product (closed source). Everything an agent records is .figs, an open format you can read or export anytime.

By contributing, you agree your contributions are MIT-licensed. See CONTRIBUTING.md.

The Figs ecosystem

Figs is one stack in three pieces — build → report → govern. Land on any repo; here's the whole picture:

| Layer | Repo | License | Role | |---|---|---|---| | 🏗️ Build | OpenFigs | MIT | build trustworthy back-office AI employees — conventions + skeleton, runtime-agnostic | | 🚀 On-ramp | create-openfigs | MIT | npm create openfigs — scaffold one employee in one line — ← you're here | | 📤 Report | .figs + CLI | MIT | the open standard an agent reports its state in | | 👁️ Govern | Figs app | hosted | the org chart + handoff inbox humans read |

Links

• 🌐 Landing: figs.so
• 🖥️ App: app.figs.so
• 📦 npm: create-openfigs
• 🏗️ Skeleton: figs-so/openfigs