Plugin Catalog

This section documents the available Codumentor plugins and how to configure them.

Audience: Users configuring and using plugins

For creating custom plugins, see the Plugin Development Guide.

Built-in Plugins

Plugin	Purpose	Documentation
Telemetry	Response timing, LLM/tool metrics	Tracks wall time, LLM calls, tool usage
Inference Metrics	LLM generation performance	Tracks TTFT, tokens/sec, tiered by prompt size
Context Summarization	Context window management	Truncates long conversations intelligently
Auto Title	Automatic conversation titling	Names conversations from content; opt-in topic-shift retitling + card
Context Management	Proactive context management	Incremental summarization with drift detection
Agentic Memory	Organizational knowledge storage	Auto-stores and retrieves knowledge
MCP	Model Context Protocol integration	Connect external MCP tool servers
Ripgrep	Fast code search	Pattern search across repositories
Web Retrieve	Web content retrieval	Fetch and analyze web pages with optional agentic processing
Web Search	Web search	Search the web with multiple provider support and optional research mode
Console Report	End-of-session report renderer	Prints structured session report from plugin-contributed sections
Token Report	Token usage section for session report	Tracks token counts, cost, and per-query breakdown
Bug Report	Bug reports and feedback	Submits user reports to Redmine as tracked issues
User Feedback	Turn-level response feedback	Adds like/dislike actions with optional dislike comments
LLM Server	LLM server management	Auto-start, health monitoring, inactivity shutdown
SVN	Subversion repository support	Checkout/update SVN repos, branch listing and switching
Branch Switching	Per-conversation git branch selection	Isolated checkout inside bwrap sandbox, branch-specific vector index
Workspace Isolation	Sandbox isolation for conversations	bwrap overlay sandboxing, subagent integration, snapshots
Document Editor	DOCX document editing	Dynamic tool injection for reading, editing, and saving DOCX files
XLSX Editor	XLSX/XLSM spreadsheet editing	Dynamic tool injection over an isolated openpyxl worker
PPTX Editor	PPTX/PPTM presentation editing	Dynamic tool injection over an isolated python-pptx worker
File Links	File download, preview, and repo browser	Tracks agent file writes; transcript cards + `/plugins/file_links/repos` browser
Mermaid Render	Render Mermaid diagrams to images	`render_mermaid` drives headless Chromium to write SVG/PNG
Client Filesystem	Browser-attached local folder access	File System Access API, agent read/write, @-mention autocomplete
Developer	Agentic code implementation tool	Subagent that reads, edits, and runs code from a plan
Explore	Read-only codebase exploration	`explore` sub-agent searches and reads code, returns a synthesis
External Agent	Delegate to external CLI agents	Run Claude Code / Codex / OpenCode / Gemini in a sandbox
FileSync	Sync repos from local/SMB/UNC paths	Copy source code from shared drives before ingestion
Log Collection	Log file analysis source type	Manage log file collections; reference implementation for source-type plugins
Permalink	File path → Git hosting links	Auto-links file paths in responses to GitHub/GitLab/Gitea
Script Filter	Strip leaked non-Latin output	Removes CJK runs live during streaming; translates fragments on finish
SSH Tunnel	Persistent SSH port-forward tunnel	Auto-opens and maintains an SSH tunnel to a fixed remote server
Remote SSH	Remote SSH/SFTP tools (experimental)	Execute commands and transfer files on remote hosts
Skills	Agent Skills (agentskills.io)	Discoverable reusable capabilities activated via slash commands
Slash Commands	Custom slash command shortcuts	Expand user-defined `/commands` to full prompts
Claude Code Hooks	External commands/HTTP on lifecycle events	Claude-Code-compatible rule engine for subprocess or HTTP callouts
User Secrets	Per-user encrypted credentials	Named API keys + shell env bindings, referenced from config as `${secret:<name>}`
OAuth	OAuth 2.0 / refresh-token storage and flows	Per-user encrypted token store, device-code + auth-code flows, GitHub/Google providers
EULA	First-login EULA modal	Blocking acceptance prompt built on the User Gates capability; version-bump re-prompts every user
Trial	Cosmetic trial badge in chat header	Configurable pill-style badge, no enforcement logic
Slack Integration	Inbound + outbound Slack	Socket Mode listener for @-mentions / DMs / slash commands, plus agent-callable post/react tools
Telegram	Telegram bot channel with voice	Long-poll listener that maps a chat to a conversation; voice-in→voice-out via STT/TTS; technical_user or per_user (own bot) modes
Read Aloud	"Read aloud" message action	Plays the final assistant message via the shared TTS service
Redmine	Per-user Redmine issue tools	search/get/create/update/comment, authenticating as the calling user via a `user_secrets` key — no MCP server
Database	SQL database tools	list/describe/query/execute over switchable native (pg8000/PyMySQL/oracledb/python-tds) or CLI (psql/mysql/go-sqlcmd) backends
Configuration Assistant	Admin chat that edits this instance's own config	Schema introspection + docs → validate → diff → approve → backup → apply → hot-reload → rollback (admin-only)
Model Profiles	Per-user model profiles	Users define model/key profiles and assign them to agent roles
Scheduler Tools	Scheduled agent runs	Create and manage one-off or cron agent runs as tools
Goals	Long-lived scheduled intents	KB-backed goals with cron-fired worker conversations

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"

