Plugin Catalog

This section documents the built-in Codumentor plugins: what they do for
users, and how to enable and configure them.

Audience: people using plugins, and operators who enable them in
codumentor.yaml.

To write a custom plugin, see the Plugin Development Guide.

One name per plugin. Every page here is named after the plugin's package:
catalog/<package>.md documents codumentor.plugins.<package>, whose web
bundle (if it has one) lives in ui/plugins/<package>/. So the file name is
also the string you write under plugins: in codumentor.yaml, and the id the
Configuration Assistant answers to. A tier-1 test enforces it, because the
packaged build filters docs and bundles per plugin by that name — a page named
anything else would ship its plugin undocumented.

Built-in Plugins

Plugin	Purpose
Telemetry	Response timing, LLM/tool metrics, transcript cards
Inference Metrics	LLM generation speed (TTFT, tokens/sec)
Context Summarization	Truncates long conversations to fit the model window
Auto Title	Names conversations from their content; opt-in topic-shift retitling
Context Management	Incremental summarization with drift detection
Agentic Memory	Stores and retrieves organizational knowledge
Agent Instructions	Operator `custom_instructions` plus optional repo-local instruction files (builtin)
MCP	Connect external Model Context Protocol tool servers
Ripgrep	Fast regex search across repositories
Web Retrieve	Fetch and analyze web pages (optional agentic mode)
Web Search	Web search with multiple providers and optional research mode
Console Report	Prints the end-of-session report in print mode
Token Report	Token counts, cost, and per-query breakdown for that report
Bug Report	User bug/feedback form forwarded to Redmine
User Feedback	Like/dislike on assistant replies
LLM Server	Auto-start, health-monitor, and idle-shutdown a self-hosted LLM
SVN	Subversion checkout/update, branch listing and switching
Branch Switching	Per-conversation git branch with isolated checkout and overlay index
Workspace Isolation	Per-conversation bwrap sandbox, snapshots, subagent isolation
SCM Push	In-sandbox `git_commit` plus a host-side Push button
Document Editor	Read, edit, and save DOCX files
XLSX Editor	Read, edit, and save XLSX/XLSM spreadsheets
PPTX Editor	Read, edit, and save PPTX/PPTM presentations
File Links	Download/preview agent-written files; repo browser
Mermaid Render	Render Mermaid diagrams to SVG/PNG (needs a Chromium-family browser)
Client Filesystem	Attach a local folder from the browser for agent read/write and @-mention
Developer	Subagent that implements a plan by reading, editing, and running code
Explore	Read-only codebase exploration subagent
External Agent	Delegate to Claude Code / Codex / OpenCode / Gemini in a sandbox
FileSync	Copy source from local/SMB/UNC paths before ingestion
Log Collection	Analyze collections of log files in isolated or merged conversations
Permalink	Turn file paths in replies into GitHub/GitLab/Gitea (etc.) links
Script Filter	Strip leaked CJK output live; translate fragments when the reply finishes
SSH Tunnel	Persistent SSH port-forward to a fixed remote server
Remote SSH	Remote command and file tools (experimental)
Skills	Agent Skills (agentskills.io) activated via slash commands
Slash Commands	User-defined `/commands` that expand to full prompts
Claude Code Hooks	Run shell commands or HTTP callouts on lifecycle events
User Secrets	Per-user encrypted credentials, referenced as `${secret:<name>}`
OAuth	Per-user OAuth 2.0 connect/refresh for Google and GitHub
GitHub OAuth	Registers GitHub as a connectable OAuth provider (device-code flow)
EULA	First-login license modal; bump `version` to re-prompt everyone
Trial	Cosmetic trial badge in the chat header
Slack Integration	Mentions, DMs, slash commands, and agent post/react tools
Telegram	Telegram bot channel with optional voice in/out
Read Aloud	Play the final assistant message via the shared TTS service
Voice Mode	Hands-free talk overlay; STT/TTS via the shared `speech:` service
Redmine	Per-user Redmine issue tools (search/get/create/update/comment)
Gitea PR	Per-user Gitea PR tools and optional `/review` webhook
Google Workspace	Per-user Gmail, Calendar, Docs, Sheets, and Drive
Database	SQL tools over native or CLI backends
Configuration Assistant	Admin chat that edits this instance's own config
Model Profiles	Per-user model/key profiles assigned to agent roles
Thinking Modes	Per-conversation thinking mode and reasoning effort
Scheduler Tools	Create and manage one-off or cron agent runs
Goals	Long-lived scheduled intents with cron-fired workers

Quick Configuration

Enable a plugin in codumentor.yaml:

plugins:
  - module: "codumentor.plugins.telemetry"
    class: "TelemetryPlugin"

  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      executable: "mcp-server"

Omit a plugin from the list to disable it. Some plugins also honor
args.enabled.

Plugin Categories

Observability

Telemetry — wall time, LLM time, tool time; cards in the transcript and a session-report section
Inference Metrics — TTFT and tokens/sec, tiered by prompt size (short/medium/long)
Console Report — prints the session report at the end of a print-mode run (session_report: true)
Token Report — token counts, cost, and per-query chart for that report (required for print-mode reports)

Context and instructions

Context Summarization — truncates long conversations to the model window
Context Management — cascading summaries, drift detection, optional history retrieval tool
Agent Instructions — prompt.custom_instructions plus optional CLAUDE.md / AGENTS.md / … (builtin; configure under agent_instructions:, not plugins:)
Auto Title — names conversations from content; optional topic-shift retitling card
Script Filter — strips leaked CJK during streaming and translates it when the reply finishes

