Build proactive custom AI bot with VM testing and vision capabilities

[coderabbitai]

Overview

This issue tracks the development of a highly advanced custom AI bot for the OmniBlocks organization with unique proactive capabilities.

Key Features

Proactive Operation

• Always awake (most of the time): The bot doesn't just rely on mentions or triggers - it actively monitors and engages with the repository
• Scheduled sleep mode: To avoid wasting tokens indefinitely, the bot can set scheduled alarms (time-based or event-based) to wake up
• Smart token management: Balances being proactive with efficient resource usage

VM Testing Environment

• Isolated VM for testing: The bot can execute and test code in its own virtual machine
• Safe code execution: Run tests, builds, and experiments without affecting the main repository
• Automated testing workflows: Can verify changes before suggesting them

Multimodal/Vision Capabilities

• Visual understanding: Can see and interpret UI elements, screenshots, and visual outputs
• UI interaction: Can click buttons and interact with interfaces in the VM
• Screenshot attachments: Can capture and attach screenshots to comments for better communication
• Visual debugging: Can identify visual issues and UI problems

Why This Matters

As noted in the original discussion - nobody has really done this before! Most AI bots are reactive (waiting for mentions/triggers), but a truly proactive bot that can:

• Monitor repository activity autonomously
• Test code in real environments
• Provide visual feedback with screenshots
• Manage its own resource usage intelligently

...would be groundbreaking in the AI dev tools space.

Background

This idea emerged from issue #249 in scratch-gui where we discussed the collection of AI bots ("clankers") and the opportunity to build something truly unique and tailored to our needs.

Technical Considerations

• GitHub Actions + Octokit API for repository integration
• LLM API integration (OpenAI, Anthropic, etc.) with vision models
• VM/containerization for safe code execution (Docker, etc.)
• Scheduling system for smart wake/sleep cycles
• Screenshot capture and image processing capabilities
• Token usage optimization strategies

---

Requested by: @supervoidcoder
Reference: OmniBlocks/scratch-gui#249

[traycerai]

Plan

Observations

This is a greenfield project - the repository is empty except for a GPL-3.0 LICENSE file. We're building a novel proactive AI bot with three core capabilities:

1. Proactive Operation: Autonomous monitoring with smart wake/sleep scheduling
2. VM Testing Environment: Isolated code execution sandbox
3. Vision Capabilities: Screenshot capture, UI interaction, and visual debugging

Based on current best practices (2025), the optimal architecture uses:

• GitHub App (not Actions-only) for proactive webhooks and cross-repo access
• Docker/Testcontainers on GitHub-hosted runners for safe code execution
• Modern LLM APIs (Anthropic Claude, OpenAI GPT-4o) with vision support
• Node.js/TypeScript ecosystem (Probot framework + Octokit)
• Playwright for screenshot capture and UI automation
• PostgreSQL for persistent state (schedules, token usage, task history)
• Redis for job queuing and rate limiting

Approach

Build a modular GitHub App bot with clear separation of concerns:

Core Services: Webhook ingestion → Job queue → Worker pool → LLM orchestrator → GitHub API client

Key Modules: Scheduler (proactive wake/sleep), Sandbox Manager (Docker execution), Vision Pipeline (screenshot capture/analysis), Token Budget Manager (cost control)

Tech Stack: Node.js + TypeScript, Probot framework, Octokit, BullMQ (Redis queue), Playwright, Docker SDK, PostgreSQL for state

Deployment: Containerized bot service + PostgreSQL + Redis, deployable to any cloud provider or self-hosted

Reasoning

Listed the repository structure and found it empty (only LICENSE). Fetched the GitHub issue to understand requirements. Searched the web for current best practices on proactive GitHub bots, VM testing in CI, and AI vision integration. Analyzed the technical landscape and identified optimal architecture patterns for this novel use case.

Proposed File Changes

📄 README.md ^(NEW) 🔗

Create comprehensive project README documenting the bot's purpose, architecture, features, and setup instructions. Include sections for: project overview (proactive AI bot for OmniBlocks), key features (proactive monitoring, VM testing, vision capabilities), architecture diagram reference, quick start guide, configuration options, development setup, deployment instructions, and links to detailed documentation. Mention that this is a novel approach to GitHub automation that goes beyond reactive bots.

📄 .gitignore ^(NEW) 🔗

Create standard Node.js/TypeScript .gitignore file. Include: node_modules/, dist/, build/, .env, .env.local, *.log, coverage/, .DS_Store, .vscode/ (except settings template), .idea/, *.swp, *.swo, .cache/, tmp/, secrets/, .pem (for GitHub App private keys), and database files (.db, *.sqlite).

📄 package.json ^(NEW) 🔗

Create package.json with project metadata and dependencies. Set name to 'boxycpu-bot', version '0.1.0', description matching the issue. Include scripts for: dev (development with hot reload), build (TypeScript compilation), start (production), test (Jest), lint (ESLint), format (Prettier). Dependencies: probot (GitHub App framework), @octokit/rest, bullmq (Redis-based queue), ioredis, pg (PostgreSQL client), playwright (screenshot/UI automation), dockerode (Docker SDK), anthropic (Claude API), openai (GPT-4 API), dotenv, winston (logging). DevDependencies: typescript, @types/node, ts-node, nodemon, jest, @types/jest, eslint, prettier, @typescript-eslint/parser, @typescript-eslint/eslint-plugin.

📄 tsconfig.json ^(NEW) 🔗

Create TypeScript configuration with strict mode enabled. Set target to ES2022, module to commonjs, outDir to './dist', rootDir to './src'. Enable: strict, esModuleInterop, skipLibCheck, forceConsistentCasingInFileNames, resolveJsonModule. Include './src/**/*', exclude 'node_modules' and 'dist'.

📄 .env.example ^(NEW) 🔗

Create environment variables template. Include: APP_ID (GitHub App ID), PRIVATE_KEY_PATH (path to .pem file), WEBHOOK_SECRET (GitHub webhook secret), WEBHOOK_PROXY_URL (for local dev with smee.io), DATABASE_URL (PostgreSQL connection string), REDIS_URL (Redis connection string), ANTHROPIC_API_KEY (Claude API key), OPENAI_API_KEY (GPT-4 API key), LOG_LEVEL (info/debug/error), NODE_ENV (development/production), PORT (default 3000), MAX_TOKENS_PER_DAY (budget limit), PROACTIVE_CHECK_INTERVAL (minutes between proactive checks), ENABLE_VISION (true/false toggle).

📁 src ^(NEW) 🔗

Create main source directory to contain all TypeScript application code.

📄 src/index.ts ^(NEW) 🔗

Create main application entry point. Initialize Probot application, load environment variables via dotenv, set up logging with Winston, initialize database connection pool, initialize Redis client, register event handlers from src/handlers/index.ts, start the scheduler service from src/services/scheduler.ts, set up graceful shutdown handlers (close DB, Redis, stop scheduler), and start the HTTP server. Export the Probot app instance for testing.

📁 src/config ^(NEW) 🔗

Create configuration directory for centralized config management.

📄 src/config/index.ts ^(NEW) 🔗

Create configuration module that loads and validates all environment variables. Export typed config object with sections: github (appId, privateKeyPath, webhookSecret), database (url, pool settings), redis (url, connection options), llm (anthropicKey, openaiKey, defaultProvider), bot (maxTokensPerDay, proactiveCheckInterval, enableVision, logLevel), server (port, nodeEnv). Include validation logic that throws descriptive errors for missing required variables. Use zod or joi for schema validation.

📁 src/handlers ^(NEW) 🔗

Create handlers directory for GitHub webhook event handlers.

📄 src/handlers/index.ts ^(NEW) 🔗

Create main handler registration module. Import and register all event handlers with Probot app instance. Register handlers for: issues.opened, issues.labeled, pull_request.opened, pull_request.synchronize, push, installation.created, installation_repositories.added. Each handler should enqueue a job to the BullMQ queue from src/services/queue.ts rather than processing synchronously (to respond to webhooks within 10 seconds). Include error handling and logging for each event type.

📄 src/handlers/issues.ts ^(NEW) 🔗

Create issue event handlers. For issues.opened: extract issue details, check if bot should respond (based on labels, keywords, or repo config from src/services/config-loader.ts), enqueue analysis job. For issues.labeled: check if label triggers bot action (e.g., 'needs-testing', 'bot-help'), enqueue appropriate job. Include logic to avoid responding to bot's own comments (check if author is the bot itself).

📄 src/handlers/pull-requests.ts ^(NEW) 🔗

Create pull request event handlers. For pull_request.opened and pull_request.synchronize: extract PR details (branch, files changed, description), enqueue testing job that will run tests in sandbox from src/services/sandbox.ts, optionally enqueue screenshot capture job if UI files changed (detect by file extensions: .html, .css, .jsx, .tsx, .vue). Include logic to check repo configuration for auto-testing preferences.

