FlowJet

🎥 Watch the demo video on Vimeo

FlowJet (flowjet-agent) is a one-shot coding-agent CLI for the terminal. Type a question, get an answer — no UI, no context-switching:

flowjet-agent explain this repo
fj explain this repo                    # alias of flowjet-agent
fj -f what did we decide last time?
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 thread is resumable.

Package / formal CLI: flowjet-agent · aliases: fj, fjf (= -f) · Runtime: soothe-nano · Repo: flowjet-agent

See docs/naming.md for the formal naming model.

---

Install

pip install flowjet-agent
# or
uv tool install flowjet-agent

Requires Python 3.11+.

Configure

Option A — Local model (guided):

fj setup

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):

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

Missing nano.yml falls back to OPENAI_API_KEY or ANTHROPIC_API_KEY.

Doctor

Check whether this machine can run fj (tool binaries, providers, observability). Requires soothe-nano with the diagnose API (1.0.8+):

fj doctor
fj doctor --deep
fj doctor --live-llm
fj doctor --format json

Run

fj who are you
fj list Python files in this directory
fj refactor the parser to use dataclasses

---

Conversation

Threads persist across runs in SQLite. Continue the latest, jump to a specific one, or list them:

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

Flags

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

Flag	Meaning
-f / --follow	Continue the latest active thread
-t ID / --thread	Continue (or pin) a specific thread
-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

Shell completion (AI-assisted, predicts natural-language intents, not just flags):

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

---

---

Extend

Skills

fj ships AgentSkills (planning, TDD, debugging, document tools, MCP builder, and more) and supports your own via 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 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 (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