Loom: AI Chat Interface for Writing JSON Schema API Documentation

The Problem Loom Solves: Schema Docs by Conversation

Writing API documentation is typically separate from writing code. Developers either maintain OpenAPI YAML files by hand or generate them from annotations inside source code. Both approaches require the developer to already know the shape of the API before the documentation can be written. Loom takes a different approach: you describe what an endpoint should do in natural language, and an AI model produces a structured JSON Schema file that captures the request and response shapes.

The tool is aimed at small teams and solo developers who are in early-stage API design, where the fastest path to something reviewable is a chat session rather than a YAML editor. The README describes the overall style as "vibe coding" for API documentation: informal, iterative, and driven by conversation. The generated files live in a docs/ directory alongside the project source and can be committed like any other documentation.

How loom chat Produces and Updates Schema Files

The loom chat command opens a terminal UI (TUI) backed by a configurable LLM. You type a description of an endpoint in natural language, and the AI returns a structured JSON object that conforms to Loom's schema format. The file is saved to docs/ automatically. A subsequent message can refine the schema, and the tool updates the file in place.

The TUI keyboard shortcuts are documented in the README: Enter sends a message, Shift+Enter or Alt+Enter inserts a line break, and the up/down arrow keys browse the conversation history across sessions. Tab autocompletes slash commands. The built-in commands include /list to see generated files, /reset to clear the conversation history, /mock and /view to start or stop the embedded servers, and /scan to trigger source-code analysis.

The default provider is DeepSeek using the deepseek-chat model at https://api.deepseek.com/v1. OpenAI is also supported by changing the provider field in the configuration file. The first run of loom chat launches an interactive wizard that creates the global configuration file at ~/.loom/config.json on macOS and Linux or at %APPDATA%/loom/config.json on Windows.

Installing and Configuring Loom

Loom requires Node.js 18 or later. Install it globally from npm:

npm install -g @vegamo/loom

The first loom chat session will prompt for a DeepSeek or OpenAI API key. For non-interactive environments, create the config file manually before running:

{
  "outDir": "docs",
  "llm": {
    "provider": "deepseek",
    "model": "deepseek-chat",
    "baseURL": "https://api.deepseek.com/v1",
    "apiKey": "your_deepseek_api_key",
    "temperature": 0.7,
    "maxTokens": 2000
  },
  "serve": { "port": 3000, "host": "0.0.0.0" },
  "mock": { "port": 3001, "host": "0.0.0.0" }
}

Once installed, the core workflow is three commands: loom chat to generate schemas, loom view to browse them in a browser, and loom mock to start the mock API server. The combined loom serve command starts both the browser viewer and the mock server on the same port, with mock routes under /mock/...

The Browser Viewer and Mock Server

loom view starts a React single-page application on port 3000 that reads the generated schema files and presents them in a table layout similar to Swagger UI. The README describes per-module browsing with endpoint counts, real-time search within a module, and automatic resolution of x-entity-ref references when rendering request and response sections. Each endpoint has a direct link URL for sharing with colleagues.

The mock server registers routes from every schema file in docs/ and generates synthetic response data from the JSON Schema definitions using the mock-json-schema library. It supports all HTTP methods: GET, POST, PUT, DELETE, and PATCH. The response status code and schema can be configured per endpoint. The mock server does not require a running backend, so a frontend team can start integration work before the real API is built.

The loom serve command combines both services on a single port. The browser viewer is at the root, the documentation API is at /api/docs, and mock routes are at /mock/... The README notes that this is the recommended setup for most projects.

Scanning Existing Source Code with /scan

The /scan command inside the loom chat TUI sends source files to the LLM to identify API endpoints and generate schema skeletons without a conversation. The scanner operates in four phases: detecting the framework and collecting files (phase 1), extracting entity definitions (phase 2), generating entity schemas (phase 3), and generating endpoint schemas (phase 4). Phases 3 and 4 accept a --lang parameter to control whether the descriptions are written in Chinese or English, defaulting to Chinese.

The scan can be paused and resumed with /scan resume, and /scan reset clears the progress. The scan cache is stored at .loom-scan-cache.json in the output directory and uses a source-hash plus per-record shape validation to invalidate stale entries, rather than a blanket version bump. The README notes that if the LLM prompts change substantially, you can manually delete that file to force a full rescan.

After running /scan, the generated schemas are in the same docs/ directory as manually written ones and can be reviewed or refined through the normal loom chat conversation.

Limitations and What Loom Does Not Provide

Loom writes its own JSON Schema dialect that uses an endpoints array with path, method, request, and response keys. This is not OpenAPI or Swagger. There is no documented tool to convert Loom schemas to OpenAPI 3.x, which means teams whose toolchain depends on the OpenAPI ecosystem (code generators, contract testing tools, API gateways) cannot use Loom output directly. If your team already maintains an OpenAPI spec, adding Loom creates a second documentation format to keep in sync.

The tool uses a single global config file per machine, but docs/ stays in the project directory. Multiple projects on the same machine share the same LLM configuration, which means switching models between projects requires editing the global config manually on each switch. The README does not document per-project configuration overrides.

The scan command relies on the LLM recognising the framework. For unusual or internal frameworks, the automatic detection in phase 1 may produce incorrect or empty results. The README does not document the list of supported frameworks.

The repository has no stated license in the prompt metadata. The README has no license section. Users who need to know the redistribution terms before deploying Loom internally should check the GitHub repository directly, as the prompt file marks the license as unknown.

Editorial conclusion

Loom works best early in a project, when API contracts are still being decided and the fastest way to get a reviewable schema is a conversation rather than editing YAML by hand. The source scanner makes it useful for teams that have existing code but no machine-readable API documentation. It is a poor fit for teams whose primary format is OpenAPI or Swagger, since Loom writes its own JSON Schema dialect with an endpoints array rather than the OpenAPI specification, and there is no documented migration path between the two. The last push to the repository was on 2026-05-28.

Frequently asked questions

Official sources

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