Supaku AgentFactory

The open-source software factory — multi-agent fleet management for coding agents.

AgentFactory turns your issue backlog into shipped code. It orchestrates a fleet of coding agents (Claude, Codex, Spring AI) through an automated pipeline: development, QA, and acceptance — like an assembly line for software.

Packages

Package	npm	Description
@supaku/agentfactory	`@supaku/agentfactory`	Core orchestrator, provider abstraction, crash recovery
@supaku/agentfactory-linear	`@supaku/agentfactory-linear`	Linear issue tracker integration
@supaku/agentfactory-server	`@supaku/agentfactory-server`	Redis work queue, session storage, worker pool
@supaku/agentfactory-cli	`@supaku/agentfactory-cli`	CLI tools: orchestrator, workers, Linear CLI (`af-linear`)
@supaku/agentfactory-nextjs	`@supaku/agentfactory-nextjs`	Next.js route handlers, webhook processor, middleware
@supaku/agentfactory-mcp	`@supaku/agentfactory-mcp`	MCP server exposing fleet capabilities to external clients
@supaku/create-agentfactory-app	`@supaku/create-agentfactory-app`	Project scaffolding tool

Quick Start

One-click deploy (fastest)

Deploy the dashboard with a single click — no local setup required:

Platform	Deploy	Redis
Vercel		Add Vercel KV or Upstash after deploy
Railway		Bundled automatically

See the dashboard template for full setup instructions.

Create a new project (recommended for customization)

npx @supaku/create-agentfactory-app my-agent

cd my-agent
cp .env.example .env.local    # Fill in LINEAR_ACCESS_TOKEN
pnpm install && pnpm dev      # Start webhook server
pnpm worker                   # Start local worker (in another terminal)

Webhook Server (Next.js)

For production use, AgentFactory provides a webhook server that receives Linear events and dispatches agents:

// src/lib/config.ts
import { createAllRoutes, createDefaultLinearClientResolver } from '@supaku/agentfactory-nextjs'

export const routes = createAllRoutes({
  linearClient: createDefaultLinearClientResolver(),
})

// src/app/webhook/route.ts
import { routes } from '@/lib/config'
export const POST = routes.webhook.POST
export const GET = routes.webhook.GET

Spawn an agent on a single issue

import { createOrchestrator } from '@supaku/agentfactory'

const orchestrator = createOrchestrator({
  maxConcurrent: 3,
  worktreePath: '.worktrees',
})

// Process a single issue
await orchestrator.spawnAgentForIssue('PROJ-123')
await orchestrator.waitForAll()

Process your entire backlog

const orchestrator = createOrchestrator({
  project: 'MyProject',
  maxConcurrent: 3,
})

const result = await orchestrator.run()
console.log(`Spawned ${result.agents.length} agents`)

await orchestrator.waitForAll()

Use the CLI

# Process backlog issues from a project
npx af-orchestrator --project MyProject --max 3

# Process a single issue
npx af-orchestrator --single PROJ-123

# Preview what would be processed
npx af-orchestrator --project MyProject --dry-run

Linear CLI

# Get issue details
npx af-linear get-issue PROJ-123

# List backlog issues for a project
npx af-linear list-backlog-issues --project "MyProject"

# Update issue status
npx af-linear update-issue PROJ-123 --state "Finished"

# Create a comment
npx af-linear create-comment PROJ-123 --body "Work complete"

Architecture

┌─────────────────────────────────────────────────┐
│                  Orchestrator                     │
│  ┌───────────┐  ┌───────────┐  ┌───────────┐   │
│  │  Agent 1   │  │  Agent 2   │  │  Agent 3   │   │
│  │ (Claude)   │  │ (Codex)    │  │ (Claude)   │   │
│  │ DEV: #123  │  │ QA: #120   │  │ DEV: #125  │   │
│  └─────┬─────┘  └─────┬─────┘  └─────┬─────┘   │
│        │              │              │           │
│  ┌─────┴─────┐  ┌─────┴─────┐  ┌─────┴─────┐   │
│  │ Worktree   │  │ Worktree   │  │ Worktree   │   │
│  │ .wt/#123   │  │ .wt/#120   │  │ .wt/#125   │   │
│  └───────────┘  └───────────┘  └───────────┘   │
└─────────────────────────────────────────────────┘
         │                    │
    ┌────┴────┐         ┌────┴────┐
    │ Linear  │         │  Git    │
    │  API    │         │  Repo   │
    └─────────┘         └─────────┘

Provider Abstraction

AgentFactory supports multiple coding agent providers through a unified interface:

interface AgentProvider {
  readonly name: 'claude' | 'codex' | 'spring-ai'
  spawn(config: AgentSpawnConfig): AgentHandle
  resume(sessionId: string, config: AgentSpawnConfig): AgentHandle
}

