pi-freeflow 🌊

23 free models. Up to 1M context. Zero API keys. Infinite scale via your own relay pool.

Thin by design: model list + dumb relay + log. Host pi-ai owns thinking, normalization & provider magic. We just make it free, fast, and unbreakable.

Join devs bypassing rate limits with their own relay pools. BYO, add as many as you need.

Features at a Glance

Philosophy: Thin by design. We only ship model list + relay proxy + log. Host owns thinking & normalization.

23 Curated Models, One Command

/model → freeflow → pick

OpenCode Zen (9 Models), Responses & Chat API

Optimized for deep reasoning, long-horizon coding & autonomous agentic workflows.

KiloCode Gateway (14 Models), OpenRouter Compatible

Keyless access with Bearer kilo-free. Clean slash-free and colon-free CLI aliases supported.

* Levels are forwarded as-is through the OpenRouter-style nested reasoning parameter; effort mapping is decided by each model. hy3 accepts no reasoning parameter today.

How It Works: BYO Relays, Zero Rate Limits

You → 127.0.0.1:18080 (dumb proxy, host-normalized) → x-relay-target → N egress IPs (your pool) → opencode.ai / api.kilo.ai
                                     ↑ host already normalized thinking → proxy just forwards

1. Per-Request Round-Robin: 10 parallel subagents hit N different egress IPs (your pool size). No thundering herd.
2. Adaptive Health & Error Cooldown: Relays hitting 429, 504, or socket disconnects enter temporary cooldown (30-90s) and automatically move behind healthy candidates. Healthy relays handle traffic with 0ms wasted delay.
3. Seamless 429 Roll: 429 / 408 / 502 / 503 / 504 / 520-530 → instant roll to next relay, never 429 to agent.
4. Stream Truncation Resilience: Stateful SSE terminal tracking prevents fatal unhandled stream closed errors when connections drop.
5. Direct Fallback Safety Net: If all relays in the pool are exhausted, transparent direct fetch to upstream.
6. Zero Subagent Connect Errors: 24h DISK_CACHE_ONLY model catalog avoids subagents hammering remote catalogs.

You bring the relays (free tiers). We bring the rolling.

Interactive Commands Reference (/freeflow)

Manage your relay pool directly from the OMP / Pi terminal:

/freeflow status                  # View active relay, pool status, and candidates
/freeflow list                    # List all relays with real-time health badges (✓ / ⚠️ [cooling])
/freeflow use <url|index|label>   # Switch active relay
/freeflow add <url> [label]       # Add new relay to the pool
/freeflow label <index|url> <name># Assign a friendly label to a relay
/freeflow remove <index|url|label># Remove a relay from the pool
/freeflow on | off | auto         # Toggle relay mode (auto = enabled for freeflow)
/freeflow deploy vercel            # Guided Vercel Edge relay deploy (also: deploy cloudflare, deploy deno)
/freeflow logs [lines]            # Inspect recent proxy logs
/freeflow debug on | off          # Toggle full HTTP lifecycle debug logging

Quick Start in 30 Seconds

1. Install

Oh My Pi (Recommended):

omp plugin install pi-freeflow
# or local dev
omp plugin link /path/to/pi-freeflow

Pi:

pi install npm:pi-freeflow

2. Pick a Model

omp
/model → freeflow → muse-spark-1.2-contributor-free (1M) → max

# or CLI
omp -p --model freeflow/muse-spark-1.2-contributor-free "build me a SaaS"
# or with short alias & thinking level
omp -p --model freeflow/step-3.7-flash:high "solve this bug"

3. Add Your Free Relays (Scale Infinitely)

Default ships direct. Add relays via /freeflow add <url> [label].

Zero setup? Run /freeflow deploy cloudflare (or deno, vercel), paste your platform token once, and the relay is created and activated for you. Manual snippets below.

Option A: Cloudflare Workers (100k req/day, no 25s timeout)

1. Go to dash.cloudflare.com → Workers → Create → Deploy → Edit code
2. Paste this Worker relay snippet:

// Only the 2 upstreams pi-freeflow talks to. Anything else = open proxy abuse.
const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];

