https://github.com/marc-shade/agent-runtime-mcp

Persistent task queues and goal decomposition for cross-session AGI autonomy.
https://github.com/marc-shade/agent-runtime-mcp
agi ai-agents ai-tools anthropic claude claude-code goals mcp model-context-protocol task-queue
Last synced: 3 months ago
JSON representation
Persistent task queues and goal decomposition for cross-session AGI autonomy.
Host: GitHub
URL: https://github.com/marc-shade/agent-runtime-mcp
Owner: marc-shade
Created: 2025-11-29T17:15:24.000Z (7 months ago)
Default Branch: main
Last Pushed: 2026-02-22T01:36:22.000Z (4 months ago)
Last Synced: 2026-04-05T22:38:39.908Z (3 months ago)
Topics: agi, ai-agents, ai-tools, anthropic, claude, claude-code, goals, mcp, model-context-protocol, task-queue
Language: Python
Size: 82 KB
Stars: 0
Watchers: 0
Forks: 0
Open Issues: 0
Metadata Files:
- Readme: README.md
Awesome Lists containing this project

README

          # Agent Runtime MCP

Persistent task queues and goal decomposition for cross-session AGI autonomy with God Agent integration.

## Description

Agent Runtime MCP provides persistent task management that survives across sessions, enabling true autonomous AGI workflows. Features include:

- **Persistent Goals & Tasks**: SQLite-backed storage that survives restarts

- **AI-Powered Goal Decomposition**: Break complex goals into executable tasks

- **Dependency Management**: Automatic task ordering based on dependencies

- **Priority Queuing**: Intelligent task scheduling by priority and readiness

- **Relay Race Protocol** (God Agent Phase 2): 48-agent pipelines with structured handoffs

- **Circuit Breaker** (God Agent Phase 5): Fault tolerance with automatic fallback

- **Cross-Session Continuity**: Resume work exactly where you left off

## Installation

### Using pip

```bash

git clone https://github.com/marc-shade/agent-runtime-mcp

cd agent-runtime-mcp

pip install -r requirements.txt

```

### Using uv (recommended)

```bash

git clone https://github.com/marc-shade/agent-runtime-mcp

cd agent-runtime-mcp

uv pip install -r requirements.txt

```

### Dependencies

```bash

pip install anthropic-mcp

```

## Configuration

Add to `~/.claude.json`:

```json

{

  "mcpServers": {

    "agent-runtime": {

      "command": "python3",

      "args": [

        "/absolute/path/to/agent-runtime-mcp/server.py"

      ]

    }

  }

}

```

## Tools

### Core Goal & Task Management (9)

| Tool | Description |

|------|-------------|

| `create_goal` | Create high-level goal with name and description |

| `decompose_goal` | Use AI to break goal into tasks (sequential/parallel/hierarchical) |

| `create_task` | Manually create task with dependencies |

| `get_next_task` | Get next ready task from queue (highest priority, deps met) |

| `update_task_status` | Update status (pending/in_progress/completed/failed/cancelled) |

| `list_goals` | List all goals, optionally filtered by status |

| `list_tasks` | List tasks by goal, status, with limit |

| `get_goal` | Get goal details by ID |

| `get_task` | Get task details by ID |

### Relay Race Protocol (God Agent Phase 2) (6)

| Tool | Description |

|------|-------------|

| `create_relay_pipeline` | Create 48-agent relay race with baton passing |

| `get_relay_status` | Get pipeline status (progress, quality scores) |

| `advance_relay` | Pass baton to next agent after completing step |

| `retry_relay_step` | Retry failed step without restarting pipeline |

| `list_relay_pipelines` | List pipelines by status |

| `get_relay_baton` | Get current baton with context for next agent |

### Circuit Breaker (God Agent Phase 5: Tiny Dancer) (7)

| Tool | Description |

|------|-------------|

| `circuit_breaker_status` | Get breaker state (CLOSED/OPEN/HALF_OPEN) |

| `circuit_breaker_list` | List all breakers with open/degraded circuits |

| `circuit_breaker_trip` | Manually trip breaker to OPEN state |

| `circuit_breaker_reset` | Reset breaker to CLOSED state |

| `circuit_breaker_configure` | Configure thresholds (failures, window, cooldown) |

| `circuit_breaker_record_failure` | Record failure for tracking |

