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

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

Tool	Description
inject	Queue a task with name, command, priority, and optional assertions
orchestrate	Auto-decompose complex task → inject subtasks → monitor → return results
status	Live view: coordinator state, queue counts, active workers
coordinator	Start / stop / restart the background coordinator loop
handle_stuck	Detect stuck workers, kill them, auto-retry failed tasks
assert	Run assertions on task output (22 assertion types)
logs	Read coordinator logs, filter by search term or worker ID
metrics	Read metrics database (scores, issues, patterns)

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:

Variable	Default	Description
AGENT_OS_BASE_PATH	C:\agent-os	Base path for all agent data
AGENT_OS_MAX_WORKERS	5	Max concurrent worker processes
AGENT_OS_LOOP_INTERVAL	5	Coordinator loop interval (seconds)
AGENT_OS_STALL_THRESHOLD	90	Seconds before worker is considered stuck

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.