@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/Alt+Enter for newline, ↑/↓ to navigate history (persisted across sessions), Tab to autocomplete commands/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/scan <dir> — Discover APIs from source code via LLM; /scan resume, /scan reset manage the checkpoint/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/scan <dir> — multi-language, LLM-driven API discovery from existing source code. Detects framework, narrows file scope via globs, extracts endpoint identities (Phase 1), discovers + generates entity schemas (Phase 1.5), then generates one schema file per route prefix (Phase 2 referencing entities via x-entity-ref)/scan resume and /scan reset — checkpoint-aware continuation of an interrupted scan, or discard of the saved checkpoint/scan, keyed by file content hash (<outDir>/.loom-scan-cache.json); incremental rescans skip unchanged files and can save 25+ minutes. Pass --no-cache to force LLM callsloom chat, stored globally at ~/.loom/history.jsonl (capped at 100 entries). Up/down arrows navigate across sessionssrc/tui/commands.ts) so the Header panel, /help text, and the autocomplete list share one source of truth{ userToken, action: "used" } once per CLI invocation. Persisted UUID at ~/.loom/install-id, offline-tolerant outbox at ~/.loom/telemetry-outbox.jsonl<outDir>/.loom-scan.log plus raw response dumps from scan-failures.ts for LLM debugging/scan tolerates reasoning-model output (e.g. DeepSeek-R1 <think> content followed by final JSON in one body)APIConnectionError and SDK-internal aborts as retryable timeouts/scan resume on an already-completed checkpoint now surfaces a "scan already complete" message instead of silently re-running analyzerequired[] rather than type unionsdoneCount increments/scan resume continues at the right step/help (now includes /scan and /abort)/init command (disabled); requirement.md is still loaded as agent context if the file exists in the project<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
The npm package @vegamo/loom receives a total of 29 weekly downloads. As such, @vegamo/loom popularity was classified as not popular.
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.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
A fake corepack.org site is impersonating the Node.js tool and delivers an infostealer and proxyware to developers who download it.
Research
/Security News
A large-scale campaign abused GitHub Actions in compromised repositories to exploit CVE-2026-41940 in cPanel and WHM and steal server credentials.
Security News
Five frontier LLMs generated the same nonexistent package names, leaving 53 available for potential slopsquatting across PyPI and npm.