devhive

v0.1.0

Published

17 days ago

The Operating System for AI-Assisted Software Development

0High
0Medium
0Low

xombi17

ai agents coding coordination multi-agent claude codex cline cursor development-tools

AgentOS

The Operating System for AI-Assisted Software Development

AgentOS is a developer infrastructure layer that coordinates multiple AI coding agents (Claude Code, Codex, Cline, KiloCode, Cursor, Gemini CLI) by providing shared memory, project intelligence, task ownership, architectural awareness, conflict prevention, and knowledge graph reasoning.

Why AgentOS?

The Problem

Modern developers use multiple AI coding assistants simultaneously:

Developer
   │
   ├── Claude Code   ← thinks it owns auth.ts
   ├── Codex         ← also editing auth.ts
   ├── Cline         ← no idea what the others did yesterday
   ├── KiloCode      ← about to introduce a circular dependency
   └── Gemini CLI    ← duplicating work on tests

Result: duplicated work, conflicting changes, forgotten architectural decisions, poor collaboration, architectural drift.

The Solution

Developer
    │
    ▼
AgentOS           ← shared coordination layer
    │
 ┌──┼─────────┐
 ▼  ▼         ▼
Claude   Codex  Cline

All agents share: Memory · Architecture · Tasks · Decisions · Ownership · Knowledge Graph

Features

Core Pillars

| Pillar | Description | |--------|-------------| | Project Intelligence | Understands your repository — files, classes, functions, APIs, dependencies | | Shared Memory | Remembers everything — architecture decisions, bug fixes, task context | | Agent Coordination | Prevents chaos — task ownership, file locking, conflict detection | | Knowledge Graph | Understands relationships — dependencies, calls, ownership chains | | Execution Tracking | Knows what happened — full event replay, AI Git Blame, reasoning trails |

Commands

Agent Registry

agent register claude --strengths architecture,planning
agent register codex --strengths testing,debugging
agent agents

Task Ownership

agent assign auth-refactor claude
agent lock src/auth/auth.ts claude --task auth-refactor --reason "JWT migration"
agent unlock src/auth/auth.ts
agent complete auth-refactor
agent tasks
agent locks

Shared Memory

agent remember why-jwt "Chose JWT over sessions for stateless API scaling"
agent recall why-jwt
agent memories
agent memories --search "authentication"
agent forget why-jwt

Intelligence

agent map src/                    # Scan and map the codebase
agent why src/auth/auth.ts        # Full reasoning trail for a file
agent conflict src/auth/auth.ts codex  # Check if safe to edit

Reporting

agent status          # Full project status
agent replay          # Timeline of all agent actions
agent context         # Generate PROJECT.md, MEMORY.md, ACTIVE_TASKS.md

Memory Categories

AgentOS auto-categorizes memories:

| Category | Icon | Key Patterns | Example | |----------|------|--------------|---------| | Architecture | 🏛 | arch:*, layer*, pattern* | arch:why-microservices | | Decision | ⚖️ | why-*, chose*, decision* | why-jwt | | Bug | 🐛 | bug:*, fix:*, issue* | bug:race-condition-auth | | Task | 📋 | task:*, sprint* | task:q1-goals | | General | 📝 | anything else | redis-config |

Quick Start

Prerequisites

Node.js >= 18
npm or yarn

Installation

# Clone the repository
git clone https://github.com/varaddesai/agentos.git
cd agentos

# Install dependencies
npm install

# Build
npm run build

# Link globally (makes `agent` available everywhere)
npm link

Usage

# Initialize in your project
agent init

# Register agents
agent register claude
agent register codex
agent register cline

# Start coordinating
agent assign auth-refactor claude
agent lock src/auth/auth.ts claude --task auth-refactor --reason "JWT migration"
agent why src/auth/auth.ts
agent replay

The Killer Demo

# 1. Register your agents
agent register claude
agent register codex
agent register cline

# 2. Assign tasks
agent assign auth-refactor claude
agent assign login-ui cline
agent assign tests codex

# 3. Claude locks a file
agent lock src/auth/auth.ts claude --task auth-refactor --reason "JWT migration"

# 4. Codex tries to edit the same file → CONFLICT ⚡
agent lock src/auth/auth.ts codex
# Output:
# ⚡ CONFLICT DETECTED
# File: src/auth/auth.ts
# Current Owner: claude (task: auth-refactor)
# Reason: JWT migration
# Suggested alternative: src/auth/login-ui.ts (owner: cline)

