Code Factory

A tree-based collaboration platform for requirements, coding-agent teams, and humans.

Code Factory is a tree-based collaboration platform where requirements, a team of coding agents, and humans work together. Every requirement is a node with its own long-lived RD agent (Codex or Claude Code). An RD agent can split its work into child requirements, and each child gets its own agent and can split further. The result is an agent team shaped like the work itself. Humans steer the whole team by talking to the root requirement, and can step into any node at any time.

Around that tree, Code Factory connects the local workspace, GitHub pull requests, on-demand AI reviewers, and external events routed through Agent Triggers in one local Web dashboard. It is designed for developers and engineering teams who already use Codex or Claude Code but need more than isolated terminal sessions: a way to decompose large work, run many agents in parallel without losing track of them, and keep humans in charge of scope and completion.

flowchart TD
    H([Human]) <-->|chat, steer, confirm| R[Root Requirement<br/>RD agent]
    R <-->|delegate, manage, message| C1[Child Requirement<br/>RD agent]
    R <--> C2[Child Requirement<br/>RD agent]
    C2 <--> G[Grandchild Requirement<br/>RD agent]
    H -.->|can join any node| C1
    C1 --> PR1[Pull request]
    G --> PR2[Pull request]

Loading

Product Positioning

Code Factory combines a requirement tree, an agent team, and a human-in-the-loop delivery workflow:

• Tree-structured work: a large requirement breaks down into a tree of linked child requirements, and the Relationships view shows the whole tree. Agent-proposed children stay in TODO until someone starts them, which prevents uncontrolled recursive work.
• An agent team, one agent per node: every requirement owns exactly one long-lived RD session. Sessions for different requirements run in parallel, while each agent keeps its own native context.
• Managed through conversation: a parent RD agent manages its direct children with code-factory-cli: it starts or retries them, stops a running child, deletes TODO children, confirms finished children, and exchanges durable messages with their agents. Humans manage the whole tree by chatting with the root requirement.
• Human-controlled: people can join any node to add context, queue corrections, interrupt a run, or reply to a finished requirement, and they decide when the work they own is done.
• Delivery-connected: agents open and register pull requests, a short-lived AI Reviewer checks them on request, and Agent Triggers feed GitHub PR status, reviews/comments, CI failures, merge conflicts, and scheduled wake-ups back into the right node. The source-neutral trigger boundary is designed to support systems such as Slack and Jira.
• Local-first: agents run in your existing repository with your installed CLI tools, project instructions, and credentials.

Code Factory is not a hosted IDE or a flat agent pool. Agents are organized by the requirement tree instead of being scheduled from a shared queue, and code execution, Git, and GitHub access stay in the developer's own environment.

The current implementation supports headless Codex and Claude Code agents.

Quick Start

cd /path/to/the/repository/to-manage
npx --package @luoyixin/code-factory code-factory-agent-manager start --daemon

The startup directory becomes the managed workspace. Only one Agent Manager may run for a canonical workspace at a time, even when another port or database path is supplied. The dashboard is available at http://127.0.0.1:4310 by default. Daemon startup failures, including an occupied port, are reported directly to the starting command.

Prerequisites, daemon operation, configuration, CLI options, and log locations are documented in Running Code Factory. To install dependencies or run a source checkout manually, see the Development guide.

How It Works

Each Requirement owns one long-lived RD session. Sessions for different Requirements can run in parallel, but a session has at most one active RD run. Directly related Requirements coordinate through explicit, durable RD-to-RD messages while keeping their native agent contexts isolated.

1. Create. A human creates a Requirement in the dashboard and selects Codex or Claude Code, with optional model and reasoning settings. Agent Manager creates the Requirement and its RD session atomically.
2. Build and delegate. Agent Manager starts or resumes that session in the managed workspace. The RD edits and tests the repository, then uses code-factory-cli to register pull requests, create directly related child Requirements, manage their permitted lifecycle transitions, message their RD agents, or schedule a later wake-up.
3. Continue. The durable Requirement conversation is also the RD delivery stream: Human and Reviewer messages, selected System events, Jev continuations, and explicit related-Agent messages are delivered to RD; the RD's own output is displayed but not fed back as new input. New input stays queued in order, and a running session processes it after the current run unless a human explicitly interrupts. An optional Jev decision considers the Run result and three latest conversation messages after a successful, failed, or timed-out Run ends without newer queued input, an active Reviewer, or an active timer. It can send continue. as Jev immediately or after a short delay, including to retry a recoverable failure. A failed Run retains its attempted input for that retry. An interrupted run with no newer input, a failed run, or a timed-out run leaves the Requirement waiting for confirmation; the Session retains its distinct waiting or failed state until another Run starts.
4. React. Today's Timer and GitHub triggers add deduplicated messages for due wake-ups, PR state changes, reviews and comments, CI failures, and merge conflicts. The source-neutral trigger boundary is designed for future Slack and Jira sources, which are not implemented yet. GitHub and the reconciler—not the RD—own PR lifecycle state.
5. Review. On request, a separate short-lived Reviewer reads the open PR, can publish inline comments, and appends a summary to the Requirement conversation, waking the RD to continue the loop.

SQLite persists Requirements, relationships, conversations, runs, sessions, PR metadata, timers, and trigger receipts across restarts. Related-agent communication becomes new input in the target Requirement; it does not merge the agents' native session contexts.

