The fit command refuses to run inside the framework directory

Three engines, one repository, three products

The project bundles three distinct pieces under one roof, and the README names each one. FIT Core is the foundation: a multi-language function computation base for Java, Python and C++ with plugin-based hot swapping. On top of it sits its stated differentiator, so-called intelligent clustered and standalone deployment, where the same code runs as a monolith or as a distributed service without modification and the runtime routes local calls or RPC itself. WaterFlow is the streaming orchestration engine, driven either graphically or through a declarative API, aimed at everything from millisecond-scale micro-flows to cross-system long transactions. FEL, short for FIT Expression for LLM, is the piece that positions itself as the LangChain answer for the Java ecosystem, wrapping large models, knowledge bases and tool chains in standardized primitives. Those three are not layers of one thing so much as three products that share a packaging, a plugin format and a launcher. The examples directory reflects that split with fel-example, fel-spring-example and fit-example, plus a separate WaterFlow quick start, so a new user picks a lane rather than one entry point.

The README version runs ahead of the published tags

The heading of the README reads FIT Framework v3.7.0-SNAPSHOT, while the newest published tag is v3.6.4 and the two before it are v3.6.3 and v3.6.2, the last two landing in February and January 2026. A SNAPSHOT suffix means the default branch carries work that has not been cut as a tag, so anything you read about in the README may not exist in the version a Maven dependency resolves to. For a framework where the whole pitch is a stable plugin contract, that gap is worth watching rather than ignoring. The badges tell you the supported toolchains, Java 17 and Java 21, both of which get a badge pointing at the corresponding Oracle archive pages. The claimed benefit is a dual mode, native and Spring, so the same framework code can run standalone or inside a Spring application, which matters if your organization standardizes on Spring.

fit start only works outside the framework directory

The environment setup section contains the rule that produces the most confusion, and it is stated as a prohibition rather than a tip. You build ./framework/fit/java with Maven, copy the contents of the resulting build directory to a local location of your choosing, and that location becomes the FIT core framework directory. Then you set a system environment variable named FIT to that path, which is what makes the fit command executable at all. For example, if the framework sits at /demo/fitframework, the variable value is /demo/fitframework. Finally you create any directory you like to hold plugins and run fit start from inside it. The rule that follows is the one to remember: the fit command cannot be executed in the directory that contains the FIT framework, only in a newly created plugin directory. In other words the framework is read-only at runtime and the working directory is where your code lives, which is a different mental model from most JVM tools where the jar and the working directory are the same place. The README also notes that the fit and sandbox commands can be aliased or added to your system path to shorten the typing.

Maven for the framework, build.sh for the commands

There are two build paths, and they produce different things. The plain Maven build compiles only the Java framework:

mvn clean install

The global build adds the Sandbox CLI on top of that and skips tests by default:

./build.sh
./build.sh --with-test

The output layout tells you what you get. Under build/ there is bin/ containing the fit startup command and the sandbox command, the latter generated by build.sh, plus a launcher jar named fit-discrete-launcher-*.jar, a lib/ directory, a plugins/ directory and more. You start it with ./build/bin/fit start. For development the README asks for IntelliJ IDEA, Java 17, a Maven 3.8.8 or newer, and ships CodeFormatterFromIdea.xml so the formatting matches the IDE the maintainers use.

FEL expresses agent flows as a builder chain

The two FEL samples in the README show the shape of the API better than any description. The agent example is four links: create a flow, map the query into a Tip, set a human prompt with a {{0}} placeholder, delegate to an agent, and close. The retrieval example is longer and shows the primitives that matter. It runs history() and passThrough() in parallel, then attaches a condition that matches on the tip having a non-empty text value for DEFAULT_HISTORY_KEY. On a match it rewrites the query with Prompts.human(REWRITE_PROMPT), generates an answer through a chat flow model, and maps the result to text. The otherwise branch falls back to reading the query directly. Retrieval then runs against a DefaultVectorRetriever with SearchOption.custom().topK(1).build(), synthesis joins the document texts with two newlines, and the flow closes. So the model is conditional branching over a typed payload, not a chain of function calls, and the topK setting is explicit rather than hidden in a default.

The sandbox runs coding agents in containers per branch

Alongside the framework the project ships a developer tool called the AI programming sandbox, documented for macOS. It is built on Colima, Docker and git worktrees, and its purpose is to run AI coding tools such as Claude Code and Codex inside containers. Multiple containers run at once, and each works on its own branch so they do not interfere with each other. The command surface is four verbs:

sandbox create feat-xxx
sandbox exec feat-xxx
sandbox ls
sandbox rm feat-xxx

In the examples the sandbox name is feat-xxx, following the git branch naming pattern, and the four verbs follow that name. This is a separate concern from the framework itself and lives under docker/sandbox with its own documentation, which is worth knowing if you were expecting the repository to be only a Java library. The repository also carries agent-facing configuration directories at the root, including .agents/, .ai-workspace/, .claude/, .codex/, .gemini/ and .opencode/, alongside AGENTS.md, SECURITY.md and git-hooks/.

Where FIT is the wrong tool

Four cases push you elsewhere. The first is a Python-first team. FEL is explicitly the Java answer to LangChain, so adopting it means the model-facing code lives in a second language ecosystem alongside whatever the Python side already does, and the framework does not present itself as one library covering both. The second is a need for published benchmarks or an adoption record. The README argues its case with claims rather than measurements: it says 80 percent of common scenarios are zero-configuration while keeping 20 percent customizable, and calls itself the first full-stack AI framework for the Java ecosystem, with no data attached to either. The third is plugin dependency on a stable contract. Hot-swappable plugins are the core of the design, but the README version sits ahead of the newest tag, so pinning a release and expecting the documented plugin behavior needs checking. The fourth is operational simplicity. A framework that decides whether a call is local or RPC, picks between HTTP, gRPC and shared memory by context, and injects plugin dependencies for you is a large amount of implicit behavior for a team that wants to see the transport in the code. The community channels are GitHub Issues, a WeChat public account, a WeChat group and a QQ group numbered 1029802553, so support is community-run rather than ticketed.

Editorial conclusion

FIT suits a Java shop that needs agent and retrieval code living inside its existing stack, plus a flow engine and a plugin runtime around it, and that accepts native and Spring as two valid hosting modes. It does not suit a team wanting one AI library shared across Python and Java, or one that wants the transport layer visible in code. Before adopting, build with mvn clean install and ./build.sh for the CLI, point the FIT environment variable at the framework directory, and remember that fit start only runs from a separate plugin directory.

Frequently asked questions

Official sources

1. License: MIT
2. ModelEngine-Group/fit-framework on GitHub
3. Project website
4. README
5. Releases