dobbe

Architecture Overview

dobbe is a CLI tool that orchestrates Claude AI agents to automate security scanning, code review, dependency analysis, test generation, and engineering intelligence for GitHub repositories.

Layer Architecture

+-----------------------------------------------------------------+
|                       Terminal User                              |
+-------------------------------+---------------------------------+
                                |
                                v
+-----------------------------------------------------------------+
|                CLI Layer (cli.py / Typer)                        |
|  Global options: --version, --no-color                          |
|  Env vars: NO_COLOR, DOBBE_QUIET                                |
+-------------------------------+---------------------------------+
                                |
                                v
+-----------------------------------------------------------------+
|                      Command Layer                               |
|  AI-Powered:                                                     |
|    vuln | review | audit | deps | test | changelog              |
|    migration | incident | insight                                |
|  Tools:                                                          |
|    scan | metrics | workflow | schedule | doctor | config | setup|
|  Shared:                                                         |
|    _helpers.py | _help_renderer.py                               |
+------+------------------+------------------+--------------------+
       |                  |                  |
       v                  v                  v
+----------------+ +-------------+ +----------------------+
|   Core Layer   | | Models Layer| |    Output Layer      |
| claude.py      | | alert.py    | | table.py             |
| pipeline.py    | | resolve.py  | | json_out.py          |
| prompts.py     | | review.py   | | markdown.py          |
| scheduler.py   | | audit.py    | | transcript.py        |
| audit_pipeline | | deps.py     | | progress.py          |
| deps_pipeline  | | changelog.py| | deps_table.py        |
| testgen_pipe.. | | incident.py | | incident_table.py    |
| changelog_pi.. | | insight.py  | | insight_table.py     |
| migration_pi.. | | metrics.py  | | metrics_table.py     |
| incident_pi..  | | migration.py| | audit_markdown.py    |
| insight_pi..   | | testgen.py  | | deps_markdown.py     |
| metrics_pi..   | | workflow.py | | incident_markdown.py |
| secrets_scan.. | | policy.py   | | insight_markdown.py  |
| workflow_eng.. | | shared.py   | | metrics_markdown.py  |
| skill_install. | | schedule.py | | narrator.py          |
+-------+--------+ +-------------+ +----------------------+
        |
        v
+-----------------------------------------------------------------+
|                Skills Layer (skills/)                             |
|  base/ | django/ | angular/ | react/ | nodejs/ | general/       |
|  Installed to ~/.claude/skills/dobbe-*/SKILL.md                  |
+-----------------------------------------------------------------+
        |
        v
+-----------------------------------------------------------------+
|               External Tools (subprocess)                        |
|  Claude Code CLI  |  gh CLI  |  MCP Servers                     |
+-----------------------------------------------------------------+

Layers

CLI Layer (cli.py)

The entry point built with Typer. Registers all 16 command groups, handles global options (--version, --no-color), and respects NO_COLOR and DOBBE_QUIET environment variables.

Commands are organized into two groups on the help screen:

Command registration uses lazy importlib.import_module() with fallback stubs so that a broken module does not prevent other commands from loading. On first subcommand invocation, the callback triggers first-run setup prompts and auto-installs skills via skill_installer.install_skills().

Command Layer (commands/)

Each module defines Typer subcommands with option parsing, validation, and orchestration:

Module Commands
vuln.py scan, resolve, status
review.py digest, post, sla
audit.py report
deps.py analyze
test.py gen
changelog.py gen
migration.py plan, run
incident.py triage, resolve
insight.py dashboard, trends
scan.py secrets
metrics.py velocity, dora
workflow.py create, run, list, logs, delete
schedule.py add, list, remove, check, run, logs, install
setup.py interactive wizard
doctor.py health checks
config.py show, check, validate

Commands validate inputs, merge CLI options with config defaults, and delegate to the core layer.

Shared Utilities (commands/_helpers.py, commands/_help_renderer.py)

_helpers.py provides reusable functions used across all command modules:

