What You Get

Every agent the factory generates is a self-contained TypeScript file built on octoflow-core — which ships production-grade agent protocols out of the box:

| Protocol / Feature | What it means for your agents | |--------------------|-------------------------------| | A2A (Agent-to-Agent) | Agents can discover and call each other over a standard protocol | | AG-UI streaming | Real-time token streaming with a structured UI event contract | | MCP tool support | Drop in any MCP tool server without custom adapter code | | Multi-backend routing | Switch between Claude, OpenAI, Gemini, or Ollama — same agent code | | Supervisor / pipeline topologies | Multi-agent orchestration wired from a single config | | Memory + RAG | Persistent recall via octoflow-brain with SQLite vector store | | Observability | Structured tracing and lifecycle hooks baked into the runtime |

No configuration. No boilerplate. These capabilities are active the moment createAgent() is called.

How It Works

You describe it
    ↓
Factory researches OctoFlow API via octocode-mcp (real GitHub source — no hallucinations)
    ↓
Factory presents a plan and waits for your approval
    ↓
Factory generates agent.ts, then runs it and fixes any errors it surfaces
    ↓
Factory shows you the output
    ↓
You own a working, standalone TypeScript agent

The factory is a conversational Pi TUI session wired with four tools (create, list, run, delete) and a live connection to octocode-mcp for API research.

Demo — Local Image to Text (Ollama)

https://github.com/user-attachments/assets/aa05d951-b96b-4669-aaf4-4e1ad26c86cc

Requirements

| Requirement | Why | How to get it | |-------------|-----|---------------| | Node.js ≥ 20 | Runs the CLI, npm install, and npx tsx agent.ts | nodejs.org | | LLM backend | Powers the builder agent | Set ANTHROPIC_API_KEY, OPENAI_API_KEY, GOOGLE_GENERATIVE_AI_API_KEY, or run Ollama locally | | GitHub auth (recommended) | Lets the factory research the OctoFlow API from real source via octocode-mcp | gh auth login once, or set GITHUB_TOKEN |

About octocode-mcp. The factory launches octocode-mcp automatically on startup (via npx, no install needed). It uses the GitHub CLI (gh) under the hood, so you need either gh auth login done once or a GITHUB_TOKEN env var. Without GitHub auth the factory still works — it falls back to its bundled create-agent-app skill (less grounded, still functional).

Quick Start

# 1. Install
npm install -g octoflow-agent-factory-cli

# 2. Set a backend key (or use Ollama — see below for zero-key setup)
export ANTHROPIC_API_KEY=sk-ant-...

# 3. (Recommended) Authenticate GitHub so the factory can research the API
#    octocode-mcp is launched automatically via npx — no install needed.
gh auth login   # or set a GITHUB_TOKEN env var

# 4. Launch
octoflow-factory

.env files in your working directory are loaded automatically.

From the monorepo:

npm run -w octoflow-agent-factory-cli start

Zero-key setup with Ollama

# Install Ollama
brew install ollama                     # macOS — see ollama.com for Linux/Windows

# Pull a model (llama3.2 is a solid speed/quality balance on consumer hardware; any Ollama model works)
ollama pull llama3.2

# Launch the factory pointing at your local model
ollama serve &
OCTOFLOW_MODEL=ollama/llama3.2 octoflow-factory

Tip: switch models any time inside the TUI with /model.

The Two Engines

Pi TUI — the terminal interface

The factory runs inside Pi, a minimal conversational TUI built for agentic workflows. Pi handles sessions, model routing, skills, and streaming output — the factory adds its four agent-management tools and a bundled create-agent-app skill on top.

# All Pi flags work with octoflow-factory
octoflow-factory                        # fresh session
octoflow-factory -c                     # continue last session
octoflow-factory -r                     # pick a past session from a list
octoflow-factory -p "list my agents"    # non-interactive one-shot
octoflow-factory --model sonnet:high    # model + thinking level

TUI commands: /model /tree /new /resume /fork /compact /settings /hotkeys /agents /exit

octocode-mcp — the research brain

Before writing a single line, the factory queries your live OctoFlow source on GitHub via octocode-mcp. This is what keeps generated agents accurate: every API call has been verified against real source — not docs, not training data.

Tools active during every session:
  ghSearchCode      — search OctoFlow source on GitHub
  ghGetFileContent  — read exact file to verify an API signature
  localSearchCode   — search your local workspace
  npmSearch         — confirm package versions
  lspGetSemantics   — resolve TypeScript types precisely

If octocode-mcp is unavailable the factory degrades gracefully to its bundled create-agent-app skill.

Your First Agent

> Build me an agent that fetches Hacker News top stories and summarises them

The factory will:

1. Research OctoFlow web-fetch and summarisation patterns via octocode
2. Map the task to the right packages (octoflow-core + octoflow-tools)
3. Show you the full architecture plan — confirm or redirect
4. Generate agent.ts, save it to ~/.octoflow/agents/hn-summariser/, and install its dependencies
5. Run it, fix anything it surfaces, and confirm with run instructions

> Run it

  ✓ exit: 0   duration: 4 823 ms
  Top 5 HN stories today:
  1. "TypeScript 6 announced" — 1 842 points
  2. ...

> List all agents
> Run hn-summariser with input "only AI stories"
> Delete hn-summariser

More Examples

Multi-agent code review

> Create a supervisor that runs a security reviewer and a performance reviewer
  in parallel, then synthesises their findings into a single markdown report

Maps to octoflow-core's supervisor topology — one leader LLM coordinates two workers, each on its own backend.

Memory-enabled research agent

> Build an agent that researches a topic on the web, stores what it finds,
  and answers follow-up questions from memory without re-fetching

Generates an agent using octoflow-brain with autoRecall + autoRemember against a local SQLite vector store.

Platform bot

> Create a Slack bot that monitors #incidents and drafts a summary every hour

Generates an agent using octoflow-adapters with the Slack adapter + octoflow-plugins scheduler.

Generated Agent Structure

Agents land in ~/.octoflow/agents/<slug>/ in your home directory:

~/.octoflow/agents/
└── hn-summariser/
    ├── agent.ts       ← complete, runnable TypeScript — the only file you need
    ├── README.md      ← mermaid diagram + usage instructions
    ├── meta.json      ← name, slug, run history, timestamps
    └── package.json   ← ESM config + the octoflow-* deps detected from the source

The factory installs the agent's dependencies into its folder on first run. To run it yourself:

cd ~/.octoflow/agents/hn-summariser
npm install            # first time only — installs the octoflow-* deps
npx tsx agent.ts
# with optional input
AGENT_INPUT="only AI stories from today" npx tsx agent.ts

Every agent.ts follows the same shape:

import { createAgent, discoverAvailableBackends, extractText } from 'octoflow-core';
// plus imports from octoflow-tools, octoflow-brain, etc. as the task needs

const discovery = await discoverAvailableBackends();
const agent = await createAgent({
  priority: discovery.ready.map((b) => b.backend),
  fallback: true,
});
try {
  const result = await agent.sendMessage({
    message: process.env['AGENT_INPUT'] ?? 'default task',
  });
  console.log(extractText(result));
} finally {
  await agent.close();
}

• Imports only from octoflow-* packages — no raw SDK calls
• A2A, AG-UI, and MCP protocols are active by default through octoflow-core
• Picks a backend via discoverAvailableBackends() so it runs against whatever is installed
• Accepts AGENT_INPUT env var as optional prompt
• Always cleans up with agent.close()

import { createAgent } from 'octoflow-core';   // ← always the entry point
// imports from octoflow-tools, octoflow-brain, etc. as needed

## OctoFlow Packages

The factory selects the right packages automatically and installs them from npm.