interface AgentHandle {
  sessionId: string | null
  stream: AsyncIterable<AgentEvent>
  injectMessage(text: string): Promise<void>
  stop(): Promise<void>
}

Spring AI support means enterprise Java teams can orchestrate Spring AI-based agents in the same fleet as Claude and Codex agents, with the same pipeline, governance, and cost tracking.

Provider is selected via environment variables:

AGENT_PROVIDER=claude            # Global default
AGENT_PROVIDER_QA=codex          # Per-work-type override
AGENT_PROVIDER_SOCIAL=spring-ai  # Per-project override

Agent-to-Agent Protocol (A2A)

AgentFactory implements the A2A protocol (v0.3.0), operating as both client and server.

Client mode: Invoke remote A2A agents (Spring AI or any A2A-compliant agent) as part of an orchestrated fleet. Route specific work types to external agents via environment config.
Server mode: Expose fleet capabilities via /.well-known/agent-card.json discovery and JSON-RPC task submission. Any A2A-aware tool can submit work to the fleet.

This enables mixed fleets across languages, frameworks, and infrastructure with no coupling.

MCP Server

Fleet capabilities are exposed as an MCP server. Any MCP-aware client (Claude Desktop, Spring AI apps, IDE agents) can interact with the fleet.

Tools:

Tool	Description
`submit-task`	Submit a new task to the fleet
`get-task-status`	Check status of a running task
`list-fleet`	List active agents and their assignments
`get-cost-report`	Retrieve cost tracking data
`stop-agent`	Stop a running agent
`forward-prompt`	Send a prompt to a specific agent

Resources:

URI	Description
`fleet://agents`	Current fleet state
`fleet://issues/{id}`	Issue progress details
`fleet://logs/{id}`	Agent execution logs

Transport: Streamable HTTP for remote access, STDIO for local CLI.

Spring AI Bench

AgentFactory agents can be evaluated through Spring AI Bench. The multi-agent pipeline (dev, QA, acceptance) improves benchmark reliability over single-agent runs.

Work Types

Issues flow through work stations based on their status:

Status	Work Type	Agent Role
Backlog	`development`	Implement the feature/fix
Started	`inflight`	Continue in-progress work
Finished	`qa`	Validate implementation
Delivered	`acceptance`	Final acceptance testing
Rejected	`refinement`	Address feedback

Crash Recovery

AgentFactory includes built-in crash recovery:

Heartbeat monitoring — agents send periodic health signals
State persistence — session state saved to .agent/ directory
Automatic resume — crashed agents are detected and restarted
Recovery limits — configurable max recovery attempts

Inactivity Timeout

Agents are monitored for inactivity:

const orchestrator = createOrchestrator({
  inactivityTimeoutMs: 300000,    // 5 minutes default
  maxSessionTimeoutMs: 7200000,   // 2 hour hard cap
  workTypeTimeouts: {
    qa: { inactivityTimeoutMs: 600000 },  // QA gets 10 min
  },
})

Distributed Workers

For teams that need horizontal scaling, AgentFactory supports a distributed worker pool:

┌────────────────┐     ┌─────────┐     ┌────────────────┐
│  Webhook Server │────▶│  Redis  │◀────│  Worker Node 1  │
│  (receives      │     │  Queue  │     │  (claims work)  │
│   issues)       │     │         │     └────────────────┘
└────────────────┘     │         │     ┌────────────────┐
                       │         │◀────│  Worker Node 2  │
                       │         │     │  (claims work)  │
                       └─────────┘     └────────────────┘

This requires the @supaku/agentfactory-server package and a Redis instance.

Configuration

Environment Variables

Variable	Required	Description
`LINEAR_ACCESS_TOKEN`	Yes	Linear API key (used by Next.js webhook server)
`LINEAR_API_KEY`	Yes	Linear API key (used by CLI tools)
`AGENT_PROVIDER`	No	Default provider: `claude`, `codex`, `spring-ai` (default: `claude`)
`LINEAR_TEAM_ID`	No	Linear team UUID
`REDIS_URL`	For distributed	Redis connection URL

Note: Set both LINEAR_ACCESS_TOKEN and LINEAR_API_KEY to the same value, or see Configuration for details.

Orchestrator Config

interface OrchestratorConfig {
  provider?: AgentProvider           // Agent provider instance
  maxConcurrent?: number             // Max concurrent agents (default: 3)
  project?: string                   // Project name filter
  worktreePath?: string              // Git worktree base path (default: .worktrees)
  linearApiKey?: string              // Linear API key
  autoTransition?: boolean           // Auto-update issue status (default: true)
  sandboxEnabled?: boolean           // Enable agent sandboxing (default: false)
  inactivityTimeoutMs?: number       // Inactivity timeout (default: 300000)
  maxSessionTimeoutMs?: number       // Hard session cap
  workTypeTimeouts?: Record<string, WorkTypeTimeoutConfig>
}

