{"id":44260582,"url":"https://github.com/supaku/agentfactory","last_synced_at":"2026-03-14T23:44:53.637Z","repository":{"id":337650272,"uuid":"1153964076","full_name":"supaku/agentfactory","owner":"supaku","description":"The open-source software factory — multi-agent fleet management for coding agents","archived":false,"fork":false,"pushed_at":"2026-03-13T17:12:10.000Z","size":2893,"stargazers_count":34,"open_issues_count":0,"forks_count":4,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-14T05:17:01.695Z","etag":null,"topics":["agent","claude","coding-agent","fleet-management","linear","multi-agent","open-source","orchestrator","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/supaku.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-09T21:41:38.000Z","updated_at":"2026-03-13T17:12:14.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/supaku/agentfactory","commit_stats":null,"previous_names":["supaku/agentfactory"],"tags_count":70,"template":false,"template_full_name":null,"purl":"pkg:github/supaku/agentfactory","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supaku%2Fagentfactory","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supaku%2Fagentfactory/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supaku%2Fagentfactory/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supaku%2Fagentfactory/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/supaku","download_url":"https://codeload.github.com/supaku/agentfactory/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/supaku%2Fagentfactory/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30520859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-14T19:51:21.629Z","status":"ssl_error","status_checked_at":"2026-03-14T19:51:12.959Z","response_time":57,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5: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":["agent","claude","coding-agent","fleet-management","linear","multi-agent","open-source","orchestrator","typescript"],"created_at":"2026-02-10T17:07:47.363Z","updated_at":"2026-03-14T23:44:53.605Z","avatar_url":"https://github.com/supaku.png","language":"TypeScript","readme":"# Supaku AgentFactory\n\n[![npm version](https://img.shields.io/npm/v/@supaku/agentfactory)](https://www.npmjs.com/package/@supaku/agentfactory)\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue?logo=typescript)](https://www.typescriptlang.org/)\n[![Linear](https://img.shields.io/badge/Linear-Integrated-5E6AD2?logo=linear)](https://linear.app)\n[![Built with AgentFactory](https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-dark.svg)](https://github.com/supaku/agentfactory)\n\n**The open-source software factory — multi-agent fleet management for coding agents.**\n\nAgentFactory turns your issue backlog into shipped code. It orchestrates a fleet of coding agents (Claude, Codex, Amp) through an automated pipeline: development, QA, and acceptance — like an assembly line for software.\n\n## Packages\n\n| Package | npm | Description |\n|---------|-----|-------------|\n| **[@supaku/agentfactory](./packages/core)** | `@supaku/agentfactory` | Core orchestrator, provider abstraction, crash recovery |\n| **[@supaku/agentfactory-linear](./packages/linear)** | `@supaku/agentfactory-linear` | Linear issue tracker integration |\n| **[@supaku/agentfactory-server](./packages/server)** | `@supaku/agentfactory-server` | Redis work queue, session storage, worker pool |\n| **[@supaku/agentfactory-cli](./packages/cli)** | `@supaku/agentfactory-cli` | CLI tools: orchestrator, workers, Linear CLI (`af-linear`) |\n| **[@supaku/agentfactory-nextjs](./packages/nextjs)** | `@supaku/agentfactory-nextjs` | Next.js route handlers, webhook processor, middleware |\n| **[@supaku/create-agentfactory-app](./packages/create-app)** | `@supaku/create-agentfactory-app` | Project scaffolding tool |\n\n## Quick Start\n\n### One-click deploy (fastest)\n\nDeploy the dashboard with a single click — no local setup required:\n\n| Platform | Deploy | Redis |\n|----------|--------|-------|\n| **Vercel** | [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https%3A%2F%2Fgithub.com%2Fsupaku%2Fagentfactory%2Ftree%2Fmain%2Ftemplates%2Fdashboard\u0026project-name=agentfactory-dashboard\u0026env=LINEAR_ACCESS_TOKEN,LINEAR_WEBHOOK_SECRET,REDIS_URL\u0026envDescription=Environment%20variables%20needed%20for%20AgentFactory%20Dashboard\u0026envLink=https%3A%2F%2Fgithub.com%2Fsupaku%2Fagentfactory%2Ftree%2Fmain%2Ftemplates%2Fdashboard%23environment-variables) | Add [Vercel KV](https://vercel.com/docs/storage/vercel-kv) or [Upstash](https://upstash.com/) after deploy |\n| **Railway** | [![Deploy on Railway](https://railway.com/button.svg)](https://railway.com/deploy/A7hIuF?referralCode=MwgIWL) | Bundled automatically |\n\n\u003e See the [dashboard template](https://github.com/supaku/agentfactory/tree/main/templates/dashboard) for full setup instructions.\n\n### Create a new project (recommended for customization)\n\n```bash\nnpx @supaku/create-agentfactory-app my-agent\n\ncd my-agent\ncp .env.example .env.local    # Fill in LINEAR_ACCESS_TOKEN\npnpm install \u0026\u0026 pnpm dev      # Start webhook server\npnpm worker                   # Start local worker (in another terminal)\n```\n\n### Webhook Server (Next.js)\n\nFor production use, AgentFactory provides a webhook server that receives Linear events and dispatches agents:\n\n```typescript\n// src/lib/config.ts\nimport { createAllRoutes, createDefaultLinearClientResolver } from '@supaku/agentfactory-nextjs'\n\nexport const routes = createAllRoutes({\n  linearClient: createDefaultLinearClientResolver(),\n})\n```\n\n```typescript\n// src/app/webhook/route.ts\nimport { routes } from '@/lib/config'\nexport const POST = routes.webhook.POST\nexport const GET = routes.webhook.GET\n```\n\n### Spawn an agent on a single issue\n\n```typescript\nimport { createOrchestrator } from '@supaku/agentfactory'\n\nconst orchestrator = createOrchestrator({\n  maxConcurrent: 3,\n  worktreePath: '.worktrees',\n})\n\n// Process a single issue\nawait orchestrator.spawnAgentForIssue('PROJ-123')\nawait orchestrator.waitForAll()\n```\n\n### Process your entire backlog\n\n```typescript\nconst orchestrator = createOrchestrator({\n  project: 'MyProject',\n  maxConcurrent: 3,\n})\n\nconst result = await orchestrator.run()\nconsole.log(`Spawned ${result.agents.length} agents`)\n\nawait orchestrator.waitForAll()\n```\n\n### Use the CLI\n\n```bash\n# Process backlog issues from a project\nnpx af-orchestrator --project MyProject --max 3\n\n# Process a single issue\nnpx af-orchestrator --single PROJ-123\n\n# Preview what would be processed\nnpx af-orchestrator --project MyProject --dry-run\n```\n\n### Linear CLI\n\n```bash\n# Get issue details\nnpx af-linear get-issue PROJ-123\n\n# List backlog issues for a project\nnpx af-linear list-backlog-issues --project \"MyProject\"\n\n# Update issue status\nnpx af-linear update-issue PROJ-123 --state \"Finished\"\n\n# Create a comment\nnpx af-linear create-comment PROJ-123 --body \"Work complete\"\n```\n\n## Architecture\n\n```\n┌─────────────────────────────────────────────────┐\n│                  Orchestrator                     │\n│  ┌───────────┐  ┌───────────┐  ┌───────────┐   │\n│  │  Agent 1   │  │  Agent 2   │  │  Agent 3   │   │\n│  │ (Claude)   │  │ (Codex)    │  │ (Claude)   │   │\n│  │ DEV: #123  │  │ QA: #120   │  │ DEV: #125  │   │\n│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘   │\n│        │              │              │           │\n│  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐   │\n│  │ Worktree   │  │ Worktree   │  │ Worktree   │   │\n│  │ .wt/#123   │  │ .wt/#120   │  │ .wt/#125   │   │\n│  └───────────┘  └───────────┘  └───────────┘   │\n└─────────────────────────────────────────────────┘\n         │                    │\n    ┌────┴────┐         ┌────┴────┐\n    │ Linear  │         │  Git    │\n    │  API    │         │  Repo   │\n    └─────────┘         └─────────┘\n```\n\n### Provider Abstraction\n\nAgentFactory supports multiple coding agent providers through a unified interface:\n\n```typescript\ninterface AgentProvider {\n  readonly name: 'claude' | 'codex' | 'amp'\n  spawn(config: AgentSpawnConfig): AgentHandle\n  resume(sessionId: string, config: AgentSpawnConfig): AgentHandle\n}\n\ninterface AgentHandle {\n  sessionId: string | null\n  stream: AsyncIterable\u003cAgentEvent\u003e\n  injectMessage(text: string): Promise\u003cvoid\u003e\n  stop(): Promise\u003cvoid\u003e\n}\n```\n\nProvider is selected via environment variables:\n\n```bash\nAGENT_PROVIDER=claude            # Global default\nAGENT_PROVIDER_QA=codex          # Per-work-type override\nAGENT_PROVIDER_SOCIAL=amp        # Per-project override\n```\n\n### Work Types\n\nIssues flow through work stations based on their status:\n\n| Status | Work Type | Agent Role |\n|--------|-----------|------------|\n| Backlog | `development` | Implement the feature/fix |\n| Started | `inflight` | Continue in-progress work |\n| Finished | `qa` | Validate implementation |\n| Delivered | `acceptance` | Final acceptance testing |\n| Rejected | `refinement` | Address feedback |\n\n### Crash Recovery\n\nAgentFactory includes built-in crash recovery:\n\n1. **Heartbeat monitoring** — agents send periodic health signals\n2. **State persistence** — session state saved to `.agent/` directory\n3. **Automatic resume** — crashed agents are detected and restarted\n4. **Recovery limits** — configurable max recovery attempts\n\n### Inactivity Timeout\n\nAgents are monitored for inactivity:\n\n```typescript\nconst orchestrator = createOrchestrator({\n  inactivityTimeoutMs: 300000,    // 5 minutes default\n  maxSessionTimeoutMs: 7200000,   // 2 hour hard cap\n  workTypeTimeouts: {\n    qa: { inactivityTimeoutMs: 600000 },  // QA gets 10 min\n  },\n})\n```\n\n## Distributed Workers\n\nFor teams that need horizontal scaling, AgentFactory supports a distributed worker pool:\n\n```\n┌────────────────┐     ┌─────────┐     ┌────────────────┐\n│  Webhook Server │────▶│  Redis  │◀────│  Worker Node 1  │\n│  (receives      │     │  Queue  │     │  (claims work)  │\n│   issues)       │     │         │     └────────────────┘\n└────────────────┘     │         │     ┌────────────────┐\n                       │         │◀────│  Worker Node 2  │\n                       │         │     │  (claims work)  │\n                       └─────────┘     └────────────────┘\n```\n\nThis requires the `@supaku/agentfactory-server` package and a Redis instance.\n\n## Configuration\n\n### Environment Variables\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `LINEAR_ACCESS_TOKEN` | Yes | Linear API key (used by Next.js webhook server) |\n| `LINEAR_API_KEY` | Yes | Linear API key (used by CLI tools) |\n| `AGENT_PROVIDER` | No | Default provider: `claude`, `codex`, `amp` (default: `claude`) |\n| `LINEAR_TEAM_ID` | No | Linear team UUID |\n| `REDIS_URL` | For distributed | Redis connection URL |\n\n\u003e **Note:** Set both `LINEAR_ACCESS_TOKEN` and `LINEAR_API_KEY` to the same value, or see [Configuration](./docs/configuration.md) for details.\n\n### Orchestrator Config\n\n```typescript\ninterface OrchestratorConfig {\n  provider?: AgentProvider           // Agent provider instance\n  maxConcurrent?: number             // Max concurrent agents (default: 3)\n  project?: string                   // Project name filter\n  worktreePath?: string              // Git worktree base path (default: .worktrees)\n  linearApiKey?: string              // Linear API key\n  autoTransition?: boolean           // Auto-update issue status (default: true)\n  sandboxEnabled?: boolean           // Enable agent sandboxing (default: false)\n  inactivityTimeoutMs?: number       // Inactivity timeout (default: 300000)\n  maxSessionTimeoutMs?: number       // Hard session cap\n  workTypeTimeouts?: Record\u003cstring, WorkTypeTimeoutConfig\u003e\n}\n```\n\n## Linear Integration\n\nThe `@supaku/agentfactory-linear` package provides:\n\n- **Agent sessions** — lifecycle management with status transitions\n- **Activity streaming** — thoughts, actions, and responses visible in Linear\n- **Plan tracking** — task checklists with progress states\n- **Work routing** — automatic work type detection from issue status\n- **Sub-issue coordination** — dependency-aware parallel execution\n\n```typescript\nimport { createLinearAgentClient, createAgentSession } from '@supaku/agentfactory-linear'\n\nconst client = createLinearAgentClient({ apiKey: process.env.LINEAR_API_KEY! })\nconst session = createAgentSession({\n  client: client.linearClient,\n  issueId: 'issue-uuid',\n  autoTransition: true,\n  workType: 'development',\n})\n\nawait session.start()\nawait session.emitThought('Analyzing requirements...')\nawait session.complete('Feature implemented with tests')\n```\n\n### Setting Up Linear\n\n**1. Create a Linear API Key**\n\nGo to [Linear Settings \u003e API](https://linear.app/settings/api) and create a **Personal API Key** (starts with `lin_api_`).\n\n**2. Configure the Webhook**\n\nIn Linear Settings \u003e API \u003e Webhooks, create a webhook:\n\n- **URL:** `https://your-app.example.com/webhook`\n- **Events to subscribe:** `AgentSession` (created, updated, prompted) and `Issue` (updated)\n- Copy the **Signing Secret** — this is your `LINEAR_WEBHOOK_SECRET`\n\nThe webhook signature is verified using HMAC-SHA256 via the `linear-signature` header. Verification is enforced in production and optional in development.\n\n**3. Set Environment Variables**\n\n| Variable | Required | Description |\n|----------|----------|-------------|\n| `LINEAR_ACCESS_TOKEN` | Yes | API key for the Next.js webhook server |\n| `LINEAR_API_KEY` | Yes | API key for CLI tools (can be the same value as above) |\n| `LINEAR_WEBHOOK_SECRET` | Production | Signing secret from your Linear webhook |\n| `LINEAR_CLIENT_ID` | No | OAuth app client ID (multi-workspace only) |\n| `LINEAR_CLIENT_SECRET` | No | OAuth app client secret (multi-workspace only) |\n| `NEXT_PUBLIC_APP_URL` | No | App URL for OAuth redirects (default: `http://localhost:3000`) |\n| `REDIS_URL` | Distributed mode | Redis connection URL for worker pool and OAuth token storage |\n\n\u003e **Tip:** `LINEAR_ACCESS_TOKEN` and `LINEAR_API_KEY` can be the same key. The server uses `LINEAR_ACCESS_TOKEN`; CLI tools use `LINEAR_API_KEY`.\n\nFor the full environment variable reference and OAuth setup, see the [Getting Started guide](./docs/getting-started.md) and [Configuration reference](./docs/configuration.md).\n\n## Agent Definitions\n\nAgent definitions tell coding agents how to behave at each stage of the pipeline. See [examples/agent-definitions](./examples/agent-definitions) for ready-to-use templates:\n\n| Definition | Stage | What it does |\n|-----------|-------|-------------|\n| [developer.md](./examples/agent-definitions/developer.md) | Development | Implements features, fixes bugs, creates PRs |\n| [qa-reviewer.md](./examples/agent-definitions/qa-reviewer.md) | QA | Validates implementation, runs tests |\n| [coordinator.md](./examples/agent-definitions/coordinator.md) | Coordination | Orchestrates parallel sub-issues |\n| [acceptance-handler.md](./examples/agent-definitions/acceptance-handler.md) | Acceptance | Validates, merges PRs, cleans up |\n| [backlog-writer.md](./examples/agent-definitions/backlog-writer.md) | Planning | Transforms plans into Linear issues |\n\nPlace your definitions in `.claude/agents/` at the root of your repository. Customize them for your stack — add your test commands, framework patterns, and deployment checks.\n\n## Development\n\n```bash\n# Install dependencies\npnpm install\n\n# Build all packages\npnpm build\n\n# Run type checking\npnpm typecheck\n\n# Run tests\npnpm test\n```\n\n## Built with AgentFactory\n\nAgentFactory powers real products in production:\n\n| Product | What it does |\n|---------|-------------|\n| [Supaku Social](https://supaku.com/products/social) | AI-powered social media management |\n| [Supaku Art](https://art.supaku.com) | Art collection curation platform |\n| [Supaku Account](https://account.supaku.com) | Unified auth across the Supaku ecosystem |\n\nBuilding with AgentFactory? Add the badge to your project and [share it in Discussions](https://github.com/supaku/agentfactory/discussions).\n\n## Badge\n\nIf you're building with AgentFactory, add the badge to your README:\n\n\u003c!-- Dark badge (default) --\u003e\n[![Built with AgentFactory](https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with.svg)](https://github.com/supaku/agentfactory)\n\n\u003c!-- Light badge (for dark READMEs) --\u003e\n[![Built with AgentFactory](https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-light.svg)](https://github.com/supaku/agentfactory)\n\nOr use HTML for GitHub theme-switching (auto light/dark):\n\n```html\n\u003ca href=\"https://github.com/supaku/agentfactory\"\u003e\n  \u003cpicture\u003e\n    \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-dark.svg\"\u003e\n    \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-light.svg\"\u003e\n    \u003cimg alt=\"Built with AgentFactory\" src=\"https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with.svg\"\u003e\n  \u003c/picture\u003e\n\u003c/a\u003e\n```\n\n## License\n\nMIT - see [LICENSE](./LICENSE)\n\n---\n\nBuilt by [Supaku](https://supaku.com)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupaku%2Fagentfactory","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsupaku%2Fagentfactory","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsupaku%2Fagentfactory/lists"}