TL;DR

StateM은 장시간 실행되는 AI agent의 작업 절차를 YAML 상태 graph와 CLI로 관리하는 독립형 Python 도구이다. agent는 현재 상태의 prompt를 읽고 합법적인 전이를 조회한 뒤 checklist, shell command, predicate, manual approval 또는 LLM review를 통과해야 다음 상태로 이동한다. 전이 기록과 검사 결과는 runtime state에 저장되고 prompt·compact-prompt·recovery node가 context refresh 이후의 재개를 지원한다. Python 3.11 이상과 Apache-2.0 license를 사용하며 Core runtime dependency가 없고, Codex와 Claude Code 연동도 제공한다. 복잡한 coding agent나 Terminal-Bench처럼 검증·복구·handoff가 필요한 long-running 작업에는 적합하지만, 단순한 단발성 script에는 상태 graph와 runbook 작성 비용이 추가된다.

핵심 포인트

• StateM은 Python 3.11 이상에서 동작하는 독립형 CLI 도구이자 AI agent용 상태 machine runbook이다. YAML로 상태·전이·검증 조건을 정의하고 shell command를 실행할 수 있어 특정 agent framework에 종속되지 않는다. Codex skill과 Claude Code adapter도 제공하므로 해당 생태계에서 long-running 작업을 연결하기 쉽다.
• 긴 agent 실행에서 계획과 진행 상황이 대화 기록에만 남는 문제를 runbook과 runtime history로 분리한다. 각 상태의 before_transfer 검사와 전이 조건을 순서대로 실행하고 실패하면 현재 상태에 머문다. 상태·전이·검사 결과·증거·timestamp·spec identity를 파일에 보존해 context refresh 뒤에도 작업을 재개할 수 있다.
• checklist·command·predicate·manual·LLM review와 task별 dynamic check를 지원한다. 전이는 outgoing edge 확인부터 현재 상태 검사, dynamic check, condition, hook 실행, 기록 저장까지 transaction 순서로 처리된다. pytest 같은 결정적 검사를 전이 gate로 묶을 수 있어 구현과 검증을 한 흐름 안에서 강제한다.
• 프로젝트에는 coding-agent 예제, Codex·Claude Code 연동, Harbor·Terminal-Bench용 runbook과 recovery prompt 기능이 포함된다. Core package는 runtime dependency가 없고 Apache-2.0 license를 사용한다. Terminal-Bench 2.1에서 GPT-5.5 xhigh + StateM 92.1%, GPT-5.6 Sol xhigh + frozen profile 95.28% raw가 기록됐지만 이는 base model이 아닌 system-level 결과다.

벤치마크

이미지 분석