📄 src/handlers/push.ts ^(NEW) 🔗

Create push event handler. Extract commit details, check if push is to monitored branch (main, develop, etc. from repo config), determine if proactive analysis is needed (based on files changed, commit message patterns), enqueue appropriate jobs. Implement rate limiting to avoid processing every single commit (e.g., batch commits within 5-minute window).

📄 src/handlers/installation.ts ^(NEW) 🔗

Create installation event handlers. For installation.created: log new installation, initialize default configuration in database via src/db/repositories/installation-repository.ts, send welcome issue/comment to the repository explaining bot capabilities. For installation_repositories.added: update database with new repositories, initialize per-repo configuration with defaults.

📁 src/services ^(NEW) 🔗

Create services directory for core business logic modules.

📄 src/services/queue.ts ^(NEW) 🔗

References

• 📄 src/config/index.ts ^(NEW)

Create job queue service using BullMQ. Define job types enum: ANALYZE_ISSUE, TEST_PR, CAPTURE_SCREENSHOT, PROACTIVE_CHECK, ANALYZE_VISION. Create and export queue instance connected to Redis from src/config/index.ts. Define job data interfaces for each job type. Implement worker that processes jobs by routing to appropriate service methods. Include retry logic (exponential backoff), job timeout settings, and concurrency limits. Add job progress tracking and result storage.

📄 src/services/scheduler.ts ^(NEW) 🔗

References

• 📄 src/services/queue.ts ^(NEW)
• 📄 src/config/index.ts ^(NEW)

Create proactive scheduler service. Implement scheduling logic that periodically (based on PROACTIVE_CHECK_INTERVAL from config) queries database for repositories that need proactive checks. Use cron-like pattern or setInterval with database-backed state. For each repository due for check: fetch recent activity via Octokit (new issues, PRs, commits since last check), determine if bot should engage (based on activity patterns, keywords, repo config), enqueue appropriate jobs to queue from src/services/queue.ts. Implement smart sleep logic: skip checks if repository is inactive, increase check frequency if repository is very active. Store last check timestamp and activity metrics in database via src/db/repositories/schedule-repository.ts. Include token budget check before scheduling new proactive work.

📄 src/services/sandbox.ts ^(NEW) 🔗

Create sandbox execution service using Docker. Implement methods: createSandbox (spin up Docker container with specified image, mount code volume, set resource limits), executeTests (run test commands inside container, stream logs, capture exit code), captureArtifacts (copy test results, screenshots, logs from container), destroySandbox (stop and remove container, cleanup volumes). Use dockerode library to interact with Docker daemon. Include timeout enforcement, resource limits (CPU, memory), and cleanup on failure. Support multiple base images (Node.js, Python, etc.) based on repository language detection. Implement security measures: no network access by default, read-only filesystem where possible, drop capabilities.

📄 src/services/vision.ts ^(NEW) 🔗

References

• 📄 src/services/llm.ts ^(NEW)

Create vision service for screenshot capture and analysis. Implement methods: captureScreenshot (use Playwright to render URL or HTML file, take screenshot with specified viewport size, return image buffer), analyzeScreenshot (send image to LLM vision API via src/services/llm.ts, get description/analysis), compareScreenshots (detect visual differences between two images, optionally use pixel-diff library). Include screenshot optimization: compress images, convert to appropriate format (PNG for UI, JPEG for photos), resize if too large. Implement caching to avoid re-analyzing identical screenshots. Support both headless browser capture and direct image file analysis.

📄 src/services/llm.ts ^(NEW) 🔗

References

• 📄 src/services/token-budget.ts ^(NEW)

Create LLM orchestration service. Implement unified interface for multiple LLM providers (Anthropic Claude, OpenAI GPT-4). Methods: analyzeText (send text prompt, get completion), analyzeImage (send image with prompt for vision models), streamResponse (for long-running analysis). Include provider selection logic (prefer Claude for computer use, GPT-4o for general vision). Implement token counting and budget tracking: before each call, check remaining budget from src/services/token-budget.ts, after call, record actual usage. Add prompt template management: load templates from src/prompts/ directory, support variable substitution. Include response caching (hash prompt+image, cache result in Redis) to save tokens. Implement retry logic with exponential backoff for API failures.

📄 src/services/token-budget.ts ^(NEW) 🔗

Create token budget management service. Track token usage per day/week/month in database via src/db/repositories/token-usage-repository.ts. Methods: checkBudget (return remaining tokens for period), recordUsage (log tokens used for specific operation), shouldThrottle (determine if bot should reduce activity based on budget), resetDaily (scheduled job to reset daily counters). Implement tiered throttling: at 70% budget, reduce proactive checks; at 90%, only respond to direct mentions; at 100%, enter sleep mode until reset. Include cost estimation: estimate tokens before making LLM call based on prompt length and model. Store usage breakdown by operation type (proactive, reactive, vision, testing) for analytics.

📄 src/services/github-client.ts ^(NEW) 🔗

Create GitHub API client wrapper around Octokit. Implement methods for common operations: createComment (on issue or PR), updateComment, createPR, updatePRStatus, uploadArtifact (to release or as gist), addLabel, removeLabel, getFileContent, listFiles, getRepoConfig (fetch .github/boxycpu.yml). Include rate limit handling: check rate limit before requests, implement exponential backoff on 403/429, use conditional requests (ETags) to save quota. Add request logging and metrics. Implement installation token management: fetch and cache installation access tokens (valid 1 hour), auto-refresh when expired. Support both REST and GraphQL APIs (use GraphQL for complex queries to reduce request count).

📄 src/services/config-loader.ts ^(NEW) 🔗

References

• 📄 src/services/github-client.ts ^(NEW)

Create repository configuration loader. Fetch and parse .github/boxycpu.yml from repositories using src/services/github-client.ts. Define configuration schema: enabled (boolean), proactiveChecks (enabled, interval, keywords), testing (enabled, commands, dockerImage), vision (enabled, captureOnPR, compareBaseline), notifications (channels, mentions), permissions (allowedBranches, restrictedPaths). Implement configuration inheritance: global defaults → organization config → repository config. Cache configurations in Redis with TTL. Validate configuration against schema, provide helpful error messages for invalid configs. Support configuration updates via special PR labels or comments.

📁 src/db ^(NEW) 🔗

Create database directory for PostgreSQL schema and data access layer.

📄 src/db/schema.sql ^(NEW) 🔗

Create database schema SQL file. Define tables: installations (id, github_installation_id, org_name, created_at, updated_at), repositories (id, installation_id, github_repo_id, full_name, config_json, last_proactive_check, activity_score, created_at, updated_at), schedules (id, repository_id, next_check_at, check_interval_minutes, is_active), token_usage (id, date, operation_type, tokens_used, cost_usd, metadata_json), jobs (id, job_type, repository_id, status, payload_json, result_json, created_at, started_at, completed_at), screenshots (id, repository_id, pr_number, url, image_path, analysis_text, created_at). Include indexes on frequently queried columns: installations.github_installation_id, repositories.full_name, schedules.next_check_at, token_usage.date, jobs.status. Add foreign key constraints and cascade delete rules.

📁 src/db/migrations ^(NEW) 🔗

Create migrations directory for database version control. Use a migration tool like node-pg-migrate or db-migrate.

📄 src/db/migrations/001_initial_schema.sql ^(NEW) 🔗

References

• 📄 src/db/schema.sql ^(NEW)

Create initial migration that applies the schema from src/db/schema.sql. Include up and down migration scripts for rollback capability.

📄 src/db/client.ts ^(NEW) 🔗

References

• 📄 src/config/index.ts ^(NEW)

Create database client module. Initialize PostgreSQL connection pool using pg library with configuration from src/config/index.ts. Export pool instance and helper methods: query (execute parameterized query), transaction (execute multiple queries in transaction), healthCheck (verify database connectivity). Implement connection retry logic on startup. Add query logging in development mode. Include graceful shutdown handler to close pool.

📁 src/db/repositories ^(NEW) 🔗

Create repositories directory for data access objects (DAO pattern).

📄 src/db/repositories/installation-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create installation repository for database operations on installations table. Methods: create (insert new installation), findByGithubId (lookup by GitHub installation ID), update (update installation details), delete (remove installation and cascade to related records), listAll (get all installations). Use parameterized queries via src/db/client.ts to prevent SQL injection. Return typed objects matching Installation interface from src/types/index.ts.

📄 src/db/repositories/repository-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create repository DAO for repositories table. Methods: create, findById, findByFullName, updateConfig (update config_json), updateLastCheck (update last_proactive_check timestamp), updateActivityScore, listByInstallation, listDueForProactiveCheck (query schedules join to find repos needing checks), delete. Include methods to serialize/deserialize config_json field.