Linear Integration

The @supaku/agentfactory-linear package provides:

Agent sessions — lifecycle management with status transitions
Activity streaming — thoughts, actions, and responses visible in Linear
Plan tracking — task checklists with progress states
Work routing — automatic work type detection from issue status
Sub-issue coordination — dependency-aware parallel execution

import { createLinearAgentClient, createAgentSession } from '@supaku/agentfactory-linear'

const client = createLinearAgentClient({ apiKey: process.env.LINEAR_API_KEY! })
const session = createAgentSession({
  client: client.linearClient,
  issueId: 'issue-uuid',
  autoTransition: true,
  workType: 'development',
})

await session.start()
await session.emitThought('Analyzing requirements...')
await session.complete('Feature implemented with tests')

Setting Up Linear

1. Create a Linear API Key

Go to Linear Settings > API and create a Personal API Key (starts with lin_api_).

2. Configure the Webhook

In Linear Settings > API > Webhooks, create a webhook:

URL: https://your-app.example.com/webhook
Events to subscribe: AgentSession (created, updated, prompted) and Issue (updated)
Copy the Signing Secret — this is your LINEAR_WEBHOOK_SECRET

The webhook signature is verified using HMAC-SHA256 via the linear-signature header. Verification is enforced in production and optional in development.

3. Set Environment Variables

Variable	Required	Description
`LINEAR_ACCESS_TOKEN`	Yes	API key for the Next.js webhook server
`LINEAR_API_KEY`	Yes	API key for CLI tools (can be the same value as above)
`LINEAR_WEBHOOK_SECRET`	Production	Signing secret from your Linear webhook
`LINEAR_CLIENT_ID`	No	OAuth app client ID (multi-workspace only)
`LINEAR_CLIENT_SECRET`	No	OAuth app client secret (multi-workspace only)
`NEXT_PUBLIC_APP_URL`	No	App URL for OAuth redirects (default: `http://localhost:3000`)
`REDIS_URL`	Distributed mode	Redis connection URL for worker pool and OAuth token storage

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.

For the full environment variable reference and OAuth setup, see the Getting Started guide and Configuration reference.

Agent Definitions

Agent definitions tell coding agents how to behave at each stage of the pipeline. See examples/agent-definitions for ready-to-use templates:

Definition	Stage	What it does
developer.md	Development	Implements features, fixes bugs, creates PRs
qa-reviewer.md	QA	Validates implementation, runs tests
coordinator.md	Coordination	Orchestrates parallel sub-issues
acceptance-handler.md	Acceptance	Validates, merges PRs, cleans up
backlog-writer.md	Planning	Transforms plans into Linear issues

Place 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.

Development

# Install dependencies
pnpm install

# Build all packages
pnpm build

# Run type checking
pnpm typecheck

# Run tests
pnpm test

Built with AgentFactory

AgentFactory powers real products in production:

Product	What it does
Supaku Social	AI-powered social media management
Supaku Art	Art collection curation platform
Supaku Account	Unified auth across the Supaku ecosystem

Building with AgentFactory? Add the badge to your project and share it in Discussions.

Badge

If you're building with AgentFactory, add the badge to your README:

Or use HTML for GitHub theme-switching (auto light/dark):

<a href="https://github.com/supaku/agentfactory">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with-light.svg">
    <img alt="Built with AgentFactory" src="https://raw.githubusercontent.com/supaku/agentfactory/main/docs/assets/badge-built-with.svg">
  </picture>
</a>

License

MIT - see LICENSE

Built by Supaku

Name		Name	Last commit message	Last commit date
Latest commit History 195 Commits
.agentfactory		.agentfactory
.githooks		.githooks
.github		.github
docs		docs
examples		examples
packages		packages
scripts		scripts
templates/dashboard		templates/dashboard
.gitignore		.gitignore
.gitleaks.toml		.gitleaks.toml
.gitleaksignore		.gitleaksignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
SECURITY.md		SECURITY.md
package.json		package.json
pnpm-lock.yaml		pnpm-lock.yaml
pnpm-workspace.yaml		pnpm-workspace.yaml
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Supaku AgentFactory

Packages

Quick Start

One-click deploy (fastest)

Create a new project (recommended for customization)

Webhook Server (Next.js)

Spawn an agent on a single issue

Process your entire backlog

Use the CLI

Linear CLI

Architecture

Provider Abstraction

Agent-to-Agent Protocol (A2A)

MCP Server

Spring AI Bench

Work Types

Crash Recovery

Inactivity Timeout

Distributed Workers

Configuration

Environment Variables

Orchestrator Config

Linear Integration

Setting Up Linear

Agent Definitions

Development

Built with AgentFactory

Badge

License

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 75

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages