What gtdx new Generates

gtdx new writes about twenty files. Most of them you will never touch. This page says what each one is, so you know where to start and — just as usefully — what to leave alone.

Run it and see:

gtdx new my-ext --kind design --yes
cd my-ext

The three files you actually edit

Everything else is scaffolding around these.

File	What it is
src/lib.rs	The component. Implements the exports your kind’s contract requires.
describe.json	The manifest. Identity, permissions, and what the extension contributes.
wit/world.wit	The world your component targets — which interfaces it imports and exports.

describe.json is what gets listed

src/lib.rs implements behaviour; contributions in describe.json is what the designer offers to users. A tool implemented in the guest but missing from contributions is never surfaced. Keep the two in step — gtdx lint --dir . checks the pairing.

What the shipped example does

Since 1.2.7, four kinds scaffold with one working example rather than empty stubs, so a fresh gtdx dev --once produces something you can see and copy:

--kind	Example	What it exercises
design	an echo tool	tool listing, input/output schemas, invocation
provider	a webhook channel	channel listing, credential + config schemas, dry-run encoding
deploy	a dry-run target	target listing, both schemas, a deploy/poll cycle that completes
bundle	a starter recipe	recipe listing, config schema, supported capabilities

llm and mcp already shipped working examples. wasm-component has no guest at all — it wraps a component someone else published, so it is describe-only.

addon (added in 1.2.13) sits between those two extremes: validation.validate-config, validation.validate-desired-state, workload.render-workload, and reconciler.plan are fully implemented, but reconciler.observe and reconciler.apply deliberately fail — they need a live backing service the scaffold cannot provide. See Addon Extensions.

Replace the example rather than adding beside it. It exists to be read once and then deleted.

One export is deliberately unimplemented

bundle’s render returns an error on purpose. A BundleArtifact carries the artifact bytes and their sha256, and consumers verify that digest — a placeholder hash fails later, and further from its cause, than an honest error. The scaffold ships no hashing crate; add sha2, build your bytes, hash them, and return all three together.

Generated — never edit these

Editing them is wasted work: they are rewritten on the next build, or they encode a version you do not control.

File	Why
src/bindings.rs	~3,400 lines of WIT ABI glue, regenerated by cargo component on every build. Header says DO NOT EDIT. Already gitignored.
wit/deps/	Vendored copies of the contracts your world depends on, pinned by the lock below.
.gtdx-contract.lock	Records which contract version was vendored, so a rebuild cannot silently drift.
Cargo.lock	Standard Cargo lockfile.

src/bindings.rs being large is normal — it is the canonical ABI marshalling for every interface in your world, not code anyone wrote by hand. Your own file next to it is under 200 lines.

Build and quality plumbing

File	What it does
Cargo.toml	Crate manifest, plus [package.metadata.component] telling cargo-component which WIT world to build against.
rust-toolchain.toml	Pins the Rust version and the wasm32-wasip2 target, so the project builds the same everywhere.
build.sh	One-liner wrapper for cargo component build --release.
ci/local_check.sh	The gate to run before publishing: fmt, clippy, test, build.
.gitignore	Excludes target/, dist/, src/bindings.rs, and *.gtxpack.

Content the extension ships

File	What it does
i18n/en.json	User-facing strings. Add locales alongside it; the designer picks by the viewer’s locale.
prompts/system.md	Prompt text contributed to the designer’s LLM context. Only scaffolded for kinds that can contribute prompts.
README.md	Starter readme for your extension, not for the SDK.

Onboarding for AI coding agents

File	What it does
AGENTS.md	Which values are placeholders to replace, and which files must never be hand-edited.
CLAUDE.md	Points Claude Code at AGENTS.md.
.claude/settings.json	Pre-approved build permissions, so an agent can compile without prompting for each command.
.claude/commands/check.md	A /check command that runs the local quality gate.

These are inert if you do not use an agent — plain markdown and a settings file.

What differs per kind

The layout above is the same for every kind. Only two things change:

• wit/deps/ carries the contracts that kind needs — extension-bundle for bundle, extension-provider for provider, wasix-mcp for mcp, and so on.
• prompts/system.md is scaffolded only for kinds that can contribute prompts (design, wasm-component, llm).

After the first build

gtdx dev --once adds two paths, both gitignored:

• target/ — Cargo’s build directory, including the compiled .wasm
• dist/<name>-<version>.gtxpack — the packed extension, with a manifest.json integrity ledger the runtime verifies at install

It also fills the real sha256 digests into describe.json, replacing the all-zero placeholders the scaffold ships. Those placeholders are why gtdx lint --publish fails on a project that has never been built — build once, and it passes.

Next

• Extension Quickstart — the full path, from install to publish
• Writing Extensions — what to put in describe.json and the component
• describe.json Manifest — the full field reference