Contributing
Repository layout, local build commands, branching and PR flow, CI expectations, and where to file issues.
Who this is for
GolemCore is open source under Apache 2.0. Contributions happen through pull requests against the canonical repositories on GitHub. This page is the map — what lives where, how to build locally, and what CI checks before a merge.
Repositories
golemcore-bot
The runtime. Java/Kotlin backend, React + Next.js dashboard. Gradle build. This is where almost all runtime changes land.
Runtime
golemcore-docs
This documentation site. Next.js 16 app; content is TSX modules under src/lib/docs/. No CMS — pages are code.
Docs
golemcore-hive
Optional fleet orchestrator. Separate Gradle project. Only relevant if you are working on multi-runtime coordination.
Hive
golemcore-plugins
First-party plugins (browser, search, mail, voice, LightRAG). Built against the plugin API exposed by golemcore-bot.
Extensions
Build locally
Clone the repository you need and build it directly. The runtime has no exotic tooling requirements beyond a recent JDK and Node.
git clone https://github.com/alexk-dev/golemcore-bot.git
cd golemcore-bot
./gradlew build
./gradlew bootRunBUILD SUCCESSFUL in 42s
...
Started GolemcoreBotApplication in 6.812 seconds
Tomcat started on port 8080 (http)git clone https://github.com/alexk-dev/golemcore-docs.git
cd golemcore-docs
npm install
npm run dev▲ Next.js 16.0.0
- Local: http://localhost:3000
✓ Ready in 1.8sBranching and PR flow
- Fork the repository and clone your fork.
- Branch from
main. Use a descriptive prefix —feat/,fix/,docs/,refactor/. - Make your change. Keep commits focused; a single PR should do one thing.
- Run the checks the CI will run. For the runtime:
./gradlew check. For docs:npm run check. - Open a pull request against
mainwith a description that explains the motivation, not just the diff. - Address review feedback with follow-up commits. Do not force-push during review unless you are squashing at the end.
What CI checks
Gradle check
Runtime: ./gradlew check runs unit tests, integration tests, ktlint, and detekt. Must pass on CI before merge.
Runtime
Docs check
Docs: npm run check runs type-check, lint, and a build. The custom docs loader exercises every page, so broken refs fail the build loudly.
Docs
Plugin compatibility
Plugins: plugin repositories pin against a published golemcore-bot version. If you change the plugin API, bump the consumer repos in the same PR sequence.
Plugins
Code and doc style
Follow the patterns that already exist in each repository. A few specific rules that are easy to miss:
- Runtime code: prefer immutable data classes, avoid new singletons, new public API needs a release note.
- Docs: editorial policies live in
AGENTS.md. Every new page must satisfy them. In particular, Cookbook recipes follow the prerequisites → steps → variants → gotchas → next steps shape. - Plugins: do not take direct references to runtime internals. Only the plugin API surface is stable.
- Commit messages: imperative mood, short first line, wrap the body. Reference the issue number in the footer if one exists.
Where to ask
Use GitHub Issues for bug reports and concrete feature requests. Use Discussions for design questions or open-ended ideas.
Bug: https://github.com/alexk-dev/golemcore-bot/issues
Feature request: https://github.com/alexk-dev/golemcore-bot/issues
Design question: https://github.com/alexk-dev/golemcore-bot/discussions
Docs fix: https://github.com/alexk-dev/golemcore-docs/issues