by hardness1020
A workflow-driven AI agent framework that executes YAML-defined decision trees. Bridging rigid automation and unpredictable agents
# Add to your Claude Code skills
git clone https://github.com/hardness1020/LeewayLast scanned: 5/30/2026
{
"issues": [],
"status": "PASSED",
"scannedAt": "2026-05-30T16:58:57.400Z",
"npmAuditRan": true,
"pipAuditRan": true
}Leeway is an open-source ai agents skill for AI coding assistants such as Claude Code, Codex CLI, and ChatGPT, built by hardness1020. A workflow-driven AI agent framework that executes YAML-defined decision trees. Bridging rigid automation and unpredictable agents. It has 104 GitHub stars.
Yes. Leeway passed SkillsLLM's automated security scan — a dependency vulnerability audit plus prompt-injection heuristics — with no high-severity issues. You can read the full report in the Security Report section on this page.
Clone the repository with "git clone https://github.com/hardness1020/Leeway" and add it to your Claude Code skills directory (see the Installation section above).
Leeway is primarily written in Python. It is open-source under hardness1020 on GitHub, so you can review or fork the full source.
Yes. SkillsLLM lists many other AI Agents skills you can browse and compare side by side. Open the AI Agents category from the badge at the top of this page, or use the Related Skills and comparison links further down to weigh Leeway against similar tools.
No comments yet. Be the first to share your thoughts!
You want to automate the same multi-step task. A skill or system prompt can guide the agent, but it can't pin the order: every run reads different files, uses different tools, reaches different conclusions. Nothing you can repeat, nothing you can audit.
Leeway enforces the graph. You write a YAML decision tree; the same nodes run in the same order every time. Each node picks its own tools and runs a full agent loop: the LLM iterates and emits a workflow_signal when done. The graph transitions on those signals.
| Who drives the flow? | What's in a node? | Best for | |
|---|---|---|---|
| AutoGPT, OpenClaw | LLM | Whatever the LLM decides | Exploratory tasks |
| n8n | Graph | Any kind of node (API call, transform, AI Agent subflow) | Connecting SaaS APIs (Slack, Stripe, Airtable) |
| Leeway | Graph (decisions) | A full agent loop with local-dev tools | Personal workflows and custom engineering pipelines that plug into your own system (files, shell, codebase) |
n8n is incredible for connecting SaaS APIs. Leeway is built specifically for personal workflows and custom engineering pipelines that integrate directly into your own system: your files, your shell, your repo, not third-party webhooks.
Pick Leeway when the task runs on your own files or shell, needs to be repeatable, and needs a model that can reason inside each step.
Five things that are hard to get from a node-graph workflow tool:
| # | Feature | What it does |
|---|---|---|
| 1 | Agent loop per node | Each node is a full agent loop. The model can call read_file, grep, bash, iterate up to max_turns, and emit a workflow_signal when done. You decide the graph; the model decides the steps within each node. |
| 2 | Per-node scoping | Every node gets its own ToolRegistry, SkillRegistry, HookRegistry, and MCP set, merged from globals and the node's allowlist. Node A can have bash + glob; node B can have web_fetch + mcp_github_search; same workflow. |
| 3 | Progressive skill loading, per node | skill(name="code-review") returns SKILL.md plus a file index. Reference files load only when the LLM explicitly asks. Combined with per-node scoping, each node only sees its allowlisted skills, and only their top-level content until the model drills in. |
| 4 | Turn budget with urgency injection | For signal-based nodes, the engine tells the LLM how many turns it has and injects an urgent reminder at 2 turns remaining, listing the exact signals to call. No silent cost runaway. |
| 5 | Auto-compaction (microcompact + LLM summary) | When context fills, Leeway first clears stale tool-result bodies in place. If that's not enough, it summarizes older messages via LLM while preserving the last 6. Fully transparent: no manual /compact, no lost context mid-workflow. |
At every branching node, the model picks which path the workflow should take next. The obvious concern: what if it picks a path that doesn't exist? Leeway catches this at the runtime layer, not via prompt discipline:
assess node might allow only needs_investigation or well_documented; the same label on a different node can mean something completely different.This does not stop the model from confidently picking a legal but wrong option. What the graph gives you in that case is bounded damage: the wrong branch still runs inside its own restricted tool set and validated inputs, and the whole path is auditable after the fact.
See docs/workflows.md for the full mechanics.
# Clone and install
git clone https://github.com/your-org/Leeway.git
cd Leeway
uv sync --extra dev
# Set your API key
export ANTHROPIC_API_KEY=sk-...
# Launch interactive mode
uv run leeway
# Or run a single prompt
uv run leeway -p "explain this codebase"
# Use different models
uv run leeway --model claude-opus-4-6
# Use OpenAI-compatible provider
uv run leeway --api-format openai --base-url https://api.openai.com/v1
# Health check on any codebase. No input needed, low token usage
uv run leeway
> /code-health start
Leeway's core agent loop, tool registry, permission system, and hook lifecycle are inspired by Claude Code's architecture: a minimal, streaming-first loop where the model drives tool use and the host enforces safety around it. Leeway reimplements that design in Python and extends it with a YAML workflow layer, parallel branches, cron scheduling, and per-node scoping.
flowchart LR
U[User Prompt] --> C[CLI / React TUI]
C --> R[RuntimeBundle]
R --> Q[QueryEngine]
Q --> A[Anthropic / OpenAI API]
A -->|tool_use| T[Tool Registry, 21+ tools]
T --> P[Permissions + Hooks]
P --> X["Files | Shell | Web | MCP | Tasks | Cron"]
X --> Q
The human defines the graph. The AI operates within each node. Deterministic transitions connect them. Parallel branches run concurrently with per-branch scoping and human-in-the-loop approval gates.
See .leeway/workflows/code-health.yaml. It covers all five patterns (linear, branch, loop, terminal, parallel) in one workflow with skills, hooks, and approval gates.
> /workflows
See docs/workflows.md for the full pattern catalog and every property table.
| Topic | Docs |
|---|---|
| Writing workflows (patterns, properties, transitions) | docs/workflows.md |
| Built-in tools and custom tool authoring | docs/tools.md |
| Skills with progressive disclosure | docs/skills.md |
| Hooks (command + HTTP lifecycle callbacks) | docs/hooks.md |
| MCP server integration | docs/mcp.md |
| Plugins (distributable bundles) | docs/plugins.md |
| Scheduling, cron, and remote triggers | docs/scheduling.md |
| Permission modes and path rules | docs/permissions.md |
| Slash command reference | docs/commands.md |
MIT