FlowJet

FlowJet is a coding agent you can run two ways:

• fj — ask a question in your terminal, get an answer. No UI, no context-switching.
• flowjet-server — the same agent as a service: ACP over WebSocket and an OpenAI-compatible HTTP API, so any OpenAI SDK can drive it.

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

Install

pip install flowjet              # CLI
pip install 'flowjet[server]'    # CLI + HTTP service

Requires Python 3.11+. The server is an optional extra — installing just flowjet pulls a single runtime dependency.

Configure

fj setup                         # guided: pick a local or hosted model
# or, with no config file at all:
export OPENAI_API_KEY=sk-...
fj summarize README.md

fj setup writes $FLOWJET_HOME/config/nano.yml (default ~/.flowjet/config/nano.yml). Without it, FlowJet falls back to OPENAI_API_KEY or ANTHROPIC_API_KEY.

Not sure your machine is ready? fj doctor (add --deep, --live-llm).

Backends

Two runtimes can build the agent; they are switched independently per surface:

soothe is the host runtime (extra middleware and tools over the same soothe-nano engine). The server defaults to nano because it needs a dual-mode agent — AGENT and ASK graphs selected per request — which soothe does not expose yet; on soothe the server builds one host agent per mode instead.

CLI

fj explain this repo
fj -f and now add tests          # continue this project's latest conversation
fjf what did we decide?          # short alias of fj -f
fj -l                            # list recent conversations

-f is scoped to your current project, so work in other checkouts never hijacks your thread.

Enable shell completion (predicts full queries, not just flags):

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

Server

flowjet-server                   # host :: (dual-stack), port 8618
fj serve --port 8618             # same, 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"))

Per-request options go in extra_body.flowjet:

Full configuration, environment variables and the security model: docs/server.md · deployment: deploy/README.md.

Extend

Add skills and MCP servers in nano.yml:

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

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

Skills are SKILL.md files loaded on demand; MCP tools activate on demand by default (defer: true).

Development

git clone https://github.com/caesar0301/flowjet.git
cd flowjet
make sync-dev && make test && make lint

Upgrading from 1.x

Version 2.0 merges the former flowjet-server project into this one. The distribution is now flowjet and import paths changed. See docs/upgrade.md.

License

MIT