📄 src/db/repositories/schedule-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create schedule repository for schedules table. Methods: create, findByRepositoryId, updateNextCheck (set next_check_at timestamp), updateInterval (change check_interval_minutes), activate, deactivate, listDueNow (query where next_check_at <= NOW() and is_active = true), delete. Used by src/services/scheduler.ts to manage proactive check scheduling.

📄 src/db/repositories/token-usage-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create token usage repository for token_usage table. Methods: recordUsage (insert usage record), getTotalForPeriod (sum tokens_used for date range), getTotalForToday, getUsageByOperationType (breakdown by operation_type), deleteOldRecords (cleanup records older than retention period). Support aggregation queries for analytics and budget tracking used by src/services/token-budget.ts.

📄 src/db/repositories/job-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create job repository for jobs table. Methods: create, findById, updateStatus (update status and timestamps), updateResult (store result_json), listByRepository, listByStatus, listRecent (for dashboard), deleteCompleted (cleanup old completed jobs). Used to persist job history beyond Redis queue for audit trail and analytics.

📄 src/db/repositories/screenshot-repository.ts ^(NEW) 🔗

References

• 📄 src/db/client.ts ^(NEW)

Create screenshot repository for screenshots table. Methods: create (store screenshot metadata and file path), findById, findByPR (get all screenshots for a PR), findLatestForUrl (for comparison), updateAnalysis (store LLM analysis text), delete, deleteOldScreenshots (cleanup based on retention policy). Store actual image files on disk or cloud storage, store only paths in database.

📁 src/types ^(NEW) 🔗

Create types directory for TypeScript type definitions and interfaces.

📄 src/types/index.ts ^(NEW) 🔗

Create central type definitions file. Define interfaces for: Installation, Repository, Schedule, TokenUsage, Job, Screenshot, RepoConfig (matches .github/boxycpu.yml schema), JobData (union type for different job payloads), LLMProvider (enum: ANTHROPIC, OPENAI), JobType (enum matching job types), JobStatus (enum: PENDING, RUNNING, COMPLETED, FAILED). Export all types for use throughout the application.

📁 src/prompts ^(NEW) 🔗

Create prompts directory for LLM prompt templates.

📄 src/prompts/analyze-issue.txt ^(NEW) 🔗

Create prompt template for analyzing GitHub issues. Template should include placeholders for: issue title, issue body, repository context, recent commits. Instruct LLM to: identify the problem, suggest potential solutions, determine if tests are needed, assess priority. Format response as structured JSON with fields: summary, suggestedActions, needsTesting, priority, confidence.

📄 src/prompts/analyze-pr.txt ^(NEW) 🔗

Create prompt template for analyzing pull requests. Include placeholders for: PR title, description, files changed (diff summary), test results from sandbox. Instruct LLM to: review code changes, identify potential issues, suggest improvements, assess test coverage. Format response as structured JSON with fields: summary, codeReview, testingRecommendations, approvalStatus.

📄 src/prompts/analyze-screenshot.txt ^(NEW) 🔗

Create prompt template for analyzing screenshots. Include placeholders for: context (what page/component), comparison mode (single or diff). Instruct vision model to: describe UI elements, identify visual issues (layout problems, missing elements, styling issues), compare with baseline if provided, suggest fixes. Format response as structured JSON with fields: description, issues, suggestions, severity.

📄 src/prompts/proactive-check.txt ^(NEW) 🔗

Create prompt template for proactive repository checks. Include placeholders for: repository name, recent activity summary (commits, issues, PRs), last check results. Instruct LLM to: assess repository health, identify stale issues/PRs, suggest maintenance tasks, determine if intervention is needed. Format response as structured JSON with fields: healthScore, recommendations, shouldEngage, suggestedActions.

📁 src/utils ^(NEW) 🔗

Create utils directory for utility functions and helpers.

📄 src/utils/logger.ts ^(NEW) 🔗

Create logging utility using Winston. Configure log levels based on LOG_LEVEL from config. Set up transports: console (with colorization in development), file (rotating logs in production), optionally cloud logging service. Include structured logging with context fields: timestamp, level, message, service, jobId, repositoryId. Export logger instance and helper methods: logJobStart, logJobComplete, logError, logMetric.

📄 src/utils/retry.ts ^(NEW) 🔗

Create retry utility with exponential backoff. Implement generic retry function that accepts: async operation, max attempts, initial delay, backoff multiplier, optional shouldRetry predicate. Use for API calls, database operations, and external service requests. Include jitter to prevent thundering herd. Export typed retry function and common retry configurations (API_RETRY_CONFIG, DB_RETRY_CONFIG).

📄 src/utils/markdown.ts ^(NEW) 🔗

Create markdown formatting utilities for GitHub comments. Implement functions: formatCodeBlock (wrap code with language syntax), formatTable (create markdown table from data), formatCollapsible (create

Details

section), formatCheckbox (create task list), embedImage (create image markdown with alt text), formatBotSignature (add consistent bot signature to comments). Used by services when posting comments to maintain consistent formatting.

📄 src/utils/token-counter.ts ^(NEW) 🔗

Create token counting utility. Implement functions to estimate tokens for different LLM providers (use tiktoken for OpenAI, approximate for Anthropic). Methods: countTextTokens (estimate from text), countImageTokens (estimate from image dimensions and detail level), estimateCost (calculate USD cost based on provider pricing). Export token counting functions used by src/services/token-budget.ts for budget management.

📁 tests ^(NEW) 🔗

Create tests directory for Jest test files.

📁 tests/unit ^(NEW) 🔗

Create unit tests directory for isolated component tests.

📁 tests/unit/services ^(NEW) 🔗

Create services test directory.

📄 tests/unit/services/token-budget.test.ts ^(NEW) 🔗

References

• 📄 src/services/token-budget.ts ^(NEW)

Create unit tests for token budget service from src/services/token-budget.ts. Test cases: checkBudget returns correct remaining tokens, recordUsage updates database correctly, shouldThrottle returns true when approaching limit, budget resets correctly at period boundary. Mock database calls using Jest mocks.

📄 tests/unit/services/scheduler.test.ts ^(NEW) 🔗

References

• 📄 src/services/scheduler.ts ^(NEW)

Create unit tests for scheduler service from src/services/scheduler.ts. Test cases: scheduler identifies repositories due for check, respects check intervals, skips inactive repositories, enqueues correct job types, handles errors gracefully. Mock database and queue dependencies.

📁 tests/integration ^(NEW) 🔗

Create integration tests directory for end-to-end workflow tests.

📄 tests/integration/webhook-flow.test.ts ^(NEW) 🔗

Create integration test for webhook to job processing flow. Test: receive webhook event, verify job enqueued, verify worker processes job, verify result stored in database, verify GitHub comment posted. Use test database and Redis instance. Mock GitHub API calls using nock library.

📁 tests/fixtures ^(NEW) 🔗

Create fixtures directory for test data (sample webhook payloads, mock responses, test images).

📁 docker ^(NEW) 🔗

Create docker directory for Docker-related files.

📄 Dockerfile ^(NEW) 🔗

Create Dockerfile for the bot application. Use Node.js 20 LTS as base image. Multi-stage build: builder stage (install dependencies, compile TypeScript), production stage (copy compiled code, install production dependencies only). Install Playwright browsers for screenshot capability. Set non-root user for security. Expose port 3000. Set CMD to run compiled application from dist/index.js. Include health check endpoint.

📄 docker-compose.yml ^(NEW) 🔗

Create Docker Compose file for local development. Define services: bot (build from Dockerfile, mount src as volume for hot reload, environment variables from .env), postgres (PostgreSQL 15, persistent volume, expose port 5432), redis (Redis 7, persistent volume, expose port 6379). Set up network for service communication. Include depends_on to ensure postgres and redis start before bot. Add healthchecks for all services.

📁 docker/sandbox-images ^(NEW) 🔗

Create directory for sandbox Docker images used by src/services/sandbox.ts for code execution.

📄 docker/sandbox-images/node.Dockerfile ^(NEW) 🔗

Create Dockerfile for Node.js sandbox environment. Base on node:20-alpine for minimal size. Install common testing tools: jest, mocha, playwright. Set working directory /workspace. Configure non-root user. Set resource limits via labels. This image is used by sandbox service to run Node.js tests in isolation.

📄 docker/sandbox-images/python.Dockerfile ^(NEW) 🔗

Create Dockerfile for Python sandbox environment. Base on python:3.11-slim. Install common testing tools: pytest, unittest, selenium. Set working directory /workspace. Configure non-root user. This image is used by sandbox service to run Python tests in isolation.

📁 .github ^(NEW) 🔗

Create .github directory for GitHub-specific configuration.

📁 .github/workflows ^(NEW) 🔗

Create workflows directory for GitHub Actions CI/CD.

📄 .github/workflows/ci.yml ^(NEW) 🔗

