Where is the state file located?

The skill targets the .claude/marathon-ralph.json file located in your project directory.

Does this skill increase my token usage?

No, it executes via Bash scripts locally, meaning the state file doesn't need to be loaded into the Claude context to perform updates.

What phases are supported by the set-phase command?

The supported phases are setup, init, coding, and complete, allowing you to track the high-level progress of your marathon.

Why should I use this instead of editing the JSON file manually?

Manual edits are prone to syntax errors and race conditions. This skill ensures atomic, deterministic updates using jq, which maintains the integrity of the marathon-ralph state.

Marathon Ralph State Manager

Name: Marathon Ralph State Manager
Author: gruckion

bygruckion

Productivity & Workflow

Automates the update of state files for Claude Code marathons using deterministic jq commands.

About

The update-state skill provides a robust, scriptable interface for managing the execution state of Claude Code marathons within the marathon-ralph framework. By utilizing deterministic bash scripts and jq, it eliminates the risks associated with manual JSON editing, ensuring that state transitions—such as starting or completing issues, switching phases, and updating progress stats—are atomic, safe, and consistent. This skill is essential for maintaining accurate project tracking without increasing token context overhead, making it ideal for long-running autonomous development tasks.

Key Features

Automated phase management for setup, init, coding, and completion
Atomic operations for starting and completing development issues
0 GitHub stars
Deterministic state updates via jq to prevent JSON corruption
Zero token overhead by executing scripts outside the LLM context
Session management tools for handling agent takeovers and force resets

Use Cases

Updating marathon progress after successfully completing a coding task
Resetting session IDs to allow manual takeover of an AI agent's workflow
Transitioning between project phases during automated development cycles

About

Key Features

Automated phase management for setup, init, coding, and completion
Atomic operations for starting and completing development issues
0 GitHub stars
Deterministic state updates via jq to prevent JSON corruption
Zero token overhead by executing scripts outside the LLM context
Session management tools for handling agent takeovers and force resets

Use Cases

Updating marathon progress after successfully completing a coding task
Resetting session IDs to allow manual takeover of an AI agent's workflow
Transitioning between project phases during automated development cycles