Permalink Plugin

Turns file-path mentions in the agent's reply into clickable links on your Git hosting platform.

Recognized automatically from the repo URL:

Platform	URL pattern
GitHub	`github.com`
GitLab.com	`gitlab.com`
Gitea / Forgejo	hostname contains `gitea.` or `forgejo.`
Codeberg	`codeberg.org`
Bitbucket	`bitbucket.org`
Azure DevOps	`dev.azure.com` or `*.visualstudio.com`

Self-hosted GitLab (or anything else that does not match those patterns) needs options.platform or options.permalink_template on the repo.

Only the main agent's replies are rewritten. Subagent output is left unchanged. Paths already inside Markdown links, and paths inside fenced code blocks, are left as-is. Unresolvable paths are left as-is.

If Branch Switching is active, links use the conversation's current branch instead of the repo's configured ref (unless the repo is pinned to a commit).

Configuration

plugins:
  - module: codumentor.plugins.permalink
    class: PermalinkPlugin
    args:
      enabled: true
      link_format: markdown   # or 'plain' for bare URLs (default: 'markdown')

Parameters

Key	Type	Default	Description
`enabled`	bool	`true`	Master switch.
`link_format`	`"markdown"` or `"plain"`	`"markdown"`	Markdown links (` path `) or bare URLs.

Per-repository overrides

repos:
  - url: https://git.example.com/org/repo.git
    name: MyRepo
    options:
      # Force a built-in URL layout when auto-detect would miss
      # (github, gitlab, gitea, bitbucket, azure_devops):
      platform: gitlab
      # Or a full custom template. Placeholders: {base_url}, {owner},
      # {repo}, {org}, {project}, {commit}, {path}
      permalink_template: "{base_url}/{owner}/{repo}/-/blob/{commit}/{path}"

permalink_template wins over platform. Repos that only have a local path (no url) never get permalinks.

What gets linked

In order, in each reply:

Full repo paths — MyRepo/src/utils.py
Relative paths — src/utils.py or src/utils/
Bare filenames — utils.py (common code/doc extensions only)

Relative paths and bare names are resolved from files the agent already opened in this conversation when that is unambiguous, otherwise from a unique match across configured repos. Ambiguous names are left unchanged.