Create CI workflow. Trigger on push and pull_request to main branch. Jobs: lint (run ESLint and Prettier check), test (run Jest tests with coverage, upload coverage report), build (compile TypeScript, verify no errors), docker-build (build Docker image, verify it starts). Use Node.js 20. Cache node_modules for faster builds. Run tests against test database (use service containers for PostgreSQL and Redis).

📄 .github/workflows/deploy.yml ^(NEW) 🔗

Create deployment workflow. Trigger on push to main branch (after CI passes) or manual workflow_dispatch. Jobs: build-and-push (build Docker image, tag with commit SHA and 'latest', push to container registry), deploy (deploy to hosting environment - placeholder for specific deployment target like Kubernetes, Cloud Run, or VPS). Include environment variables and secrets configuration. Add deployment status notifications.

📄 .github/boxycpu.yml ^(NEW) 🔗

Create example bot configuration file for this repository (dogfooding). Enable all features: proactiveChecks with 60-minute interval, testing with npm test command and node sandbox image, vision enabled with captureOnPR true. Set notifications preferences. This serves as both configuration for the bot monitoring its own repo and as documentation/example for other repositories.

📁 docs ^(NEW) 🔗

Create documentation directory.

📄 docs/ARCHITECTURE.md ^(NEW) 🔗

Create architecture documentation. Describe system components: GitHub App (webhook receiver), Job Queue (BullMQ/Redis), Worker Pool (job processors), Scheduler (proactive checks), Sandbox Manager (Docker execution), Vision Pipeline (Playwright + LLM), Database (PostgreSQL for state), GitHub Client (Octokit wrapper). Include architecture diagram (ASCII or reference to external diagram). Explain data flow for key scenarios: reactive (webhook → job → action), proactive (scheduler → check → job → action), testing (PR → sandbox → results → comment), vision (capture → analyze → comment). Document design decisions and trade-offs.

📄 docs/SETUP.md ^(NEW) 🔗

Create setup guide. Step-by-step instructions: 1) Create GitHub App (permissions, webhook events, generate private key), 2) Set up infrastructure (PostgreSQL, Redis, Docker), 3) Configure environment variables (copy .env.example, fill in values), 4) Run database migrations, 5) Start the bot (development: docker-compose up, production: deploy Docker image), 6) Install bot on repositories, 7) Configure repositories (add .github/boxycpu.yml). Include troubleshooting section for common issues.

📄 docs/CONFIGURATION.md ^(NEW) 🔗

Create configuration reference documentation. Document all options in .github/boxycpu.yml schema with descriptions, types, defaults, and examples. Explain configuration inheritance (global → org → repo). Provide example configurations for common scenarios: minimal (just reactive), proactive monitoring, full testing suite, vision-only. Document environment variables and their purposes. Include security best practices for secrets management.

📄 docs/API.md ^(NEW) 🔗

Create API documentation for bot interactions. Document special comment commands that trigger bot actions (e.g., '@boxycpu test this', '@boxycpu analyze screenshot', '@boxycpu sleep'). Document labels that trigger behaviors (e.g., 'bot-help', 'needs-testing'). Document webhook endpoints and payloads. Include examples of bot responses and comment formats. Document rate limits and throttling behavior.

📄 docs/DEVELOPMENT.md ^(NEW) 🔗

Create development guide. Explain project structure and module organization. Document development workflow: local setup with docker-compose, hot reload with nodemon, running tests, debugging. Explain how to add new features: new job types, new handlers, new LLM prompts. Document coding standards and conventions. Include guide for testing: unit tests, integration tests, mocking strategies. Explain how to test webhooks locally using smee.io or similar.

📄 docs/DEPLOYMENT.md ^(NEW) 🔗

Create deployment guide. Document deployment options: Docker Compose (simple VPS), Kubernetes (scalable), Cloud Run (serverless), Heroku (PaaS). Provide deployment configurations for each platform. Document infrastructure requirements: compute resources, storage, networking. Explain scaling considerations: horizontal scaling of workers, database connection pooling, Redis clustering. Include monitoring and observability setup: logs, metrics, alerts. Document backup and disaster recovery procedures.

📄 docs/SECURITY.md ^(NEW) 🔗

Create security documentation. Document security measures: webhook signature verification, installation token management, sandbox isolation (no network, resource limits, read-only filesystem), secrets handling (never log, use environment variables), rate limiting, input validation. Explain threat model: malicious repositories, resource exhaustion, token theft, data leakage. Document security best practices for deployment: HTTPS only, firewall rules, least privilege permissions, regular updates. Include incident response procedures.

📁 scripts ^(NEW) 🔗

Create scripts directory for utility scripts.

📄 scripts/setup-github-app.sh ^(NEW) 🔗

Create shell script to help set up GitHub App. Provide interactive prompts for: App name, homepage URL, webhook URL, permissions needed. Generate manifest JSON that can be used with GitHub's App creation flow. Output instructions for completing setup and obtaining App ID and private key. Make script executable.

📄 scripts/migrate-db.sh ^(NEW) 🔗

References

• 📄 src/db/migrations

Create database migration script. Run all pending migrations from src/db/migrations/ directory in order. Support up (apply) and down (rollback) operations. Verify database connection before running. Log migration results. Make script executable.

📄 scripts/seed-db.ts ^(NEW) 🔗

Create database seeding script for development. Insert sample data: test installation, test repositories with various configurations, sample schedules, historical token usage. Use TypeScript and import database repositories from src/db/repositories/. Include flag to clear existing data before seeding. Useful for local development and testing.

📄 scripts/build-sandbox-images.sh ^(NEW) 🔗

References

• 📄 docker/sandbox-images

Create script to build all sandbox Docker images from docker/sandbox-images/. Build each Dockerfile with appropriate tags (boxycpu-sandbox-node, boxycpu-sandbox-python, etc.). Optionally push to container registry if registry URL provided. Make script executable.

📄 .eslintrc.json ^(NEW) 🔗

Create ESLint configuration. Extend recommended TypeScript rules (@typescript-eslint/recommended). Configure parser options for TypeScript. Set environment to node and es2022. Add custom rules: enforce consistent code style, warn on console.log (use logger instead), enforce explicit return types on exported functions. Configure to work with Prettier (no conflicting rules).

📄 .prettierrc.json ^(NEW) 🔗

Create Prettier configuration. Set formatting rules: single quotes, trailing commas (es5), 2-space indentation, 100 character line width, semicolons required, arrow function parentheses (avoid when possible). Ensure consistency with ESLint configuration.

📄 jest.config.js ^(NEW) 🔗

