Agent Operating System (Agent OS)

A comprehensive agent management and cleanup system designed to standardize AI agent workflows, eliminate code duplication, enforce quality gates, and maintain lean repository structures.

Comment

Agent Operating System (Agent OS) - Project Narrative

Inspiration

The inspiration for Agent OS came from a critical problem in modern AI-assisted development: AI slop. As developers increasingly rely on multiple AI coding assistants (Claude, Codex, Cline, Kilo, Gemini), we noticed a disturbing pattern: repositories were accumulating duplicate code, unnecessary dependencies, stale files, and inconsistent quality standards. Each AI agent operated in isolation, unaware of what others had created, leading to:

  • Functions and types duplicated across multiple files
  • Dependencies added "just in case" without justification
  • Planning artifacts and temporary files committed to repositories
  • Inconsistent coding standards across different agent sessions
  • No systematic way to audit or clean up AI-generated code

We realized that while AI agents are powerful tools, they need an operating system — a unified framework that enforces quality gates, prevents duplication, and maintains repository hygiene across all platforms. The goal was simple: eliminate 90% of AI slop by giving agents clear contracts, reusable skills, and verification gates before any code is accepted.

What it does

Agent OS is a comprehensive management system that standardizes AI agent workflows and maintains lean, professional codebases. It provides:

Repository Management

  • Tracks multiple code repositories with health scores
  • Executes comprehensive audits analyzing dependencies, duplicates, stale files, and test coverage
  • Recommends cleanup phases based on audit findings
  • Monitors repository status from "clean" to "needs cleanup"

Agent Provider Configuration

  • Manages six major AI platforms: Claude, Codex, Cline, Kilo, Gemini, and Z.ai
  • Configures provider-specific profiles (default, read-only audit, cleanup, deep review)
  • Enables/disables providers globally
  • Maintains consistent settings across all platforms

Skills Management

  • Provides six core reusable skills:
    • Repository Audit: Inspect before changing
    • Repository Cleanup: Remove slop in small phases
    • Dependency Cleanup: Remove unused packages
    • Deduplication: Find duplicates before creating new code
    • Test Quality: Improve coverage and remove weak tests
    • Code Review: Review diffs for quality and security
  • Enables/disables skills per provider
  • Tracks provider compatibility

MCP Server Configuration

  • Manages Model Context Protocol servers
  • Classifies security levels (read-only, write, dangerous)
  • Controls tool access with allowlists and denylists
  • Enforces "global MCPs are read-mostly" policy

Policy Management

  • Defines four core policies:
    • Global Operating Contract: Core agent behavior rules
    • Dependency Policy: Runtime vs dev dependency criteria
    • Cleanup Policy: Repository cleanup standards
    • Testing Policy: Test quality requirements
  • Version-controlled policy documents
  • Syncs policies across all providers

Task History & Verification

  • Logs all agent operations with timestamps
  • Tracks success/failure rates
  • Records verification results (typecheck, test, lint, build, audit, dedup)
  • Provides audit trail for debugging

How we built it

Research Phase We began with extensive research into AI agent best practices, studying:

  • OpenAI's Codex guidance on strong prompts and verification
  • GitHub Copilot's recommendations for code validation
  • NIST's Secure Software Development Framework
  • Google's agent evaluation criteria
  • Real-world repository cleanup patterns

Architecture Design We designed Agent OS around three core principles:

  1. Contract-First Development: Every task starts with a clear contract defining goal, scope, constraints, and acceptance criteria
  2. Verification Gates: No code is accepted without passing typecheck, tests, lint, build, dependency audit, and dedup scan
  3. Thin Structure: Repositories should be purpose-driven, not bloated with enterprise patterns

Technology Stack

  • Frontend: React 18 with TypeScript for type safety
  • UI Framework: shadcn/ui components for consistency
  • Styling: Tailwind CSS with a minimal monochromatic design
  • State Management: React hooks + localStorage for MVP
  • Routing: React Router v6 for navigation
  • Build Tool: Vite for fast development

Implementation Approach We followed a systematic development workflow:

  1. Type System First: Defined 20+ TypeScript interfaces for all data models
  2. Service Layer: Built localStorage service for CRUD operations
  3. Mock Data: Created comprehensive demo data (4 repos, 6 skills, 3 MCP servers, 2 policies)
  4. Layout System: Implemented responsive MainLayout with sidebar navigation
  5. Page Components: Built 8 fully functional pages with consistent patterns
  6. Quality Gates: Ensured zero lint errors and type-safe operations

