[EPIC] CIDX Self-Monitoring

[jsbattig]

Epic: CIDX Self-Monitoring

Executive Summary

CIDX server automatically monitors its own logs, classifies issues (server bug / client misuse / documentation gap), and creates actionable, non-duplicate GitHub issues via Claude Code execution on a configurable cadence.

Business Value: Self-monitoring software that identifies and reports issues automatically, enabling faster resolution and eventually self-improvement capabilities.

Target Users:

• Primary: Developers maintaining CIDX (receive actionable bug reports)
• Secondary: Future agentic solutions for auto-fixing
• Indirect: MCP clients who benefit from better documentation and fewer bugs

Architecture Overview

CONFIGURATION (config.json - SelfMonitoringConfig)
  - enabled, cadence_minutes, model, prompt_template, prompt_user_modified
                    |
                    v
SCHEDULED SERVICE (SelfMonitoringService)
  - Timer fires on configured cadence
  - Submits job to existing Claude job queue (single-threaded)
  - Tags job as "self_monitoring" (distinct from golden_repo)
                    |
                    v
CLAUDE CODE EXECUTION
  - Receives: log DB path, schema, last scan log_id, existing issues
  - Queries logs directly via sqlite3 CLI (no MCP tool)
  - Classifies issues, creates bug reports via embedded issue_manager.py
  - Returns JSON response with created issue IDs
                    |
                    v
OPERATIONAL DATA (SQLite)
  - self_monitoring_scans: scan history
  - self_monitoring_issues: issue metadata with GitHub links
                    |
                    v
WEB UI (New "Self-Monitoring" tab after Logs)
  - Configuration: enable/disable, cadence, model selector, prompt editor
  - Dashboard: scan history, issue list, Run Now button

Key Technical Decisions

Decision	Rationale
Claude queries logs via sqlite3 CLI	Simpler than MCP tool, handles large logs
Settings in config.json	Follows existing SelfMonitoringConfig pattern
Issue metadata in SQLite	Queryable, does not bloat config
Path derivation via file	Established codebase pattern
Prompt externalized + editable	Upgrade-safe, customizable
Own tab in Web UI	Feature is substantial, deserves dedicated space
Model configurable (Opus/Sonnet)	Cost/quality flexibility
Three-tier deduplication	Reliable duplicate detection via error codes, fingerprints, and semantic similarity
Error code standardization	Enables deterministic Tier 1 deduplication

Embedded Assets

Asset	Source	Target
issue_manager.py	~/.claude/scripts/utils/issue_manager.py	src/code_indexer/server/self_monitoring/issue_manager.py
bug_report_standards.md	~/.claude/standards/bug-report-standards.md	src/code_indexer/server/self_monitoring/standards/bug_report_standards.md
Default prompt	New file	src/code_indexer/server/self_monitoring/prompts/default_analysis_prompt.md

Features and Stories

Feature 1: Self-Monitoring Core Infrastructure

• Story [STORY] Log Context Inventory and Standardization #86: Log Context Inventory and Standardization (PREREQUISITE - P2)
• Story [STORY] Self-Monitoring Configuration and Service #72: Self-Monitoring Configuration and Service
• Story [STORY] Log Analysis and Issue Creation #73: Log Analysis and Issue Creation (depends on [STORY] Log Context Inventory and Standardization #86)

Feature 2: Web UI and Observability

• Story [STORY] Self-Monitoring Web UI Tab #74: Self-Monitoring Web UI Tab
• Story [STORY] Manual Scan Trigger #75: Manual Scan Trigger

Feature 3: Model Configuration

• Story [STORY] Claude Model Selection for Jobs #76: Claude Model Selection for Jobs

Implementation Order (Dependency-Aware)

1. Story [STORY] Log Context Inventory and Standardization #86 (P2) - Log Context Inventory - MUST be first, provides error codes for deduplication
2. Story [STORY] Self-Monitoring Configuration and Service #72 (P4) - Configuration and Service infrastructure
3. Story [STORY] Log Analysis and Issue Creation #73 (P1) - Log Analysis with three-tier deduplication (depends on [STORY] Log Context Inventory and Standardization #86)
4. Story [STORY] Claude Model Selection for Jobs #76 (P3) - Model Selection (can parallelize with [STORY] Log Analysis and Issue Creation #73)
5. Story [STORY] Self-Monitoring Web UI Tab #74 (P4) - Web UI Tab
6. Story [STORY] Manual Scan Trigger #75 (P4) - Manual Scan Trigger

Success Criteria

• Admin can enable/disable self-monitoring via web UI
• System runs Claude Code on configured cadence to analyze logs
• Issues are correctly classified (server_bug, client_misuse, documentation_gap)
• Duplicate issues are detected via three-tier algorithm and skipped
• Issue metadata is persisted in SQLite with GitHub links
• Dashboard shows scan history and created issues
• Manual Run Now trigger works
• Model selection works for both self-monitoring and golden repo jobs
• All warning/error/critical logs have standardized error codes

Dependencies

• GitHub CI/CD must be configured for issue creation
• Claude Code must be registered and available
• Existing single-threaded Claude job queue
• Existing logs SQLite database (~/.cidx-server/logs.db)

[jsbattig]

Implementation Order

Feature 1: Self-Monitoring Core Infrastructure

• [STORY] Self-Monitoring Configuration and Service #72 [STORY] Self-Monitoring Configuration and Service
• [STORY] Log Analysis and Issue Creation #73 [STORY] Log Analysis and Issue Creation

Feature 2: Web UI and Observability

• [STORY] Self-Monitoring Web UI Tab #74 [STORY] Self-Monitoring Web UI Tab
• [STORY] Manual Scan Trigger #75 [STORY] Manual Scan Trigger

Feature 3: Model Configuration

• [STORY] Claude Model Selection for Jobs #76 [STORY] Claude Model Selection for Jobs

---

Stories should be implemented in order within each feature. Feature 1 must be completed before Feature 2.

[jsbattig]

Epic Progress Update

✅ Story #86 COMPLETED: Log Context Inventory and Standardization

Implementation Details:

• 887 unique error codes defined in src/code_indexer/server/error_codes.py
• All 810+ log statements migrated to use format_error_log() pattern
• 96 server files updated with standardized logging
• Documentation: docs/error-codes.md

Error Code Format: [SUBSYSTEM-CATEGORY-NNN]

• 14 Subsystems: AUTH, GIT, MCP, CACHE, REPO, QUERY, VALID, DEPLOY, SCIP, TELEM, STORE, SVC, WEB, APP

Validation:

• fast-automation.sh: 3919 passed, 0 failures

Next Story: #72 - Self-Monitoring Configuration and Service

Proceeding to implement the configuration schema and background monitoring service.

[jsbattig]

Epic Progress Update

✅ Story #72 COMPLETED: Self-Monitoring Configuration and Service

Implementation Details:

• SelfMonitoringConfig dataclass with 5 configuration fields
• SQLite tables for scan history and issue tracking
• SelfMonitoringService with timer-based background execution
• Default analysis prompt template

New Files:

• src/code_indexer/server/self_monitoring/service.py (214 lines)
• src/code_indexer/server/self_monitoring/prompts/default_analysis_prompt.md

Error Codes Added: MONITOR-GENERAL-001 through 006

Validation: 19 unit tests + fast-automation.sh (3919 passed)

Next Story: #73 - Log Analysis and Issue Creation

This story implements the core analysis logic using Claude CLI and the three-tier deduplication algorithm.