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.
pip install flowjet # CLI
pip install 'flowjet[server]' # CLI + HTTP serviceRequires Python 3.11+. The server is an optional extra — installing just flowjet pulls a single runtime dependency.
fj setup # guided: pick a local or hosted model
# or, with no config file at all:
export OPENAI_API_KEY=sk-...
fj summarize README.mdfj 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).
Two runtimes can build the agent; they are switched independently per surface:
| Env var | Surface | Default | Values |
|---|---|---|---|
FLOWJET_BACKEND |
CLI (fj) |
soothe |
soothe, nano |
FLOWJET_SERVER_BACKEND |
flowjet-server / fj serve |
nano |
soothe, nano |
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.
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| Flag | Meaning |
|---|---|
-f / --follow |
Continue the latest thread in this project |
-t ID / --thread |
Continue (or pin) a specific thread — overrides -f |
-l / --list |
List recent threads (newest first) |
-n NUM |
How many threads -l shows (0 = all) |
-a / --ask |
Read-only: answer without touching files |
-v / --verbose |
Mirror tool calls on stderr |
-c PATH / -w DIR |
Alternate nano.yml / workspace root |
-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 bashflowjet-server # host :: (dual-stack), port 8618
fj serve --port 8618 # same, from the CLIfrom 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"))| Endpoint | Purpose |
|---|---|
POST /v1/responses |
Create a response (stream=true → SSE) |
GET / DELETE /v1/responses/{id} |
Retrieve / cancel |
POST /v1/chat/completions |
Chat Completions (non-stream + SSE) |
GET /v1/models |
Model ids |
GET /health |
Liveness |
WS /acp |
Agent Client Protocol |
Per-request options go in extra_body.flowjet:
| Field | Values | Meaning |
|---|---|---|
session |
string | Isolates workspace + conversation thread |
interaction_mode |
agent (default) | ask |
ask is hard read-only |
projection |
report | progress | developer |
How much SSE detail to expose |
Full configuration, environment variables and the security model: docs/server.md · deployment: deploy/README.md.
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).
git clone https://github.com/caesar0301/flowjet.git
cd flowjet
make sync-dev && make test && make lintVersion 2.0 merges the former flowjet-server project into this one. The distribution is now flowjet and import paths changed. See docs/upgrade.md.
MIT