{"id":49576557,"url":"https://github.com/tbrandenburg/shai","last_synced_at":"2026-05-03T17:34:52.064Z","repository":{"id":324103815,"uuid":"1095928428","full_name":"tbrandenburg/shai","owner":"tbrandenburg","description":"A minimal framework for chaining AI agents together using pure shell scripts","archived":false,"fork":false,"pushed_at":"2026-02-05T08:14:40.000Z","size":2116,"stargazers_count":3,"open_issues_count":3,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-05T19:56:32.054Z","etag":null,"topics":["agents","ai","automation","bash","cli","opencode","pipeline","shell"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tbrandenburg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-11-13T17:48:53.000Z","updated_at":"2026-02-05T08:14:44.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tbrandenburg/shai","commit_stats":null,"previous_names":["tbrandenburg/shai"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tbrandenburg/shai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrandenburg%2Fshai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrandenburg%2Fshai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrandenburg%2Fshai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrandenburg%2Fshai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tbrandenburg","download_url":"https://codeload.github.com/tbrandenburg/shai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tbrandenburg%2Fshai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32578847,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","automation","bash","cli","opencode","pipeline","shell"],"created_at":"2026-05-03T17:34:51.326Z","updated_at":"2026-05-03T17:34:52.058Z","avatar_url":"https://github.com/tbrandenburg.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🫖 **SHAI - Shell AI Agents**\n\nOrchestrate agents with shell scripts - and drink a chai :wink:\n\n\u003cdiv align=\"center\"\u003e\n  \u003cimg width=\"640\" height=\"640\" alt=\"image\" src=\"https://github.com/user-attachments/assets/edd5f668-f095-465b-90f3-1c5287d86a5c\" /\u003e\n\u003c/div\u003e\n\n## Lightweight agent orchestration using plain shell scripts\n\n**SHAI** (Shell-AI / sh-ai) is a minimal, file-based agent orchestration\nframework built entirely around **shell scripts**.\nNo servers, no daemons, no Docker - just **Bash + your preferred LLM\nCLI + MCPs**.\n\nIt enables you to create deterministic, debuggable, Unix-style pipelines\nof AI \"agents\" where each stage consumes and produces **explicit\nfiles** (`plan.md`, `essay.md`, `review.md`, etc.), making automation\ntransparent and reproducible.\n\n## 🚀 Features\n\n- 🧩 **Composable agent stages** written as standard shell scripts\n- 📁 **Strict file-based input/output** --- no hidden conversation state\n- 🎯 **Multi-role task execution** with role-based task assignments\n- 📊 **Real-time progress tracking** with task completion counters\n- 🆔 **Parallel execution support** with unique ID-based output directories\n- 🔎 **Optional web-enabled agents** for research stages\n- 🔐 **Mandatory output verification** (stops pipeline if file missing)\n- 🪢 **Pipeable workflows**---think Unix pipelines, but with agents\n- 💬 Works with any LLM CLI\n- 🤖 **GitHub Actions integration** for automated issue processing\n\n## ✨ Unified SHAI CLI (Next Evolution)\n\nTo 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.\n\nNow, instead of remembering specific script locations and argument formats, you can run any SHAI pipeline with a single, clear command:\n\n```bash\nshai \u0026lt;pipeline_type\u0026gt; \u0026lt;prompt_text | --file \u0026lt;path\u0026gt;\u0026gt; [--id \u0026lt;identifier\u0026gt;]\n```\n\n### 🚀 Key Benefits\n\n-   **Single Entry Point:** One command to rule them all: `shai`.\n-   **Intuitive\n\nRunning agents with shell scripts unlocks powerful capabilities:\n\n- **🔄 Reusable bash scripts** – Write once, run anywhere: locally, in CI/CD pipelines, or scheduled workflows\n- **🏗️ GitHub Actions integration** – Embed agent pipelines directly into GitHub workflows for automated content generation, analysis, and reviews\n- **🛠️ Full MCP tooling** – Access file operations, web search, and custom tools from within deterministic shell scripts\n- **📊 Testable \u0026 debuggable** – Each agent stage produces explicit output files; inspect, validate, and iterate independently\n- **⚡ No infrastructure overhead** – No servers, containers, or external services; pure bash + LLM CLI orchestration\n- **🔗 Composable automation** – Chain agents into sophisticated pipelines: research → planning → writing → review → publication\n\nPerfect for content workflows, code generation, research automation and intelligent document processing at scale.\n\n## 📦 Example: Task Machine Pipeline\n\n    User request → Planner → Executor Loop → Completed tasks\n\nThe **Task Machine** is SHAI's most advanced pipeline, featuring multi-role task execution with real-time progress tracking:\n\n```bash\n# Basic usage\n./scripts/pipeline_task_machine.sh \"Create a weather dashboard app\"\n\n# With unique ID for parallel execution\n./scripts/pipeline_task_machine.sh \"Build user authentication\" --id \"auth-123\"\n\n# Using input file\n./scripts/pipeline_task_machine.sh --file requirements.md --id \"project-456\"\n```\n\n### 🎯 Task Machine Features\n\n- **Multi-role execution**: Tasks are assigned to specific roles (Developer, Designer, Analyst, etc.)\n- **Progress tracking**: Real-time updates show `completed/total` tasks and remaining work\n- **Dynamic adaptation**: New subtasks can be added during execution\n- **Parallel execution**: Use `--id` to run multiple instances without conflicts\n- **GitHub integration**: Automatically triggered by `@task` comments in issues\n\n### Example Task Machine Output Structure\n\n```\noutput/project-123/\n├── task_request.txt           # Original request\n└── task_machine_plan.md       # Plan with role assignments and progress\n```\n\nEach task in the plan follows this format:\n```markdown\n- [ ] [Developer] Set up project structure — Create folders, package.json, and basic configuration files\n- [x] [Designer] Create wireframes — Design user interface mockups for main screens\n```\n\n## 📦 Example: Essay Pipeline\n\n    User topic → Planner → Writer → Reviewer → Final output\n\nCall it via:\n\n```bash\n./scripts/pipeline_essay.sh \"Scouts in Sweden\"\n```\n\n```bash\nshai essay \"Scouts in Sweden\"\n# Or with a custom ID:\nshai essay \"Scouts in Sweden\" --id sweden-scouts-report\n# Or with file input:\nshai essay --file sweden_scouts_topic.txt --id sweden-scouts-file\n```\n\nEach agent:\n\n-   Receives a *single* input file (or none)\n-   Produces a *single* required output file\n-   Is called by a simple `opencode run \"...\"`\n-   Uses MCP tools to write output files internally\n\n## 🧠 Example Agent: Task Machine Planner\n\n``` bash\n#!/usr/bin/env bash\nset -euo pipefail\n\n# Task Machine Planner with role-based assignments\nread -r -d '' PLANNER_PROMPT \u003c\u003cEOF || true\nYou are the **TASK MACHINE PLANNER** in a two-stage pipeline.\n\nMANDATORY BEHAVIOR:\n- Use MCP tools to read the user's goal from \\`${CONTEXT_FILE}\\`\n- Use MCP tools to read the multi-role template from \\`${TEMPLATE_FILE}\\`\n- Produce a markdown document written to: \\`${PLAN_FILE}\\`\n- The document MUST contain three sections:\n  1. \\`## Context\\` summarizing the overall objective\n  2. \\`## Role Descriptions\\` for each role needed\n  3. \\`## Chronologic Task List\\` with role assignments\n- Every task MUST specify which role is responsible:\n  \\`- [ ] [Role Name] Task description — detailed instructions\\`\n- Keep the plan lightweight and avoid unnecessary busywork\n- This workflow is UNSUPERVISED: make decisions autonomously\n\nTASK: Create the plan for the request in \\`${CONTEXT_FILE}\\`\nEOF\n\nopencode run \"$PLANNER_PROMPT\"\n\n[[ -f \"$PLAN_FILE\" ]] || { echo \"Planner failed: $PLAN_FILE missing\"; exit 1; }\n```\n\n## 🔄 Example Agent: Task Machine Executor\n\n``` bash\n# Executor loop with progress tracking\niteration=1\nwhile grep -q \"\\\\[ \\\\]\" \"$PLAN_FILE\"; do\n  # Count progress\n  total_tasks=$(grep -c \"^- \\[.\\]\" \"$PLAN_FILE\" || echo \"0\")\n  completed_tasks=$(grep -c \"^- \\[x\\]\" \"$PLAN_FILE\" || echo \"0\")\n  remaining_tasks=$(grep -c \"^- \\[ \\]\" \"$PLAN_FILE\" || echo \"0\")\n  \n  echo \"Iteration ${iteration}... (${completed_tasks}/${total_tasks} completed, ${remaining_tasks} remaining)\"\n  \n  # Execute first unchecked task\n  opencode run \"$EXECUTOR_PROMPT\"\n  \n  iteration=$((iteration + 1))\ndone\n\necho \"All tasks completed! (${final_completed_tasks}/${final_total_tasks} tasks finished)\"\n```\n\n## 🖇️ Example Pipeline Script\n\n``` bash\n#!/usr/bin/env bash\nset -euo pipefail\n\n# Task Machine Pipeline with ID support\nINPUT_ARG=\"\"\nID_ARG=\"\"\nCONTEXT_FILE=\"\"\n\n# Parse arguments for flexible usage\nwhile [[ $# -gt 0 ]]; do\n  case $1 in\n    --id)\n      ID_ARG=\"$2\"\n      shift 2\n      ;;\n    --file)\n      CONTEXT_FILE=\"$2\"\n      shift 2\n      ;;\n    *)\n      if [[ -z \"$INPUT_ARG\" ]]; then\n        INPUT_ARG=\"$1\"\n      fi\n      shift\n      ;;\n  esac\ndone\n\n# Set output directory with optional ID suffix\nif [[ -n \"$ID_ARG\" ]]; then\n  OUTPUT_DIR=\"output/${ID_ARG}\"\nelse\n  OUTPUT_DIR=\"output\"\nfi\nmkdir -p \"$OUTPUT_DIR\"\n\nPLAN_FILE=\"$OUTPUT_DIR/task_machine_plan.md\"\n\n# Helper: Mandatory output enforcement\nrequire_file() {\n  local filename=\"$1\"\n  if [[ ! -f \"$filename\" ]]; then\n    echo \"ERROR: Required output file '$filename' was NOT created.\"\n    exit 1\n  fi\n}\n\n# Run planner\nopencode run \"$PLANNER_PROMPT\"\nrequire_file \"$PLAN_FILE\"\n\n# Run executor loop with progress tracking\niteration=1\nwhile grep -q \"\\\\[ \\\\]\" \"$PLAN_FILE\"; do\n  # Progress tracking\n  total_tasks=$(grep -c \"^- \\[.\\]\" \"$PLAN_FILE\" || echo \"0\")\n  completed_tasks=$(grep -c \"^- \\[x\\]\" \"$PLAN_FILE\" || echo \"0\")\n  remaining_tasks=$(grep -c \"^- \\[ \\]\" \"$PLAN_FILE\" || echo \"0\")\n  \n  echo \"Running executor iteration ${iteration}... (${completed_tasks}/${total_tasks} completed, ${remaining_tasks} remaining)\"\n  \n  opencode run \"$EXECUTOR_PROMPT\"\n  require_file \"$PLAN_FILE\"\n  \n  iteration=$((iteration + 1))\ndone\n\necho \"All tasks completed!\"\n```\n\n## 🤖 GitHub Actions Integration\n\nSHAI includes automated GitHub Actions integration for issue-based task processing:\n\n```yaml\n# Triggered by @task comments in issues\non:\n  issue_comment:\n    types: [created]\n  issues:\n    types: [opened, edited, reopened]\n\njobs:\n  task-machine:\n    runs-on: ubuntu-latest\n    steps:\n      - name: Run task machine pipeline\n        run: |\n          bash scripts/pipeline_task_machine.sh --file \"$PROMPT_FILE\" --id \"$ISSUE_NUMBER\"\n```\n\nFeatures:\n- **Admin-only execution**: Only repository admins can trigger `@task`\n- **Automatic ID assignment**: Uses issue number for unique output directories\n- **Progress tracking**: Shows real-time task completion in issue comments\n- **File isolation**: Each issue gets its own output directory (`output/123/`, `output/456/`)\n\n## 🧪 Testing Your Pipeline\n\n``` bash\n# Test task machine locally\nbash scripts/pipeline_task_machine.sh \"Create a todo app\"\n\n# Test with ID for parallel execution\nbash scripts/pipeline_task_machine.sh \"Build API endpoints\" --id \"backend-dev\"\n\n# Test essay pipeline\nbash scripts/pipeline_essay.sh \"Evolution of renewable energy\"\n\n# Test with file input\nbash scripts/pipeline_task_machine.sh --file requirements.md --id \"project-123\"\n```\n\nOr test individual stages with your own prompts.\n\n## ⚙️ Web-Research Agents\n\nInclude instructions like:\n\n````\nYou MUST perform multiple web searches to gather facts and context.\n...\n- **TIMEOUT SAFETY:** Keep searches focused on 2-3 key topics per search to avoid timeouts.\n````\n\n## 📜 Philosophy\n\n\u003e *\"Do one thing well.\"* --- Unix Philosophy\n\nAgents are small, replaceable, debuggable, and transparent.\n\n## 🛠 Requirements\n\n-   Bash ≥ 4\n-   [opencode](https://github.com/sst/opencode) installed and a default model configured\n-   Any CLI-based LLM runner\n-   Optional MCP tools for file writing\n\n## ⚠️ Important Disclaimer\n\n**For experimental use only; using this script as a bot in violation of any service's terms is prohibited and may be illegal.**\n\n## 🙌 Contributing\n\nPRs and issues welcome!\n\n## 📄 License\n\nMIT\n\n## Credits\n\nCredits to [Cole Medin](https://github.com/coleam00/) for some of his ideas used here.\n\n## 🫖 Enjoy your shai!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbrandenburg%2Fshai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftbrandenburg%2Fshai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftbrandenburg%2Fshai/lists"}