{"id":46375580,"url":"https://github.com/irchelper/ainative","last_synced_at":"2026-03-05T05:04:48.387Z","repository":{"id":340560064,"uuid":"1166594957","full_name":"irchelper/ainative","owner":"irchelper","description":"AI-native multi-agent workbench: task queue + web UI for coordinating AI agents (SQLite + Go + Vue 3)","archived":false,"fork":false,"pushed_at":"2026-02-27T08:50:05.000Z","size":68934,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-27T10:18:40.226Z","etag":null,"topics":["ai-agents","golang","human-in-the-loop","multi-agent","sqlite","task-queue","vue","workbench"],"latest_commit_sha":null,"homepage":null,"language":"Go","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/irchelper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","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":null,"dco":null,"cla":null}},"created_at":"2026-02-25T11:48:51.000Z","updated_at":"2026-02-27T08:50:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/irchelper/ainative","commit_stats":null,"previous_names":["irchelper/agent-queue","irchelper/ainative"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/irchelper/ainative","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irchelper%2Fainative","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irchelper%2Fainative/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irchelper%2Fainative/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irchelper%2Fainative/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/irchelper","download_url":"https://codeload.github.com/irchelper/ainative/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/irchelper%2Fainative/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30111728,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-05T03:40:26.266Z","status":"ssl_error","status_checked_at":"2026-03-05T03:39:15.902Z","response_time":93,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: 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-agents","golang","human-in-the-loop","multi-agent","sqlite","task-queue","vue","workbench"],"created_at":"2026-03-05T05:04:15.404Z","updated_at":"2026-03-05T05:04:48.374Z","avatar_url":"https://github.com/irchelper.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"[中文文档](./README.zh-CN.md)\n\n# ainative\n\n[![Release](https://img.shields.io/github/v/release/irchelper/ainative?label=release)](https://github.com/irchelper/ainative/releases/tag/v1.0.0)\n[![Go](https://img.shields.io/badge/go-1.22+-00ADD8)](https://go.dev/)\n[![License](https://img.shields.io/badge/license-MIT-blue)](./LICENSE)\n\n**Stop babysitting your AI agents.** ainative is a lightweight task queue with a built-in AI-native workbench UI that lets multiple AI agents coordinate autonomously — no central orchestrator required.\n\nAgents poll for work, claim tasks atomically, and report completion via HTTP. Serial chains run end-to-end without human intervention: when task A finishes, task B unlocks automatically. The next agent picks it up on its next poll cycle.\n\nSingle binary. Zero external dependencies. Runs on your laptop.\n\n---\n\n## What's in v1.0.0\n\n**Task Engine**\n- FSM state machine (8 states: pending → claimed → in_progress → done / failed / cancelled / review / blocked)\n- `depends_on` dependency graph — upstream `done` auto-unlocks downstream\n- `POST /dispatch/chain` serial chains; `POST /dispatch/graph` arbitrary DAG dispatch\n- Dynamic priority (`priority`: 0=normal / 1=high / 2=urgent) — `ORDER BY priority DESC`\n- Batch operations (`POST /api/tasks/bulk`: cancel + reassign)\n- Task templates (`POST /dispatch/from-template/:name`)\n- Human approval nodes in chains\n\n**Reliability**\n- RetryQueue with exponential backoff (30s / 60s / 120s)\n- Auto-retry routing table (`retry_routing`) — failed tasks route to the right agent\n- Stale task recovery — unclaimed tasks re-dispatched after configurable threshold\n- Agent timeout auto-fail\n\n**Notifications**\n- CEO chain/task completion via SessionNotifier\n- Discord per-agent webhook routing\n- Outbound webhook (`AGENT_QUEUE_WEBHOOK_URL`) with HMAC-SHA256 signature\n\n**Web UI (AI Workbench)**\n- Dashboard (task cards, search, multi-select bulk ops), Kanban, TaskDetail with timeline + chain inline view\n- DAG visualization (`/graph`) — Kahn BFS level layout, status-color nodes\n- Agent stats panel (`/stats`) — success rate, avg duration, progress bars\n- Settings page (`/settings`) — webhook status, system info\n- Task comments — threaded, SSE real-time, `Ctrl+Enter` submit\n- i18n Chinese/English toggle (vue-i18n@9, localStorage persistence)\n- Mobile responsive — hamburger menu, breakpoint grid\n\n**API \u0026 Docs**\n- Scalar interactive API docs at `GET /docs` (OpenAPI 3.1, 18 endpoints)\n- SSE real-time updates (`GET /events`)\n- `GET /api/agents/stats` — per-agent aggregated metrics\n- `GET /api/graph/:chain_id` — DAG graph data\n\n---\n\n## Quick Start\n\n\u003e Agent flow: agents poll (`GET /tasks/poll?assigned_to=\u003cagent\u003e`), claim atomically, then PATCH results. For serial workflows, use `POST /dispatch/chain` (or `POST /dispatch` for single tasks).\n\n```bash\n# 1. Clone and build\ngit clone https://github.com/irchelper/ainative.git\ncd ainative\nmake build          # compiles Go binary + embeds frontend\n\n# 2. Start the server\n./agent-queue       # listening on :19827\n\n# 3. Open the dashboard\nopen http://localhost:19827/\n\n# 4. Create your first task\ncurl -s -X POST localhost:19827/tasks \\\n  -H 'Content-Type: application/json' \\\n  -d '{\"title\":\"My first task\",\"assigned_to\":\"coder\"}'\n```\n\nGo 1.22+ required. No database setup needed — SQLite is embedded.\n\n---\n\n## Why ainative?\n\nWithout a persistent task queue, multi-agent systems break in predictable ways:\n\n- **The orchestrator bottleneck**: A \"CEO\" agent must stay online to push each step forward. It sleeps → the chain stalls.\n- **Lost state**: Task status lives in LLM context. Context compression or a new session = lost progress.\n- **Silent failures**: Agents complete work but no one is notified. Users ask \"did it finish?\" instead of being told.\n\nainative moves task state out of agent memory and into SQLite. Any agent can crash and recover. Chains advance automatically. Completions notify you directly.\n\n---\n\n## Features\n\n- **Task queue** — Full CRUD with optimistic locking (`version` field); concurrent claim → 409 Conflict\n- **Dependency graph** — `depends_on` array; upstream `done` → downstream auto-unlocks\n  - V7+: `superseded_by` allows auto-retry to *replace* a failed task without breaking downstream dependencies (deps are satisfied by the superseding retry task).\n- **8-state machine** — `pending → claimed → in_progress → review → done / blocked / failed / cancelled`\n- **Atomic dispatch** — `POST /dispatch` creates task + wakes agent session in one call\n- **Serial chain dispatch** — `POST /dispatch/chain` creates a full chain with `depends_on` wired automatically\n- **CEO notifications** — Task/chain completion notifies CEO session via SessionNotifier (RetryQueue: 30s/60s/120s backoff)\n- **Auto retry routing** — Failed tasks route to the right agent automatically via `retry_routing` table\n  - Use `retry_assigned_to: \u003cagent\u003e` in the failure result to indicate the next assignee; the server creates a follow-up retry task automatically.\n  - `failed` is terminal for the original task (the retry is a new task); deep retry chains are capped to reduce noise.\n- **Stale task recovery** — Unclaimed tasks are re-dispatched after a configurable threshold\n- **Web UI** — Built-in SPA dashboard (Vue 3 + TypeScript + Tailwind); embed.FS, no separate server needed\n- **Discord webhooks** — Per-agent or global webhook for `done`/`failed` notifications\n- **Health check** — `GET /health` for uptime monitoring and launchd/systemd integration\n\n---\n\n## API Reference\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `GET` | `/health` | Service and database health check |\n| `POST` | `/tasks` | Create task (`title`, `assigned_to`, `depends_on`, `notify_ceo_on_complete`, …) |\n| `GET` | `/tasks` | List tasks — filter by `status`, `assigned_to`, `parent_id`, `deps_met` |\n| `GET` | `/tasks/:id` | Task detail with dependency chain and state history |\n| `PATCH` | `/tasks/:id` | Update status/result with optimistic lock (`version` required) |\n| `POST` | `/tasks/:id/claim` | Atomic claim — body: `{\"version\": N, \"agent\": \"name\"}` |\n| `GET` | `/tasks/poll` | Best available task for agent (`?assigned_to=X`); returns `null` if none |\n| `GET` | `/tasks/summary` | Global task counts + active task list |\n| `POST` | `/dispatch` | Create task + trigger agent session; supports `notify_ceo_on_complete` (bool) |\n| `POST` | `/dispatch/chain` | Create full serial chain with auto-set `depends_on` |\n\nFull API spec: [`docs/api/openapi.yaml`](./docs/api/openapi.yaml)\n\n### Agent poll loop (minimal example)\n\n```bash\n# Poll for work\nRESP=$(curl -s \"localhost:19827/tasks/poll?assigned_to=myagent\")\nTASK_ID=$(echo $RESP | jq -r '.task.id // empty')\n\nif [ -n \"$TASK_ID\" ]; then\n  VER=$(echo $RESP | jq -r '.task.version')\n\n  # Claim it\n  curl -s -X POST \"localhost:19827/tasks/$TASK_ID/claim\" \\\n    -H 'Content-Type: application/json' \\\n    -d \"{\\\"version\\\":$VER,\\\"agent\\\":\\\"myagent\\\"}\"\n\n  # Mark in progress\n  curl -s -X PATCH \"localhost:19827/tasks/$TASK_ID\" \\\n    -H 'Content-Type: application/json' \\\n    -d \"{\\\"status\\\":\\\"in_progress\\\",\\\"version\\\":$((VER+1))}\"\n\n  # ... do the work ...\n\n  # Report done\n  curl -s -X PATCH \"localhost:19827/tasks/$TASK_ID\" \\\n    -H 'Content-Type: application/json' \\\n    -d \"{\\\"status\\\":\\\"done\\\",\\\"result\\\":\\\"Work complete\\\",\\\"version\\\":$((VER+2))}\"\nfi\n```\n\nSee [Agent Integration Guide](./docs/guides/agent-integration.md) for patterns, error handling, and OpenClaw setup.\n\n---\n\n## Configuration\n\nainative works out of the box with no configuration. All settings are optional:\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `AGENT_QUEUE_DISCORD_WEBHOOK_URL` | — | Discord Incoming Webhook for task notifications |\n| `AGENT_QUEUE_AGENT_WEBHOOKS` | — | Per-agent webhooks: `agent1=url1,agent2=url2` |\n| `AGENT_QUEUE_OPENCLAW_API_URL` | `http://localhost:18789` | OpenClaw gateway URL (for agent dispatch) |\n| `AGENT_QUEUE_OPENCLAW_API_KEY` | — | OpenClaw gateway token |\n| `AGENT_QUEUE_DB_PATH` | `data/queue.db` | SQLite database path |\n| `AGENT_QUEUE_STALE_CHECK_INTERVAL` | `10m` | How often to scan for stale tasks |\n| `AGENT_QUEUE_STALE_THRESHOLD` | `30m` | Task is stale if unclaimed beyond this |\n| `AGENT_QUEUE_MAX_STALE_DISPATCHES` | `3` | Max re-dispatch attempts before alerting |\n\n### Config file (optional)\n\nCreate `config.yaml` in the working directory:\n\n```yaml\nserver:\n  port: 19827\n  db: data/queue.db\nnotifications:\n  webhook_url: \"https://discord.com/api/webhooks/...\"\n  openclaw_url: \"http://localhost:18789\"\ntimeouts:\n  stale_check_interval: 10m\n  stale_threshold: 30m\n```\n\nSee [Configuration Reference](./docs/guides/configuration.md) for all options.\n\n---\n\n## Deployment\n\n### macOS (launchd)\n\n```bash\nmake build\n# Edit launchd/com.irchelper.agent-queue.plist with your env vars\nbash scripts/launchd-install.sh\ncurl http://localhost:19827/health   # verify\n\nNotes:\n- Update `launchd/com.irchelper.agent-queue.plist` with your real values (e.g. `AGENT_QUEUE_DISCORD_WEBHOOK_URL`, `AGENT_QUEUE_DISCORD_USER_ID`).\n- `KeepAlive: true` means launchd will restart the service if it crashes.\n- After editing the plist, reload the service (`launchctl unload` + `launchctl load`) for changes to take effect.\n- Logs: `~/Library/Logs/agent-queue/` (e.g. `stdout.log`).\n```\n\n### Linux (systemd)\n\n```bash\nmake build\n# Copy agent-queue binary to /usr/local/bin/\n# Create /etc/systemd/system/ainative.service (see docs/guides/configuration.md)\nsystemctl enable --now ainative\n```\n\n### Docker\n\n```bash\ndocker run -p 19827:19827 \\\n  -e AGENT_QUEUE_DISCORD_WEBHOOK_URL=https://... \\\n  -v $(pwd)/data:/app/data \\\n  ghcr.io/irchelper/ainative:latest\n```\n\n---\n\n## Development\n\n```bash\nmake test      # run all tests (with -race)\nmake vet       # go vet\nmake build     # compile Go binary (embeds frontend from dist/)\nmake build-web # build frontend only (cd web \u0026\u0026 npm run build)\nmake clean     # remove binary (safe — does NOT delete database)\nmake clean-all # remove binary + database (destructive)\n```\n\n\u003e **Note:** `make clean-all` permanently deletes all task records. Never run during active execution.\n\nFrontend development (hot reload):\n```bash\nmake dev-api          # start Go API server\ncd web \u0026\u0026 npm run dev # start Vite dev server (proxies API to :19827)\n```\n\n---\n\n## Architecture\n\n- **Storage**: SQLite WAL mode — single file, zero ops, ACID; path via `AGENT_QUEUE_DB_PATH`\n- **Backend**: Go `net/http`, no framework; optimistic locking via `version` field\n- **Frontend**: Vue 3 + TypeScript + Vite + Tailwind; embedded via `embed.FS` (single binary)\n- **Notifications**: Discord Incoming Webhook (user audit) + SessionNotifier (agent wakeup / CEO alerts)\n- **Deployment**: Single binary; launchd (macOS) / systemd (Linux); KeepAlive auto-restart\n\nFull architecture: [`docs/ARCH.md`](./docs/ARCH.md) | Product spec: [`docs/PRD.md`](./docs/PRD.md)\n\n---\n\n## Contributing\n\nSee [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup, coding guidelines, and PR process.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firchelper%2Fainative","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Firchelper%2Fainative","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Firchelper%2Fainative/lists"}