Mod development

modular mod works against the mod development bridge in the running app.

Create and check a mod

modular mod create coding-worker \
  --display-name 'Coding Worker' \
  --description 'Runs a durable coding-agent terminal.'

modular mod check local.coding-worker

Names are kebab-case and install as local.<name>. check reports the static, fold, build, and runtime verdict for the committed generation.

Everyday workflow

edit source
  └──▶ wait for its generation
        └──▶ read the verdict
              └──▶ inspect the API only when needed

For automation, wait for the exact source snapshot:

modular mod check local.coding-worker \
  --source-content-hash d071ef44a7f0 \
  --timeout-ms 15000

Or accept that generation or a newer one:

modular mod check local.coding-worker \
  --min-source-generation 12 \
  --timeout-ms 15000

A wait selector requires --timeout-ms. Without a selector, check returns the current committed verdict immediately. An unavailable layer is not a pass.

Inspect the installed SDK

Read the SDK that this app actually exposes:

modular mod docs local.coding-worker
modular mod docs local.coding-worker --page surface
modular mod docs local.coding-worker --symbol TerminalAgent

Use docs --symbol before writing an unfamiliar export. After the symbol is in source, query its resolved type at an exact position:

modular mod language local.coding-worker hover src/mod.ts \
  --line 18 --column 24

Line and column are zero-based. Query kinds are hover, definition, references, completions, and signature-help.

Inspect and recover generations

modular mod ledger local.coding-worker --limit 10
modular mod diff local.coding-worker --from 11 --to 12
modular mod rollback local.coding-worker --to-generation 11

ledger lists retained generations. diff compares their generated public declarations. rollback promotes a retained generation without rewriting your current source files.

Command reference

Command	Use it for
list [--query <text>]	find installed mod ids
create	install a new local starter
check	read or await a build verdict
docs	read installed SDK documentation
language	query the current source snapshot
ledger	list retained generations
diff	compare generated declarations
rollback	promote a retained generation
delete	uninstall the mod and remove its source

delete is irreversible:

modular mod delete local.coding-worker

Successful commands print JSON. Use modular mod <command> --help for the live option contract.