Knowledge and feedback

Agentic Memory — stores agent answers as searchable notes; review UI and Rapid Direction Cues
User Feedback — like/dislike on assistant replies; optional dislike comment
Bug Report — in-app form that opens a Redmine issue

Tools and integrations

MCP — local (stdio) or remote (HTTP/SSE) MCP servers; one server per plugin entry
Ripgrep — fast regex search across repositories
Web Retrieve — fetch page text (and PDF/Office); optional agentic extraction; JS rendering needs a system browser
Web Search — DuckDuckGo, Brave, Tavily, Serper, Google CSE, SearXNG; optional research mode
Slack Integration — @-mentions, DMs, /codumentor; agent can post and react
Telegram — bot channel; technical_user or per_user; optional voice via speech:
Gitea PR — read PRs in chat; gated review comments; optional /review webhook
Google Workspace — each user connects their Google account from Settings
Database — list/describe/query/execute; native or CLI backends; Postgres, MySQL, Oracle, SQL Server, SQLite
Redmine — per-user issue tools, authenticating as the calling user

Documents and files

Document Editor — DOCX tools appear once a document is open
XLSX Editor — XLSX/XLSM editing
PPTX Editor — PPTX/PPTM editing
File Links — download/preview cards and a repo browser
Client Filesystem — attach a local folder; files stay on the user's machine
Permalink — file paths in replies become links to GitHub, GitLab, Gitea, …

Source control and isolation

SVN — checkout/update, trunk + branches/*, svn switch
Branch Switching — pick a git branch per conversation (needs workspace isolation)
FileSync — copy from a local directory or SMB/UNC share before ingestion
Workspace Isolation — per-conversation bwrap overlay (or host read-only)
SCM Push — git_commit in the sandbox; people click Push in the UI

Agentic tools

Developer — implement a plan by reading, editing, and running code
Explore — read-only exploration subagent
External Agent — run Claude Code / Codex / OpenCode / Gemini
Remote SSH — ssh_exec / ssh_upload / ssh_download (experimental)
Mermaid Render — render_mermaid → SVG/PNG

User experience

Slash Commands — per-user /commands that expand to prompts
Skills — reusable skills from four directory tiers, activated with slash commands
Voice Mode — full-screen talk overlay; needs speech:
Read Aloud — play the final assistant message
Trial — cosmetic header badge; no trial enforcement

Source types

Log Collection — collections of log files; isolated (logs only) or merged (logs + repos)

Infrastructure

SSH Tunnel — one persistent port-forward, reconnected on failure
LLM Server — auto-start / health / idle-shutdown for a self-hosted LLM
Claude Code Hooks — shell or HTTP callouts on agent events; Claude Code settings.json schema

Compliance and credentials

EULA — blocks the app until the user accepts; bump version to re-prompt
User Secrets — ${secret:<name>} placeholders, shell env bindings, host-only secrets
OAuth — users connect Google/GitHub from Settings; needs auth.jwt_secret
GitHub OAuth — the GitHub provider: client_id, device-code flow, read:user/repo scopes

Admin and scheduling

Configuration Assistant — admin chat: propose → diff → approve → apply → rollback
Model Profiles — users pick model/key profiles per agent role
Thinking Modes — per-conversation mode + reasoning effort; curated in thinking_modes:
Scheduler Tools — one-off and cron agent runs as tools
Goals — long-lived intents with cron-fired workers

Common configuration patterns

Enabling and disabling

plugins:
  - module: "codumentor.plugins.read_aloud"
    class: "ReadAloudPlugin"
    args:
      enabled: true

  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      executable: "mcp-server"
      enabled: false

Not every plugin has args.enabled. To be sure a plugin is off, omit it
from plugins:.

Plugin priority

Higher priority runs that plugin's handlers earlier:

plugins:
  - module: "codumentor.plugins.telemetry"
    class: "TelemetryPlugin"
    priority: 100

Agent-specific tools

Some plugins accept target_agents so tools go only to the main agent,
only to subagents, or to both:

plugins:
  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      executable: "mcp-server"
      target_agents: "main"

Options: "main", "subagent", "all" (default for most plugins).

A value may also name one subagent instead of a whole kind — "explore",
"agentic_developer", "agentic_memory_store", "web_search",
"web_retrieve", "goal", "context_summarization". So
target_agents: "explore" offers the tools to the explore reader and to
nothing else, while "subagent" keeps its meaning of any subagent. Anything
outside those names is treated as a typo: the plugin registers with every agent
and logs a warning, rather than silently withholding a tool you asked for.

A setting also takes a list, meaning any of — which is the only way to
mix the two grains:

args:
  target_agents: ["main", "explore"]   # the main agent and the explore reader

Per-plugin tables below list only the three kinds, which is the common case;
every one of them accepts a role name and a list too.

Reads and writes, gated separately

Gating a whole family forces a bad choice for an outward-facing integration: a
subagent investigating a bug has every reason to read a ticket and none to
close one. Five plugins therefore accept a second setting,
write_target_agents, in the same vocabulary, applied to their write tools
alone — redmine, gitea_pr,
google_workspace, database and
mcp. It defaults to "main" in all five: a subagent's tool calls land
with nobody reading them, so write_target_agents falls back to the closed
value on an unrecognized setting, where target_agents falls back to the open
one.

mcp is the odd one out on which tools count as writes. The other four say so
in their own code; an MCP server's tools are somebody else's, so Codumentor
reads each one's readOnlyHint annotation — and a tool that carries no
annotation is treated as a write. See Who gets which
half before wondering why a subagent cannot see
your MCP server.