Loom: an AI agent that writes JSON Schema API docs and serves them

The problem Loom targets: API docs that drift from the schema

Most API documentation tools assume the schema already exists. Loom inverts that. The README describes it as an AI-based JSON Schema documentation generator, and the primary interface is a terminal chat where you describe an endpoint in natural language and the model produces a schema file. That places it in a narrow slot: teams that want JSON Schema as the source of truth but do not want to hand-write every property, required array, and response code. The audience is a developer working alone or in a small group who is comfortable in a TUI, has a DeepSeek or OpenAI key, and treats docs/ as a checked-in directory rather than a build artifact. It is not aimed at teams that need OpenAPI as the interchange format, and it is not aimed at anyone who wants documentation generated automatically from running code without a conversation in the loop.

How the pieces fit together: chat, schema files, viewer, mock

The architecture is a set of subcommands over one project directory. loom chat runs the TUI and writes JSON Schema files into docs/ (configurable via outDir). Each file describes a module with a title, a description, and an endpoints array; each endpoint carries path, method, summary, tags, an optional request object with headers, params, query and body, and a response object keyed by status code. The second layer is entities. Reusable schemas live in docs/entities/*.entity.schema.json, and an endpoint references one through x-entity-ref, either as a bare string like "User" or as an object with an entity name and a pick array that selects a subset of properties. The third layer is the viewer, a React SPA served by loom view, which resolves those entity references when rendering request and response sections. The fourth is the mock server, which registers routes from the schema files and generates response data with the mock-json-schema package. A manifest file, .loom-manifest.json, indexes the whole thing; loom manifest rebuild exists precisely because that index can fall out of step with the files on disk.

The entity reference model is the design decision worth studying

Splitting reusable objects into docs/entities and pointing at them with x-entity-ref is the part of Loom that is not just an LLM wrapper. It means a User object is defined once and the viewer expands it wherever an endpoint references it, including partial selections through pick. The trade-off is that x-entity-ref is a Loom-specific extension, not a JSON Schema keyword. A generic JSON Schema validator will not resolve it, and the README does not describe how the reference is flattened for consumers outside the viewer. So the entity layer buys you consistency inside Loom and costs you portability outside it. If your schemas are consumed by anything other than Loom's own viewer and mock server, that cost is real and you should confirm how the reference is meant to be resolved before you commit to the pattern.

Getting it running: install, config, and the commands that matter

Installation is global through npm or yarn. The README gives npm install -g @vegamo/loom and yarn global add @vegamo/loom, with Node.js 18 or newer required. Configuration lives at ~/.loom/config.json on macOS and Linux, or %APPDATA%/loom/config.json on Windows, and the first run of loom chat walks you through creating it. The documented defaults are provider deepseek, model deepseek-chat, baseURL https://api.deepseek.com/v1, with the apiKey left for you to supply; temperature defaults to 0.7 and maxTokens to 2000. The config also holds outDir (default docs), a serve block with port 3000 and host 0.0.0.0, and a mock block with port 3001. The day-to-day commands are loom chat for generation, loom view to browse, loom mock to serve fake data, and loom serve to run viewer and mock together on one port, where the viewer sits at / and mock routes under /mock/. Inside the chat, /mock and /view start, stop, and restart those servers without leaving the terminal. loom upgrade pulls the latest version from npm, and the tool also checks for new versions when you run other commands.

The /scan workflow and its language setting

The most ambitious feature is /scan, which asks the LLM to identify APIs from existing source code rather than from your description. The changelog for v0.3.0 states that /scan and /scan resume gained a --lang zh|en parameter, and that Phase 3 (generate-entity) and Phase 4 (generate-endpoint) emit description and summary text in the selected language. The default is zh, and it can be overridden globally through scan.language in ~/.loom/config.json or per invocation with the flag. The same release note says the LLM cache for those two phases is now keyed per language, with the language suffix appended to the cache key. Two things follow from this. First, scanning a codebase is a multi-phase pipeline, not a single prompt, and the resume and reset subcommands exist because long scans get interrupted. Second, if you work in English and do not pass the flag, you will get Chinese descriptions in your schema files by default, which is easy to miss until the viewer renders them.

Where Loom is the wrong tool

The generation step is probabilistic. The README documents temperature 0.7 as the default for the chat model, and nothing in the material describes a validation pass that checks generated schemas against the endpoints they claim to document. A schema that parses is not a schema that is correct, and Loom has no way to know whether the response shape it invented matches what your server returns. That makes it a drafting tool, not a verification tool. The mock server compounds this: it generates data from the schema, so a wrong schema produces confident, well-formed, wrong mock responses. The second limitation is dependency on a hosted model. DeepSeek is listed as required in the environment requirements, and the config schema points at api.deepseek.com. Any environment that cannot reach an external LLM endpoint, or that cannot store an API key in a home-directory config file, is out of scope. The third is format lock-in. Loom defines its own JSON Schema dialect with endpoints, request, response and x-entity-ref; it is not OpenAPI, and the material does not describe an export path to one.

How this differs from writing an OpenAPI file by hand

The obvious alternative is a hand-maintained OpenAPI document plus a mock server such as Prism or a schema-driven tool like JSON Server. The difference is not quality, it is where the authoring effort sits. With OpenAPI you write YAML or JSON, and the specification's tooling ecosystem (validators, code generators, client SDKs) reads it directly. With Loom you describe endpoints in chat, the model writes files in a Loom-specific dialect, and the payoff is the viewer and mock server that come bundled and stay pointed at the same directory. The entity reference system has no direct equivalent in a plain OpenAPI file without components and $ref, though OpenAPI's version is a standard that other tools understand. If your schemas need to be consumed by code generators or published as a contract, the OpenAPI route costs more typing and less rework. If you mainly need browsable docs and a mock endpoint for frontend work, Loom removes a step.

Maintenance, upgrades, and what the licence question leaves open

Loom ships an upgrade path: loom upgrade installs the latest npm version, and the tool checks npm for new releases when other commands run, prompting you to confirm. That is convenient and also means a CLI you invoke for documentation can change behaviour between sessions. The repository metadata supplied here lists no licence, and the README does not state one. Under npm's default, a package published without a licence field is not granted for reuse by default, so if you are considering vendoring Loom, modifying it, or shipping it inside a product, that is a question to resolve with the maintainer or the package's licence file before you build on it. This is not legal advice; it is a gap in the material that a procurement or legal review will ask about. The manifest rebuild command is the other maintenance item worth knowing: .loom-manifest.json is an index, and the existence of a rebuild command implies it can drift, so a CI step that runs loom manifest rebuild and fails on a dirty working tree would catch index inconsistencies, though the README does not document such a check.

Editorial conclusion

Adopt Loom if your team already writes JSON Schema by hand and wants an LLM to draft the boilerplate, or if you need a mock server that stays in sync with those schemas without a separate tool. Do not adopt it if your API contract has to be reviewed and versioned as a single artifact, or if you cannot put a DeepSeek or OpenAI API key on the machine that runs it. Before committing, run loom chat on a throwaway directory, inspect the generated files under docs/entities, and check whether the x-entity-ref resolution in loom view produces the request and response tables you would actually hand to a client.

Official sources

1. husu/loom on GitHub
2. Issues
3. Project website
4. README