devs

Imported from codename-co/devs (AGENTS.md). Install upstream with npx skills add codename-co/devs. Copyright stays with the author.

DEVS - AI Agent Orchestration Platform

The Web as the runtime for agentic AI. Open your browser and start delegating.

What DEVS Is

An open-source, browser-native platform that lets anyone delegate complex tasks to a swarm of AI agents — without servers, without subscriptions, without surrendering data.

• Delegate, don't chat. Users describe a goal; the system analyzes complexity, assembles a purpose-built team, decomposes work, and delivers structured output.
• Bring Your Own Model. 12+ LLM backends — cloud APIs, self-hosted endpoints, local in-browser inference.
• Privacy by architecture. All data stays on-device. Yjs CRDTs handle the data layer; Web Crypto encrypts credentials. No telemetry unless the user opts in.
• Swarm intelligence. Agents have roles, tools, memories, and knowledge bases. The orchestrator routes by complexity tier.
• Extensible. A marketplace of apps, agents, connectors, and tools — YAML-defined, sandboxed in iframes.

Live: devs.new | Repository: github.com/codename-co/devs | License: MIT

Documentation

Detailed documentation lives in docs/:

Additional deep-dives in docs/more/:

Technical Stack

Key Features

LLM Provider Independence

BYOK (Bring Your Own Key) support for 12+ providers behind a unified LLMProviderInterface:

Tool calling uses the OpenAI function-calling format as canonical schema. Streaming, multimodal attachments (image/document/text), and extended thinking are supported.

Agent System

• AI Studio — Create, edit, configure custom agents with roles, instructions, temperature, tags, tools, and knowledge base
• Built-in agents — Ship as JSON; custom agents stored in Yjs
• Agent memory — LLM-powered extraction from conversations, human review workflow (approve/reject/edit), context injection into future conversations
• Agent portraits — AI-generated
• Skills — Installable capability bundles (tools + instructions)

Multi-Agent Orchestration

The orchestrator lives in src/lib/orchestrator/ and uses a strategy pattern:

Flow: User prompt -> TaskAnalyzer (LLM-powered complexity assessment) -> Tier 0 (single agent) or Tier 1+ (multi-agent with decomposition, dependency resolution, parallel execution, synthesis).

Methodology templates: 8D, A3, Agile, AOSTC, DMAIC, PDCA, Scrum, YOLO.

Tool System

Self-registering plugins in src/tools/:

Connectors

OAuth 2.0 PKCE integrations in src/features/connectors/:

• Google Drive, Gmail, Google Calendar, Google Tasks, Google Meet, Google Chat
• Notion, Slack, Figma, Dropbox, OneDrive, Outlook, Qonto

Knowledge Base

File upload, folder watching (File System Access API), SHA-256 deduplication, background sync. Supports text, image, and document files (PDF, DOCX, XLSX, PPTX, CSV).

Collaboration

• P2P sync via WebRTC and WebSocket relay (Yjs)
• Password-protected rooms
• QR code sharing
• CRDT-based automatic conflict resolution

Spaces

Multi-workspace isolation. Every space-scoped entity carries spaceId?: string. Per-space settings overrides. See docs/more/SPACES.md.

Project Structure

src/
  app/            App shell, providers, router, initialization
  components/     Shared UI components
  config/         Product constants, API endpoints
  features/       Independent feature modules (connectors, marketplace, studio, traces, sync, etc.)
  hooks/          Shared custom React hooks
  i18n/           Translations and language utilities
  layouts/        Page layout templates
  lib/            Business logic, services, utilities
  pages/          Route-level page components
  stores/         Zustand stores (Yjs-backed)
  styles/         Global CSS, Tailwind config
  test/           Test files (mirrors src/ structure)
  tools/          Tool plugin definitions
  types/          Shared TypeScript type definitions
  workers/        Web Worker scripts

Features in src/features/ are self-contained: they may import from src/lib/, src/stores/, and src/types/ but never from other features.

Data Layer

Yjs-First Architecture

