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

The factory is three open components working as one:

┌─ Pi TUI (earendil-works/pi) ────────────────────────────┐
│  Conversational terminal — sessions, model routing,      │
│  streaming output, slash commands                        │
│                                                          │
│  ┌─ octocode-mcp (bgauryy/octocode) ─────────────────┐  │
│  │  Reads live OctoFlow source on GitHub so every     │  │
│  │  API call the factory writes is verified against   │  │
│  │  real code — not docs, not training data           │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  ┌─ octoflow-core ────────────────────────────────────┐  │
│  │  Runtime inside every generated agent.ts:          │  │
│  │  createAgent() · A2A · AG-UI · MCP · topologies    │  │
│  └────────────────────────────────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

When you describe an agent, the factory runs a grounded research loop before writing a single line:

REASON   — identify which OctoFlow features the task needs
ACT      — query 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     — show you the full architecture and wait for approval
GENERATE — write agent.ts using only confirmed patterns
VALIDATE — run it; read the output and fix any errors that surface
DELIVER  — print run command + env vars + next-step suggestions

octocode-mcp launches automatically on startup via npx — nothing to install. It uses gh or GITHUB_TOKEN to query the live OctoFlow repo. Without GitHub auth it falls back to the bundled skill (less grounded, still functional).

Demo — Local Image to Text (Ollama)

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

Getting Started

You need one LLM backend. Set an API key, or run Ollama locally — no key needed.

With an API key

# Anthropic
ANTHROPIC_API_KEY=sk-ant-... npx octoflow

# OpenAI
OPENAI_API_KEY=sk-... npx octoflow

# Google Gemini
GEMINI_API_KEY=... npx octoflow

# Any OpenAI-compatible provider (Groq, Azure, etc.)
OPENAI_API_KEY=gsk_... OPENAI_BASE_URL=https://api.groq.com/openai/v1 npx octoflow

Env vars can be exported, inlined before the command, or placed in a .env file — all work the same way.

Also recommended: authenticate GitHub so the factory can research the OctoFlow API from real source:

gh auth login   # or: export GITHUB_TOKEN=ghp_...

With Ollama (no API key)

brew install ollama        # macOS — see ollama.com for Linux/Windows
ollama pull llama3.2
ollama serve &
OCTOFLOW_MODEL=ollama/llama3.2 npx octoflow

Instant scaffold (no LLM needed)

If you want a reproducible starter without the interactive factory, create-octoflow-app scaffolds the same agent shape in one command:

npx create-octoflow-app my-agent
cd my-agent && npm install && npx tsx agent.ts

Integrations for existing apps:

# Add OctoFlow to a Next.js app
cd my-next-app && npx create-octoflow-app . --integrate=next

# Add OctoFlow to an Electron app
cd my-electron-app && npx create-octoflow-app . --integrate=electron

# Add OctoFlow AG-UI client to a React Native / Expo app
cd my-expo-app && npx create-octoflow-app . --integrate=react-native

# Sandbox — Docker-isolated tool execution (drops all caps, no network, memory-capped)
npx create-octoflow-app my-agent --sandbox

Each --integrate target writes server-tier wiring + an OctoflowChat component and drops an OCTOFLOW.md with the exact setup steps into your project.

Configuration

OctoFlow uses the same configuration system across the CLI and every generated agent.

Environment variables