Create Jest configuration. Set preset to ts-jest for TypeScript support. Set testEnvironment to node. Configure test match patterns: **/*.test.ts. Set up coverage collection: include src directory, exclude types and index files, set coverage thresholds (80% for statements, branches, functions, lines). Configure module name mapper for path aliases if used. Set up test timeout (10 seconds default).

📄 .dockerignore ^(NEW) 🔗

Create .dockerignore file to exclude unnecessary files from Docker build context. Exclude: node_modules, dist, .git, .env, *.log, coverage, tests, docs, scripts, .github, README.md, docker-compose.yml. This reduces build context size and speeds up Docker builds.

📄 CONTRIBUTING.md ^(NEW) 🔗

References

• 📄 docs/DEVELOPMENT.md ^(NEW)

Create contributing guidelines. Explain how to contribute: fork repository, create feature branch, make changes following coding standards from docs/DEVELOPMENT.md, write tests, submit pull request. Document PR requirements: tests pass, code coverage maintained, linting passes, descriptive commit messages. Explain code review process. Include code of conduct reference. Encourage opening issues for bugs and feature requests before starting work.

📄 CHANGELOG.md ^(NEW) 🔗

Create changelog file following Keep a Changelog format. Start with [Unreleased] section. Add initial version 0.1.0 entry with: Added - Initial release with proactive monitoring, VM testing, and vision capabilities. Document future versions as features are added. Use semantic versioning.

Diagram

sequenceDiagram
    participant GH as GitHub
    participant Bot as Bot Server
    participant Queue as Job Queue (Redis)
    participant Worker as Worker Pool
    participant Scheduler as Proactive Scheduler
    participant Sandbox as Docker Sandbox
    participant LLM as LLM API (Vision)
    participant DB as PostgreSQL

    Note over Scheduler,DB: Proactive Flow
    Scheduler->>DB: Query repos due for check
    DB-->>Scheduler: Return repo list
    Scheduler->>GH: Fetch recent activity
    GH-->>Scheduler: Activity data
    Scheduler->>Queue: Enqueue proactive job
    
    Note over GH,Worker: Reactive Flow (PR opened)
    GH->>Bot: Webhook: PR opened
    Bot->>DB: Store event
    Bot->>Queue: Enqueue test job
    Bot-->>GH: 200 OK (< 10s)
    
    Note over Queue,LLM: Job Processing
    Worker->>Queue: Dequeue job
    Worker->>DB: Update job status
    Worker->>Sandbox: Create container
    Sandbox->>Sandbox: Run tests
    Sandbox->>Worker: Test results + logs
    Worker->>LLM: Capture screenshot
    LLM-->>Worker: Screenshot
    Worker->>LLM: Analyze with vision
    LLM-->>Worker: Analysis
    Worker->>DB: Store results
    Worker->>GH: Post comment with results
    Worker->>DB: Record token usage
    Worker->>Sandbox: Destroy container

Loading

Import In IDE

🤖 Prompt for AI Agents

I have created the following plan after thorough exploration and analysis of the codebase. Follow the below plan verbatim. Trust the files and references. Do not re-verify what's written in the plan. Explore only when absolutely necessary. First implement all the proposed file changes and then I'll review all the changes together at the end.

### Observations

This is a **greenfield project** - the repository is empty except for a GPL-3.0 LICENSE file. We're building a novel proactive AI bot with three core capabilities:

1. **Proactive Operation**: Autonomous monitoring with smart wake/sleep scheduling
2. **VM Testing Environment**: Isolated code execution sandbox
3. **Vision Capabilities**: Screenshot capture, UI interaction, and visual debugging

Based on current best practices (2025), the optimal architecture uses:
- **GitHub App** (not Actions-only) for proactive webhooks and cross-repo access
- **Docker/Testcontainers** on GitHub-hosted runners for safe code execution
- **Modern LLM APIs** (Anthropic Claude, OpenAI GPT-4o) with vision support
- **Node.js/TypeScript** ecosystem (Probot framework + Octokit)
- **Playwright** for screenshot capture and UI automation
- **PostgreSQL** for persistent state (schedules, token usage, task history)
- **Redis** for job queuing and rate limiting


### Approach

Build a **modular GitHub App bot** with clear separation of concerns:

**Core Services**: Webhook ingestion → Job queue → Worker pool → LLM orchestrator → GitHub API client

**Key Modules**: Scheduler (proactive wake/sleep), Sandbox Manager (Docker execution), Vision Pipeline (screenshot capture/analysis), Token Budget Manager (cost control)

**Tech Stack**: Node.js + TypeScript, Probot framework, Octokit, BullMQ (Redis queue), Playwright, Docker SDK, PostgreSQL for state

**Deployment**: Containerized bot service + PostgreSQL + Redis, deployable to any cloud provider or self-hosted


### Reasoning

Listed the repository structure and found it empty (only LICENSE). Fetched the GitHub issue to understand requirements. Searched the web for current best practices on proactive GitHub bots, VM testing in CI, and AI vision integration. Analyzed the technical landscape and identified optimal architecture patterns for this novel use case.


## Mermaid Diagram

sequenceDiagram
    participant GH as GitHub
    participant Bot as Bot Server
    participant Queue as Job Queue (Redis)
    participant Worker as Worker Pool
    participant Scheduler as Proactive Scheduler
    participant Sandbox as Docker Sandbox
    participant LLM as LLM API (Vision)
    participant DB as PostgreSQL

    Note over Scheduler,DB: Proactive Flow
    Scheduler->>DB: Query repos due for check
    DB-->>Scheduler: Return repo list
    Scheduler->>GH: Fetch recent activity
    GH-->>Scheduler: Activity data
    Scheduler->>Queue: Enqueue proactive job
    
    Note over GH,Worker: Reactive Flow (PR opened)
    GH->>Bot: Webhook: PR opened
    Bot->>DB: Store event
    Bot->>Queue: Enqueue test job
    Bot-->>GH: 200 OK (< 10s)
    
    Note over Queue,LLM: Job Processing
    Worker->>Queue: Dequeue job
    Worker->>DB: Update job status
    Worker->>Sandbox: Create container
    Sandbox->>Sandbox: Run tests
    Sandbox->>Worker: Test results + logs
    Worker->>LLM: Capture screenshot
    LLM-->>Worker: Screenshot
    Worker->>LLM: Analyze with vision
    LLM-->>Worker: Analysis
    Worker->>DB: Store results
    Worker->>GH: Post comment with results
    Worker->>DB: Record token usage
    Worker->>Sandbox: Destroy container

## Proposed File Changes

### README.md(NEW)

Create comprehensive project README documenting the bot's purpose, architecture, features, and setup instructions. Include sections for: project overview (proactive AI bot for OmniBlocks), key features (proactive monitoring, VM testing, vision capabilities), architecture diagram reference, quick start guide, configuration options, development setup, deployment instructions, and links to detailed documentation. Mention that this is a novel approach to GitHub automation that goes beyond reactive bots.

### .gitignore(NEW)

Create standard Node.js/TypeScript .gitignore file. Include: node_modules/, dist/, build/, .env, .env.local, *.log, coverage/, .DS_Store, .vscode/ (except settings template), .idea/, *.swp, *.swo, .cache/, tmp/, secrets/, *.pem (for GitHub App private keys), and database files (*.db, *.sqlite).

### package.json(NEW)

Create package.json with project metadata and dependencies. Set name to 'boxycpu-bot', version '0.1.0', description matching the issue. Include scripts for: dev (development with hot reload), build (TypeScript compilation), start (production), test (Jest), lint (ESLint), format (Prettier). Dependencies: probot (GitHub App framework), @octokit/rest, bullmq (Redis-based queue), ioredis, pg (PostgreSQL client), playwright (screenshot/UI automation), dockerode (Docker SDK), anthropic (Claude API), openai (GPT-4 API), dotenv, winston (logging). DevDependencies: typescript, @types/node, ts-node, nodemon, jest, @types/jest, eslint, prettier, @typescript-eslint/parser, @typescript-eslint/eslint-plugin.

### tsconfig.json(NEW)

Create TypeScript configuration with strict mode enabled. Set target to ES2022, module to commonjs, outDir to './dist', rootDir to './src'. Enable: strict, esModuleInterop, skipLibCheck, forceConsistentCasingInFileNames, resolveJsonModule. Include './src/**/*', exclude 'node_modules' and 'dist'.

### .env.example(NEW)

Create environment variables template. Include: APP_ID (GitHub App ID), PRIVATE_KEY_PATH (path to .pem file), WEBHOOK_SECRET (GitHub webhook secret), WEBHOOK_PROXY_URL (for local dev with smee.io), DATABASE_URL (PostgreSQL connection string), REDIS_URL (Redis connection string), ANTHROPIC_API_KEY (Claude API key), OPENAI_API_KEY (GPT-4 API key), LOG_LEVEL (info/debug/error), NODE_ENV (development/production), PORT (default 3000), MAX_TOKENS_PER_DAY (budget limit), PROACTIVE_CHECK_INTERVAL (minutes between proactive checks), ENABLE_VISION (true/false toggle).

### src(NEW)

Create main source directory to contain all TypeScript application code.

### src/index.ts(NEW)

Create main application entry point. Initialize Probot application, load environment variables via dotenv, set up logging with Winston, initialize database connection pool, initialize Redis client, register event handlers from `src/handlers/index.ts`, start the scheduler service from `src/services/scheduler.ts`, set up graceful shutdown handlers (close DB, Redis, stop scheduler), and start the HTTP server. Export the Probot app instance for testing.

### src/config(NEW)

Create configuration directory for centralized config management.

### src/config/index.ts(NEW)

Create configuration module that loads and validates all environment variables. Export typed config object with sections: github (appId, privateKeyPath, webhookSecret), database (url, pool settings), redis (url, connection options), llm (anthropicKey, openaiKey, defaultProvider), bot (maxTokensPerDay, proactiveCheckInterval, enableVision, logLevel), server (port, nodeEnv). Include validation logic that throws descriptive errors for missing required variables. Use zod or joi for schema validation.

### src/handlers(NEW)

Create handlers directory for GitHub webhook event handlers.

### src/handlers/index.ts(NEW)

Create main handler registration module. Import and register all event handlers with Probot app instance. Register handlers for: issues.opened, issues.labeled, pull_request.opened, pull_request.synchronize, push, installation.created, installation_repositories.added. Each handler should enqueue a job to the BullMQ queue from `src/services/queue.ts` rather than processing synchronously (to respond to webhooks within 10 seconds). Include error handling and logging for each event type.

### src/handlers/issues.ts(NEW)

Create issue event handlers. For issues.opened: extract issue details, check if bot should respond (based on labels, keywords, or repo config from `src/services/config-loader.ts`), enqueue analysis job. For issues.labeled: check if label triggers bot action (e.g., 'needs-testing', 'bot-help'), enqueue appropriate job. Include logic to avoid responding to bot's own comments (check if author is the bot itself).

### src/handlers/pull-requests.ts(NEW)

Create pull request event handlers. For pull_request.opened and pull_request.synchronize: extract PR details (branch, files changed, description), enqueue testing job that will run tests in sandbox from `src/services/sandbox.ts`, optionally enqueue screenshot capture job if UI files changed (detect by file extensions: .html, .css, .jsx, .tsx, .vue). Include logic to check repo configuration for auto-testing preferences.