export default {
  async fetch(req) {
    const target = req.headers.get("x-relay-target");
    const relayPath = req.headers.get("x-relay-path") || "/";
    if (!target) return new Response(JSON.stringify({ error: "Missing x-relay-target header" }), { status: 400 });
    const cleanTarget = target.replace(/\/$/, "");
    if (!ALLOWED_TARGETS.includes(cleanTarget)) return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
    if (!relayPath.startsWith("/")) return new Response(JSON.stringify({ error: "Bad path" }), { status: 400 });
    const headers = new Headers(req.headers);
    headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
    return fetch(cleanTarget + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
  },
};

1. Deploy and add it:

omp → /freeflow add https://your.workers.dev cf-worker-1

Option B: Vercel Edge Relay (1M req/mo), Auto Deploy

/freeflow deploy  # prompts token in-memory, auto-adds to pool

Option C: Deno Deploy (100k req/day)

1. Go to dash.deno.com → New Project → Playground
2. Paste this relay and click Deploy:

const ALLOWED_TARGETS = ["https://opencode.ai", "https://api.kilo.ai"];

Deno.serve(async (req) => {
  const target = req.headers.get("x-relay-target");
  const relayPath = req.headers.get("x-relay-path") || "/";
  if (!target || !ALLOWED_TARGETS.includes(target.replace(/\/$/, ""))) {
    return new Response(JSON.stringify({ error: "Forbidden target" }), { status: 403 });
  }
  const headers = new Headers(req.headers);
  headers.delete("x-relay-target"); headers.delete("x-relay-path"); headers.delete("host");
  const res = await fetch(target.replace(/\/$/, "") + relayPath, { method: req.method, headers, body: req.method !== "GET" && req.method !== "HEAD" ? req.body : undefined });
  return new Response(res.body, { status: res.status, headers: res.headers });
});

1. Add it:

/freeflow add https://your-project.deno.dev deno-relay-1

Verify your pool:

/freeflow status        # relay-A 1/N (ON) → candidates:N
/freeflow list          # lists all relays with health status
/freeflow logs          # tail -25
cat ~/.pi/agent/pi-freeflow.log | tail -n 20

Logs & Debugging

/freeflow logs
cat ~/.pi/agent/pi-freeflow.log | tail -n 50

# debug toggle
/freeflow debug on

Log rotation at 5MB. Clean, parseable, real-time HTTP lifecycle tracking.

Design

This package stays thin. It ships three things: a model catalog, a relay proxy, and a log. There is no build step and there are no runtime dependencies. Thinking and prompt normalization stay with the host (pi-ai).

Current size: about 4.6k lines including tests. 16 tests pass, typecheck clean.

FAQ

Do I need API keys?
No. Kilo uses Bearer kilo-free, OpenCode uses opencodeHeaders().

What if all relays are 429?
Proxy tries direct. If that is also 429, Pi shows the rate limit. That number is the global upstream cap; without relays you would hit the same wall.

Can I use without relays?
Yes. /freeflow off → direct. Add relays later to scale.

Where's the normalizer?
Deleted in 1.3.0. If zai/qwen/deepseek thinking broke before, it's fixed now because host handles it.

Why is context free?
We use OpenCode Zen & Kilo free tiers. You pay only with your own Cloudflare/Vercel free tiers for egress.

Contributing

Contributions welcome — bug fixes, new relay platforms, model additions, docs improvements.

Prerequisites

• Node.js ≥ 22.6.0 (uses --experimental-strip-types, no build step)
• pnpm (package manager)

Setup & Verify

git clone https://github.com/trefeon/pi-freeflow
cd pi-freeflow
pnpm install

# run all three before opening a PR
pnpm test        # 16 tests across 2 test files
pnpm typecheck   # tsc --noEmit, must pass clean
pnpm smoke       # verifies extensions/index.ts loads without crashing

Project Structure

src/
├── index.ts          # extension entry, lifecycle hooks
├── models.ts         # 23-model catalog definitions
├── catalog.ts        # model catalog cache (24h disk)
├── proxy.ts          # local proxy server (127.0.0.1:18080)
├── relay.ts          # relay selection & round-robin
├── relay-state.ts    # relay pool state, health tracking
├── rate-limiter.ts   # adaptive cooldown on 429/504/socket errors
├── stream-pipe.ts    # SSE stream piping & truncation resilience
├── commands.ts       # /freeflow CLI subcommands
├── deploy.ts         # guided relay deploy (vercel/cloudflare/deno)
├── config.ts         # relay pool persistence
├── logger.ts         # file logger with 5MB rotation
└── types.ts          # shared type definitions
extensions/
└── index.ts          # OMP/Pi extension manifest
test/
└── *.test.ts         # mirrors src/, node:test runner

Guidelines

• Stay thin. No runtime dependencies. No build step. If it belongs in the host (pi-ai), don't add it here.
• Test what you touch. Every src/*.ts has a matching test/*.test.ts. Add or update tests for your change.
• Keep model IDs clean. Slash-free, colon-free aliases for CLI compatibility. See existing patterns in models.ts.
• One concern per PR. Bug fix? One PR. New relay platform? Separate PR. Easier to review, faster to merge.

Reporting Issues

Found a bug or want a feature? Open an issue with:

• What happened vs what you expected
• Your relay setup (/freeflow status output helps)
• Relevant logs (/freeflow logs or ~/.pi/agent/pi-freeflow.log)

License

MIT © trefeon