20x: Instructions file for Codex

AGENTS.md — Multi-Agent Architecture (Implemented)

This document describes the production multi-agent system powering 20x. The architecture spans three agent backends, a centralized polling coordinator, skill management, auto-triage, secret management, heartbeat monitoring, and enterprise sync.

Overview

20x supports running multiple AI coding agents in parallel, each working on assigned tasks within specific codebases. Agents are managed through adapter interfaces and interact with users via streaming transcripts with human-in-the-loop (HITL) approval flows. Three backend adapters are supported: OpenCode SDK, Claude Code, and Codex (ACP).

Agent Model

Each agent is a persistent configuration stored in SQLite:

interface AgentRecord {
  id: string                    // cuid2
  name: string                  // e.g. "Backend Agent", "Frontend Agent"
  server_url: string            // Default: 'http://localhost:4096'
  config: AgentConfigRecord     // stored as JSON
  is_default: boolean           // one agent is pre-seeded on first launch
  created_at: string
  updated_at: string
}

interface AgentConfigRecord {
  coding_agent?: 'opencode' | 'claude-code' | 'codex'
  model?: string
  auth_method?: 'subscription' | 'api_key'
  permission_mode?: 'ask' | 'allow'
  system_prompt?: string
  mcp_servers?: Array<string | AgentMcpServerEntry>
  skill_ids?: string[]
  secret_ids?: string[]
  api_keys?: {
    openai?: string
    anthropic?: string
  }
}

interface AgentMcpServerEntry {
  serverId: string
  enabledTools?: string[]
}

A default agent is seeded on first launch with sensible defaults.

Database Schema

CREATE TABLE agents (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  server_url TEXT NOT NULL DEFAULT 'http://localhost:4096',
  config TEXT NOT NULL DEFAULT '{}',
  is_default INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

-- Tasks table has agent_id for assignment:
ALTER TABLE tasks ADD COLUMN agent_id TEXT REFERENCES agents(id) ON DELETE SET NULL;

-- Skills table stores reusable instructions:
CREATE TABLE skills (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT NOT NULL,
  content TEXT NOT NULL,
  version INTEGER NOT NULL DEFAULT 1,
  confidence REAL NOT NULL DEFAULT 0.5,
  uses INTEGER NOT NULL DEFAULT 0,
  last_used TEXT,
  tags TEXT NOT NULL DEFAULT '[]',
  is_deleted INTEGER NOT NULL DEFAULT 0,
  enterprise_skill_id TEXT DEFAULT NULL,
  uses_at_last_sync INTEGER NOT NULL DEFAULT 0,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

-- Secrets table for encrypted env vars:
CREATE TABLE secrets (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  description TEXT NOT NULL DEFAULT '',
  env_var_name TEXT NOT NULL UNIQUE,
  value BLOB NOT NULL,
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);

-- MCP servers table:
CREATE TABLE mcp_servers (
  id TEXT PRIMARY KEY,
  name TEXT NOT NULL,
  type TEXT NOT NULL DEFAULT 'local',
  command TEXT NOT NULL DEFAULT '',
  args TEXT NOT NULL DEFAULT '[]',
  url TEXT,
  headers TEXT NOT NULL DEFAULT '{}',
  environment TEXT NOT NULL DEFAULT '{}',
  tools TEXT NOT NULL DEFAULT '[]',
  oauth_metadata TEXT NOT NULL DEFAULT '{}',
  source TEXT NOT NULL DEFAULT 'user',
  created_at TEXT NOT NULL,
  updated_at TEXT NOT NULL
);