### src/handlers/push.ts(NEW)

Create push event handler. Extract commit details, check if push is to monitored branch (main, develop, etc. from repo config), determine if proactive analysis is needed (based on files changed, commit message patterns), enqueue appropriate jobs. Implement rate limiting to avoid processing every single commit (e.g., batch commits within 5-minute window).

### src/handlers/installation.ts(NEW)

Create installation event handlers. For installation.created: log new installation, initialize default configuration in database via `src/db/repositories/installation-repository.ts`, send welcome issue/comment to the repository explaining bot capabilities. For installation_repositories.added: update database with new repositories, initialize per-repo configuration with defaults.

### src/services(NEW)

Create services directory for core business logic modules.

### src/services/queue.ts(NEW)

References: 

- src/config/index.ts(NEW)

Create job queue service using BullMQ. Define job types enum: ANALYZE_ISSUE, TEST_PR, CAPTURE_SCREENSHOT, PROACTIVE_CHECK, ANALYZE_VISION. Create and export queue instance connected to Redis from `src/config/index.ts`. Define job data interfaces for each job type. Implement worker that processes jobs by routing to appropriate service methods. Include retry logic (exponential backoff), job timeout settings, and concurrency limits. Add job progress tracking and result storage.

### src/services/scheduler.ts(NEW)

References: 

- src/services/queue.ts(NEW)
- src/config/index.ts(NEW)

Create proactive scheduler service. Implement scheduling logic that periodically (based on PROACTIVE_CHECK_INTERVAL from config) queries database for repositories that need proactive checks. Use cron-like pattern or setInterval with database-backed state. For each repository due for check: fetch recent activity via Octokit (new issues, PRs, commits since last check), determine if bot should engage (based on activity patterns, keywords, repo config), enqueue appropriate jobs to queue from `src/services/queue.ts`. Implement smart sleep logic: skip checks if repository is inactive, increase check frequency if repository is very active. Store last check timestamp and activity metrics in database via `src/db/repositories/schedule-repository.ts`. Include token budget check before scheduling new proactive work.

### src/services/sandbox.ts(NEW)

Create sandbox execution service using Docker. Implement methods: createSandbox (spin up Docker container with specified image, mount code volume, set resource limits), executeTests (run test commands inside container, stream logs, capture exit code), captureArtifacts (copy test results, screenshots, logs from container), destroySandbox (stop and remove container, cleanup volumes). Use dockerode library to interact with Docker daemon. Include timeout enforcement, resource limits (CPU, memory), and cleanup on failure. Support multiple base images (Node.js, Python, etc.) based on repository language detection. Implement security measures: no network access by default, read-only filesystem where possible, drop capabilities.

### src/services/vision.ts(NEW)

References: 

- src/services/llm.ts(NEW)

Create vision service for screenshot capture and analysis. Implement methods: captureScreenshot (use Playwright to render URL or HTML file, take screenshot with specified viewport size, return image buffer), analyzeScreenshot (send image to LLM vision API via `src/services/llm.ts`, get description/analysis), compareScreenshots (detect visual differences between two images, optionally use pixel-diff library). Include screenshot optimization: compress images, convert to appropriate format (PNG for UI, JPEG for photos), resize if too large. Implement caching to avoid re-analyzing identical screenshots. Support both headless browser capture and direct image file analysis.

### src/services/llm.ts(NEW)

References: 

- src/services/token-budget.ts(NEW)

Create LLM orchestration service. Implement unified interface for multiple LLM providers (Anthropic Claude, OpenAI GPT-4). Methods: analyzeText (send text prompt, get completion), analyzeImage (send image with prompt for vision models), streamResponse (for long-running analysis). Include provider selection logic (prefer Claude for computer use, GPT-4o for general vision). Implement token counting and budget tracking: before each call, check remaining budget from `src/services/token-budget.ts`, after call, record actual usage. Add prompt template management: load templates from `src/prompts/` directory, support variable substitution. Include response caching (hash prompt+image, cache result in Redis) to save tokens. Implement retry logic with exponential backoff for API failures.

### src/services/token-budget.ts(NEW)

Create token budget management service. Track token usage per day/week/month in database via `src/db/repositories/token-usage-repository.ts`. Methods: checkBudget (return remaining tokens for period), recordUsage (log tokens used for specific operation), shouldThrottle (determine if bot should reduce activity based on budget), resetDaily (scheduled job to reset daily counters). Implement tiered throttling: at 70% budget, reduce proactive checks; at 90%, only respond to direct mentions; at 100%, enter sleep mode until reset. Include cost estimation: estimate tokens before making LLM call based on prompt length and model. Store usage breakdown by operation type (proactive, reactive, vision, testing) for analytics.

### src/services/github-client.ts(NEW)

Create GitHub API client wrapper around Octokit. Implement methods for common operations: createComment (on issue or PR), updateComment, createPR, updatePRStatus, uploadArtifact (to release or as gist), addLabel, removeLabel, getFileContent, listFiles, getRepoConfig (fetch .github/boxycpu.yml). Include rate limit handling: check rate limit before requests, implement exponential backoff on 403/429, use conditional requests (ETags) to save quota. Add request logging and metrics. Implement installation token management: fetch and cache installation access tokens (valid 1 hour), auto-refresh when expired. Support both REST and GraphQL APIs (use GraphQL for complex queries to reduce request count).

### src/services/config-loader.ts(NEW)

References: 

- src/services/github-client.ts(NEW)

Create repository configuration loader. Fetch and parse .github/boxycpu.yml from repositories using `src/services/github-client.ts`. Define configuration schema: enabled (boolean), proactiveChecks (enabled, interval, keywords), testing (enabled, commands, dockerImage), vision (enabled, captureOnPR, compareBaseline), notifications (channels, mentions), permissions (allowedBranches, restrictedPaths). Implement configuration inheritance: global defaults → organization config → repository config. Cache configurations in Redis with TTL. Validate configuration against schema, provide helpful error messages for invalid configs. Support configuration updates via special PR labels or comments.

### src/db(NEW)

Create database directory for PostgreSQL schema and data access layer.

### src/db/schema.sql(NEW)

Create database schema SQL file. Define tables: installations (id, github_installation_id, org_name, created_at, updated_at), repositories (id, installation_id, github_repo_id, full_name, config_json, last_proactive_check, activity_score, created_at, updated_at), schedules (id, repository_id, next_check_at, check_interval_minutes, is_active), token_usage (id, date, operation_type, tokens_used, cost_usd, metadata_json), jobs (id, job_type, repository_id, status, payload_json, result_json, created_at, started_at, completed_at), screenshots (id, repository_id, pr_number, url, image_path, analysis_text, created_at). Include indexes on frequently queried columns: installations.github_installation_id, repositories.full_name, schedules.next_check_at, token_usage.date, jobs.status. Add foreign key constraints and cascade delete rules.

### src/db/migrations(NEW)

Create migrations directory for database version control. Use a migration tool like node-pg-migrate or db-migrate.

### src/db/migrations/001_initial_schema.sql(NEW)

References: 

- src/db/schema.sql(NEW)

Create initial migration that applies the schema from `src/db/schema.sql`. Include up and down migration scripts for rollback capability.

### src/db/client.ts(NEW)

References: 

- src/config/index.ts(NEW)

Create database client module. Initialize PostgreSQL connection pool using pg library with configuration from `src/config/index.ts`. Export pool instance and helper methods: query (execute parameterized query), transaction (execute multiple queries in transaction), healthCheck (verify database connectivity). Implement connection retry logic on startup. Add query logging in development mode. Include graceful shutdown handler to close pool.

### src/db/repositories(NEW)

Create repositories directory for data access objects (DAO pattern).

### src/db/repositories/installation-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create installation repository for database operations on installations table. Methods: create (insert new installation), findByGithubId (lookup by GitHub installation ID), update (update installation details), delete (remove installation and cascade to related records), listAll (get all installations). Use parameterized queries via `src/db/client.ts` to prevent SQL injection. Return typed objects matching Installation interface from `src/types/index.ts`.

### src/db/repositories/repository-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create repository DAO for repositories table. Methods: create, findById, findByFullName, updateConfig (update config_json), updateLastCheck (update last_proactive_check timestamp), updateActivityScore, listByInstallation, listDueForProactiveCheck (query schedules join to find repos needing checks), delete. Include methods to serialize/deserialize config_json field.

### src/db/repositories/schedule-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create schedule repository for schedules table. Methods: create, findByRepositoryId, updateNextCheck (set next_check_at timestamp), updateInterval (change check_interval_minutes), activate, deactivate, listDueNow (query where next_check_at <= NOW() and is_active = true), delete. Used by `src/services/scheduler.ts` to manage proactive check scheduling.

