Golem Scala Code Generation
Developmentgolem-scala-code-generationGolem Scala Code Generation is an Agent Skill for development published in the golemcloud/golem repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
Generating Scala code in the Golem Scala SDK. Use when adding code generation steps, build-time source generators, scalameta AST construction, or sbt/Mill sourceGenerators to the sdks/scala/ subtree.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/golemcloud/golem/blob/HEAD/.agents/skills/golem-scala-code-generation/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/golem-scala-code-generation, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
Golem Scala Code Generation
Guidelines for writing Scala code generators in the Golem Scala SDK.
Core Principle: Scalameta AST, Never String Templates
Always construct generated code as scalameta AST nodes using quasiquotes (q"...", t"...", source"...", param"..."). Never use string interpolation or text templates to produce Scala source files.
// ✅ Correct — typed AST
val tree = q"""
object $name {
def register(): Unit = {
..$registrations
()
}
}
"""
// ❌ Wrong — string interpolation
val code = s"""object $name {
def register(): Unit = { ... }
}"""
Shared Codegen Library (sdks/scala/codegen/)
All build-time code generation logic lives in sdks/scala/codegen/, a pure (no ZIO, no sbt, no Mill) Scala library that cross-compiles to Scala 2.12 (for sbt) and Scala 3.3.7 (for Mill). Both plugins depend on this shared library.
Cross-compilation constraints
Because the library must compile under Scala 2.12:
- Use
import scala.meta.dialects.Scala213for the implicit dialect needed by quasiquotes and.parse[T]calls. - For parsing with a specific dialect, use
dialects.Scala3(code).parse[Source](explicit dialect application) rather thanimplicit val d: Dialect = ...which causes ambiguity. - Use
parseMeta[T](code)(implicit parse: Parse[T])helper pattern for snippet parsing. - Avoid Scala 3-only syntax in shared code.
Type and term references
Parse dotted strings into scalameta AST nodes for use in quasiquotes:
private def parseMeta[T](code: String)(implicit parse: Parse[T]): T =
Scala213(code).parse[T].get
private def parseTermRef(dotted: String): Term.Ref =
parseMeta[Term](dotted).asInstanceOf[Term.Ref]
private def parseType(tpe: String): Type =
parseMeta[Type](tpe)
private def parseImporter(dotted: String): List[Importer] =
parseMeta[Stat](s"import $dotted").asInstanceOf[Import].importers
API pattern
Generators should expose a pure, effect-free API that accepts source text and returns generated outputs + diagnostics:
object MyCodegen {
final case class GeneratedFile(relativePath: String, content: String)
final case class Warning(path: Option[String], message: String)
final case class Result(files: Seq[GeneratedFile], warnings: Seq[Warning])
def generate(inputs: ...): Result = {
// 1. Parse/scan inputs
// 2. Build scalameta AST via quasiquotes
// 3. Pretty-print via .syntax
// 4. Return GeneratedFile with relative path + content
}
}
The plugin wrappers (sbt/Mill) handle file I/O, logging, and build-tool integration.
Build Integration Pattern
sbt Plugin (sdks/scala/sbt/)
The sbt plugin GolemPlugin is an AutoPlugin compiled as part of the meta-build via ProjectRef in project/plugins.sbt. It hooks into sourceGenerators:
Compile / sourceGenerators += Def.task {
val inputs = scalaSources.map { f =>
MyCodegen.SourceInput(f.getAbsolutePath, IO.read(f))
}
val result = MyCodegen.generate(inputs)
result.warnings.foreach(w => log.warn(s"[golem] ${w.message}"))
result.files.map { gf =>
val out = managedRoot / gf.relativePath
IO.write(out, gf.content)
out
}
}.taskValue
For new generators:
- Add the pure generation logic to
sdks/scala/codegen/src/main/scala/golem/codegen/. - Add sbt integration in
sdks/scala/sbt/src/main/scala/golem/sbt/. - Hook into
Compile / sourceGeneratorsas a.taskValue. - Use
FileFunction.cachedwithFileInfo.hashif the generation has an input file (schema, WIT, etc.) to avoid unnecessary regeneration.
Mill Plugin (sdks/scala/mill/)
The Mill plugin GolemAutoRegister is a trait mixed into ScalaJSModule. It uses generatedSources and T { ... } tasks. Follow the same pattern as golemGeneratedAutoRegisterSources.
Shared logic, not duplicated
All generation logic lives in sdks/scala/codegen/. The sbt and Mill plugins are thin wrappers that:
- Collect source files and read their contents
- Call the shared
generate(...)function - Log warnings
- Write returned files under managed/generated roots
- Configure build-tool-specific hooks (module initializers, compile dependencies)
When adding a new generation step, implement the logic once in sdks/scala/codegen/, then add thin wrappers in both GolemPlugin.scala and GolemAutoRegister.scala.
Existing Code Generation in Golem Scala SDK
1. Auto-Registration (shared codegen + sbt/Mill wrappers)
Scans sources for @agentImplementation classes using scalameta's parser, then generates RegisterAgents.scala and per-package __GolemAutoRegister_*.scala files using scalameta quasiquotes.
Key behavior: When golemBasePackage is set, the plugin adds a scalaJSModuleInitializer pointing to RegisterAgents.main(). The codegen generates this class only if @agentImplementation classes are found. If no implementations are found (e.g. because source directories don't include the component subdirectory), the module initializer references a non-existent class, causing a Scala.js linker error. See the "Known Issue: Multi-Component App" section in the golem-scala-development skill.
Files:
sdks/scala/codegen/src/main/scala/golem/codegen/autoregister/AutoRegisterCodegen.scala— shared logicsdks/scala/sbt/src/main/scala/golem/sbt/GolemPlugin.scala— sbt wrapper (source generator + module initializer)sdks/scala/mill/src/golem/mill/GolemAutoRegister.scala— Mill wrapper
2. RPC Client Generation (shared codegen + sbt/Mill wrappers)
Scans sources for @agentDefinition traits, extracts their method surfaces, and generates XClient companion objects with XRemote traits and per-method wrapper classes.
Generated per-method class provides five call modes:
apply(args...)— async await viaasyncInvokeAndAwaithost function + pollablecancelable(args...)— returns(Future[Out], CancellationToken)for cancellable async awaittrigger(args...)— fire-and-forget viainvokehost functionscheduleAt(args..., when)— scheduled invocationscheduleCancelableAt(args..., when)— cancelable scheduled invocation
Runtime call chain: Generated method → AbstractRemoteMethod.awaitWith/cancelableAwaitWith/triggerWith/scheduleWith → ResolvedAgent.await/cancelableAwait/trigger/schedule → RpcInvoker.asyncInvokeAndAwait/cancelableAsyncInvokeAndAwait/invoke/... → WasmRpcApi.WasmRpcClient → WIT golem:agent/[email protected] wasm-rpc resource
Key async detail: The default apply() path uses async-invoke-and-await (not invoke-and-await), returning a FutureInvokeResult resource. The runtime polls via subscribe() → pollable.promise() → get(), yielding genuine async Futures that allow concurrent RPC calls. This matches the TypeScript SDK behavior.
Files:
sdks/scala/codegen/src/main/scala/golem/codegen/rpc/RpcCodegen.scala— shared generation logicsdks/scala/core/js/src/main/scala/golem/runtime/rpc/AbstractRemoteMethod.scala— base class for generated wrapperssdks/scala/core/js/src/main/scala/golem/runtime/rpc/AgentClientRuntime.scala—ResolvedAgentwith async/cancelable dispatchsdks/scala/core/js/src/main/scala/golem/runtime/rpc/RemoteAgentClient.scala—WasmRpcInvokerimplementing pollable-based asyncsdks/scala/core/js/src/main/scala/golem/runtime/rpc/host/WasmRpcApi.scala— Scala.js facades forWasmRpcandFutureInvokeResultsdks/scala/core/js/src/main/scala/golem/runtime/rpc/RpcInvoker.scala— trait with sync, async, and cancelable invoke methodssdks/scala/core/js/src/main/scala/golem/runtime/rpc/CancellationToken.scala— cancellation token (wraps() => Unit)sdks/scala/sbt/src/main/scala/golem/sbt/GolemPlugin.scala— sbt wrappersdks/scala/mill/src/golem/mill/GolemAutoRegister.scala— Mill wrapper
3. Scala 3 Macros (compile-time, not build-time)
Macros generate code at compile time, not as a build step. They live in sdks/scala/macros/ and use scala.quoted.*:
AgentDefinitionMacro— extractsAgentMetadatafrom@agentDefinitiontraitsAgentImplementationMacro— generates implementation wrappers from@agentImplementationclassesAgentClientMacro— generates RPC client typesAgentCompanionMacro— generates companion object boilerplate (get,getPhantom, etc.)
These are not build-time code generators. Do not confuse them with sourceGenerators.
Generation Pipeline Shape
Follow this pipeline for new generators:
1. Load schema/input (WIT file, annotation scan, external spec)
2. Parse into models (typed case classes, not raw strings)
3. Classify/transform (determine what code to emit)
4. Build AST (scalameta quasiquotes)
5. Pretty-print (.syntax on the AST root)
6. Return (GeneratedFile with relativePath + content)
The plugin wrappers handle file writing, formatting, and incremental build integration.
Conventions
- Pure functions — all generator methods are pure. No ZIO, no sbt/Mill types, no file I/O in the shared library.
- Trait mixin composition — split generators into traits (
ModelGenerator,ClientGenerator, etc.) and mix them into the main codegen class if complexity warrants it. - Dialect-aware — use
dialects.Scala3for parsing user sources (withScala213fallback). UseScala213for quasiquote construction (compatible with both 2.12 and 3.x codegen host). - Generated file header — include
/** Generated. Do not edit. */as a comment in generated objects/classes. - Output location — write to
sourceManaged(sbt) orT.dest(Mill), never to source directories.