@vegamo/loom
Advanced tools
AI-powered JSON Schema document generator with TUI, web viewer and mock server
docs/entities and reference them in endpoint schemas via x-entity-ref/mock, /view)loom manifest rebuild)npm install -g loom
# or
yarn global add loom
git clone <repository-url>
cd loom
npm install
npm run build:all
Loom uses a global config file (no .env dependency).
Default global config path:
~/.loom/config.json%APPDATA%/loom/config.jsonOptional override:
LOOM_CONFIG=/custom/path/config.jsonWhen you run loom chat for the first time, it will guide you to create/update this global file interactively.
Default chat onboarding values:
provider: deepseekmodel: deepseek-chatbaseURL: https://api.deepseek.com/v1apiKey: required, must be entered by userYou can also create the global config manually:
{
"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"
}
}
docs/ remains in each project directory (--dir) and is not moved to global storage.
# Start interactive TUI to generate JSON Schema
loom chat
# Or specify project directory
loom chat --dir ./my-api-project
In loom chat, you can also control local services:
/mock, /mock stop, /mock restart [port]/view, /view stop, /view restart [port]# Start web documentation viewer
loom view
# Or with custom port
loom view --port 8080
# Start mock API server
loom mock
# Or with custom port
loom mock --port 8081
# Start both viewer and mock server on same port
loom serve
# Access at:
# - Web Viewer: http://localhost:3000
# - Mock API: http://localhost:3000/mock/...
# Manually trigger upgrade
loom upgrade
Loom also checks npm for updates when you run commands.
If a newer version is found, you can confirm and let Loom auto-upgrade.
loom chatInteractive terminal UI for generating JSON Schema documents through AI conversation.
loom chat [options]
Options:
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
Example Workflow:
loom chatdocs/ directory (configurable)Built-in chat commands:
Enter to send, Shift+Enter or Alt+Enter for newline/help — Show command help/reset — Reset conversation history/list — List generated schema files/mock, /mock stop, /mock restart [port] — Manage mock server/view, /view stop, /view restart [port] — Manage web viewer/abort — Abort current request/exit — Exit Loomloom viewModern web-based documentation viewer with React SPA interface.
loom view [options]
Options:
-p, --port <number> Port number (default: 3000)
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
Features:
docs/entitiesx-entity-ref auto-resolve in endpoint request/response renderingloom mockDynamic mock API server that generates realistic data based on JSON Schema.
loom mock [options]
Options:
-p, --port <number> Port number (default: 3001)
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
Features:
loom serveCombined service that runs both web viewer and mock server together.
loom serve [options]
Options:
-p, --port <number> Port number (default: 3000)
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
URL Structure:
http://localhost:3000/ - Web documentation viewerhttp://localhost:3000/api/docs - Documentation APIhttp://localhost:3000/api/schemas - Schema file APIhttp://localhost:3000/api/entities - Entity file APIhttp://localhost:3000/mock/... - Mock API endpointsloom manifest rebuildRebuild docs manifest index file (.loom-manifest.json) for dependency/index consistency.
loom manifest rebuild [options]
Options:
-d, --dir <path> Target project directory (default: current directory)
-h, --help Display help
loom upgradeUpgrade loom to the latest npm version.
loom upgrade
Loom uses a custom JSON Schema format optimized for API documentation:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Authentication API",
"description": "User authentication endpoints",
"version": "1.0.0",
"endpoints": [
{
"path": "/api/auth/login",
"method": "POST",
"summary": "User login",
"description": "Authenticate user with credentials",
"tags": ["auth"],
"request": {
"headers": {
"Content-Type": { "type": "string", "enum": ["application/json"] }
},
"body": {
"type": "object",
"properties": {
"username": { "type": "string" },
"password": { "type": "string" }
},
"required": ["username", "password"]
}
},
"response": {
"200": {
"type": "object",
"properties": {
"token": { "type": "string" },
"user": { "type": "object" }
}
},
"400": {
"type": "object",
"properties": {
"error": { "type": "string" }
}
}
}
}
]
}
Loom supports reusable entity schemas in:
docs/entities/*.entity.schema.json
Example entity file:
{
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "User",
"description": "Reusable user entity",
"type": "object",
"properties": {
"id": { "type": "integer" },
"name": { "type": "string" },
"email": { "type": "string", "format": "email" }
},
"required": ["id", "name", "email"]
}
In endpoint schemas, reference an entity with x-entity-ref:
{
"user": {
"x-entity-ref": {
"entity": "User",
"pick": ["id", "name", "email"]
}
}
}
Supported forms:
"x-entity-ref": "User""x-entity-ref": { "entity": "User", "pick": ["id", "name"] }loom/
├── src/
│ ├── agents/ # AI agent system with tool calling
│ │ ├── core/ # Agent core logic
│ │ └── memory/ # Conversation memory management
│ ├── llm/ # LLM client (DeepSeek, OpenAI)
│ │ ├── client.ts # Streaming LLM client
│ │ └── config.ts # LLM configuration
│ ├── tools/ # Tool system for agent
│ │ ├── schema-gen.ts # Schema generation tools
│ │ ├── schema-validate.ts # Schema validation tools
│ │ ├── file-ops.ts # Schema file operations tools
│ │ ├── entity-file-ops.ts # Entity file operations tools
│ │ └── entity-workflow.ts # Entity impact/sync/validate tools
│ ├── tui/ # Terminal UI (chat interface)
│ │ ├── app.tsx # Main TUI application
│ │ └── components/ # React components for TUI
│ ├── view/ # Web documentation viewer
│ │ ├── server.ts # Fastify web server
│ │ ├── routes/ # API routes
│ │ ├── frontend/ # React SPA frontend
│ │ └── public/ # Static assets
│ ├── mocks/ # Mock server
│ │ ├── server.ts # Mock server implementation
│ │ ├── router.ts # Dynamic route registration
│ │ └── generator.ts # Mock data generation
│ ├── shared/ # Shared utilities
│ │ ├── config.ts # Configuration loader
│ │ ├── entity-utils.ts # Entity read/write/reference helpers
│ │ ├── manifest-utils.ts # Manifest index builder
│ │ ├── schema-entity-resolver.ts # x-entity-ref resolver for viewer APIs
│ │ ├── types.ts # TypeScript definitions
│ │ └── logger.ts # Logging utilities
│ ├── serve.ts # Combined viewer + mock server
│ └── index.ts # CLI entry point
├── docs/ # Generated schema files
├── scripts/ # Build scripts
├── dist/ # Compiled output
└── package.json
# Build TypeScript backend
npm run build
# Build React frontend
npm run build:view
# Build both (recommended)
npm run build:all
# Start TypeScript development server
npm run dev
# Watch mode for frontend development
npm run dev:view
src/llm/config.ts and src/llm/client.tssrc/tools/ and register in src/agents/core/agent.tssrc/view/frontend/components/src/view/routes/ or src/mocks/router.tsFor maintainers, to publish a new version to npm registry:
# Login to npm (first time only)
npm login
# Update version if needed
npm version patch # or minor, major
# Build and create package
npm run build:all
# Publish to npm
npm publish
# Or publish with dry-run first
npm publish --dry-run
The package includes:
dist/loom)Package configuration:
prepack script ensures fresh build before packaging.npmignore excludes source files and development artifacts<name>.mock.json storage for hand-written mock responses (one active override per endpoint)/mock/<path> return real HTTP 400)request schema (path params, query, headers, body all filled with samples)@cname, @integer(1,100), 'list|1-5': [...] etc.) — templates are stored as-is and expanded on each requestsetNotFoundHandler error when starting the Web Viewer (loom view) or combined server (loom serve)@stoplight/json-schema-viewer dependency (incompatible with React 19)Contributions are welcome! Please follow these steps:
git checkout -b feature/amazing-featuregit commit -m 'Add amazing feature'git push origin feature/amazing-featureThis project is licensed under the ISC License - see the LICENSE file for details.
FAQs
AI-powered JSON Schema document generator with TUI, web viewer and mock server
We found that @vegamo/loom demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Security News
Two compromised GitHub Actions were re-enabled with malicious tags intact, exposing thousands of downstream repositories to Mini Shai-Hulud.
Research
/Security News
A malicious Firefox extension fetches its payload after installation to evade detection, steal Google session cookies, and automate account takeover.
Research
/Security News
The compromise affects MemTensor's MemOS, an open source memory framework for large language models (LLMs) and AI agents. Both npm package @memtensor/memos-cloud-openclaw-plugin and the PyPI package MemoryOS are compromised. They drop cross-platform Go binaries that exfiltrate developer secrets.