sahaidachny 0.6.2

Hierarchical task planning and autonomous agentic execution for Claude Code

Sahaidachny

Autonomous AI agent orchestrator for hierarchical task execution in Claude Code and Codex

Installation • Quick Start • How It Works • Documentation

---

Named after Petro Sahaidachny, the legendary Ukrainian Cossack hetman known for strategic planning and decisive execution.

What is Sahaidachny?

Sahaidachny solves a fundamental problem in AI-assisted coding: how to reliably implement complex features that span multiple files, require architectural decisions, and need verification.

It's a Claude Code plugin for planning plus a runner-agnostic execution loop that enables:

• Structured Planning — Build hierarchical task specifications with user stories, design decisions, API contracts, and test specs
• Autonomous Execution — Run agentic loops across multiple context windows that implement, verify, and iterate
• State Persistence — Maintain learnings and progress between iterations, enabling resume after interruption

Why Not Just Prompt Claude?

Aspect	Simple Prompting	Sahaidachny
Task structure	Single prompt	Hierarchical artifacts
Planning	Ad-hoc	Guided workflow
Implementation	One-shot	Iterative with feedback
Verification	Manual	Automated DoD checks
Code quality	Hope for the best	Ruff, ty, complexity checks
State	Lost on context switch	Persisted to disk

Installation

Prerequisites

• Python 3.11+
• Claude Code CLI installed and configured (planning)
• Codex CLI installed and configured (optional for execution)

Install from PyPI (Recommended)

Using pipx (recommended for CLI tools):

pipx install sahaidachny

Using uv:

uv tool install sahaidachny

Using pip:

pip install sahaidachny

Install from Source

For development or latest changes:

git clone https://github.com/roman-romanov-o/sahaidachny.git
cd sahaidachny
uv tool install .

Verify Installation

saha version
saha tools

Quick Start

1. Launch Claude Code with Sahaidachny

saha claude

2. Initialize a Task

# In Claude Code:
/saha:init user-authentication --mode=full

3. Plan the Task

/saha:research      # Explore codebase (for existing projects)
/saha:task          # Define what to build
/saha:stories       # Generate user stories
/saha:verify        # Approve artifacts
/saha:plan          # Create implementation phases

4. Execute Autonomously

# Back in terminal:
saha run task-01

To run execution agents with Codex instead of Claude Code, set:

export SAHA_AGENTS__DEFAULT_RUNNER=codex

Or run a single task with Codex:

saha run task-01 --runner codex

5. Monitor Progress

saha status task-01 --verbose

How It Works

Sahaidachny operates in two phases:

Phase 1: Planning (Interactive)

You work with Claude Code using slash commands to create structured task artifacts:

/saha:init → /saha:research → /saha:task → /saha:stories → /saha:plan

This produces a task folder with:

task-01/
├── task-description.md       # What to build
├── user-stories/             # Requirements with acceptance criteria
├── design-decisions/         # Architecture decisions
├── implementation-plan/      # Phased execution steps
└── test-specs/               # Test specifications

Phase 2: Execution (Autonomous)

The agentic loop runs without intervention:

┌─────────────────┐
│ Implementation  │ ← Write code according to plan
└────────┬────────┘
         ▼
┌─────────────────┐
│       QA        │ ← Verify acceptance criteria
└────────┬────────┘
         │
    DoD achieved? ──No──┐
         │              │
        Yes             │
         ▼              │
┌─────────────────┐     │
│  Code Quality   │     │
└────────┬────────┘     │
         │              │
   Quality passed? ─No──┤
         │              │
        Yes             │
         ▼              ▼
┌─────────────────┐  ┌──────────┐
│    Manager      │  │ fix_info │
└────────┬────────┘  └────┬─────┘
         ▼                │
┌─────────────────┐       │
│   DoD Check     │       │
└────────┬────────┘       │
         │                │
   Task complete? ──No────┘
         │
        Yes
         ▼
      DONE

Each iteration learns from previous failures via fix_info, enabling targeted fixes.

Planning Commands

Command	Purpose
/saha:init	Create task folder structure
/saha:research	Explore codebase patterns
/saha:task	Define task description
/saha:stories	Generate user stories
/saha:decide	Record design decisions
/saha:contracts	Define API contracts
/saha:test-specs	Write test specifications
/saha:plan	Create implementation phases
/saha:verify	Approve artifacts
/saha:status	Show planning progress

Execution Commands

Command	Purpose
saha run <task-id>	Execute task autonomously
saha resume <task-id>	Resume interrupted execution
saha status [task-id]	Check execution status
saha tools	List available quality tools
saha clean [task-id]	Remove execution state
saha claude	Launch Claude Code with plugin

To stop a running loop, press Ctrl+C. Sahaidachny will stop the current agent, run the Manager to update task artifacts, and mark the task as stopped so you can resume later.

Code Quality Tools

The execution loop integrates with:

• Ruff — Fast Python linter
• ty — Fast Python type checker
• complexipy — Cognitive complexity analyzer
• pytest — Test runner

Configuration

Configure via environment variables (prefix: SAHA_) or .env file:

SAHA_MAX_ITERATIONS=15
SAHA_RUNNER=claude
SAHA_TOOL_COMPLEXITY_THRESHOLD=20
SAHA_HOOK_NTFY_ENABLED=true

# Use Codex for execution agents
# SAHA_AGENTS__DEFAULT_RUNNER=codex
# SAHA_CODEX_MODEL=o3
# SAHA_CODEX_DANGEROUSLY_BYPASS_SANDBOX=false
# SAHA_CLAUDE_DANGEROUSLY_SKIP_PERMISSIONS=false

Documentation

• User Guide — Complete usage guide
• Architecture — Developer reference

Status

Alpha — Actively developed. API may change.

License

MIT

---

_{Built for Claude Code planning and multi-runner execution (Claude Code, Codex, Gemini)}