Plugin Categories

Observability

Telemetry - Response timing, LLM call durations, tool usage metrics
Great for performance monitoring and optimization
Exports data to evaluation reports

Inference Metrics - LLM generation performance metrics
Tracks Time to First Token (TTFT) and generation speed (tokens/sec)
Rolling global averages tiered by prompt size (short/medium/long)

Console Report - End-of-session report renderer
Assembles sections contributed by Telemetry, Inference Metrics, and other plugins
Prints a formatted console report on exit (enabled by default, disable by setting session_report: false in codumentor.yaml)

Context Management

Context Summarization - Automatic context window management
Truncates long conversations while preserving important context
Configurable per-model limits

Context Management - Proactive multi-resolution summarization
Maintains cascading summaries at multiple token levels
LLM-based semantic drift detection for smart compaction
Optional history retrieval tool for accessing compressed context

Knowledge & Memory

Agentic Memory - Organizational knowledge base
Auto-stores agent responses as searchable knowledge
Retrieves relevant "Rapid Direction Cues" during conversations
Web UI with voting and review workflows

User Feedback - Turn-level assistant response feedback
Adds message-actions UI controls (like/dislike) next to copy
Stores immediate votes and optional free-text dislike details

Bug Report - Bug reports and feedback submission
User-facing form for reporting bugs and sending feedback
Forwards submissions to Redmine as tracked issues
Admin panel for reviewing recent submissions
Supports custom fields, parent issues, and status configuration

Tool Integration

MCP - Model Context Protocol servers
Connect to local (stdio) or remote (HTTP/SSE) MCP servers
Automatically exposes MCP tools to the agent

Ripgrep - Code search tool
Fast regex search across repositories
Replaces shell-based grep commands

Web Retrieve - Web content retrieval
Fetch and extract text from web pages
Optional agentic mode for complex information extraction
Pre-fetches content to minimize subagent overhead

Web Search - Web search
Search the web with multiple provider support
Providers: DuckDuckGo (free), Brave, Tavily, Serper, Google CSE, SearXNG
Optional research mode for comprehensive multi-page analysis

Slack Integration - Two-way Slack bridge
Inbound: Socket Mode listener for @-mentions, DMs, and the /codumentor slash command
Outbound: slack_send_message and slack_add_reaction tools the agent can call
Auto-replies the agent's final answer back into the originating Slack thread

Telegram - Telegram bot channel with voice
Long-poll listener mapping each chat to a Codumentor conversation; auto-replies the final answer
Voice in → voice out: transcribes voice notes (STT) and synthesizes replies (TTS) via the general config.speech service
Two modes: technical_user (one shared bot) or per_user (each user brings their own bot via user_secrets)

Database - SQL database tools
sql_list_connections / sql_list_tables / sql_describe_table / sql_query / sql_execute
Switchable backends per connection: native pure-Python driver (pg8000 / PyMySQL / oracledb-thin / python-tds) or a CLI (psql / mysql / go-sqlcmd), chosen by mode: native|cli|auto
Engines: Postgres, MySQL/MariaDB, Oracle, SQL Server (plus SQLite)
Per-user password_secret or shared ${secret:...}; read-only guard, gated writes, JSON results

Document Editing

Document Editor - DOCX document editing
Dynamic tool-injection pattern: editing tools appear only when a document is open
Full suite of reading, searching, replacing, table editing, and property tools
UI integration with transcript cards and file download support

XLSX Editor - XLSX/XLSM spreadsheet editing
Dynamic tool injection over an isolated openpyxl worker

PPTX Editor - PPTX/PPTM presentation editing
Dynamic tool injection over an isolated python-pptx worker

File Links - File download, preview, and repo browser
Tracks agent file writes and surfaces download/view cards in the transcript
Repo browser page with per-conversation vs all-files scope

Source Control & File Ingestion

