Skip to content

Helmholtz Codebase AI Assistant

What is this?

The Helmholtz Codebase AI Assistant is an automated code-review and improvement bot for your GitLab projects, powered by PR-Agent. Once connected, it reviews and improves every merge request (MR) by posting inline suggestions, answering questions, preparing a changelog entry or adding documentation using configurable slash commands (similar to GitLab quick actions).

The integration is built in a way that it works out of the box.

Status: Alpha Test

This is an early integration, depicted as alpha test. We appreciate your feedback (see below).

Privacy and data security by design

The entire stack - the PR-Agent service and every language model we offer – is hosted in the data center of the Helmholtz Codebase provider (HZDR). Your code and data never leave the facility.

No agentic methods

PR-Agent is currently built in a way that there is no autonomous tool calling implemented. In the future it might implement the capability to extend its context by reading additional lines or files.

Setup

1. Configure the project webhook

In your project’s Settings → Webhooks, add a new webhook:

Field Value
Name Helmholtz Codebase AI Assistant
URL https://code-agent.fz-rossendorf.de/webhook
Secret token hifis
Trigger events Push Events, Comments, Merge Request Events

Note on the token

The receiver is only reachable from HZDR GitLab servers, so the token is not a security boundary. However, the current PR-Agent implementation requires a non-empty secret to be set.

Use the Test → Merge request hook button in GitLab to confirm delivery.

2. Add the bot user to your project or group
Username helmholtz-codebase-agent
Recommended role Developer
Minimum role Reporter

Developer (recommended for all features to work)

  • Can comment on MRs
  • Can push to non-protected branches, which is required for /update_changelog --pr_update_changelog.push_changelog_changes=true

Reporter (minimum)

  • Most features still work, but the bot cannot push changes back to branches
  • See the restricted-mode docs for the full list of affected features

We use it to gather feedback during the alpha and to announce updates.

Verify your setup

  1. Create a small test MR in your project (even a one-line change works).
  2. Within a few minutes you should see comments from helmholtz-codebase-agent running /review and /improve.
  3. If nothing appears after ~10 minutes, see Troubleshooting.

Default behaviour

Only the settings that differ from PR-Agent defaults are listed here. The defaults are tuned to reduce noise.

  • Model: deepseek-v4.1-flash
  • reasoning_effort = max
  • Context window: 1 M tokens
  • qwen3.8-27b is used for self-reflecting findings with reasoning_effort set to xhigh
  • Suggestion threshold: --pr_code_suggestions.suggestions_score_threshold = 7 (any suggestion scoring below 7 is dropped)
  • On MR creation: /review and /improve run automatically

Customising the configuration

You can override settings at the project or group level via a config file, or pass options inline with slash commands. See the full Configuration Options reference.

Choosing a different model

Besides the default DeepSeek V4.1 Flash, additional models are hosted at HZDR:

Model Config value reasoning_effort Notes
DeepSeek V4.1 Flash (default) openai/deepseek-v4.1-flash-hosted-at-hzdr max 1M context
Qwen 3.8 27B openai/qwen3.8-27b-hosted-at-hzdr xhigh 256K context

Via config file (.pr_agent.toml in the repo root, or group level):

1
2
3
[config]
model = "openai/qwen3.8-27b-hosted-at-hzdr"
reasoning_effort = "xhigh"

Tuning feedback volume

To get more (and lower-scoring) suggestions, try to lower the threshold:

1
2
3
[pr_code_suggestions]
suggestions_score_threshold = 3
focus_only_on_problems = false

Or in a single command:

1
/improve --pr_code_suggestions.suggestions_score_threshold=0 --pr_code_suggestions.focus_only_on_problems=false

Cost and energy impact

Lowering the threshold to 0 and disabling focus_only_on_problems makes the model generate and self-reflect on considerably more suggestions. Each run consumes GPU time on the HZDR infrastructure. Prefer a moderate value (e.g. 3) over 0 for day-to-day use, and use 0 selectively via the inline command when you actually want to see everything.

Troubleshooting

Symptom Likely cause / fix
No comments on an MR The bot user helmholtz-codebase-agent is not added to the project, or the webhook is missing / misconfigured. Check Settings → Webhooks → Test.
Webhook fires but bot stays silent Verify the secret token in the webhook matches what the service expects.
All suggestions are filtered out suggestions_score_threshold is too high (default 7). Lower it, e.g., try 3 first (0 shows everything).
/update_changelog doesn’t push The bot needs Developer role (push access to non-protected branches).
Bot reacts to comments but not MRs Ensure Merge Request Events is ticked in the webhook triggers.

If none of the above helps, ask in the Matrix channel.

Removing the agent

To disconnect the agent from a project:

  1. Delete the webhook under Settings → Webhooks.
  2. Remove the helmholtz-codebase-agent user from the project/group members.