For the complete domain model, state machines, concurrency rules, and delivery semantics, see Final architecture and domain model.

Web Dashboard

The bundled dashboard provides a relationship tree and four boards:

• Relationship tree: each root Requirement with its parent/child hierarchy; search matches are shown with their ancestors for context
• Requirement board: TODO / DOING / Waiting for confirmation / DONE
• Pull Request board: DRAFT / OPEN / CLOSED / MERGED
• RD Session board: Idle / Running / Waiting for human / Failed / Completed
• Timer board: Active / Completed / Cancelled, with each timer linked to its Requirement

Opening a Requirement shows its description, linked PRs, run information, per-Run Agent trace, and unified Human/RD/Reviewer conversation. Requirement descriptions and conversation messages render GitHub Flavored Markdown, including tables, lists, links, and code blocks. The Session board cards open this work surface directly; the latest Run trace is selected by default and shows Provider-emitted reasoning summaries, tool calls, command/tool results, messages, and errors in real time. Starting a TODO card opens that conversation first, so optional instructions and attachments can be included in the initial Run; it also offers an explicit start-without-instructions action. Before execution starts, a human can change the TODO Requirement's Agent provider, model, and reasoning effort or restore the CLI defaults from this work surface. TODO cards can be deleted before execution; the action requires confirmation and removes the Requirement from active lists. Messages support images and file attachments. The chat composer can create and cancel one-time or recurring scheduled wake-ups in minutes, hours, or days, while the Timer board shows timers across the workspace and opens their associated Requirements. New input can be queued while RD is running; Steering interrupts only when newer input is waiting for the next Run, while Stop Run explicitly pauses the current Run. Replying to a completed Requirement reactivates it and resumes its original RD Session in a new Run. Requirement and Reviewer forms provide provider-specific model dropdowns populated by an Agent Manager catalog that refreshes every 24 hours.

The dashboard supports light and dark modes from the top-right theme control, remembers the selected theme, and follows the operating-system preference until one is selected. It also supports English and Simplified Chinese, remembers the selected locale, and initially follows the browser language. Its settings dialog persists workspace configuration, applies Requirement retention periods and the optional Jev API key at runtime, identifies changes that require a restart, and updates browser-local notification preferences immediately.

Browser notifications default to enabled and can be changed immediately in the settings dialog or from the header bell. A browser still requires an explicit permission grant before it can display notifications. In a Windows browser reached through port forwarding, open the dashboard at http://localhost:<forwarded-port>, use either notification control, and allow notifications for that site. Successful, failed, timed-out, and cancelled RD Runs show their Requirement title and outcome; clicking a notification opens the Requirement. The browser stores the preference locally. Keep the dashboard tab open to receive notifications; browsers require a secure context such as localhost or HTTPS, and the site's notification permission must remain granted.

All four boards share a time-range filter with options for the last 24 hours, 7 days, 30 days, 90 days, or all time. Requirement, PR, and Session boards filter by creation time. The Timer board always retains active timers by their upcoming wake-up and filters completed or cancelled history by its latest update. The default range is 7 days.

The shared search box uses a local hybrid index over Requirement titles and descriptions, complete conversation messages, and Pull Request titles and metadata. Persisted word and character n-gram vectors add similarity ranking to full-text matching, including useful partial and fuzzy matches; Agent Manager also uses SQLite FTS5 ranking when the installed Node.js SQLite build provides it. Search indexing and ranking stay inside the workspace's Agent Manager process and do not call an external embedding service.

The Web dashboard, HTTP API, and SSE event stream run in the same process and use the same port. No separate Web deployment is required.

Security Model

Every headless RD and Reviewer invocation skips interactive CLI approval and sandbox checks. Agents therefore inherit the launching user's filesystem, network, and command-execution permissions. Start Agent Manager only inside a trusted workspace and expose its HTTP port only to trusted users and networks.

Versioning and releases

Code Factory uses Semantic Versioning and is published as @luoyixin/code-factory. The installed version is available through code-factory-agent-manager --version, code-factory-cli --version, the startup banner, and GET /api/health. See the release guide for version preparation, the tag workflow, verification, and recovery rules.

License

Code Factory is licensed under the Apache License 2.0.

Design Documentation

• Running Code Factory
• Development guide
• Final architecture and domain model
• Headless Agent Runner
• Agent Manager HTTP API Reference
• HTTP and event protocol
• Dashboard perceived-latency audit
• Development roadmap
• Release guide

Current Boundaries

The current implementation includes the Agent Manager core, a supervised daemon mode with automatic process restart, SQLite Store, HTTP/SSE API, Codex and Claude Code adapters, conversation-driven RD continuation, persistent scheduled wake-ups, PR tracking, manually triggered Reviewer runs, and the bundled Web dashboard.

The AgentTrigger lifecycle and extension API are currently code-level, and every delivered trigger message must target an existing Requirement. The native Timer Agent Trigger has HTTP, dashboard, and RD CLI configuration, but dynamic third-party trigger discovery/configuration, Slack and Jira sources, and trigger-created Requirements remain future work. GitHub synchronization currently uses local gh polling rather than webhooks. Stale-review indicators after a head-SHA change, local access tokens, detailed tool-execution logs, and Manager-enforced worktree isolation also remain future work. RD Agents are instructed to create or reuse a Requirement-specific Git worktree before changing code, but Agent Manager does not provision or enforce that isolation; every child process still starts in the shared Manager workspace.