| Variable | What it controls | |----------|-----------------| | ANTHROPIC_API_KEY | Anthropic backend API key | | OPENAI_API_KEY | OpenAI backend API key | | GEMINI_API_KEY | Google Gemini API key | | OLLAMA_API_KEY | Ollama bearer auth key | | ANTHROPIC_BASE_URL | Override Anthropic endpoint (proxies, custom deployments) | | OPENAI_BASE_URL | Override OpenAI endpoint (Groq, Azure, other compatible APIs) | | OLLAMA_HOST | Ollama server URL (default http://localhost:11434) | | OLLAMA_MODEL | Default model for the Ollama backend | | OCTOFLOW_MODEL | Builder model — provider/modelId or bare modelId | | OCTOFLOW_CONFIG | Path to a specific config file | | OCTOFLOW_HOME | Relocate user home and storage root (default ~/.octoflow) | | OCTOFLOW_IGNORE_CONFIG | Set to 1 to skip all config-file discovery | | OCTOCODE_MCP_VERSION | Pin a specific octocode-mcp version |

Run npx octoflow-core env --all to see which variables are currently set and which backends they activate.

Config file

Drop an octoflow.config.json in your project root for committed, non-secret defaults:

{
  "priority": ["anthropic-api", "openai-api", "ollama"],
  "defaultProfile": "local-trusted"
}

Discovery order: OCTOFLOW_CONFIG env var → nearest octoflow.config.json → nearest .octoflow.json → ~/.octoflow/config.json.

Full reference: docs/config-env.md · docs/configuration.md · docs/config-runtime.md

Commands

Launch

npx octoflow                            # fresh session
npx octoflow -c                         # continue last session
npx octoflow -r                         # pick a past session from a list
npx octoflow -p "list my agents"        # non-interactive one-shot
npx octoflow --model sonnet:high        # model + thinking level
npx octoflow --verbose                  # full startup diagnostics

Model can also be set via OCTOFLOW_MODEL=anthropic/claude-opus-4-8 npx octoflow, or switched mid-session with /model inside the TUI.

TUI slash commands

/model      switch model mid-session
/agents     list agents in the registry
/new        start a fresh session
/resume     pick a past session
/fork       branch the current session
/tree       show the agent call tree
/compact    compress context
/settings   open Pi settings
/hotkeys    keyboard shortcut reference
/exit       quit

Agent management

These work both interactively and via -p for scripting:

npx octoflow -p "Build me an agent that fetches Hacker News top stories and summarises them"
npx octoflow -p "list all agents"
npx octoflow -p "run hn-summariser"
npx octoflow -p "run hn-summariser with input 'only AI stories'"
npx octoflow -p "run hn-summariser with a 5-minute timeout"
npx octoflow -p "delete hn-summariser"

Once an agent exists, run it standalone:

cd ./octoflow/hn-summariser
npm install                                        # first time only
npx tsx agent.ts
AGENT_INPUT="only AI stories from today" npx tsx agent.ts

All CLI flags

| Flag | What it does | |------|-------------| | -c, --continue | Resume the most recent session | | -r, --resume | Interactive session browser | | -p "text" | Non-interactive print mode | | --model, --provider, --thinking | Model and reasoning level | | --no-session, --session, --fork | Session lifecycle | | --no-extensions | Raw Pi without factory tools | | --no-builtin-tools, --tools, --no-tools | Override the default tool set | | --verbose | Full startup diagnostics |

create-octoflow-app flags

npx create-octoflow-app [directory] [options]

  --force                  Scaffold into a non-empty directory
  --core-version=<ver>     Pin a specific octoflow-core version
  --sandbox                Harden tool execution in Docker
  --integrate=next         Wire into an existing Next.js app
  --integrate=electron     Wire into an existing Electron app
  --integrate=react-native Wire AG-UI client into an Expo/RN app

Templates

Default scaffold

npx create-octoflow-app my-agent

my-agent/
├── agent.ts        ← discover backend → send → print
├── agent.test.ts   ← vitest unit test (no network)
├── package.json    ← octoflow-core pinned to latest at scaffold time
├── tsconfig.json
├── vitest.config.ts
├── .gitignore
└── README.md

Scripts: npm run dev · npm test · npm run typecheck · npm run format

Next.js integration

npx create-next-app@latest my-app && cd my-app
npx create-octoflow-app . --integrate=next

Adds a server-side AG-UI route handler (app/api/octoflow/agui/run/route.ts), a demo chat page using OctoFlowProvider + useOctoFlowChat, and .env.example. Merges octoflow-core + octoflow-react.

Electron integration

cd my-electron-app
npx create-octoflow-app . --integrate=electron

Adds a gateway in the main process, a contextBridge preload, and a renderer chat component. Merges octoflow-core + octoflow-react. The CORS/IPC step is yours to enable — documented in the generated OCTOFLOW.md.

React Native / Expo integration

cd my-expo-app
npx create-octoflow-app . --integrate=react-native

Adds an OctoflowChat.tsx component that points at a remote backend. Merges octoflow-react only — the agent always runs server-side, never in the mobile bundle. A streaming-fetch polyfill step is documented in the generated OCTOFLOW.md.

Examples

Your first agent

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

The factory researches OctoFlow patterns via octocode-mcp, maps the task to the right packages, shows you the full architecture plan, generates agent.ts, and runs it:

> Run it

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

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

Uses 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

Uses octoflow-adapters with the Slack adapter + octoflow-plugins scheduler.

Generated Agent Structure

Agents land in ./octoflow/<slug>/ — relative to where you launched the CLI:

./octoflow/
└── hn-summariser/
    ├── agent.ts       ← the only file you need
    ├── PLAN.md        ← the approved build plan
    ├── README.md      ← mermaid diagram + usage instructions
    ├── meta.json      ← name, slug, run history, timestamps
    └── package.json   ← ESM config + octoflow-* deps

Every agent.ts follows the same shape — octoflow-core imports only, backend auto-detected, AGENT_INPUT env var as optional prompt, always cleans up:

import { createAgent, discoverAvailableBackends, extractText } from 'octoflow-core';

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();
}

