CodeSentinel

SEAM Protected™ by CodeSentinel
(Security, Efficiency, And Minimalism)

A Polymath Project | Created by joediggidyyy

CodeSentinel is a cross-platform automated maintenance and security monitoring system that integrates seamlessly with development workflows. It provides intelligent repository maintenance, security scanning, and multi-channel alerting to keep your codebase healthy, secure, and SEAM-tight.

Powered by ORACL™ - An intelligent decision support system that learns from your repository's history to provide context-aware recommendations and automated remediation guidance.

Features

Security

• Automated vulnerability scanning - Daily security audits of dependencies
• Secret detection - Prevents credential leakage with pattern matching
• File integrity monitoring - SHA-256 baseline verification
• Audit logging - Comprehensive operation tracking with timestamps

Efficiency

• Automated maintenance - Daily, weekly, and monthly scheduled tasks
• Smart cleanup - Intelligent cache, temp, and build artifact removal
• Code duplication detection - Identifies redundant implementations
• Root directory management - Policy-based organization enforcement

Minimalism

• Non-destructive operations - Archive-first approach for all deletions
• Focused codebase - Single source of truth for each feature
• Dependency optimization - Minimal, essential dependencies only
• Clean repository structure - Automated policy enforcement

Intelligence & Learning

• ORACL™ Intelligence Ecosystem - Omniscient Recommendation Archive & Curation Ledger
  • Historical decision context - Learn from past operations and remediation patterns
  • 3-Tier memory architecture - Short-term session cache, mid-term weekly summaries, long-term strategic patterns
  • Confidence-based recommendations - AI-powered suggestions with success rate tracking
  • Pattern discovery - Automatic identification of recurring issues and optimal solutions
  • Intelligent remediation - Context-aware guidance for policy violations and code quality issues

Developer Experience

• Multi-channel alerts - Email, Slack, console, and file notifications
• CLI-first design - Comprehensive command-line interface
• GUI setup wizard - User-friendly configuration assistant
• IDE integration - VS Code and GitHub Copilot support
• Development audits - Interactive !!!! command with ORACL™-powered insights

Quick Start

Installation

# Install from PyPI
pip install codesentinel

# Or install from source
git clone https://github.com/joediggidyyy/CodeSentinel.git
cd CodeSentinel
pip install -e .

Initial Setup

# Run interactive setup wizard
codesentinel setup

# Or use GUI setup (optional)
codesentinel setup --gui

Basic Usage

# Check system status
codesentinel status

# Run security scan
codesentinel scan

# Start automated scheduler
codesentinel schedule start

# Clean repository artifacts
codesentinel clean

# Run development audit
codesentinel !!!!

Command Reference

Core Commands

Maintenance Commands

Scan → Clean Workflow: Use scan --bloat-audit to identify bloat, then clean to remove it.

# Step 1: Analyze repository bloat
codesentinel scan --bloat-audit

# Step 2: Review recommendations and clean specific artifacts
codesentinel clean --cache --test --build --force

# Or: Run both in sequence
codesentinel scan --bloat-audit && codesentinel clean --cache --test --build --force

Scheduler Commands

Documentation Commands

Integration Commands

Development Audit

Alert Commands

File Integrity

Configuration

CodeSentinel uses a central codesentinel.json configuration file:

{
  "project_name": "MyProject",
  "alert_channels": ["console", "file"],
  "scheduler": {
    "enabled": true,
    "daily_time": "02:00",
    "weekly_day": "sunday",
    "weekly_time": "03:00"
  },
  "maintenance": {
    "auto_cleanup": true,
    "archive_retention_days": 30
  }
}

Environment Variables

For sensitive configuration (email, Slack tokens):

# Email alerts
export EMAIL_HOST="smtp.gmail.com"
export EMAIL_PORT="587"
export EMAIL_USER="your-email@gmail.com"
export EMAIL_PASSWORD="your-app-password"

# Slack alerts
export SLACK_WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"

Workflows

Repository Health: Scan → Clean

CodeSentinel uses a two-phase approach for repository maintenance:

Phase 1: Analyze (Scan)

# Identify bloat and inefficiencies
codesentinel scan --bloat-audit

This performs comprehensive analysis:

• Cache artifacts (**pycache**, .pytest_cache, .pyc files)
• Build artifacts (dist/, build/, .egg-info)
• Large files (>1MB without clear purpose)
• Documentation bloat (session/checkpoint docs)
• Test artifact organization
• Archive structure
• Configuration file duplication
• Dependency file issues

