Random Agent

A powerful MCP server for multi-worker autonomous agent orchestration. Decompose complex tasks, run parallel workers, auto-review, and generate follow-up tasks — all through the Model Context Protocol.

Features

• Parallel Workers — Run up to 5 concurrent AI agent processes

• Task Decomposition — Auto-split complex tasks into subtasks with dependencies

• Auto-Review & Reflection — Coordinator generates reviews and reflections on completed tasks

• Follow-up Generation — Reflections auto-create new tasks for continuous improvement

• 22 Assertion Types — Validate outputs with equals, contains, regex, file-exists, json-path, and more

• Stall Detection — Detect stuck workers, kill them, and auto-retry

• Real-time Monitoring — Live status dashboard with queue counts and worker states

• Metrics Collection — Track scores, issues, and patterns over time

Related MCP server: agent-mcp

Installation

git clone https://github.com/randomchips/random_agent.git
cd random_agent
npm install
npm run build

Usage

Add to your OpenCode config (~/.config/opencode/opencode.jsonc):

{
  "mcp": {
    "random-agent": {
      "type": "local",
      "command": ["node", "/path/to/random_agent/dist/index.js"],
      "enabled": true,
      "environment": {
        "AGENT_OS_BASE_PATH": "C:\\agent-os"
      }
    }
  }
}

Tools

Pipeline Stages

inject → pending → in-progress → completed → review → reflection → follow-up

1. Inject — Task queued in task-queue/pending/

2. Worker — Spawns AI process, executes command

3. Completed — Task moved to task-queue/completed/

4. Review — AI generates review saved to reviews/

5. Reflection — AI generates reflection saved to reflections/

6. Follow-up — New tasks auto-generated for next cycle

Configuration

Environment variables:

Project Structure

random_agent/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript type definitions
│   ├── services/
│   │   ├── assertions.ts     # Assertion engine (22 types)
│   │   ├── coordinator.ts    # Coordinator lifecycle
│   │   ├── decomposer.ts     # Task decomposition
│   │   ├── file-reader.ts    # File system operations
│   │   └── worker-monitor.ts # Worker health monitoring
│   └── tools/
│       ├── assert.ts         # Assert tool
│       ├── handle-stuck.ts   # Handle stuck workers
│       ├── inject.ts         # Inject tasks
│       ├── lifecycle.ts      # Coordinator control
│       ├── logs.ts           # Read logs
│       ├── metrics.ts        # Read metrics
│       ├── orchestrate.ts    # Full orchestration
│       └── status.ts         # System status
├── package.json
├── tsconfig.json
└── README.md

License

MIT

Contributing

Contributions welcome! Open an issue or submit a PR at github.com/randomchips/random_agent.