OctoFlow Packages

The factory selects and installs the right packages automatically.

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

Agent topology

When the factory runs your generated agent, that agent uses octoflow-core and can itself spawn sub-agents — each on any backend, each inheriting the full protocol stack (A2A, AG-UI, MCP) without extra setup:

You
 └─ Builder Agent (Pi TUI)        researches, plans, generates
     └─ createAgent()             main agent in agent.ts
         ├─ Worker A              via createSubagentAction()
         ├─ Worker B              via createSubagentAction()
         └─ Worker N…             unlimited depth, any backend

flowchart TD
    U(["You"])

    subgraph CLI["OctoFlow Factory"]
        Builder(["Builder Agent\nresearch · plan · generate"])
        Tools["create · list · run · delete"]
        Registry[("./octoflow/")]
    end

    subgraph Research["octocode-mcp"]
        GH["OctoFlow source on GitHub"]
        Local["Local workspace"]
    end

    subgraph AgentRuntime["Generated agent.ts — octoflow-core"]
        CA["createAgent()"]
        subgraph Protocols["Protocols OOTB"]
            A2A["A2A"] 
            AGUI["AG-UI"]
            MCP2["MCP"]
        end
        subgraph Topologies["Topologies"]
            Solo["solo"]
            Sup["supervisor"]
            Pipe["pipeline"]
        end
        Extra["octoflow-tools · octoflow-brain · octoflow-adapters"]
        Backend[("Claude · OpenAI · Gemini · Ollama")]
    end

    U -->|"describe the agent"| Builder
    Builder -->|"research API"| GH
    Builder -->|"research API"| Local
    Builder --> Tools
    Tools --> Registry
    Registry -->|"npx tsx agent.ts"| CA
    CA --> Protocols
    CA --> Topologies
    CA --> Extra
    Extra --> Backend

Security

The factory generates code with an LLM and executes it on your machine — understand this before running untrusted requests:

• Generated agents run locally with your full environment. run_agent spawns agent.ts via npx tsx inheriting the factory's environment, so the agent can see your API keys. Review agent.ts before running anything sensitive.
• First run installs dependencies. The factory runs npm install inside ./octoflow/<slug>/ on first run — standard npm trust applies.
• No network/file sandbox by default. Generated agents have unrestricted access. For untrusted workloads, use create-octoflow-app --sandbox for Docker-isolated tool execution, or run inside a container.
• The builder itself is constrained. It has no shell or file tools; it only writes through create_agent_flow (which rejects path traversal) and runs through run_agent.
• Pinned research tooling. octocode-mcp is pinned rather than resolving @latest on every launch. Override with OCTOCODE_MCP_VERSION.

Troubleshooting

No backends ready at startup

Run npx octoflow-core env --all to see which env vars OctoFlow recognizes and which are currently set. Then set the matching key:

export ANTHROPIC_API_KEY=sk-ant-...
# or for Ollama:
ollama pull llama3.2 && ollama serve

If you're using an OpenAI-compatible provider (Groq, Azure, etc.), you also need OPENAI_BASE_URL.

octocode-mcp unavailable

The factory warns but continues with the bundled create-agent-app skill. Research is less grounded but still functional. If you want full grounding, make sure gh auth login is done or GITHUB_TOKEN is set.

Agent times out

Default run timeout is 120 s. Ask the factory in plain English:

> Run hn-summariser with a 5-minute timeout

Errors in the generated agent

The factory validates by running the agent and fixes errors it surfaces. tsx transpiles and runs — it does not type-check, so errors show at runtime. If the factory gets stuck:

> Fix the errors in the last agent you generated

Tools / actions not firing

If the agent answers in prose instead of calling a tool, check that:

• The tool is registered via tools: [...] in createAgent()
• The backend supports function calling (agent.info() → capabilities)
• The schema uses parameters (a JSON Schema object) — OctoFlow normalizes this to the provider's envelope automatically

MCP server not connecting

Set mcp.options.throwOnLoadError: true while debugging so failures surface instead of being swallowed. Common fixes: verify the server command is on $PATH, add args: ['-y'] for npx-based servers, bump mcp.options.timeoutMs for slow starts.

Brain / memory not recalling

Recall must use the same scope id that was used on brain:remember. Set defaultScope and scopeIdSource on the brain config so they align per session. Also check that the embedder is configured — without one, vector recall silently degrades to keyword recall.

Full troubleshooting guide: docs/troubleshooting.md