FlowJet
FlowJet is a friendly one-shot coding agent for your terminal. Ask a question in plain English, get an answer — no UI, no context-switching.
fj explain this repo # the short alias for flowjet-agent
fj -f what did we decide last time # continue the last conversation
fjf what did we decide last time # alias of fj -f
It runs on soothe-nano — tools, skills, MCP, subagents, and progressive loading — with SQLite persistence so every conversation is resumable.
Package: flowjet-agent · aliases:
fj,fjf(=-f) · Runtime: soothe-nano · Naming details: docs/naming.md
Install
pip install flowjet-agent
# or
uv tool install flowjet-agent
Requires Python 3.11+.
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...>
| Flag | Meaning |
|---|---|
-f / --follow |
Continue the latest active thread in this project directory |
-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) |
-c PATH / --config |
Use an alternate nano.yml |
-w DIR / --workspace |
Workspace root |
--no-stream |
Wait for the full answer instead of streaming |
-v / --verbose |
Mirror tool calls on stderr |
-tand-fcan be combined;-twins (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.
Development
git clone https://github.com/caesar0301/flowjet-agent.git
cd flowjet-agent
make sync-dev
make test
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
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file flowjet_agent-1.1.7.tar.gz.
File metadata
- Download URL: flowjet_agent-1.1.7.tar.gz
- Upload date:
- Size: 161.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
027da79022ce78ee1c39e2d2bd2aaf640a123a76dccfd162893aae43e3ddfff7
|
|
| MD5 |
3b742c0ca92211e774029472d93c990e
|
|
| BLAKE2b-256 |
4739e3835289d0ea333cfd7c1d42f30e84de030815eb84b9957457842e595145
|
File details
Details for the file flowjet_agent-1.1.7-py3-none-any.whl.
File metadata
- Download URL: flowjet_agent-1.1.7-py3-none-any.whl
- Upload date:
- Size: 204.1 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via:
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ebaa2acf9d7f370be93aad0daae07668f65ec946d825c4e146df4bb3f689af18
|
|
| MD5 |
dfe3cf38db8967a8b6dd77c8129dd3c4
|
|
| BLAKE2b-256 |
f288db421b7c83319ae9639baea96895ac4f08944f7c496e203b4ee5cabc7edb
|
