{"id":47925464,"url":"https://github.com/nadimtuhin/loopwork","last_synced_at":"2026-04-04T06:29:02.853Z","repository":{"id":334457645,"uuid":"1141330259","full_name":"nadimtuhin/loopwork","owner":"nadimtuhin","description":"AI-powered task automation with pluggable backends and extensible integrations. Run Claude, OpenCode \u0026 Gemini against GitHub Issues or JSON files with Next.js-style composable plugins.","archived":false,"fork":false,"pushed_at":"2026-02-01T22:47:18.000Z","size":45016,"stargazers_count":0,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-02T08:38:59.233Z","etag":null,"topics":["ai","automation","bun","claude","github-issues","plugin-architecture","task-runner","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/nadimtuhin.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"nadimtuhin"}},"created_at":"2026-01-24T17:07:45.000Z","updated_at":"2026-02-01T22:47:24.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/nadimtuhin/loopwork","commit_stats":null,"previous_names":["nadimtuhin/loopwork"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/nadimtuhin/loopwork","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Floopwork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Floopwork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Floopwork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Floopwork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nadimtuhin","download_url":"https://codeload.github.com/nadimtuhin/loopwork/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nadimtuhin%2Floopwork/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31390134,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-04T04:26:24.776Z","status":"ssl_error","status_checked_at":"2026-04-04T04:23:34.147Z","response_time":60,"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":["ai","automation","bun","claude","github-issues","plugin-architecture","task-runner","typescript"],"created_at":"2026-04-04T06:29:02.090Z","updated_at":"2026-04-04T06:29:02.841Z","avatar_url":"https://github.com/nadimtuhin.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nadimtuhin"],"categories":[],"sub_categories":[],"readme":"# Loopwork 🔁\n\n\u003e **AI-powered task automation with pluggable backends and extensible integrations**\n\n[![npm version](https://img.shields.io/npm/v/@loopwork-ai/loopwork.svg)](https://www.npmjs.com/package/@loopwork-ai/loopwork)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nLoopwork is an extensible task automation framework that runs AI CLI tools (Claude, OpenCode, Gemini) against task backlogs from various sources (GitHub Issues, JSON files, or custom backends). Features a Next.js-style composable plugin architecture for integrations with time tracking, notifications, and project management tools.\n\n## 🎯 What Loopwork Does\n\nLoopwork automates repetitive task execution by coordinating AI tools with task management systems. You define tasks (as Markdown files or GitHub Issues), and Loopwork orchestrates AI models to complete them automatically with:\n\n- **Real-time execution** - Watch AI models work through your task backlog in real-time\n- **Smart retries** - Automatic failover between AI models if one fails\n- **Cost awareness** - Track token usage and enforce daily budgets\n- **Rich notifications** - Get updates via Telegram, Discord, or Slack\n- **Production-ready** - State persistence, orphan process cleanup, health checks\n\n**Real-world use case:** You have 50 TypeScript refactoring tasks. You write a task description once, and Loopwork orchestrates your AI model to execute all 50 tasks, tracking progress, retrying failures, and notifying you when done.\n\n## ✨ Key Features\n\n- 🤖 **Multiple AI Backends** - Support for Claude, OpenCode, and Gemini\n- 📋 **Flexible Task Sources** - GitHub Issues, JSON files, with plugin support for custom backends\n- 🔌 **Plugin Architecture** - Next.js-style config with composable plugins\n- ⏱️ **Time Tracking** - Everhour integration with daily limits\n- 📊 **Project Management** - Asana, Todoist sync\n- 🔔 **Notifications** - Telegram bot \u0026 Discord webhooks\n- 💰 **Cost Tracking** - Token usage and cost monitoring\n- 🌳 **Sub-tasks \u0026 Dependencies** - Hierarchical task structures\n- 🤖 **Dynamic Task Creation** - Automatic follow-up task generation based on output analysis\n- 🔧 **MCP Server** - Model Context Protocol for AI tool integration\n- 📺 **Real-time Streaming** - Live output from AI execution\n- 🎯 **Smart Retries** - Automatic failover between AI models\n\n---\n\n## ⚡ Zero to Hero: Get Started in 5 Minutes\n\nThis guide will take you from **zero setup** to running your first **AI task orchestration** in under 5 minutes. No prior experience needed!\n\n### PHASE 1: Prerequisites Setup (2 minutes)\n\nYou need exactly two things to get started. **Copy and paste** these commands into your terminal:\n\n#### Step 1A: Install JavaScript Runtime\n\n**Choose ONE option below:**\n\n**Bun (Recommended - Fastest):**\n```bash\ncurl -fsSL https://bun.sh/install | bash\n# Close and reopen your terminal\nbun --version\n```\n\n**OR Node.js (if you prefer):**\n```bash\n# macOS with Homebrew\nbrew install node\n\n# Or download from: https://nodejs.org/ (LTS version)\n\nnode --version\n```\n\n\u003e ✅ **Must See:** A version number like `1.0.0`. If you see \"command not found\", restart your terminal and try again.\n\n#### Step 1B: Install AI CLI Tool\n\n**Claude Code (Recommended - Easiest Setup):**\n- Go to https://claude.ai/code and click \"Install\"\n- Follow the on-screen setup steps (installs automatically)\n- In a new terminal window, verify: `claude --version`\n- **This is the recommended option** - it's the most reliable and easiest to set up\n\n**OR OpenCode (Alternative):**\n- Visit https://opencode.sh/ for installation instructions\n- Download and install the appropriate binary for your OS\n- Verify: `opencode --version`\n\n**OR Use any AI CLI that accepts prompts:**\n- If you have another AI CLI tool that can process text prompts, you can configure Loopwork to use it\n- Just make sure the CLI is in your PATH\n\n\u003e ✅ **Must See:** A version number when you run `claude --version` (or your chosen CLI). If \"command not found\", restart your terminal and try again.\n\u003e\n\u003e **Note:** This guide uses Claude Code in all examples. If you use a different CLI, adjust the commands accordingly.\n\n### PHASE 2: Clone \u0026 Build Loopwork (2 minutes)\n\nCopy and paste these commands **exactly as shown**:\n\n```bash\n# Clone the repository\ngit clone https://github.com/nadimtuhin/loopwork.git\ncd loopwork\n\n# Install dependencies (this takes 30-60 seconds)\nbun install\n# OR if using Node.js: npm install\n\n# Build Loopwork (REQUIRED - don't skip this step!)\nbun run build\n# OR if using Node.js: npm run build\n```\n\n\u003e ✅ **Verify it worked:** Run this command. You should see the loopwork binary (about 50MB):\n\u003e ```bash\n\u003e ls -lh packages/loopwork/bin/loopwork\n\u003e ```\n\u003e Expected output: `-rwxrwxrwx ... 50M ... packages/loopwork/bin/loopwork`\n\u003e\n\u003e ❌ **If you see \"No such file or directory\":** The build failed. Common fixes:\n\u003e - Make sure you're in the `loopwork` directory: `pwd` should end with `/loopwork`\n\u003e - Try cleaning and rebuilding: `rm -rf node_modules \u0026\u0026 bun install \u0026\u0026 bun run build`\n\u003e - Check for error messages during the build step above\n\n### PHASE 3: Run Your First AI Task (1 minute)\n\n```bash\n# Navigate to the example\ncd examples/basic-json-backend\n\n# Verify everything is ready\n./verify-setup.sh\n```\n\n**If all checks pass** (you'll see green ✅ marks), continue:\n\n```bash\n# Option A: Interactive menu (recommended for first time)\n./quick-start.sh\n# Then select: 4) Reset and Run (fresh start)\n\n# Option B: Direct commands (if you prefer)\n./quick-start.sh --reset\n./quick-start.sh --run\n```\n\n\u003e 🎯 **What happens next:**\n\u003e - Loopwork will launch Claude AI to work through 3 sample tasks\n\u003e - You'll see real-time output in your terminal as Claude reads each task and works on it\n\u003e - Claude will create files, write code, run tests - all automatically\n\u003e - Each task takes 30-90 seconds\n\u003e - Total time: 2-5 minutes\n\u003e - **You don't need to do anything** - just watch!\n\n### 🎬 What You'll See\n\nWhen you run `./quick-start.sh --run`, the terminal will display real-time output:\n\n```\n⚡ Running Loopwork...\n\n📋 TASK-001: Create Hello World function\n⏳ Running Claude...\n   \u003e Creating file: hello.ts\n   \u003e Writing helloWorld function\n   \u003e Running tests\n✅ Completed in 2.3s\n\n📋 TASK-002: Add Sum function\n⏳ Running Claude...\n   \u003e Adding sum function to math.ts\n   \u003e Updating tests\n✅ Completed in 1.8s\n\n📋 TASK-003: Create README\n⏳ Running Claude...\n   \u003e Creating README.md with documentation\n   \u003e Adding examples\n✅ Completed in 3.1s\n\n📊 Summary:\n   ✅ 3 completed\n   ❌ 0 failed\n   ⏱️ Duration: 7.2s\n```\n\nThe AI will:\n1. Read each task description from `.specs/tasks/TASK-*.md` files\n2. Execute the work (creating/modifying files, running tests)\n3. Mark the task complete and move to the next one\n4. Show you a summary when done\n\n**No intervention needed.** You just watch it work!\n\n### 🧠 What Just Happened\n\n**You didn't write any code.** You didn't copy-paste into ChatGPT. You just ran Loopwork, and it acted as a **Project Manager**:\n\n1. **Loaded** 3 task descriptions ✓\n2. **Assigned** each task to Claude AI ✓\n3. **Monitored** execution in real-time ✓\n4. **Verified** results and marked tasks complete ✓\n5. **Showed you a summary** ✓\n\nImagine scaling this to **50 refactoring tasks**, **100 documentation updates**, or **1000 code fixes**. Running automatically. While you sleep. That is the power of Loopwork.\n\n---\n\n### 🚀 Quick Reference\n\n**Already set up? Just want to run tasks?** Copy-paste this:\n\n```bash\ncd loopwork/examples/basic-json-backend\n./verify-setup.sh           # Quick sanity check (should see all ✅)\n./quick-start.sh --reset    # Reset tasks to \"pending\"\n./quick-start.sh --run      # Run tasks and watch AI work!\n```\n\n**First time? Use this full setup:**\n\n```bash\ngit clone https://github.com/nadimtuhin/loopwork.git\ncd loopwork\n\n# Install and build (30-60 seconds)\nbun install \u0026\u0026 bun run build\n\n# Run example\ncd examples/basic-json-backend\n./verify-setup.sh           # Must show all green ✅\n./quick-start.sh --run      # Watch AI complete 3 tasks!\n```\n\n---\n\n## 🔧 Troubleshooting Guide\n\n### Pre-Flight Checklist\n\nBefore troubleshooting, verify you completed all setup steps:\n\n```bash\n# 1. Check JavaScript runtime is installed\nbun --version || node --version\n# ✅ Should show version number\n\n# 2. Check AI CLI is installed\nwhich claude || which opencode || which gemini\n# ✅ Should show a file path like /usr/local/bin/claude\n\n# 3. Check loopwork is built\nls -la ../../packages/loopwork/bin/loopwork\n# ✅ Should show the binary file\n\n# 4. Check you're in the right directory\npwd\n# ✅ Should end with: .../loopwork/examples/basic-json-backend\n```\n\nIf any of these fail, that's your issue. Fix it below:\n\n---\n\n### Installation Issues\n\n#### \"Command not found: bun\"\n\n**What this means:** Bun installed but can't be found in your PATH.\n\n**Quick fix:**\n```bash\n# Restart your terminal completely (close and open a new one)\n# Then try again\nbun --version\n```\n\n**If that doesn't work:**\n```bash\n# Check where Bun was installed\nls -la ~/.bun/bin/bun\n\n# Add Bun to PATH manually\necho 'export PATH=\"$HOME/.bun/bin:$PATH\"' \u003e\u003e ~/.bashrc\n\n# Reload shell\nsource ~/.bashrc\n\n# Verify\nbun --version\n```\n\n**Can't fix it? Use Node.js instead:**\n```bash\n# Install Node.js (v18+) from https://nodejs.org\nnode --version\n\n# Then use 'npm' instead of 'bun' for all commands:\nnpm install      # instead of: bun install\nnpm run build    # instead of: bun run build\n```\n\n#### \"Command not found: claude\" (or opencode/gemini)\n\n**What this means:** Your AI CLI isn't installed or not found in PATH.\n\n**Step-by-step fix:**\n\n1. **First, restart your terminal completely:**\n   - Close your terminal window entirely\n   - Open a new terminal window\n   - Try again: `which claude`\n\n   (Many PATH issues are fixed by restarting!)\n\n2. **If still not found, reinstall Claude Code:**\n   ```bash\n   # Visit https://claude.ai/code\n   # Download and run the installer\n   # Follow on-screen prompts\n\n   # After installation, restart terminal and verify:\n   which claude\n   claude --version\n   ```\n\n3. **If Claude Code installer doesn't work, check:**\n   - Make sure you downloaded from the official site: https://claude.ai/code\n   - Check system requirements (macOS, Windows, or Linux)\n   - Look for error messages during installation\n   - Try running from terminal: `~/Applications/Claude.app/Contents/MacOS/claude` (macOS example)\n\n4. **If Claude won't work, try OpenCode instead:**\n   ```bash\n   # Visit https://opencode.sh/ for download links\n   # Download and install for your OS\n   # Then verify:\n   opencode --version\n\n   # Then edit loopwork.config.js:\n   # Change: cli: 'claude'\n   # To:     cli: 'opencode'\n   ```\n\n5. **Verify the fix:**\n   ```bash\n   # Should show a file path (not \"not found\")\n   which claude\n\n   # Should show version (not error)\n   claude --version\n\n   # Try a simple test\n   echo \"What is 2+2?\" | claude\n   ```\n\n### Configuration Issues\n\n#### \"Config file not found\" or \"loopwork.config.js not found\"\n\n**What this means:** Loopwork can't find the configuration file.\n\n**Fix:**\n\n1. **Verify you're in the right directory:**\n   ```bash\n   pwd\n   # ✅ Should end with: /examples/basic-json-backend\n\n   # Check the config file exists\n   ls -la loopwork.config.js\n   # ✅ Should show the file\n   ```\n\n2. **If in wrong directory:**\n   ```bash\n   cd examples/basic-json-backend\n   ./quick-start.sh --run\n   ```\n\n3. **If config file is missing:**\n   - This shouldn't happen if you cloned the repo correctly\n   - Try re-cloning: `git clone https://github.com/nadimtuhin/loopwork.git`\n\n4. **If you modified the config and broke it:**\n   ```bash\n   # Valid configuration format:\n   module.exports = {\n     backend: {\n       type: 'json',\n       tasksFile: '.specs/tasks/tasks.json'\n     },\n     cli: 'claude',\n     maxIterations: 10\n   }\n\n   # Check for syntax errors - common mistakes:\n   # ❌ Missing commas between properties\n   # ❌ Quotes around values (use: 'value' not value)\n   # ❌ Trailing commas in objects\n   ```\n\n### Task Loading Issues\n\n#### \"No tasks found\" or all tasks show as \"completed\"\n\n**What this means:** Tasks exist but are all marked as \"completed\" from a previous run.\n\n**Quick fix:**\n```bash\n./quick-start.sh --reset\n./quick-start.sh --run\n```\n\n**Detailed verification:**\n\n1. **Check task file is valid:**\n   ```bash\n   cat .specs/tasks/tasks.json | jq .\n   # ✅ Should show valid JSON with a \"tasks\" array\n   # ❌ If it shows \"parse error\", the JSON is broken\n   ```\n\n2. **Check task status:**\n   ```bash\n   ./quick-start.sh --status\n   # ✅ You should see: TASK-001: pending, TASK-002: pending, etc.\n   # ❌ If all show \"completed\", run: ./quick-start.sh --reset\n   ```\n\n3. **Check task description files exist:**\n   ```bash\n   ls .specs/tasks/TASK-*.md\n   # ✅ Should show: TASK-001.md, TASK-002.md, TASK-003.md\n   ```\n\n4. **Check file structure:**\n   ```bash\n   # Correct structure:\n   examples/basic-json-backend/\n   ├── .specs/tasks/\n   │   ├── tasks.json         ✅ Must exist\n   │   ├── TASK-001.md        ✅ Must exist\n   │   └── TASK-002.md        ✅ Must exist\n   └── loopwork.config.js     ✅ Must exist\n   ```\n\n### Execution Issues\n\n#### Task seems stuck (no output for 30+ seconds)\n\n**Symptom:** Task starts but no output, AI seems frozen\n\n**Solutions:**\n1. **Check AI CLI is responsive:**\n   ```bash\n   # Test the CLI directly\n   claude --version\n\n   # Or try a simple command\n   echo \"test\" | claude \"what is 2+2?\"\n   ```\n\n2. **Increase timeout if task is just slow:**\n   ```typescript\n   // In loopwork.config.ts\n   export default compose(\n     withCli({\n       models: [\n         ModelPresets.claudeSonnet({ timeout: 600 })  // increased from 300\n       ]\n     }),\n     // ...\n   )(defineConfig({\n     timeout: 900,  // increased from 600\n   }))\n   ```\n\n3. **Check API rate limits:**\n   - Claude: max 5 concurrent requests\n   - OpenCode: check your plan limits\n   - Wait a few minutes and try again\n\n4. **Stop and check logs:**\n   ```bash\n   # Press Ctrl+C to stop\n\n   # Check what happened\n   cat .loopwork/runs/*/logs/iteration-*.txt | tail -20\n   ```\n\n#### Task fails with error\n\n**Symptom:** Task marked as failed with error message\n\n**Common errors and solutions:**\n\n**\"API key not found\" or \"Unauthorized\"**\n```bash\n# AI CLI needs API key setup\nclaude --version  # might prompt for setup\n\n# Or set environment variable\nexport ANTHROPIC_API_KEY=\"your-key-here\"\nloopwork\n```\n\n**\"Timeout exceeded\"**\n```typescript\n// Task took longer than timeout\n// Option 1: Increase timeout\nexport default compose(\n  // ...\n  withCli({\n    models: [\n      ModelPresets.claudeSonnet({ timeout: 600 })  // 10 minutes\n    ]\n  }),\n)(defineConfig({\n  timeout: 900,\n}))\n```\n\n**\"Task failed to parse\"**\n```bash\n# Task description file might be invalid\n# Check the .md file\ncat .specs/tasks/TASK-001.md\n\n# Should have this structure:\n# # TASK-001: Title\n# ## Goal\n# Description\n# ## Requirements\n# - Req 1\n# - Req 2\n```\n\n### Verification Steps\n\nAfter fixing an issue, verify Loopwork works:\n\n```bash\n# 1. Verify AI CLI works\nclaude --version\n# Expected: version number\n\n# 2. Verify config loads\ncat loopwork.config.js\n# Expected: valid JavaScript/TypeScript\n\n# 3. Verify tasks exist\ncat .specs/tasks/tasks.json | jq .\n# Expected: valid JSON with pending tasks\n\n# 4. Verify task descriptions exist\nls .specs/tasks/TASK-*.md\n# Expected: list of markdown files\n\n# 5. Try a dry-run\nloopwork --dry-run\n# Expected: list of tasks to execute\n\n# 6. Try actual run\nloopwork\n# Expected: tasks execute with status updates\n```\n\n### Debug Mode\n\nEnable detailed logging for troubleshooting:\n\n```bash\n# Run with debug output\nloopwork --debug\n\n# Or set environment variable\nexport DEBUG=loopwork:*\nloopwork\n```\n\nThis shows:\n- Configuration being loaded\n- Backend initialization\n- Task selection logic\n- CLI invocation details\n- Full response output\n\n### Check Logs\n\nEvery run saves detailed logs:\n\n```bash\n# Find latest run\nls -t .loopwork/runs/ | head -1\n# Shows: 2024-01-31-14-23-45/\n\n# View current task prompt\ncat .loopwork/runs/2024-01-31-14-23-45/logs/current-prompt.md\n\n# View iteration details\ncat .loopwork/runs/2024-01-31-14-23-45/logs/iteration-1-prompt.md\ncat .loopwork/runs/2024-01-31-14-23-45/logs/iteration-1-output.txt\n\n# View state\ncat .loopwork/runs/2024-01-31-14-23-45/state.json\n```\n\n### Getting Help\n\nIf you're still stuck:\n\n1. **Check the examples:**\n   ```bash\n   cat examples/basic-json-backend/README.md\n   ```\n\n2. **Read architecture docs:**\n   ```bash\n   cat docs/explanation/architecture-overview.md\n   ```\n\n3. **Search GitHub issues:**\n   Visit: https://github.com/nadimtuhin/loopwork/issues\n\n4. **File a new issue with:**\n   - Your OS: `uname -a`\n   - Runtime version: `bun --version` or `node --version`\n   - Error message (copy-paste)\n   - Steps to reproduce\n   - Your config file (sanitize API keys)\n   - Recent logs from `.loopwork/runs/`\n\n### Performance \u0026 Optimization\n\n**Speed up task execution:**\n```typescript\n// Use faster, cheaper models first\nexport default compose(\n  withCli({\n    models: [\n      ModelPresets.claudeHaiku({ timeout: 120 }),      // Fast, cheap\n      ModelPresets.claudeSonnet({ timeout: 300 }),     // Balanced\n    ],\n    fallbackModels: [\n      ModelPresets.claudeOpus({ timeout: 600 }),       // Slow, expensive\n    ]\n  }),\n)(defineConfig({\n  maxIterations: 10,\n}))\n```\n\n**Reduce API costs:**\n```typescript\n// Use cost tracking to enforce daily budget\nexport default compose(\n  withCostTracking({\n    enabled: true,\n    dailyBudget: 10.00,  // Stop if daily cost exceeds $10\n  }),\n  // ...\n)(defineConfig({}))\n```\n\n**Monitor resource usage:**\n```bash\n# Check for orphan processes\ncat .loopwork/orphan-events.log\n\n# See what consumed the most time\ncat .loopwork/runs/*/logs/iteration-*.txt | grep Duration\n```\n\n## 🎓 Next Steps: Beyond the Basics\n\nNow that you've successfully run Loopwork, here are ways to expand your usage:\n\n### 1. Add More Tasks\n\nCreate new tasks to automate more of your workflow:\n\n```bash\n# Edit task registry\nnano .specs/tasks/tasks.json\n\n# Add a new task\n{\n  \"id\": \"TASK-004\",\n  \"status\": \"pending\",\n  \"priority\": \"high\"\n}\n\n# Create task description\nnano .specs/tasks/TASK-004.md\n```\n\n**Task description template:**\n```markdown\n# TASK-004: Your Task Title\n\n## Goal\nOne-sentence summary of what should be accomplished.\n\n## Requirements\n- Specific requirement 1\n- Specific requirement 2\n- Specific requirement 3\n\n## Example (optional)\nShow example code or output.\n\n## Success Criteria\n- How to verify the task is complete\n- What files should exist\n- What should work correctly\n```\n\n### 2. Try Different AI Models\n\nLoopwork supports Claude, OpenCode, and Gemini. Test different models:\n\n```typescript\n// loopwork.config.ts - try different models\nexport default compose(\n  withCli({\n    models: [\n      ModelPresets.claudeHaiku({ timeout: 120 }),      // Fast, cheap\n      ModelPresets.claudeSonnet({ timeout: 300 }),     // Balanced\n      ModelPresets.geminiFlash({ timeout: 300 }),      // Fast alternative\n    ],\n    fallbackModels: [\n      ModelPresets.claudeOpus({ timeout: 600 }),       // Heavy tasks\n    ]\n  }),\n)(defineConfig({\n  maxIterations: 50,\n}))\n```\n\nThen run:\n```bash\nloopwork --cli opencode  # or specify different model\n```\n\n### 3. Add Notifications\n\nGet updates via Telegram, Discord, or Slack:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),\n\n  // Add Telegram notifications\n  withTelegram({\n    botToken: process.env.TELEGRAM_BOT_TOKEN,\n    chatId: process.env.TELEGRAM_CHAT_ID,\n    notifyOnComplete: true,\n    notifyOnFail: true,\n  }),\n\n  // Or add Discord webhooks\n  // withDiscord({\n  //   webhookUrl: process.env.DISCORD_WEBHOOK_URL,\n  //   notifyOnComplete: true,\n  // }),\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\nSet environment variables:\n```bash\nexport TELEGRAM_BOT_TOKEN=\"your-token-here\"\nexport TELEGRAM_CHAT_ID=\"your-chat-id-here\"\n```\n\n### 4. Enable Cost Tracking\n\nMonitor API spending and set daily budgets:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  // ... other plugins\n\n  withCostTracking({\n    enabled: true,\n    dailyBudget: 10.00,  // Stop if over $10/day\n  }),\n\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\nCheck costs:\n```bash\nloopwork --debug  # Shows cost info\n```\n\n### 5. Use GitHub as Task Source\n\nInstead of JSON files, pull tasks from GitHub Issues:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  // Switch from JSON to GitHub\n  withGitHubBackend({\n    repo: 'myorg/myrepo',  // Your GitHub repo\n    label: 'loopwork-task', // Filter to issues with this label\n  }),\n\n  // ... other plugins\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\nOn GitHub, create issues with:\n- Label: `loopwork-task` - Marks it as a task\n- Label: `priority:high` - Set priority\n- Label: `feature:auth` - Feature area (for filtering)\n\n### 6. Set Up Time Tracking\n\nTrack time spent on tasks with Everhour:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),\n\n  withEverhour({\n    autoStartTimer: true,   // Start timer when task begins\n    autoStopTimer: true,    // Stop when task completes\n  }),\n\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\n### 7. Enable Dynamic Task Creation\n\nAutomatically create follow-up tasks based on completed work:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),\n\n  withDynamicTasks({\n    enabled: true,\n    analyzer: 'pattern',        // Fast: looks for TODO, FIXME, etc.\n    // analyzer: 'llm',          // Smart: Claude analyzes output\n    createSubTasks: true,\n    maxTasksPerExecution: 5,\n    autoApprove: true,\n  }),\n\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\nWhen AI completes a task and outputs \"TODO: refactor this\", Loopwork automatically creates a follow-up task.\n\n### 8. Sync with Asana or Todoist\n\nKeep your task manager in sync:\n\n```typescript\n// loopwork.config.ts\nexport default compose(\n  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),\n\n  // Sync with Asana\n  withAsana({\n    projectId: process.env.ASANA_PROJECT_ID,\n    syncStatus: true,  // Update Asana when tasks complete\n  }),\n\n  // Or sync with Todoist\n  // withTodoist({\n  //   projectId: process.env.TODOIST_PROJECT_ID,\n  //   syncStatus: true,\n  // }),\n\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\n### 9. Deep Dive Into Documentation\n\nRead detailed guides for advanced features:\n\n```bash\n# Core architecture\ncat docs/explanation/architecture-overview.md\n\n# CLI execution and model selection\ncat docs/explanation/cli-invocation.md\n\n# Process management\ncat docs/explanation/process-management.md\n\n# Full package README\ncat packages/loopwork/README.md\n```\n\n### 10. Create Custom Plugins\n\nBuild your own plugins to extend Loopwork:\n\n```typescript\n// loopwork.config.ts\nimport { withPlugin } from '@loopwork-ai/loopwork'\n\nexport default compose(\n  withJSONBackend({ tasksFile: '.specs/tasks/tasks.json' }),\n\n  // Custom plugin example\n  withPlugin({\n    name: 'my-custom-plugin',\n\n    onLoopStart: (namespace) =\u003e {\n      console.log(`Starting tasks in: ${namespace}`)\n    },\n\n    onTaskStart: (task) =\u003e {\n      console.log(`📋 Starting: ${task.id}`)\n    },\n\n    onTaskComplete: (task, result) =\u003e {\n      console.log(`✅ Completed: ${task.id} in ${result.duration}s`)\n    },\n\n    onTaskFailed: (task, error) =\u003e {\n      console.log(`❌ Failed: ${task.id} - ${error}`)\n      // Send alert, log to external service, etc.\n    },\n\n    onLoopEnd: (stats) =\u003e {\n      console.log(`📊 Done: ${stats.completed}/${stats.total}`)\n    },\n  }),\n\n)(defineConfig({\n  cli: 'claude',\n  maxIterations: 50,\n}))\n```\n\n### Learning Resources\n\n- **Examples:** Browse `examples/` directory for working setups\n- **Tests:** Check `packages/loopwork/test/` for usage patterns\n- **Source:** Read `packages/loopwork/src/` to understand internals\n- **GitHub:** See real projects using Loopwork\n\n### Community \u0026 Support\n\n- **GitHub Issues:** Report bugs or request features\n- **Discussions:** Join conversations about usage patterns\n- **Examples:** Share your own Loopwork configurations\n- **Plugins:** Build and share custom plugins with the community\n\n---\n\n## 🤝 Contributing\n\nContributions are welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch (`git checkout -b feature/amazing-feature`)\n3. Commit your changes (`git commit -m 'Add some amazing feature'`)\n4. Push to the branch (`git push origin feature/amazing-feature`)\n5. Open a Pull Request\n\n## 📄 License\n\nMIT © [Nadim Tuhin](https://github.com/nadimtuhin)\n\n## 🙏 Acknowledgments\n\n- Built with [Bun](https://bun.sh)\n- Powered by Claude, OpenCode, and Gemini AI models\n- Inspired by modern task automation workflows\n\n---\n\n**Star ⭐ this repo if you find it useful!**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnadimtuhin%2Floopwork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnadimtuhin%2Floopwork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnadimtuhin%2Floopwork/lists"}