Function Purpose
auto_detect_repo() Detect the GitHub repo slug and local path from the current working directory. Exits with an error if CWD is not a recognized git repository. Used by commands that accept an optional --repo flag.
parse_pr_ref() Parse a PR number (42), GitHub URL (https://github.com/org/repo/pull/42), or shorthand (org/repo#42) into a (repo_slug, pr_number) tuple.
discover_tools() Discover MCPs, plugin prefixes, and user-configured extra tools. Shows a spinner during discovery.
run_with_spinner() Execute a callable with a Rich spinner when not in quiet mode.
render_report() Route a Pydantic report to the appropriate renderer (table/JSON/markdown) based on --format and --output flags.
write_or_print() Write content to a file or print to console.
confirm_action() Prompt for confirmation before destructive operations (skipped in CI or with --yes).
validate_repo_exists() Quick check if a GitHub repo exists via gh api.

_help_renderer.py provides RichPanelGroup, a custom Typer/Click Group class that renders subcommand help as Rich panels with a two-column flag layout. Used as typer.Typer(cls=RichPanelGroup, ...) by all command modules.

Core Layer (core/)

Business logic that is command-agnostic:

Module Responsibility
claude.py Claude subprocess invocation, tool allowlists, retry logic
pipeline.py Vulnerability resolve pipeline orchestration
review_pipeline.py Review digest/post async pipeline
audit_pipeline.py Security posture audit pipeline
deps_pipeline.py Dependency health analysis pipeline
testgen_pipeline.py Test generation pipeline for coverage gaps
changelog_pipeline.py Release notes generation pipeline
migration_pipeline.py Dependency migration planning and execution pipeline
incident_pipeline.py Sentry incident triage and resolution pipeline
insight_pipeline.py Engineering intelligence dashboard and trends pipeline
metrics_pipeline.py DORA and velocity metrics pipeline
secrets_scanner.py Secrets and credentials scanning engine
workflow_engine.py Multi-step workflow execution engine
agentic_pipeline.py Shared agentic pipeline base for streaming pipelines
prompts.py All prompt templates and builders
prompt_loader.py Prompt template loading and composition
config_manager.py Config loading, saving, defaults
scheduler.py Schedule persistence, locking, execution, hooks
mcp_discovery.py MCP server discovery and classification
repo_resolver.py Local/remote repository resolution
repo_cache.py Repository metadata caching
response_parser.py Claude response JSON parsing
response_cache.py Response caching for repeated queries
notifier.py Slack/Jira notification dispatch
github_review.py GitHub PR review posting logic
state_manager.py State persistence and run counting
first_run.py First-run setup prompts and tips
skill_installer.py Skill installation, composition, and framework detection
policy_engine.py Approval gate and trust policy evaluation
schemas.py JSON schema definitions for Claude structured output
sanitize.py Input sanitization utilities
session_store.py Session state storage
sla_monitor.py SLA tracking for review and vulnerability response times
version_utils.py Version comparison and upgrade utilities
vuln_tracker.py Vulnerability state tracking across runs

Models Layer (models/)

Pydantic v2 models for structured data:

Module Models
shared.py Enums: Severity, AccessMode, FixStatus, VerifyCategory, ReviewCategory
alert.py Alert, TriageResult, AlertGroup, RepoResult, ScanReport
resolve.py FixAction, SkippedFix, FixResult, VerifyResult, PipelineIteration, ResolveReport, BatchResolveReport
review.py PRInfo, ReviewConcern, PRReviewResult, ReviewDigest, PostResult, ReviewPostReport
schedule.py ScheduleInterval, Schedule, RunLog, CheckResult
audit.py AuditCheckType, RiskLevel, LicenseRiskLevel, AuditFinding, LicenseResult, SecretsResult, QualityResult, RepoAuditResult, AuditReport
deps.py DependencyHealth, LicenseRisk, DepFinding, DepAnalysisResult, DepsReport
testgen.py TestFramework, CoverageGap, GeneratedTest, TestGenResult, TestGenReport
changelog.py ChangeCategory, ChangelogEntry, ChangelogSection, Changelog
migration.py MigrationStatus, MigrationStep, MigrationPlan, MigrationReport
incident.py IncidentStatus, SentryIssue, TriagedIssue, IncidentTriageResult, IncidentResolveResult, IncidentReport
insight.py MetricPoint, TrendData, InsightSnapshot, InsightReport
metrics.py VelocityMetrics, DORAMetrics, MetricsReport
workflow.py StepType, OnFailure, WorkflowStep, StepResult, WorkflowDef, WorkflowRun
org.py TeamInfo, RepoHealth, TeamSummary, OrgStatusReport
policy.py ApprovalGate, TrustPolicy, PolicyCheckResult
vuln_state.py VulnRecord, VulnSLAConfig, VulnStatusReport

Output Layer (output/)

Renderers for different output formats:

Module Format
table.py Rich table output for vulnerability reports
review_table.py Rich table output for review digests
review_post_table.py Rich table output for review post results
deps_table.py Rich table output for dependency analysis
incident_table.py Rich table output for incident triage
insight_table.py Rich table output for engineering insights
metrics_table.py Rich table output for DORA/velocity metrics
json_out.py JSON serialization
markdown.py Markdown report generation for vulnerability reports
review_markdown.py Markdown report generation for review digests
review_post_markdown.py Markdown report generation for review posts
audit_markdown.py Markdown report generation for audit reports
deps_markdown.py Markdown report generation for dependency analysis
incident_markdown.py Markdown report generation for incident triage
insight_markdown.py Markdown report generation for engineering insights
metrics_markdown.py Markdown report generation for DORA/velocity metrics
upgrade_pr_body.py PR body generation for upgrade PRs
narrator.py Narrative text generation for reports
transcript.py Agent conversation transcript
progress.py Rich progress bars and spinners
status.py Status messages
helpers.py Shared output utilities

Skills Layer (skills/)

Skills are Markdown files that Claude Code discovers as slash commands. They provide domain-specific knowledge that enhances dobbe’s prompts for particular frameworks and concern areas.

Skill Categories

skills/
  base/           Foundational checks (security, testing, performance, ...)
  django/         Django-specific checks (ORM, settings, migrations, ...)
  angular/        Angular-specific checks (modules, RxJS, a11y, ...)
  react/          React-specific checks (hooks, state, rendering, ...)
  nodejs/         Node.js-specific checks (event loop, security, ...)
  general/        Framework-agnostic skills (PR review, dependency audit)
Category Skills
base security, testing, performance, code-quality, accessibility, dependency-health, deployment
django security, testing, performance, code-quality, api-design, dependency-health, deployment
angular security, testing, performance, code-quality, accessibility, build-optimization, state-management
react security, testing, performance, code-quality, build-optimization, state-management
nodejs security, testing, performance, code-quality, api-design, deployment
general dependency-audit, pr-review-security, pr-review-performance, pr-review-a11y

Composition Model

Framework skills are composed with their matching base skill at install time. For example, django/security.md is merged with base/security.md to produce a single ~/.claude/skills/dobbe-django-security/SKILL.md that includes both generic and Django-specific security checks. General skills pass through without base composition.

The composition process:

base/security.md  +  django/security.md
       |                     |
       v                     v
 [strip frontmatter]   [extract frontmatter + strip body]
       |                     |
       v                     v
 +--------------------------------------------------+
 | django frontmatter                                |
 | base body (generic security checks)               |
 | ---                                                |
 | ## Django-Specific Checks                          |
 | django body (ORM injection, settings, etc.)        |
 +--------------------------------------------------+
       |
       v
 ~/.claude/skills/dobbe-django-security/SKILL.md

Auto-Install on Version Change

Skills are installed automatically when a dobbe subcommand is invoked. The installer compares the current package version against a marker file (~/.claude/skills/.dobbe-skill-version). When the version changes (or on first run), all skills are re-installed. This ensures that skill content stays in sync with the dobbe release without requiring manual intervention.

Framework Auto-Detection

detect_framework() in skill_installer.py inspects the current working directory for framework markers:

Detected frameworks are used by get_enhancing_skills() to select which framework-specific skill content to append to prompts at runtime.

Claude Integration Model

dobbe invokes Claude Code as a subprocess, not as an API:

claude -p "<prompt>" --allowedTools "Bash,Read,Grep,Glob" --output-format json

Key design choices:

Tool Sets by Role

Scan agent:    [Bash, Read, Grep, Glob] + MCP tools
Fix agent:     [Bash, Read, Grep, Glob, Edit, Write] + MCP tools
Verify agent:  [Bash, Read, Grep, Glob]
Report agent:  [Read]
Review agent:  [Bash, Read, Grep, Glob] + MCP tools

MCP Discovery

dobbe auto-discovers MCP servers from Claude Code’s settings:

  1. Read ~/.claude/settings.json (user-level)
  2. Read .claude/settings.json (project-level)
  3. Extract mcpServers and enabledPlugins
  4. Classify each server against known patterns (GitHub, Slack, Atlassian, Sentry, Figma)
  5. Cache results for the session

Tool prefix mapping for --allowedTools:

MCP Prefix Pattern
GitHub mcp__github__*
Slack mcp__claude_ai_Slack__*
Atlassian mcp__claude_ai_Atlassian__*
Sentry mcp__claude_ai_Sentry__*
Figma mcp__claude_ai_Figma__*

When the GitHub MCP is not available, dobbe falls back to using gh CLI commands via the Bash tool.

Repository Resolution

dobbe resolves repository slugs (org/repo) to local paths for direct file access:

1. Check configured local_paths in ~/.dobbe/config.toml
2. Scan common project directories:
   ~/projects, ~/Projects, ~/Desktop/Projects,
   ~/code, ~/Code, ~/src, ~/repos, ~/dev,
   ~/workspace, ~/Developer
3. Check current working directory
4. Fall back to remote access (MCP or gh CLI)

Returns AccessMode.LOCAL with a path or AccessMode.REMOTE with None. Batch resolution pre-scans directories once for efficiency.

Output Pipeline

All output follows the same flow:

Claude JSON response
       |
       v
Pydantic model parsing (with validation)
       |
       v
Format selection (--format flag or config default)
       |
       v
Renderer: Rich table / JSON / Markdown
       |
       v
Destination: stdout / --output file / --notify platform

See Also

This site is open source. Improve this page.