# 5. See the full reasoning trail
agent why src/auth/auth.ts
# Output:
# Modified by: claude
# Reason: JWT migration
# Task: Authentication rewrite
# Date: 2024-01-15 09:01
# Related decisions: why-jwt, arch:auth-layer
# Dependencies: UserRepository, TokenService

# 6. See everything that happened
agent replay
# Output:
# 09:01 claude created AuthService
# 09:10 codex generated tests
# 09:22 cline updated Login UI
# 09:35 ⚡ Conflict detected (claude vs codex on auth.ts)
# 09:36 ✅ Auto-resolution suggested

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        AgentOS Core                          │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  ┌───────────────┐    ┌───────────────┐    ┌─────────────┐ │
│  │ Code Parser   │───▶│ Knowledge     │───▶│   Memory    │ │
│  │ (tree-sitter) │    │   Graph       │    │   Layer     │ │
│  └───────────────┘    │ (SQLite)      │    │ (SQLite)    │ │
│                       └───────────────┘    └─────────────┘ │
│                            │                  │            │
│                            ▼                  ▼            │
│                       ┌───────────────┐    ┌─────────────┐ │
│                       │    Task       │    │  Conflict   │ │
│                       │   Engine      │    │  Detector   │ │
│                       └───────────────┘    └─────────────┘ │
│                                                             │
└─────────────────────────────────────────────────────────────┘
                              │
                              ▼
                       ┌───────────────┐
                       │   Agent CLI   │
                       │  (Commander)  │
                       └───────────────┘
                              │
              ┌───────────────┼───────────────┐
              ▼               ▼               ▼
           Claude          Codex           Cline

Data Storage

~/.agentos/
  agentos.db              ← all agents, tasks, memory, events

your-project/
  .agentos/
    PROJECT.md            ← repo intelligence for agents
    MEMORY.md             ← all decisions and architecture notes
    ACTIVE_TASKS.md       ← who owns what
    AGENTS.md             ← registered agent profiles

Feed the .agentos/ files to your agents at the start of each session.

Tech Stack

| Component | Technology | Purpose | |-----------|-----------|---------| | Runtime | Node.js + TypeScript | Core runtime | | Database | SQLite (sql.js) | Metadata, memory, events | | Parsing | Tree-sitter | Code symbol extraction | | CLI | Commander.js | Command interface | | Output | Chalk + Boxen | Terminal UI | | Future | Neo4j | Knowledge graph queries | | Future | Qdrant | Vector memory search | | Future | OpenRouter | LLM integration |

Documentation

Product Requirements Document (PRD) — What we're building and why
Technical Requirements Document (TRD) — How we're building it
Architecture — System design and components
Flow Diagrams — Data flow and architecture diagrams
Roadmap — Implementation phases and timeline

Roadmap

Phase 1: Repository Intelligence (Weeks 1-2)

[x] Tree-sitter parsing
[x] File graph
[x] Dependency graph
[x] agent map command

Phase 2: Shared Memory (Week 3)

[x] agent remember / agent recall
[x] Memory categorization
[x] Vector search foundation

Phase 3: Task Ownership (Week 4)

[x] agent assign / agent lock / agent unlock
[x] Task tracking
[x] Conflict detection

Phase 4: Knowledge Graph (Weeks 5-6)

[ ] Neo4j integration
[ ] Relationship mapping
[ ] Graph queries

Phase 5: Conflict Prevention (Week 7)

[x] Overlap detection
[ ] Smart suggestions
[ ] Auto-resolution

Phase 6: Context Generation (Week 8)

[x] PROJECT.md generation
[x] MEMORY.md generation
[x] ACTIVE_TASKS.md generation
[ ] AGENTS.md generation

Post-MVP

[ ] agent replay --visual — animated timeline
[ ] Architecture Guardian (auto-detect layer violations)
[ ] VS Code extension
[ ] MCP server
[ ] Real-time agent websocket sync
[ ] OpenRouter LLM integration

Contributing

Contributions are welcome! Please read our Contributing Guide first.

# Fork and clone
git clone https://github.com/xombi17/agentos.git

# Install dependencies
npm install

# Run in dev mode
npm run dev

# Build
npm run build

License

MIT — see LICENSE for details.

Acknowledgments

AgentOS is inspired by the need for better coordination between AI coding agents. Built with tree-sitter, sql.js, and the amazing AI coding community.

Star History

If AgentOS helps your workflow, consider starring the repo!