FlowJet

🎥 Watch the demo on Vimeo

FlowJet is one agent runtime, two surfaces:

Both are the same distribution and the same flowjet.core runtime: one nano bootstrap, one stream mapper, one RuntimeEvent contract. The terminal renders those events as a progress line; the server renders them as SSE or ACP updates.

# CLI
fj explain this repo
fj -f what did we decide last time     # continue the latest conversation
fjf what did we decide last time       # alias of fj -f

# Server (OpenAI-compatible + ACP)
flowjet-server                         # or: fj serve --port 8618

It runs on soothe-nano — tools, skills, MCP, subagents, and progressive loading — with SQLite persistence so every conversation is resumable.

Package: flowjet · CLI aliases: fj, fjf (=-f) · Server: flowjet-server · Runtime: soothe-nano · Naming details: docs/naming.md

Upgrading from 1.x? The distribution and all import paths were renamed. See docs/upgrade.md.

Install

pip install flowjet            # CLI only (one runtime dependency: soothe-nano)
pip install 'flowjet[server]'  # + the HTTP service (fastapi, uvicorn, ACP)
# or
uv tool install 'flowjet[server]'

Requires Python 3.11+. The server half is an optional extra — fj never imports FastAPI or uvicorn.

Configure

Option A — Local model (guided setup):

fj setup

This walks you through an OpenAI-compatible endpoint (Ollama, LM Studio, vLLM, …) and writes the basics to ~/.soothe/config/nano.yml.

Option B — Cloud (no config file needed):

export OPENAI_API_KEY=sk-...
fj summarize README.md

Without a nano.yml, FlowJet falls back to OPENAI_API_KEY or ANTHROPIC_API_KEY.

Doctor

Check whether your machine is ready to run fj (tool binaries, providers, observability):

fj doctor                 # quick check
fj doctor --deep          # thorough check
fj doctor --live-llm      # actually call the model
fj doctor --format json   # machine-readable

Conversations

Threads persist in SQLite, so you can pick up where you left off — continue the latest, jump to a specific one, or list them:

fj -f and now add tests          # continue this project's latest active thread
fj -t abc123 continue from here  # continue a specific thread
fj -l                            # list recent threads

-f is scoped to the project you are in — the git repo root, or the current directory when it is not a repo — so parallel work in other checkouts never hijacks your thread. fj -l still lists every thread; pick one up from anywhere with -t ID.

Flags

fj [options] [--] <query...>

-t and -f can be combined; -t wins (explicit id overrides follow).

Shell completion is AI-assisted — it predicts natural-language intents, not just flags:

eval "$(fj completion zsh)"     # or: fj completion bash

Extend

Skills

FlowJet ships with AgentSkills (planning, TDD, debugging, document tools, MCP builder, and more). Add your own in nano.yml:

skills:
  - ~/.soothe/skills/my-reviewer
  - ./skills/deploy

Each skill is a SKILL.md with frontmatter; progressive loading keeps the catalog compact and loads skills on demand.

MCP servers

Connect any Model Context Protocol server:

mcp_servers:
  - name: filesystem
    transport: stdio
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]

With defer: true (the default), MCP tools activate on demand.

Server

Start the service and point any OpenAI-compatible client at it:

flowjet-server                       # defaults: host :: (dual-stack), port 8618
fj serve --port 8618                 # same thing from the CLI

from openai import OpenAI

client = OpenAI(api_key="local", base_url="http://127.0.0.1:8618/v1")
print(client.responses.create(model="default", input="Hello"))

FlowJet options travel in extra_body.flowjet:

Environment

Security model

The two surfaces have deliberately different invariants (enforced in flowjet.core.modes, not by whichever module loaded first):

FLOWJET_CORS_ORIGINS defaults to * with credentials enabled so browser clients work out of the box; set it to an explicit origin list in production.

Full protocol reference and deployment guide: deploy/README.md, docs/specs/RFC-001-openai-compatible-api.md.

Development

git clone https://github.com/caesar0301/flowjet-agent.git
cd flowjet-agent
make sync-dev          # dev + server extras
make test              # unit + integration + server suites
make test-server       # HTTP/ACP suites only
make run               # start the server locally
make lint

CI runs format, lint, and tests on Python 3.11–3.13; releases go GitHub Release → PyPI.

Powered by

Built on soothe-nano. For a full TUI coding agent from the same stack, see mirasoth/soothe.

License

MIT