### src/db/repositories/token-usage-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create token usage repository for token_usage table. Methods: recordUsage (insert usage record), getTotalForPeriod (sum tokens_used for date range), getTotalForToday, getUsageByOperationType (breakdown by operation_type), deleteOldRecords (cleanup records older than retention period). Support aggregation queries for analytics and budget tracking used by `src/services/token-budget.ts`.

### src/db/repositories/job-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create job repository for jobs table. Methods: create, findById, updateStatus (update status and timestamps), updateResult (store result_json), listByRepository, listByStatus, listRecent (for dashboard), deleteCompleted (cleanup old completed jobs). Used to persist job history beyond Redis queue for audit trail and analytics.

### src/db/repositories/screenshot-repository.ts(NEW)

References: 

- src/db/client.ts(NEW)

Create screenshot repository for screenshots table. Methods: create (store screenshot metadata and file path), findById, findByPR (get all screenshots for a PR), findLatestForUrl (for comparison), updateAnalysis (store LLM analysis text), delete, deleteOldScreenshots (cleanup based on retention policy). Store actual image files on disk or cloud storage, store only paths in database.

### src/types(NEW)

Create types directory for TypeScript type definitions and interfaces.

### src/types/index.ts(NEW)

Create central type definitions file. Define interfaces for: Installation, Repository, Schedule, TokenUsage, Job, Screenshot, RepoConfig (matches .github/boxycpu.yml schema), JobData (union type for different job payloads), LLMProvider (enum: ANTHROPIC, OPENAI), JobType (enum matching job types), JobStatus (enum: PENDING, RUNNING, COMPLETED, FAILED). Export all types for use throughout the application.

### src/prompts(NEW)

Create prompts directory for LLM prompt templates.

### src/prompts/analyze-issue.txt(NEW)

Create prompt template for analyzing GitHub issues. Template should include placeholders for: issue title, issue body, repository context, recent commits. Instruct LLM to: identify the problem, suggest potential solutions, determine if tests are needed, assess priority. Format response as structured JSON with fields: summary, suggestedActions, needsTesting, priority, confidence.

### src/prompts/analyze-pr.txt(NEW)

Create prompt template for analyzing pull requests. Include placeholders for: PR title, description, files changed (diff summary), test results from sandbox. Instruct LLM to: review code changes, identify potential issues, suggest improvements, assess test coverage. Format response as structured JSON with fields: summary, codeReview, testingRecommendations, approvalStatus.

### src/prompts/analyze-screenshot.txt(NEW)

Create prompt template for analyzing screenshots. Include placeholders for: context (what page/component), comparison mode (single or diff). Instruct vision model to: describe UI elements, identify visual issues (layout problems, missing elements, styling issues), compare with baseline if provided, suggest fixes. Format response as structured JSON with fields: description, issues, suggestions, severity.

### src/prompts/proactive-check.txt(NEW)

Create prompt template for proactive repository checks. Include placeholders for: repository name, recent activity summary (commits, issues, PRs), last check results. Instruct LLM to: assess repository health, identify stale issues/PRs, suggest maintenance tasks, determine if intervention is needed. Format response as structured JSON with fields: healthScore, recommendations, shouldEngage, suggestedActions.

### src/utils(NEW)

Create utils directory for utility functions and helpers.

### src/utils/logger.ts(NEW)

Create logging utility using Winston. Configure log levels based on LOG_LEVEL from config. Set up transports: console (with colorization in development), file (rotating logs in production), optionally cloud logging service. Include structured logging with context fields: timestamp, level, message, service, jobId, repositoryId. Export logger instance and helper methods: logJobStart, logJobComplete, logError, logMetric.

### src/utils/retry.ts(NEW)

Create retry utility with exponential backoff. Implement generic retry function that accepts: async operation, max attempts, initial delay, backoff multiplier, optional shouldRetry predicate. Use for API calls, database operations, and external service requests. Include jitter to prevent thundering herd. Export typed retry function and common retry configurations (API_RETRY_CONFIG, DB_RETRY_CONFIG).

### src/utils/markdown.ts(NEW)

Create markdown formatting utilities for GitHub comments. Implement functions: formatCodeBlock (wrap code with language syntax), formatTable (create markdown table from data), formatCollapsible (create <details> section), formatCheckbox (create task list), embedImage (create image markdown with alt text), formatBotSignature (add consistent bot signature to comments). Used by services when posting comments to maintain consistent formatting.

### src/utils/token-counter.ts(NEW)

Create token counting utility. Implement functions to estimate tokens for different LLM providers (use tiktoken for OpenAI, approximate for Anthropic). Methods: countTextTokens (estimate from text), countImageTokens (estimate from image dimensions and detail level), estimateCost (calculate USD cost based on provider pricing). Export token counting functions used by `src/services/token-budget.ts` for budget management.

### tests(NEW)

Create tests directory for Jest test files.

### tests/unit(NEW)

Create unit tests directory for isolated component tests.

### tests/unit/services(NEW)

Create services test directory.

### tests/unit/services/token-budget.test.ts(NEW)

References: 

- src/services/token-budget.ts(NEW)

Create unit tests for token budget service from `src/services/token-budget.ts`. Test cases: checkBudget returns correct remaining tokens, recordUsage updates database correctly, shouldThrottle returns true when approaching limit, budget resets correctly at period boundary. Mock database calls using Jest mocks.

### tests/unit/services/scheduler.test.ts(NEW)

References: 

- src/services/scheduler.ts(NEW)

Create unit tests for scheduler service from `src/services/scheduler.ts`. Test cases: scheduler identifies repositories due for check, respects check intervals, skips inactive repositories, enqueues correct job types, handles errors gracefully. Mock database and queue dependencies.

### tests/integration(NEW)

Create integration tests directory for end-to-end workflow tests.

### tests/integration/webhook-flow.test.ts(NEW)

Create integration test for webhook to job processing flow. Test: receive webhook event, verify job enqueued, verify worker processes job, verify result stored in database, verify GitHub comment posted. Use test database and Redis instance. Mock GitHub API calls using nock library.

### tests/fixtures(NEW)

Create fixtures directory for test data (sample webhook payloads, mock responses, test images).

### docker(NEW)

Create docker directory for Docker-related files.

### Dockerfile(NEW)

Create Dockerfile for the bot application. Use Node.js 20 LTS as base image. Multi-stage build: builder stage (install dependencies, compile TypeScript), production stage (copy compiled code, install production dependencies only). Install Playwright browsers for screenshot capability. Set non-root user for security. Expose port 3000. Set CMD to run compiled application from dist/index.js. Include health check endpoint.

### docker-compose.yml(NEW)

Create Docker Compose file for local development. Define services: bot (build from Dockerfile, mount src as volume for hot reload, environment variables from .env), postgres (PostgreSQL 15, persistent volume, expose port 5432), redis (Redis 7, persistent volume, expose port 6379). Set up network for service communication. Include depends_on to ensure postgres and redis start before bot. Add healthchecks for all services.

### docker/sandbox-images(NEW)

Create directory for sandbox Docker images used by `src/services/sandbox.ts` for code execution.

### docker/sandbox-images/node.Dockerfile(NEW)

Create Dockerfile for Node.js sandbox environment. Base on node:20-alpine for minimal size. Install common testing tools: jest, mocha, playwright. Set working directory /workspace. Configure non-root user. Set resource limits via labels. This image is used by sandbox service to run Node.js tests in isolation.

### docker/sandbox-images/python.Dockerfile(NEW)

Create Dockerfile for Python sandbox environment. Base on python:3.11-slim. Install common testing tools: pytest, unittest, selenium. Set working directory /workspace. Configure non-root user. This image is used by sandbox service to run Python tests in isolation.

### .github(NEW)

Create .github directory for GitHub-specific configuration.

### .github/workflows(NEW)

Create workflows directory for GitHub Actions CI/CD.

### .github/workflows/ci.yml(NEW)

Create CI workflow. Trigger on push and pull_request to main branch. Jobs: lint (run ESLint and Prettier check), test (run Jest tests with coverage, upload coverage report), build (compile TypeScript, verify no errors), docker-build (build Docker image, verify it starts). Use Node.js 20. Cache node_modules for faster builds. Run tests against test database (use service containers for PostgreSQL and Redis).

### .github/workflows/deploy.yml(NEW)

Create deployment workflow. Trigger on push to main branch (after CI passes) or manual workflow_dispatch. Jobs: build-and-push (build Docker image, tag with commit SHA and 'latest', push to container registry), deploy (deploy to hosting environment - placeholder for specific deployment target like Kubernetes, Cloud Run, or VPS). Include environment variables and secrets configuration. Add deployment status notifications.

### .github/boxycpu.yml(NEW)

Create example bot configuration file for this repository (dogfooding). Enable all features: proactiveChecks with 60-minute interval, testing with npm test command and node sandbox image, vision enabled with captureOnPR true. Set notifications preferences. This serves as both configuration for the bot monitoring its own repo and as documentation/example for other repositories.

### docs(NEW)

Create documentation directory.

