Maggy Engineering System

The Maggy v2 Dashboard is a multi-project command center designed to provide developers with a unified view of their development ecosystem. It aggregates data from various backend modules to provide visibility into task management, resource consumption, and agent performance.

Key monitoring areas include:

• Inbox: AI-ranked tickets aggregated from GitHub Issues, Asana, Linear, and Jira.
• Budget: Real-time token spend tracking per provider with burn rate trends (using green/yellow/red status indicators).
• Agents: Monitoring of active Polyphony containers, including current tasks, models being used, and progress.
• CIKG (Competitive Intelligence): Visualization of the competitive landscape, gap maps, and threat radars.
• Process Health: Trends in CI pass rates, review rounds, and CodeRabbit findings.
• Model Performance: Reward heatmaps derived from the routing table.

The roadmap is organized into three priority tiers designed to close the gap between the current code-intelligence stack and fully autonomous coding agents.

Tier 1: High Leverage (Unlocks the rest)

Focuses on critical feedback loops and safety:

• Runtime observability: Provides production feedback signals to detect if code changes actually worked.
• Verifiable contracts: Converts natural-language iCPG postconditions into machine-checkable property-based tests.
• Human escalation protocol: Provides a formal channel to 'page a human' with a context packet when an agent is stuck.

Tier 2: Valuable (Non-blocking)

Focuses on operational stability and coordination:

• Auto CODE_INDEX: Automatically derives the capability index from the graph.
• Multi-agent coordination: Implements locking and negotiation when multiple agents touch the same code area.
• Rollback & recovery: Provides automated revert paths when drift is detected.

Tier 3: Frontier (Optional)

Focuses on advanced optimization and multimodal capabilities:

• Confidence calibration: A reinforcement loop to learn from past agent failures.
• Cost / budget awareness: Implements hard budget stops to prevent agents from burning money in loops.
• Multimodal ingestion: Enables 'Graphify-style' ingestion for repos containing docs, images, or video.

Maggy is composed of several specialized subsystems that handle different aspects of the AI development lifecycle:

• CIKG (Code Intelligence Knowledge Graph): Manages codebase nodes and technology detection.
• Forge: Detects MCP (Model Context Protocol) capability gaps and suggests tools.
• History: Parses CLI session history for Claude, Codex, and Kimi.
• Improve: Handles self-improvement via signal collection and health scoring.
• Budget: Manages daily token spend limits with per-provider breakdowns.
• Model Router: Uses a reward-based heatmap for model selection by task type.
• Heartbeat: Runs scheduled jobs like history refresh, engram expiry, and mesh sync.
• Engram: Provides persistent memory with typed records and namespace isolation.
• Event Spine: Enables structured event emission and querying across all services.
• P2P Mesh: Facilitates multi-node session sync via WebSockets, scoped to organizations.

Mnemos calculates a composite fatigue score based on four passively observable dimensions. This score determines the agent's current state and triggers automatic actions.

Fatigue Dimensions

• Token Utilization (0.40): context_window.used_percentage / 100. Measures context window fullness.
• Scope Scatter (0.25): Ratio of unique directories touched in the last 30 tool calls. High scatter indicates an unfocused agent.
• Re-read Ratio (0.20): Proportion of Read tool calls targeting files already read. High ratio indicates context degradation.
• Error Density (0.15): Ratio of failed tool calls to total tool calls in the rolling window.

State Thresholds and Auto-Actions

Maggy uses an autonomous AUTO-SEED process triggered upon project registration to eliminate manual configuration. Instead of requiring a user to define policies, Maggy spawns a Pi agent (using a cost-effective model like qwen or kimi) to perform a deep analysis of the project's history.

The Seeding Workflow

1. Detection: Maggy detects a new project in the registry.
2. Analysis: The Pi agent executes a series of commands to extract patterns:
   • GitHub Data: Uses gh CLI to analyze PR sizes, review rounds, time-to-merge, and reviewer patterns (gh pr list, gh pr view).
   • CI/CD History: Uses gh api to check CI pass/fail rates and identify flaky tests.
   • Git History: Uses git log to detect reverts and branch naming conventions.
   • Structural Analysis: Uses codebase-memory-mcp (get_architecture and search_graph) to understand module structure and dependency depth.
3. Database Seeding: The agent writes findings to specialized databases:
   • process_patterns.db (review comments)
   • ci_patterns.db (CI failures)
   • pr_patterns.db (merge velocity)
   • task_history.db (git log data)
   • environments/{project}.yaml (workflow configuration)
4. Policy Generation: An initial policy.yaml is automatically computed based on these patterns (e.g., if ruff failures are frequent, it enables a pre-check).
5. Ledger Entry: The seed is recorded as modification #1 in the improvement_ledger to serve as the baseline for all future autonomous optimizations.

Benefits

• Zero Configuration: No manual setup or flag-driven seeding required.
• Low Cost: Uses cheap models for structured data extraction (~$0.10-$0.50 per project).
• Immediate Value: Provides a "Day 1 Analysis" dashboard showing predicted improvements based on historical data.

// Example of Day 1 Analysis output
MAGGY — Day 1 Analysis (auto-generated from project history)

zensurveys-backend (200 PRs analyzed):
  Current process health:
    CI first-pass rate: 72%
    Avg review rounds: 2.8
    Top review comment: "add error handling" (23 times)
    Avg time-to-merge: 36h

  Predicted improvements if Maggy had been active:
    CI first-pass rate: 72% → ~94% (pre-lint + pre-type)
    Review rounds: 2.8 → ~1.4 (auto error handling + tests)
    Time-to-merge: 36h → ~12h (smaller PRs + fewer rounds)