| `circuit_breaker_record_success` | Record success (helps recovery) |

## Usage Examples

### Basic Goal Creation

```python

# Create goal

goal = mcp__agent-runtime__create_goal({

    "name": "Build REST API",

    "description": "Create RESTful API for user authentication with JWT tokens",

    "metadata": {"priority": "high", "project": "auth-service"}

})

# Returns: {"id": 1, "name": "Build REST API", "status": "active", ...}

```

### AI Goal Decomposition

```python

# Decompose goal into tasks (sequential strategy)

result = mcp__agent-runtime__decompose_goal({

    "goal_id": 1,

    "strategy": "sequential"

})

# Returns: {

#   "goal_id": 1,

#   "strategy": "sequential",

#   "tasks_created": [101, 102, 103, 104, 105],

#   "count": 5

# }

# Tasks: Research → Plan → Implement → Test → Document (with dependencies)

```

### Parallel Decomposition

```python

# Decompose for parallel execution

result = mcp__agent-runtime__decompose_goal({

    "goal_id": 1,

    "strategy": "parallel"

})

# Creates: Backend, Frontend, Testing tasks (no dependencies, run simultaneously)

```

### Hierarchical Decomposition

```python

# Decompose into phases

result = mcp__agent-runtime__decompose_goal({

    "goal_id": 1,

    "strategy": "hierarchical"

})

# Creates: Phase 1 (Foundation) → Phase 2 (Core) → Phase 3 (Integration) → Phase 4 (Optimization)

```

### Task Queue Processing

```python

# Get next ready task

task = mcp__agent-runtime__get_next_task()

# Returns: Highest priority task with all dependencies met

# {"id": 101, "title": "Research requirements...", "priority": 10, ...}

# Start work

mcp__agent-runtime__update_task_status({

    "task_id": 101,

    "status": "in_progress"

})

# Complete task

mcp__agent-runtime__update_task_status({

    "task_id": 101,

    "status": "completed",

    "result": "Requirements documented in docs/api-spec.md"

})

# Get next (automatically handles dependencies)

next_task = mcp__agent-runtime__get_next_task()

# Returns: Task 102 (Plan approach) since Research (101) is complete

```

### Manual Task Creation with Dependencies

```python

# Create task with explicit dependencies

mcp__agent-runtime__create_task({

    "goal_id": 1,

    "title": "Deploy to production",

    "description": "Deploy authentication service",

    "priority": 7,

    "dependencies": [103, 104]  # Wait for Implementation and Testing

})

```

### Relay Race Pipeline (48-Agent)

```python

# Create relay pipeline for complex workflow

pipeline = mcp__agent-runtime__create_relay_pipeline({

    "name": "Research Paper Analysis",

    "goal": "Extract insights from 10 AGI papers",

    "agent_types": [

        "researcher",      # Gather papers

        "analyzer",        # Extract key points

        "synthesizer",     # Find patterns

        "validator",       # Check quality

        "formatter"        # Create report

    ],

    "token_budget": 100000

})

# Returns: {"pipeline_id": "rp_abc123", "agent_count": 5, ...}

# Check pipeline status

status = mcp__agent-runtime__get_relay_status({

    "pipeline_id": "rp_abc123"

})

# Returns: {

#   "current_step": 2,

#   "total_steps": 5,

#   "status": "in_progress",

#   "quality_scores": [0.92, 0.88, ...],

#   "tokens_used": 24531

# }

# Get current baton (context for next agent)

baton = mcp__agent-runtime__get_relay_baton({

    "pipeline_id": "rp_abc123"

})

# Returns: {

#   "baton": {...},

#   "prompt": "You are the Synthesizer. Previous output: ..."

# }

# Advance to next step

mcp__agent-runtime__advance_relay({

    "pipeline_id": "rp_abc123",

    "quality_score": 0.88,

    "l_score": 0.85,

    "output_entity_id": 456,

    "tokens_used": 8234,

    "output_summary": "Found 3 key patterns across papers"

})

# Retry failed step

mcp__agent-runtime__retry_relay_step({

    "pipeline_id": "rp_abc123",

    "step_index": 2

})

```

### Circuit Breaker (Fault Tolerance)