SVN - Subversion repository support
Checks out or updates SVN working copies before ingestion
Branch listing (trunk + branches/*) and switching via svn switch
Multi-project repository support with automatic project-prefix detection
Credential support with ${ENV_VAR} expansion

Branch Switching - Per-conversation git branch selection
Isolated git checkout inside each conversation's bwrap sandbox
Branch-specific Chroma overlay indexes for accurate semantic search
Background overlay builds with staleness detection and auto-rebuild

FileSync - Sync repositories from shared drives
Copies source code from local directories or Windows SMB/UNC network shares
Runs before ingestion so the local copy is indexed normally
Credential support with ${ENV_VAR} expansion

Workspace Isolation

Workspace Isolation - Sandbox isolation for conversations
Per-conversation bwrap overlay sandboxing with copy-on-write
Automatic subagent change integration via VCS-aware diffing
Stable base snapshots to decouple ingestion from active sessions
AI-based merge resolution for conflicting subagent changes

Agentic Tools

Developer - Agentic code implementation
Subagent specialized for implementing features and fixing bugs from a plan
Has access to file reading, editing, shell execution, and knowledge search
Scoped to the current conversation's source context

Remote SSH - Remote command execution and file transfer (experimental)
ssh_exec, ssh_upload, ssh_download tools for remote hosts
Connection pooling with idle timeout and keepalive
TOFU host key verification (OpenSSH-format known hosts file)
Per-user enable/disable and ad-hoc connection controls

User Experience

Client Filesystem - Browser-attached local folder access
Uses the browser's File System Access API — files stay on the user's machine
Dynamic tool injection: tools only appear when a folder is attached
@-mention fuzzy autocomplete from the attached folder's file index

Slash Commands - Custom slash command shortcuts
Per-user configurable /commands that expand to full prompts
Admin-configurable defaults shown in the settings UI for easy editing
Arguments after the command name are appended to the expanded prompt

Skills - Agent Skills (agentskills.io)
Discoverable reusable capabilities loaded from four directory tiers
Activated via slash commands; skill content injected as prompt context
Per-user skill disable support via settings UI

Permalink - File path → Git hosting links
Auto-replaces file paths in agent responses with Markdown links to GitHub/GitLab/Gitea
Resolves full repo paths, relative paths, and bare filenames
Branch-aware when used with Branch Switching

Source Types

Log Collection - Log file analysis
Manage collections of log files; conversations scoped to the collection
Isolated mode (logs only) or merged mode (logs + code repos)
Reference implementation for building custom source-type plugins

Infrastructure Management

SSH Tunnel - Persistent SSH port-forward tunnel
Auto-opens and maintains a tunnel to a fixed remote server at startup
Background maintenance loop with automatic reconnection on failure
Module-level singleton: only one tunnel per server lifetime

LLM Server - LLM server management
Auto-detects connection errors to local LLM server
Checks for existing instances before starting new ones
Health monitoring with automatic error detection
Auto-shutdown after configurable inactivity period
Multi-user synchronization to prevent duplicate starts
Real-time progress tracking during startup

EULA - First-login End-User License Agreement modal
Blocks the app until the user accepts the configured terms
Acceptance persisted per (user, gate, version); bump the version to re-prompt
Built on the generic User Gates capability — extend the same primitive for privacy-policy updates, forced password changes, telemetry consent, etc.

Credentials & Secrets

User Secrets - Per-user encrypted credentials
Named API keys / tokens stored with Fernet-at-rest, keyed off auth.jwt_secret
Three delivery modes: ${secret:<name>} placeholders in config, shell env bindings (agent never sees the value), and an opt-in os.environ mode for in-process Python libraries
Consumers: LLM profile api_key, MCP headers, web-search provider keys, shell tool

OAuth - OAuth 2.0 / refresh-token storage and flows
Encrypted-at-rest token store, device-code + auth-code (PKCE) flows, in-line + background refresh
Provider plugins (github_oauth, google_workspace) declare an OAuthProviderConfig; consumers call await registry.get_access_token("github") inside an agent turn
TUI pane covers Connect, "Add scopes", and Revoke (with upstream revocation when supported)

Extensibility

Trial - Cosmetic trial badge in chat header
Renders a configurable pill-style badge using Shadow DOM
Badge text and visibility driven by YAML config — no frontend rebuild needed
Does not enforce any trial logic; purely visual

Claude Code Hooks - External hook runner, Claude-Code-compatible
Runs shell commands or HTTP endpoints on agent lifecycle events
Drop-in compatible with Claude Code's settings.json hooks schema
Opt-in discovery of existing .claude/settings.json files
Exposes seven Codumentor-unique events (LLM calls, prompt assembly, tool progress, persistence)

Observability (Session Reports)

Token Report - Token usage section for session report
Accumulates per-query token data via onUsageTracked
Renders model, cost, totals, input/output breakdown, and per-query bar chart
Pairs with the Console Report plugin

Common Configuration Patterns

Enabling/Disabling Plugins

plugins:
  - module: "codumentor.plugins.telemetry"
    class: "TelemetryPlugin"
    args:
      enabled: true  # Most plugins support this

  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      enabled: false  # Disabled

Plugin Priority

Control handler execution order:

plugins:
  - module: "my_plugin"
    class: "MyPlugin"
    priority: 100  # Higher = runs earlier

Agent-Specific Tools

Some plugins support target_agents to control which agents receive tools:

plugins:
  - module: "codumentor.plugins.mcp"
    class: "MCPPlugin"
    args:
      executable: "mcp-server"
      target_agents: "main"  # Only main agent, not subagents

Options: "main", "subagent", "all" (default)