fj-ai 1.0.18

fj — one-shot CLI coding agent powered by soothe-nano

fj

🎥 Watch the demo video on Vimeo

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

fj explain this repo
fj -f what did we decide last time?
fjf what did we decide last time?  // The same as fj -f

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

Package: fj-ai · Runtime: soothe-nano

---

Install

pip install fj-ai
# or
uv tool install fj-ai

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/fj-ai.git
cd fj-ai
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