```python

# Check agent circuit breaker status

status = mcp__agent-runtime__circuit_breaker_status({

    "agent_id": "researcher_agent"

})

# Returns: {

#   "agent_id": "researcher_agent",

#   "state": "CLOSED",

#   "failure_count": 0,

#   "success_count": 42

# }

# Record failure

mcp__agent-runtime__circuit_breaker_record_failure({

    "agent_id": "researcher_agent",

    "failure_type": "timeout",

    "error_message": "API request timed out after 30s"

})

# List all circuit breakers

breakers = mcp__agent-runtime__circuit_breaker_list()

# Returns: {

#   "total_breakers": 10,

#   "open_circuits": ["failing_agent_1", "failing_agent_2"],

#   "half_open_circuits": ["recovering_agent"],

#   "breakers": [...]

# }

# Configure thresholds

mcp__agent-runtime__circuit_breaker_configure({

    "agent_id": "researcher_agent",

    "failure_threshold": 5,

    "window_seconds": 60,

    "cooldown_seconds": 300,

    "fallback_agent": "generalist"

})

# Manually trip (emergency stop)

mcp__agent-runtime__circuit_breaker_trip({

    "agent_id": "researcher_agent",

    "reason": "Manual intervention - debugging required"

})

# Reset after fix

mcp__agent-runtime__circuit_breaker_reset({

    "agent_id": "researcher_agent"

})

```

### Cross-Session Resume

```python

# Session 1: Create goal and start work

goal = mcp__agent-runtime__create_goal({"name": "Big Project", ...})

mcp__agent-runtime__decompose_goal({"goal_id": goal["id"]})

task1 = mcp__agent-runtime__get_next_task()

mcp__agent-runtime__update_task_status({"task_id": task1["id"], "status": "in_progress"})

# [Close Claude Code, restart later]

# Session 2: Resume exactly where left off

pending = mcp__agent-runtime__list_tasks({"status": "in_progress"})

# Returns: [task1] - still marked as in_progress

task1_updated = mcp__agent-runtime__update_task_status({

    "task_id": task1["id"],

    "status": "completed"

})

next_task = mcp__agent-runtime__get_next_task()

# Automatically gets task2 (next in dependency chain)

```

## Requirements

- **Python**: 3.10+

- **Dependencies**: `anthropic-mcp` (MCP SDK)

- **Storage**: `~/.claude/agent_runtime.db` (SQLite)

## Database Schema

Tables in `~/.claude/agent_runtime.db`:

- `goals` - High-level goals with status and metadata

- `tasks` - Individual tasks with dependencies, priority, results

- `task_queue` - Queue position and scheduling info

- `relay_pipelines` - Relay race pipeline definitions (God Agent Phase 2)

- `relay_batons` - Baton state for pipeline steps

- `circuit_breakers` - Circuit breaker state and history (God Agent Phase 5)

## Decomposition Strategies

### Sequential

```

Task 1 → Task 2 → Task 3 → Task 4 → Task 5

```

Each task depends on previous. Linear execution.

### Parallel

```

Task 1 (Backend)  ─┐

Task 2 (Frontend) ─┼─→ All run simultaneously

Task 3 (Testing)  ─┘

```

No dependencies. Maximum parallelism.

### Hierarchical

```

Phase 1 (Foundation)

  ↓

Phase 2 (Core Implementation)

  ↓

Phase 3 (Integration)

  ↓

Phase 4 (Optimization)

```

Large phases that can be further decomposed.

## Testing

```bash

# Run test suite

python3 test_agent_runtime.py

# Test relay protocol

python3 test_relay_protocol.py

# Test circuit breaker

python3 test_circuit_breaker.py

```

## God Agent Integration

### Phase 2: Relay Race Protocol

- 48-agent sequential pipelines

- Structured baton passing with context

- Quality gates at each step

- L-Score tracking for output quality

- Single-step retry (no full restart)

### Phase 5: Circuit Breaker (Tiny Dancer)

- Automatic failure detection

- State machine: CLOSED → OPEN → HALF_OPEN → CLOSED

- Configurable thresholds and cooldowns

- Fallback agent routing

- Recovery monitoring

## Links

- GitHub: https://github.com/marc-shade/agent-runtime-mcp

- Issues: https://github.com/marc-shade/agent-runtime-mcp/issues
ecosyste.ms

Data

Tools

Indexes

Applications

Experiments

Awesome

https://github.com/marc-shade/agent-runtime-mcp

Awesome Lists containing this project

README