Design Philosophy We applied the "Minimal" aesthetic template:

  • Monochromatic color palette (pure grays, no decorative colors)
  • Ample whitespace for visual breathing room
  • Clear typography hierarchy (font size, weight, spacing)
  • No shadows or decorative elements
  • Focus on content and functionality over decoration

Challenges we ran into

1. Multi-Provider Complexity Each AI platform (Claude, Codex, Cline, Kilo, Gemini) has different configuration formats, file structures, and conventions. Creating a unified interface that respects each provider's uniqueness while maintaining consistency was challenging. We solved this by:

  • Abstracting common patterns into the ProviderConfig model
  • Supporting provider-specific profiles
  • Allowing flexible settings objects

2. Deduplication Logic Detecting duplicate code across functions, types, interfaces, and schemas is non-trivial. We needed to:

  • Define what constitutes a "duplicate" (exact match vs semantic similarity)
  • Track similarity percentages
  • Show locations clearly
  • Avoid false positives

We addressed this by creating a structured DuplicateAnalysis model with separate categories and similarity scores.

3. Policy Synchronization Keeping policies consistent across multiple providers while allowing provider-specific overrides required careful design. We implemented:

  • Version-controlled policies with timestamps
  • Markdown-based content for readability
  • Clear sync mechanisms
  • Provider-specific AGENTS.md files

4. Security Classification MCP servers have varying security implications. We needed a clear classification system:

  • Read-only: Safe for global use (docs, search)
  • Write: Project-level only (GitHub, databases)
  • Dangerous: Explicit approval required (browser automation, filesystem)

We added visual warnings and enforced scope restrictions.

5. Responsive Design with Complex Layouts Creating a sidebar navigation that works seamlessly on both desktop and mobile required:

  • Desktop: Fixed sidebar with 256px width
  • Mobile: Sheet-based overlay menu
  • Consistent navigation state
  • Touch-friendly controls

We solved this with shadcn/ui's Sheet component and careful breakpoint management.

6. Type Safety with Dynamic Data TypeScript's strict mode caught many potential runtime errors, but required careful typing of:

  • Union types for status and classification enums
  • Optional fields with proper null handling
  • Generic CRUD operations in the storage service
  • Type-safe filter and search operations

Accomplishments that we're proud of

1. Zero AI Slop The application itself follows all the principles it enforces:

  • No duplicate code across 2,500+ lines
  • All dependencies justified (React, React Router, shadcn/ui, Tailwind)
  • Clean project structure with clear separation of concerns
  • Zero lint errors
  • Type-safe throughout

2. Comprehensive Data Models We created 10 core data models with 100+ fields total, covering every aspect of agent management:

  • Repository tracking with health scores
  • Detailed audit results with 6 analysis categories
  • Provider configurations with profiles
  • Skills with provider compatibility
  • MCP servers with security levels
  • Policies with version control
  • Task logs with verification results

3. Production-Ready Code Quality

  • TypeScript: 100% type coverage, strict mode enabled
  • Linting: Zero errors, consistent code style
  • Architecture: Modular components, reusable services
  • Naming: Clear, intention-revealing names throughout
  • Error Handling: Graceful fallbacks and user-friendly messages

4. Minimal Aesthetic Excellence We achieved a truly minimal design:

  • Pure monochromatic palette (no decorative colors)
  • Generous whitespace (24px-48px gaps)
  • Typography hierarchy (3 font sizes, 2 weights)
  • No shadows or gradients
  • Focus on content clarity

5. Comprehensive Documentation

  • README.md: Full feature overview and usage guide
  • IMPLEMENTATION.md: Technical implementation details
  • Inline comments: Clear explanations of complex logic
  • Type definitions: Self-documenting interfaces

6. Real-World Applicability The mock data is based on actual repositories:

  • universal-agent-os
  • universal-agent-toolkit
  • ebay-mcp
  • portfolio

This makes the demo immediately relatable to real cleanup scenarios.

What we learned

1. Contracts Beat Cleverness The most important insight: AI agents need explicit contracts, not vague instructions. A clear contract with goal, scope, constraints, and acceptance criteria prevents 90% of slop. We learned to:

  • Define "done" before starting
  • List verification commands upfront
  • Specify what NOT to do (forbidden patterns)
  • Require justification for new dependencies