| Package | Role |
|---------|------|
| [`octoflow-core`](https://www.npmjs.com/package/octoflow-core) ★ | **Main runtime** — `createAgent()`, all backends, topologies, A2A, AG-UI, MCP |
| [`octoflow-tools`](https://www.npmjs.com/package/octoflow-tools) | Ready-made tool presets (filesystem, git, web, SQL, Docker…) |
| [`octoflow-brain`](https://www.npmjs.com/package/octoflow-brain) | Persistent memory + RAG — SQLite/vector store, `autoRecall` |
| [`octoflow-adapters`](https://www.npmjs.com/package/octoflow-adapters) | Platform bots — Slack, Discord, Telegram, WhatsApp, Teams… |
| [`octoflow-react`](https://www.npmjs.com/package/octoflow-react) | React AG-UI chat — `OctoFlowProvider`, `useOctoFlowChat` |
| [`octoflow-plugins`](https://www.npmjs.com/package/octoflow-plugins) | Scheduler, curator, TUI — `createSchedulerPlugin()` |

---

## The ReAct Loop

Before writing any code the factory runs a grounded research loop:

REASON — identify which OctoFlow features the agent needs ACT — search octocode-mcp for real examples and exact API shapes OBSERVE — read the source; confirm imports and option signatures ↑ repeat until every feature has a verified code pattern PLAN — present the full architecture and wait for your approval GENERATE — write agent.ts using only confirmed patterns VALIDATE — run the agent (run_agent); read the output and fix anything it surfaces DELIVER — print run command + env vars + next-step suggestions

---

## Choosing the Builder Model

The **builder** is the LLM inside the TUI that researches, plans, and generates agents. Three ways to set it (highest priority wins):

```bash
# Environment variable — format: provider/modelId or just modelId (defaults to anthropic)
OCTOFLOW_MODEL=anthropic/claude-opus-4-8 octoflow-factory
OCTOFLOW_MODEL=ollama/llama3.2 octoflow-factory

# CLI flag — supports provider prefix and thinking level
octoflow-factory --model anthropic/claude-opus-4-8
octoflow-factory --model sonnet:high

# Inside the TUI — persisted to Pi settings
/model

Flow: From Prompt to Running Agent

flowchart TD
    U(["You\nnatural language"])

    subgraph CLI["OctoFlow Agent Factory CLI"]
        direction TB
        Bin["bin/factory.js\nspawns Pi with extension"]
        Pi["Pi TUI\nearendil-works/pi"]
        Ext["extension.ts\nhooks · tools · branding"]
        Prompt["System Prompt\n+ live backend context\n+ create-agent-app skill"]
        Builder(["Builder Agent\nLLM inside Pi\nresearch · plan · generate"])
        Tools["Factory Tools\ncreate_agent_flow\nlist_agents · run_agent · delete_agent"]
        Registry[("Agent Registry\n~/.octoflow/agents/")]
    end

    subgraph Research["octocode-mcp  bgauryy/octocode"]
        direction TB
        MCP["octocode-mcp server"]
        GH["OctoFlow source\non GitHub"]
        Local["Local workspace"]
    end

    subgraph AgentRuntime["Generated agent.ts  →  octoflow-core"]
        direction TB
        CA["createAgent()\nentry point"]

        subgraph Protocols["Protocols  OOTB"]
            A2A["A2A\nAgent-to-Agent"]
            AGUI["AG-UI\nstreaming"]
            MCP2["MCP\ntool servers"]
        end

        subgraph Topologies["Topologies"]
            Solo["solo agent"]
            Sup["supervisor\n+ workers"]
            Pipe["pipeline"]
        end

        subgraph SubAgents["Sub-agents  via createSubagentAction()"]
            SA1["Worker A"]
            SA2["Worker B"]
            SA3["Worker N…"]
        end

        Extra["octoflow-tools\noctoflow-brain\noctoflow-adapters…"]
        Backend[("LLM Backend\nClaude · OpenAI\nGemini · Ollama")]
    end

    U -->|"describe the agent"| Bin
    Bin --> Pi
    Pi --> Ext
    Ext -->|"registers tools + merges prompt"| Builder
    Ext --> Prompt
    Prompt -.->|"context"| Builder

    Builder -->|"1. research API"| MCP
    MCP --> GH
    MCP --> Local

    Builder -->|"2. call create_agent_flow"| Tools
    Tools -->|"save agent.ts"| Registry

    Builder -->|"3. call run_agent"| Registry
    Registry -->|"npx tsx agent.ts"| CA

    CA --> Protocols
    CA --> Topologies
    Topologies -->|"createSubagentAction()"| SubAgents
    CA --> Extra
    Extra --> Backend
    SubAgents --> Backend

Key insight — the main agent is the factory

When the factory calls run_agent, it spawns the generated agent.ts as a subprocess. That agent uses octoflow-core's createAgent() which can itself call createSubagentAction() to spin up further child agents — each connected to any backend, each inheriting the full protocol stack (A2A, AG-UI, MCP) without any extra setup.

You
 └─ Builder Agent (Pi TUI)        ← factory's LLM, orchestrates creation
     └─ createAgent()             ← octoflow-core, main agent in agent.ts
         ├─ Worker A              ← via createSubagentAction()
         ├─ Worker B              ← via createSubagentAction()
         └─ Worker N…             ← unlimited depth, any backend

Architecture

| File | Role | |------|------| | bin/factory.js | Spawns Pi with the factory extension preloaded | | extension.ts | Session hooks, prompt merge, skill registration, /agents command, branding | | src/agent-registry.ts | Persist, list, run, and delete agents on disk | | src/agent-tools-pi.ts | The four factory tool definitions | | src/factory-prompt.ts | Merges FACTORY_SYSTEM_PROMPT + live backend context | | src/octoflow-context.ts | Calls discoverAvailableBackends() + allTools() at runtime | | src/prompt.ts | FACTORY_SYSTEM_PROMPT — OctoFlow rules, ReAct loop, octocode steps | | src/skill-config.ts | Registers the bundled create-agent-app skill with Pi | | src/mcp-bridge.ts | Connects to octocode-mcp via MCP stdio transport | | src/index.ts | SDK entry point (InteractiveMode without Pi extension) | | skills/create-agent-app/ | Bundled skill: feature map, code patterns, docs index |