### docs/ARCHITECTURE.md(NEW)

Create architecture documentation. Describe system components: GitHub App (webhook receiver), Job Queue (BullMQ/Redis), Worker Pool (job processors), Scheduler (proactive checks), Sandbox Manager (Docker execution), Vision Pipeline (Playwright + LLM), Database (PostgreSQL for state), GitHub Client (Octokit wrapper). Include architecture diagram (ASCII or reference to external diagram). Explain data flow for key scenarios: reactive (webhook → job → action), proactive (scheduler → check → job → action), testing (PR → sandbox → results → comment), vision (capture → analyze → comment). Document design decisions and trade-offs.

### docs/SETUP.md(NEW)

Create setup guide. Step-by-step instructions: 1) Create GitHub App (permissions, webhook events, generate private key), 2) Set up infrastructure (PostgreSQL, Redis, Docker), 3) Configure environment variables (copy .env.example, fill in values), 4) Run database migrations, 5) Start the bot (development: docker-compose up, production: deploy Docker image), 6) Install bot on repositories, 7) Configure repositories (add .github/boxycpu.yml). Include troubleshooting section for common issues.

### docs/CONFIGURATION.md(NEW)

Create configuration reference documentation. Document all options in .github/boxycpu.yml schema with descriptions, types, defaults, and examples. Explain configuration inheritance (global → org → repo). Provide example configurations for common scenarios: minimal (just reactive), proactive monitoring, full testing suite, vision-only. Document environment variables and their purposes. Include security best practices for secrets management.

### docs/API.md(NEW)

Create API documentation for bot interactions. Document special comment commands that trigger bot actions (e.g., '@boxycpu test this', '@boxycpu analyze screenshot', '@boxycpu sleep'). Document labels that trigger behaviors (e.g., 'bot-help', 'needs-testing'). Document webhook endpoints and payloads. Include examples of bot responses and comment formats. Document rate limits and throttling behavior.

### docs/DEVELOPMENT.md(NEW)

Create development guide. Explain project structure and module organization. Document development workflow: local setup with docker-compose, hot reload with nodemon, running tests, debugging. Explain how to add new features: new job types, new handlers, new LLM prompts. Document coding standards and conventions. Include guide for testing: unit tests, integration tests, mocking strategies. Explain how to test webhooks locally using smee.io or similar.

### docs/DEPLOYMENT.md(NEW)

Create deployment guide. Document deployment options: Docker Compose (simple VPS), Kubernetes (scalable), Cloud Run (serverless), Heroku (PaaS). Provide deployment configurations for each platform. Document infrastructure requirements: compute resources, storage, networking. Explain scaling considerations: horizontal scaling of workers, database connection pooling, Redis clustering. Include monitoring and observability setup: logs, metrics, alerts. Document backup and disaster recovery procedures.

### docs/SECURITY.md(NEW)

Create security documentation. Document security measures: webhook signature verification, installation token management, sandbox isolation (no network, resource limits, read-only filesystem), secrets handling (never log, use environment variables), rate limiting, input validation. Explain threat model: malicious repositories, resource exhaustion, token theft, data leakage. Document security best practices for deployment: HTTPS only, firewall rules, least privilege permissions, regular updates. Include incident response procedures.

### scripts(NEW)

Create scripts directory for utility scripts.

### scripts/setup-github-app.sh(NEW)

Create shell script to help set up GitHub App. Provide interactive prompts for: App name, homepage URL, webhook URL, permissions needed. Generate manifest JSON that can be used with GitHub's App creation flow. Output instructions for completing setup and obtaining App ID and private key. Make script executable.

### scripts/migrate-db.sh(NEW)

References: 

- src/db/migrations

Create database migration script. Run all pending migrations from `src/db/migrations/` directory in order. Support up (apply) and down (rollback) operations. Verify database connection before running. Log migration results. Make script executable.

### scripts/seed-db.ts(NEW)

Create database seeding script for development. Insert sample data: test installation, test repositories with various configurations, sample schedules, historical token usage. Use TypeScript and import database repositories from `src/db/repositories/`. Include flag to clear existing data before seeding. Useful for local development and testing.

### scripts/build-sandbox-images.sh(NEW)

References: 

- docker/sandbox-images

Create script to build all sandbox Docker images from `docker/sandbox-images/`. Build each Dockerfile with appropriate tags (boxycpu-sandbox-node, boxycpu-sandbox-python, etc.). Optionally push to container registry if registry URL provided. Make script executable.

### .eslintrc.json(NEW)

Create ESLint configuration. Extend recommended TypeScript rules (@typescript-eslint/recommended). Configure parser options for TypeScript. Set environment to node and es2022. Add custom rules: enforce consistent code style, warn on console.log (use logger instead), enforce explicit return types on exported functions. Configure to work with Prettier (no conflicting rules).

### .prettierrc.json(NEW)

Create Prettier configuration. Set formatting rules: single quotes, trailing commas (es5), 2-space indentation, 100 character line width, semicolons required, arrow function parentheses (avoid when possible). Ensure consistency with ESLint configuration.

### jest.config.js(NEW)

Create Jest configuration. Set preset to ts-jest for TypeScript support. Set testEnvironment to node. Configure test match patterns: **/*.test.ts. Set up coverage collection: include src directory, exclude types and index files, set coverage thresholds (80% for statements, branches, functions, lines). Configure module name mapper for path aliases if used. Set up test timeout (10 seconds default).

### .dockerignore(NEW)

Create .dockerignore file to exclude unnecessary files from Docker build context. Exclude: node_modules, dist, .git, .env, *.log, coverage, tests, docs, scripts, .github, README.md, docker-compose.yml. This reduces build context size and speeds up Docker builds.

### CONTRIBUTING.md(NEW)

References: 

- docs/DEVELOPMENT.md(NEW)

Create contributing guidelines. Explain how to contribute: fork repository, create feature branch, make changes following coding standards from `docs/DEVELOPMENT.md`, write tests, submit pull request. Document PR requirements: tests pass, code coverage maintained, linting passes, descriptive commit messages. Explain code review process. Include code of conduct reference. Encourage opening issues for bugs and feature requests before starting work.

### CHANGELOG.md(NEW)

Create changelog file following Keep a Changelog format. Start with [Unreleased] section. Add initial version 0.1.0 entry with: Added - Initial release with proactive monitoring, VM testing, and vision capabilities. Document future versions as features are added. Use semantic versioning.

---

Developer Humor

🤖 A bot walked into a repo...

I'm always watching, it said with a grin,

I'll test your code, capture your screen,

And sleep when I'm tired—the smartest you've seen!

The developers cheered, Finally, a bot with a brain!

🎉 BoxyCPU: Because reactive bots are so 2024 🎉

---

Execution Information

Branch: main
Commit: ae56483

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.

[supervoidcoder]

/q dev

[amazon-q-developer]

Progress Updates

• I'll start by exploring the repository structure to understand the codebase and then plan the implementation of a proactive AI bot with VM testing and vision capabilities.
• The repository appears to be mostly empty with just a LICENSE file. I'll examine the LICENSE file to understand the project context and then create the necessary structure for the proactive AI bot implementation.
• Planning the implementation of a proactive AI bot with VM testing and vision capabilities for the OmniBlocks organization.
• Now I'll create a comprehensive plan for implementing the proactive AI bot system with all the required features, then start building the project structure.
• Create a comprehensive implementation plan for a proactive AI bot with VM testing and vision capabilities for the OmniBlocks organization
• Now I'll start implementing the project structure and core components based on the comprehensive plan. I'll begin with the foundation layer and project structure.
• Now I'll create the core project structure with all the necessary directories and start implementing the main components, beginning with the source code structure and configuration files.
• Now I'll create the remaining core components including the scheduler, event processor, and then move on to implementing the other subsystems like monitoring, testing, vision, GitHub integration, and LLM management.
• Now I'll create the utility modules including logging, state management, and then start implementing the monitoring, testing, vision, GitHub, and LLM subsystems.
• Now I'll create the monitoring subsystem that handles repository monitoring and event detection, followed by the other major subsystems.
• Now I'll create the GitHub client integration module that handles all GitHub API interactions, followed by the other subsystems.
• Now I'll create the requirements.txt file and configuration files to complete the basic project structure, then continue with the remaining subsystems.
• Now I'll create the remaining core subsystems including the VM manager for testing, vision engine, and LLM manager to complete the implementation.
• Now I'll create the vision engine for screenshot capture and UI interaction, followed by the LLM manager for AI intelligence integration.
• Now I'll create the LLM manager for AI intelligence integration, which will handle interactions with OpenAI, Anthropic, and other LLM providers.

---

✅ I finished the proposed code changes, and the pull request is ready for review: #2.

Comment on the pull request to provide feedback and request a new iteration.

To provide feedback on how Amazon Q Developer performed with code generation, create an issue in the Amazon Q Developer public repository.