2. Verification Gates Are Non-Negotiable Code generation is easy; verification is hard. We learned that agents must run:

  • typecheck (catch type errors)
  • test (verify behavior)
  • lint (enforce style)
  • build (ensure compilation)
  • dependency audit (find vulnerabilities)
  • dedup scan (prevent duplicates)

Without these gates, slop accumulates silently.

3. Thin Structure Beats Enterprise Patterns Repositories should be purpose-driven, not pattern-driven. We learned:

  • Folders should exist because the product needs them
  • Don't create "enterprise architecture" for small projects
  • Prefer flat structures over deep nesting
  • Delete unused code aggressively

4. Global vs Project-Level Configuration Not everything belongs in global config. We learned to separate:

  • Global: Personal defaults, reusable skills, read-only MCPs
  • Project: Repo-specific rules, write-capable MCPs, custom workflows

This prevents one project's assumptions from leaking into others.

5. Security Levels Matter MCP servers have vastly different security implications. We learned to classify:

  • Read-only: Safe for global use
  • Write: Requires project-level approval
  • Dangerous: Explicit confirmation required

This prevents accidental data loss or security breaches.

6. Mock Data Drives Design Creating realistic mock data early forced us to:

  • Think through real-world scenarios
  • Design data models that handle edge cases
  • Create UI that works with actual content lengths
  • Test filtering and search with realistic datasets

7. Minimal Design Requires Discipline Achieving true minimalism is harder than adding decoration. We learned:

  • Every color must be justified
  • Whitespace is a design element, not empty space
  • Typography hierarchy replaces visual decoration
  • Consistency matters more than variety

8. TypeScript Catches Real Bugs Strict TypeScript caught dozens of potential runtime errors:

  • Null/undefined access
  • Type mismatches in filters
  • Missing required fields
  • Incorrect enum values

The upfront cost of typing pays off immediately.

What's next for Agent Operating System (Agent OS)

Phase 1: Real Agent Integration (Q3 2026)

  • Replace mock data with live agent connections
  • Implement actual audit execution using provider APIs
  • Real-time cleanup execution with diff capture
  • Rollback functionality with git integration

Phase 2: Backend & Authentication (Q4 2026)

  • Replace localStorage with Supabase backend
  • User authentication and authorization
  • Multi-user collaboration features
  • Cloud synchronization across devices
  • Team workspaces with shared repositories

Phase 3: Advanced Automation (Q1 2027)

  • Scheduled audits and cleanup tasks
  • Automated dependency updates with verification
  • CI/CD pipeline integration
  • GitHub/GitLab webhook support
  • Slack/Discord notifications

Phase 4: Intelligence Layer (Q2 2027)

  • Machine learning for duplicate detection
  • Predictive health scoring
  • Anomaly detection in code patterns
  • Automated cleanup recommendations
  • Learning from user feedback

Phase 5: Ecosystem Expansion (Q3 2027)

  • Plugin marketplace for custom skills
  • Community-contributed policies
  • Provider-specific extensions
  • Integration with more AI platforms
  • API for third-party tools

Phase 6: Enterprise Features (Q4 2027)

  • Role-based access control
  • Audit trail and compliance reporting
  • Custom approval workflows
  • Organization-wide policy enforcement
  • Advanced analytics dashboards

Phase 7: Developer Experience (Q1 2028)

  • VS Code extension
  • CLI tool for terminal workflows
  • Browser extension for web-based IDEs
  • Mobile app for monitoring
  • Desktop app for offline use

Phase 8: AI-Powered Insights (Q2 2028)

  • Natural language queries ("Show me all repos with high duplicate counts")
  • Automated cleanup execution with AI approval
  • Intelligent skill recommendations
  • Predictive maintenance alerts
  • Code quality trends and forecasting

Long-term Vision

Agent OS aims to become the standard operating system for AI-assisted development, ensuring that:

  1. Every repository is clean: No slop, no duplicates, no unnecessary dependencies
  2. Every agent follows contracts: Clear goals, constraints, and verification
  3. Every change is verified: Automated quality gates before acceptance
  4. Every team has standards: Shared policies and reusable skills
  5. Every developer is productive: Less time cleaning up, more time building

We envision a future where AI agents are not just tools, but reliable team members that follow professional standards, respect existing code, and maintain repository hygiene automatically.

The ultimate goal: Make AI slop a thing of the past.

Built With

Share this project:

Updates

Submission history