FlowJet

🎥 Watch the demo on Vimeo

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

-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.

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

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

flowjet_agent-1.1.9.tar.gz (161.9 kB view details)

Uploaded Sep 1, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

flowjet_agent-1.1.9-py3-none-any.whl (204.1 kB view details)

Uploaded Sep 1, 2026 Python 3

File details

Details for the file flowjet_agent-1.1.9.tar.gz.

File metadata

Download URL: flowjet_agent-1.1.9.tar.gz
Upload date: Sep 1, 2026
Size: 161.9 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for flowjet_agent-1.1.9.tar.gz
Algorithm	Hash digest
SHA256	`bcf69ccd84c7b793becd01983d682826378dca98aabacf623b64550a349d9fca`
MD5	`d9a55b28545444e059078a3e6f0d3426`
BLAKE2b-256	`ec81067dc11e08fbec40e22a3e973b5a19745afc22d8bc8e7bc3cef9ba506c97`

See more details on using hashes here.

File details

Details for the file flowjet_agent-1.1.9-py3-none-any.whl.

File metadata

Download URL: flowjet_agent-1.1.9-py3-none-any.whl
Upload date: Sep 1, 2026
Size: 204.1 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for flowjet_agent-1.1.9-py3-none-any.whl
Algorithm	Hash digest
SHA256	`62b93a41791d485d6d376ab7830d0d00ba7018e03a6362cb11debcfce24b5293`
MD5	`3766e5ad7595d01abc110efa06955e84`
BLAKE2b-256	`5c97c6d6c700ec38475ad138c691f7ebd2f30b4817a2c468324a34af52945066`