Yjs is the single source of truth. All persistent data lives in typed Y.Map instances within one Y.Doc. Stores are thin wrappers that provide write functions and reactive read hooks.

// Write: direct Yjs mutation
export function createAgent(data: AgentData): Agent {
  const agent = { ...data, id: nanoid(), createdAt: new Date() }
  agents.set(agent.id, agent)
  return agent
}

// Read: reactive hook observing Y.Map
export function useAgents(): Agent[] {
  return useLiveMap(agents).filter(a => !a.deletedAt)
}

Soft delete everywhere (deletedAt?: Date). Read hooks filter out deleted entities.

Data Maps

Key Yjs maps: agents, conversations, tasks, artifacts, memories, workflows, sessions, studioEntries, traces, spans, preferences, credentials, connectors, skills, spaces, threadTags (20+ maps total).

Data Schema

Data types are defined in src/types/index.ts.

interface Agent {
  id: string
  slug: string
  name: string
  icon?: IconName
  role: string
  instructions: string
  temperature?: number
  tags?: string[]
  tools?: Tool[]
  createdAt: Date
  updatedAt?: Date
  version?: string
}

interface Task {
  id: string
  workflowId: string
  title: string
  description: string
  complexity: 'simple' | 'complex'
  status: 'pending' | 'in_progress' | 'completed' | 'failed'
  assignedAgentId?: string
  parentTaskId?: string
  dependencies: string[]
  requirements: Requirement[]
  artifacts: string[]
  steps: TaskStep[]
  createdAt: Date
  updatedAt: Date
  completedAt?: Date
}

interface Conversation {
  id: string
  agentId: string
  participatingAgents: string[]
  workflowId: string
  timestamp: Date
  updatedAt: Date
  messages: Message[]
  title?: string
  isPinned?: boolean
  summary?: string
}

interface KnowledgeItem {
  id: string
  name: string
  type: 'file' | 'folder'
  fileType?: 'document' | 'image' | 'text'
  content?: string
  contentHash?: string
  path: string
  lastModified: Date
  createdAt: Date
  tags?: string[]
}

interface Artifact {
  id: string
  taskId: string
  agentId: string
  type: string
  description: string
  content: string
  status: 'pending' | 'completed'
  validates?: string[]
  createdAt: Date
}

State Management

Yjs-backed Zustand stores:

All stores follow the same pattern: direct Yjs writes, reactive hooks via useLiveMap/useLiveValue, error handling with toast notifications.

Development

Commands

npm run dev          # Start development server
npm run build        # Build for production
npm run lint         # Run linting
npm run typecheck    # Type checking
npm run test:run     # Run all unit tests once
npm run test:watch   # Tests in watch mode (recommended during development)
npm run test:coverage # Tests with coverage report
npm run test:e2e     # Run E2E tests

TDD Mandate

All new code in src/lib/ and src/stores/ must follow TDD:

1. Red — Write a failing test
2. Green — Minimal code to pass
3. Refactor — Clean up, keep tests green
4. Verify — npm run test:coverage

Coverage Targets

Design Principles

1. Accessibility first — Works on 2GB RAM devices. Multi-language. Keyboard navigable. Screen reader compatible.
2. Privacy by design — Data never leaves the client unless the user connects P2P sync or an external connector.
3. Progressive disclosure — A single prompt area by default. Complexity revealed as needed.
4. Real-time transparency — Users see the orchestration trace.
5. Graceful degradation — Offline-capable. Missing providers handled. Tool failures don't crash workflows.

Internationalization (i18n) Guidelines

When working with translation strings, apostrophes must use ' instead of '. All user-facing strings go through the i18n system. Supported languages: English, French, German, Spanish, Arabic, Korean.

AI Agent Guidelines

Context7 MCP for Documentation

Always use Context7 MCP automatically when working on tasks that involve:

• Library or framework API documentation
• Code generation with external dependencies
• Setup or configuration steps for tools/packages
• Implementation patterns for React, Vite, Zustand, Playwright, HeroUI, or other project dependencies

This ensures accurate, up-to-date documentation is referenced without requiring explicit requests.