> ## Content Index > Fetch the complete content index at: https://www.stirup.si/llms.txt > Use this file to discover other available public pages before exploring further. # Stepbook: Managing Long-Horizon Agent Tasks with Modular Steps - URL: https://www.stirup.si/stepbook-managing-long-horizon-agent-tasks-with-modular-steps-d095022d/ - Published: 2026-10-13T12:55:06.000Z - Updated: 2026-10-13T12:55:06.000Z - Description: Stepbook is useful for tasks requiring sequential steps with clear completion criteria, such as test suite execution, service migration, and documentation updates, but not for open-ended or real-time tasks. - Author: Satish Das - Tags: Community, News, Stirup Research ## Use Cases for Stepbook Stepbook is particularly useful for tasks that require an agent to perform a sequence of steps with clear completion criteria. It is well-suited for scenarios such as running a test suite after a framework upgrade, where each test must pass, or migrating services while ensuring each one remains functional. It is also effective for managing long lists of items that require specific actions, such as updating documentation pages or triaging evaluation failures. Additionally, Stepbook can be used when tracking measurable outcomes, such as evaluating accuracy, latency, or cost per case. However, it is not ideal for open-ended tasks with no clear endpoint, like cleaning up a module, or for short tasks that are being monitored in real time, where a standard agent chat would be more appropriate. To get started, plan one step per unit of work, such as fixing a test file or migrating a service, and begin with a small number of steps before increasing the limit based on progress. ## How Stepbook Operates Stepbook operates by breaking long agent tasks into discrete steps, each handled by a fresh instance of the agent's CLI. For every step, Stepbook initializes the agent with the current skill, state, and latest result, then collects one state update and one action before ending the session. Only `state.json` and the journal are carried over between steps, ensuring that each new step begins with a clean slate except for essential data. This design means the prompt size depends on the state rather than the number of prior steps, allowing any agent capable of reading the run folder to resume the task seamlessly. This approach enables efficient, modular execution of complex workflows while maintaining state continuity. ## Implementation and Safety Features Implementation and Safety Features of Stepbook emphasize controlled execution and state management. Outside a container, a run refuses to start unless the environment variable `STEPBOOK_SANDBOX=1` is set or the flag `--unsandboxed-i-accept-the-risk` is passed, ensuring user awareness of potential risks. Each step operates as a fresh session, reading only the current state rather than the full history, which helps maintain performance and memory efficiency, as noted in the implementation details. Stepbook is an independent implementation inspired by the research paper *"SKILL.state: Scalable Long-Horizon Agent Skills"* by Sanket Badhe, Priyanka Tiwari, and Jonghyun Chung (arXiv:2608.26263, [https://arxiv.org/abs/2608.26263](https://arxiv.org/abs/2608.26263?ref=stirup.si)), which outlines the foundational concept of managing long-horizon agent tasks through modular steps. ## Custom Skill Creation and Usage Custom skill creation in Stepbook allows users to define and manage long-running agent tasks as modular, reusable components. To create a custom skill, users can either invoke Stepbook with a command like `run my eval-triage skill with stepbook` or manually convert an existing skill using the command `stepbook author ./eval-triage-state --from .claude/skills/eval-triage`. This process generates a new folder containing the original `SKILL.md` file, along with a state schema and initial state, without modifying the source folder. Once created, the skill can be launched by specifying its folder path in place of a skill name, such as `stepbook run ./eval-triage-state`. Additionally, Stepbook supports resuming tasks from a previous run using `stepbook run --resume --executor codex`, ensuring continuity and enabling collaboration between agents. ## Installation and Execution Installation of Stepbook involves following the guide at [https://raw.githubusercontent.com/bahdan111/stepbook/main/docs/install-for-agents.md](https://raw.githubusercontent.com/bahdan111/stepbook/main/docs/install-for-agents.md?ref=stirup.si) to set up the tool for use with coding agents. For users working in a shell environment, the process includes adding the Stepbook plugin to Codex via the command `codex plugin marketplace add bahdan111/stepbook`, followed by `codex plugin add stepbook@stepbook-plugins`. Alternatively, the CLI can be installed using `uv tool install stepbook`, which allows plugins to call Stepbook directly or through `uvx` if it is not installed this way. Once installed, users can manage tasks with commands like `stepbook status`, `stepbook say "Do not change the tests"`, `stepbook pause`, and `stepbook run --resume --steps 60`. The `status` command provides details on the current task progress, including the checklist and the exact resume command. ## Sources and reporting notes - [Hacker News Show](https://github.com/bahdan111/stepbook?ref=stirup.si) Based on published source material. No independent hands-on testing is claimed.