Phase 2: Execute (Clean)

# Remove identified bloat
codesentinel clean --cache --test --build --force

Clean command options:

• --cache - Python cache artifacts
• --test - Test artifacts and coverage data
• --build - Build/distribution artifacts
• --root - Root directory clutter
• --force - Skip confirmation prompts
• --dry-run - Preview actions without executing

Example Workflow:

# Step 1: Full analysis
codesentinel scan --bloat-audit --json > bloat-report.json

# Step 2: Review recommendations
cat bloat-report.json

# Step 3: Clean specific categories
codesentinel clean --cache --test --force

# Step 4: Verify cleanup
codesentinel scan --bloat-audit

Security Monitoring

# Run security scan
codesentinel scan

# Run both security and bloat analysis
codesentinel scan --all

# Schedule automated scans
codesentinel schedule start

Architecture

Project Structure

CodeSentinel/
 codesentinel/          # Core Python package
    cli/              # Command-line interface
    core/             # Core business logic
    gui/              # GUI components
    utils/            # Shared utilities (including ORACL™)
 tools/                # Automation scripts
    codesentinel/     # Maintenance automation
    config/           # Configuration templates
 tests/                # Test suite
 docs/                 # Documentation
 scripts/              # Helper scripts

Dual Architecture

CodeSentinel follows a dual-architecture pattern:

• codesentinel/ - Main Python package with CLI (codesentinel, codesentinel-setup)
• tools/codesentinel/ - Comprehensive maintenance automation scripts
• tools/config/ - JSON configuration files for alerts, scheduling, and policies

ORACL™ Intelligence Ecosystem

ORACL™ (Omniscient Recommendation Archive & Curation Ledger) provides intelligent decision support through a 3-tier memory architecture:

Tier 1: Session Memory (0-60 minutes)

• High-speed ephemeral cache for current task context
• Prevents redundant file reads and re-analysis within active sessions
• Automatic invalidation after 60 minutes

Tier 2: Context Memory (7-day rolling window)

• Curated summaries from recently completed sessions
• Aggregated insights on successful operations and key decisions
• Provides recent historical context for related work

Tier 3: Intelligence Archive (Permanent)

• Long-term strategic patterns and historical wisdom
• Pattern discovery engine for recurring issues
• Confidence-scored recommendations based on success rates
• Tamper-proof verification with SHA-256 checksums

Key Benefits:

• 20-50% reduction in redundant agent operations
• Historical learning from past remediation attempts
• Confidence scoring for automated decision-making
• Pattern recognition for proactive issue resolution

Learn more: See docs/ORACL_MEMORY_ARCHITECTURE.md for technical details.

Security Best Practices

CodeSentinel is SEAM Protected™ with security as the highest priority:

1. No Hardcoded Credentials - All sensitive data in environment variables
2. Audit Logging - All operations logged with timestamps
3. Configuration Validation - Secure defaults with auto-validation
4. Dependency Scanning - Automated vulnerability detection
5. Non-Destructive Operations - Archive-first approach for all deletions

See SECURITY.md for detailed security policies and vulnerability reporting.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

Development Setup

# Clone repository
git clone https://github.com/joediggidyyy/CodeSentinel.git
cd CodeSentinel

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate

# Install development dependencies
pip install -r requirements-dev.txt

# Run tests
python run_tests.py

Code Quality

• DRY Principle: Code reuse and modularization is mandatory
• SEAM Protection™: Security, Efficiency, And Minimalism guide all decisions
• Non-Destructive: Never delete without archiving first
• Feature Preservation: All existing functionality must be maintained

Requirements

• Python: 3.13 or higher
• Operating Systems: Windows, macOS, Linux
• Dependencies: See requirements.txt

Optional Dependencies

• GUI Support: tkinter (usually included with Python)
• Development Tools: pytest, black, mypy, flake8

Documentation

• Quick Start Guide - Get up and running quickly
• Security Policy - Security practices and reporting
• Contributing Guide - How to contribute
• Changelog - Version history and changes
• Full Documentation - Comprehensive guides and references

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

CodeSentinel is a Polymath Project created with a focus on:

• SEAM Protection™: Security, Efficiency, And Minimalism
• Developer Experience: Making maintenance effortless
• Code Quality: DRY principles and best practices
• Community: Open-source collaboration

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Email: joediggidy3@gmail.com

CodeSentinel - Keeping your code SEAM-tight! 🛡️