https://github.com/tbrandenburg/shai
A minimal framework for chaining AI agents together using pure shell scripts
https://github.com/tbrandenburg/shai
agents ai automation bash cli opencode pipeline shell
Last synced: about 1 month ago
JSON representation
A minimal framework for chaining AI agents together using pure shell scripts
- Host: GitHub
- URL: https://github.com/tbrandenburg/shai
- Owner: tbrandenburg
- License: mit
- Created: 2025-11-13T17:48:53.000Z (7 months ago)
- Default Branch: main
- Last Pushed: 2026-02-05T08:14:40.000Z (4 months ago)
- Last Synced: 2026-02-05T19:56:32.054Z (4 months ago)
- Topics: agents, ai, automation, bash, cli, opencode, pipeline, shell
- Language: Shell
- Homepage:
- Size: 2.02 MB
- Stars: 3
- Watchers: 0
- Forks: 1
- Open Issues: 3
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Agents: AGENTS.md
Awesome Lists containing this project
README
# 🫖 **SHAI - Shell AI Agents**
Orchestrate agents with shell scripts - and drink a chai :wink:
## Lightweight agent orchestration using plain shell scripts
**SHAI** (Shell-AI / sh-ai) is a minimal, file-based agent orchestration
framework built entirely around **shell scripts**.
No servers, no daemons, no Docker - just **Bash + your preferred LLM
CLI + MCPs**.
It enables you to create deterministic, debuggable, Unix-style pipelines
of AI "agents" where each stage consumes and produces **explicit
files** (`plan.md`, `essay.md`, `review.md`, etc.), making automation
transparent and reproducible.
## 🚀 Features
- 🧩 **Composable agent stages** written as standard shell scripts
- 📁 **Strict file-based input/output** --- no hidden conversation state
- 🎯 **Multi-role task execution** with role-based task assignments
- 📊 **Real-time progress tracking** with task completion counters
- 🆔 **Parallel execution support** with unique ID-based output directories
- 🔎 **Optional web-enabled agents** for research stages
- 🔐 **Mandatory output verification** (stops pipeline if file missing)
- 🪢 **Pipeable workflows**---think Unix pipelines, but with agents
- 💬 Works with any LLM CLI
- 🤖 **GitHub Actions integration** for automated issue processing
## ✨ Unified SHAI CLI (Next Evolution)
To make SHAI even easier to use and remember for daily command-line tasks, we're introducing a unified `shai` command-line interface. This wrapper script simplifies pipeline execution by handling script paths, ID generation, and consistent input parsing.
Now, instead of remembering specific script locations and argument formats, you can run any SHAI pipeline with a single, clear command:
```bash
shai <pipeline_type> <prompt_text | --file <path>> [--id <identifier>]
```
### 🚀 Key Benefits
- **Single Entry Point:** One command to rule them all: `shai`.
- **Intuitive
Running agents with shell scripts unlocks powerful capabilities:
- **🔄 Reusable bash scripts** – Write once, run anywhere: locally, in CI/CD pipelines, or scheduled workflows
- **🏗️ GitHub Actions integration** – Embed agent pipelines directly into GitHub workflows for automated content generation, analysis, and reviews
- **🛠️ Full MCP tooling** – Access file operations, web search, and custom tools from within deterministic shell scripts
- **📊 Testable & debuggable** – Each agent stage produces explicit output files; inspect, validate, and iterate independently
- **⚡ No infrastructure overhead** – No servers, containers, or external services; pure bash + LLM CLI orchestration
- **🔗 Composable automation** – Chain agents into sophisticated pipelines: research → planning → writing → review → publication
Perfect for content workflows, code generation, research automation and intelligent document processing at scale.
## 📦 Example: Task Machine Pipeline
User request → Planner → Executor Loop → Completed tasks
The **Task Machine** is SHAI's most advanced pipeline, featuring multi-role task execution with real-time progress tracking:
```bash
# Basic usage
./scripts/pipeline_task_machine.sh "Create a weather dashboard app"
# With unique ID for parallel execution
./scripts/pipeline_task_machine.sh "Build user authentication" --id "auth-123"
# Using input file
./scripts/pipeline_task_machine.sh --file requirements.md --id "project-456"
```
### 🎯 Task Machine Features
- **Multi-role execution**: Tasks are assigned to specific roles (Developer, Designer, Analyst, etc.)
- **Progress tracking**: Real-time updates show `completed/total` tasks and remaining work
- **Dynamic adaptation**: New subtasks can be added during execution
- **Parallel execution**: Use `--id` to run multiple instances without conflicts
- **GitHub integration**: Automatically triggered by `@task` comments in issues
### Example Task Machine Output Structure
```
output/project-123/
├── task_request.txt # Original request
└── task_machine_plan.md # Plan with role assignments and progress
```
Each task in the plan follows this format:
```markdown
- [ ] [Developer] Set up project structure — Create folders, package.json, and basic configuration files
- [x] [Designer] Create wireframes — Design user interface mockups for main screens
```
## 📦 Example: Essay Pipeline
User topic → Planner → Writer → Reviewer → Final output
Call it via:
```bash
./scripts/pipeline_essay.sh "Scouts in Sweden"
```
```bash
shai essay "Scouts in Sweden"
# Or with a custom ID:
shai essay "Scouts in Sweden" --id sweden-scouts-report
# Or with file input:
shai essay --file sweden_scouts_topic.txt --id sweden-scouts-file
```
Each agent:
- Receives a *single* input file (or none)
- Produces a *single* required output file
- Is called by a simple `opencode run "..."`
- Uses MCP tools to write output files internally
## 🧠 Example Agent: Task Machine Planner
``` bash
#!/usr/bin/env bash
set -euo pipefail
# Task Machine Planner with role-based assignments
read -r -d '' PLANNER_PROMPT < *"Do one thing well."* --- Unix Philosophy
Agents are small, replaceable, debuggable, and transparent.
## 🛠 Requirements
- Bash ≥ 4
- [opencode](https://github.com/sst/opencode) installed and a default model configured
- Any CLI-based LLM runner
- Optional MCP tools for file writing
## ⚠️ Important Disclaimer
**For experimental use only; using this script as a bot in violation of any service's terms is prohibited and may be illegal.**
## 🙌 Contributing
PRs and issues welcome!
## 📄 License
MIT
## Credits
Credits to [Cole Medin](https://github.com/coleam00/) for some of his ideas used here.
## 🫖 Enjoy your shai!