agent-sequencer

agent-sequencer

日本語版 README

An MCP skill + server that lets a Python script drive an AI agent through strictly-defined workflows and long-running tasks.

+--------------+    MCP tool call     +-------------------------------+
|              | -------------------> |       agent-sequencer         |
|   AI Agent   |                      |     (MCP stdio server)        |
| (Claude Code)| <------------------- |                               |
|              |    yield Instruction |  +-------------------------+  |
+------+-------+                      |  |   Sequencer Program     |  |
       |                              |  |   (Python generator)    |  |
       | step execution via own tools |  |   branching / control   |  |
       | (Bash / Edit / Skill / ...)  |  +-------------------------+  |
       v                              |                               |
     User                             |  +-------------------------+  |
                                      |  |   JSONL event log       |  |
                                      |  |   (deterministic replay)|  |
                                      |  +-------------------------+  |
                                      +-------------------------------+

Architecture overview

• Sequencer program: a classical program written as a Python generator. Workflow branching, aggregation, and termination logic stay inside the program.
• Step boundary: each yield Instruction(...) in the program is one step. It declares an instruction text plus a JSON Schema for the response; the AI agent executes the instruction with its own tools (Bash / Edit / Skill / ...) and returns the result as JSON.
• Deterministic replay: every event is appended to a JSONL log; after a server restart, an interrupt, or a context compaction, the program is fully recoverable by re-running it from the start and re-injecting the recorded inputs.

Because guardrails live in code rather than in prompts, the system stays stable as conversation context degrades over long-running tasks.

• Supported editors: Claude Code
• Language / runtime: Python ≥ 3.11
• Distribution: Claude Code plugin (git-based)
• License: MIT

---

Features

• Author your own sequencer program in Python — keep workflow branching, aggregation, and termination logic in code, and delegate per-step execution to the AI agent. Author's guide: docs/authoring-programs.md.
• Invoke it from an AI agent (Claude Code) via MCP tools — sequencer_list_programs to discover, sequencer_start to launch, sequencer_next to submit a result, sequencer_resume to recover an interrupted instance. Full tool list: skills/agent-sequencer/README.md
• Stable execution of long-running workflows — every step's response is validated against a JSON Schema with automatic retry on violation; interruptions and post-compact desyncs recover via deterministic replay of a JSONL event log; --watch hot-reloads program edits during development.

For details, see SKILL.md (driving rules) and the program author's guide.

For your own programs, the bundled review-rounds program (three specialist agents review → fix → verify in parallel) is available as a self-review helper — and as a sample implementation to crib from.

---

Installation

Prerequisites

• uv (used to run the MCP server). If not yet installed:

  # Windows (PowerShell)
  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

  # macOS / Linux
  curl -LsSf https://astral.sh/uv/install.sh | sh
  

Option A: Install as a Claude Code plugin (recommended)

/plugin marketplace add OPENSPHERE-Inc/agent-sequencer
/plugin install agent-sequencer@agent-sequencer

This sets up the skill, the bundled programs, and the MCP server automatically. The plugin's .mcp.json invokes uv run via ${CLAUDE_PLUGIN_ROOT} and passes the bundled programs/ to the MCP server through AGENT_SEQUENCER_PROGRAMS_DIR.

Option B: Clone and use as a developer

git clone https://github.com/OPENSPHERE-Inc/agent-sequencer.git
cd agent-sequencer
uv sync
uv run agent-sequencer --help

If you launch Claude Code with this directory as cwd, the repository's bundled .mcp.json and skills/agent-sequencer/ are loaded. The ${CLAUDE_PLUGIN_ROOT} variable is only expanded inside the Claude Code plugin context, so for development you need to either create a separate .claude/.mcp.json or set the relevant environment variables (see Development setup).

---

Quick start